ai-memory: Long-Term Memory for Coding CLIs

Every coding CLI you use has amnesia by design. You explain your architecture to Claude Code on Monday, switch to Codex on Tuesday, and start from zero — re-explaining the failed approaches, the open questions, and where you left off. Each agent keeps its own notes, on its own machine, invisible to everything else.

In this guide I show you what ai-memory is and why 6,000+ developers starred it in under four months, how its capture → consolidate → recall → handoff pipeline works in 4 steps, the verified quickstart you can run today with Docker or cargo, and — just as important — when you should NOT use it.

1. What ai-memory Is: Stars, License, and the Idea

ai-memory is an open-source, Rust-built long-term memory layer for AI coding CLIs, created by Fabio Akita (akitaonrails) in May 2026 — built collaboratively with Claude Code, per the README. Its tagline says it all: quit Claude Code mid-task, start OpenAI Codex in the same directory, and continue without re-explaining the architecture, the failed approaches, or the open questions. As of September 12, 2026 the repository at github.com/akitaonrails/ai-memory sits at roughly 6,600+ stars and 450+ forks under the MIT license — one of the fastest-growing agent-infrastructure repos of the year.

Repo Facts (verified Sept 2026)

Repository: github.com/akitaonrails/ai-memory
Stars: ~6,600+ (check the live count on GitHub)
License: MIT — commercial use allowed
Stack: One Rust binary (axum MCP/HTTP server) + SQLite + Markdown wiki
Agents: 20+ harnesses: Claude Code, Codex, OpenCode, Cursor, Gemini CLI, and more

The core bet is simple and echoes Karpathy: agent memory is text. Text lives on disk as a git-backed wiki of plain Markdown files — grep it, open it in Obsidian, edit it by hand. SQLite is a derived index that can always be rebuilt from the files. And the default path uses zero LLM calls: capture, search, and handoffs all work with no API key at all.

Why this matters in 2026

Every platform is adding its own memory feature, but all of them share the same walls: the notes live on one machine, belong to one agent, and vanish the moment you switch tools — or teammates. ai-memory puts one shared memory underneath 20+ harnesses, on your laptop or a homelab box, so the project you left on the desktop is the project you resume on the laptop.

2. Architecture in 4 Steps: From Keystroke to Handoff

The README and docs/ARCHITECTURE.md describe the flow as capture → consolidate → recall → handoff. Here it is, step by step, exactly as the project documents it:

📥

Step 1 — hooks capture silently

Lifecycle hooks (shell hooks for Claude Code and Codex, a TypeScript plugin for OpenCode, JSON lifecycle config for Cursor and Gemini CLI) POST sanitized observations — prompts, tool calls, session boundaries — fire-and-forget to the local HTTP server at 127.0.0.1:49374. The agent never waits; if ai-memory is down, the session continues normally, just without capture.

📝

Step 2 — sessions consolidate into wiki pages

At session end, observations are compiled into coherent Markdown pages in the project's wiki (optionally LLM-written, useful even without). The wiki is the source of truth: wiki/ holds the pages, raw/ holds immutable sanitized transcript segments, db/ holds the SQLite indexes, and one SQLite writer serializes all writes (~700/s measured ceiling, not guessed).

🔍

Step 3 — recall fuses five signals

Retrieval runs through FTS5 full-text, entity-match and graph-neighbor RRF, optional vector RRF when an embedder is configured, a bounded source-authority adjustment, and a bounded raw-observation fallback. The next session — any agent, any machine — gets a bounded brief and can search everything, with explain: true showing why each hit ranked where it did.

🔀

Step 4 — handoffs are a protocol, not a convention

Cross-agent handoffs carry the baton explicitly: typed, owned, claimed exactly once. The optional managed launcher (ai-memory run claude, then ai-memory run codex --yolo) adds native session resume plus portable visible history on top of shared memory, so an obsolete local session can never overwrite newer cross-harness history.

Design notes worth knowing

One server owns one data directory — never two. Knowledge is shared per project while personal handoffs stay personal, with multi-user auth, per-person attribution, and an audit log of every mutation built in, not as a paid tier. Purge commands document exactly what “deleted” means, and install commands are idempotent with timestamped backups next to every file they touch.

3. Quickstart: Shared Memory in 10 Minutes (Verified)

All commands below come straight from the live README and docs/install.md — I verified each one against the repo on September 12, 2026. Docker is the recommended path; cargo from source and AUR packages are documented alternatives. Omit the LLM lines for zero-LLM mode — FTS5 search still works with no keys.

# Option A — build from source with cargo (workspace, pinned toolchain in rust-toolchain.toml)
git clone https://github.com/akitaonrails/ai-memory.git
cd ai-memory
cargo build --release
./target/release/ai-memory --version

# Option B — Arch Linux (AUR)
yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory        # builds from source

# Option C (recommended) — Docker: install the CLI wrapper, then start the server
mkdir -p ~/.local/bin
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper -o ~/.local/bin/ai-memory
chmod +x ~/.local/bin/ai-memory

docker run -d --name ai-memory \
  --restart unless-stopped \
  -p 127.0.0.1:49374:49374 \
  -v ai-memory-data:/data \
  -e AI_MEMORY_LLM_PROVIDER=anthropic \
  -e ANTHROPIC_API_KEY=sk-ant-... \
  docker.io/akitaonrails/ai-memory:latest

# Wire your agent CLI in two commands (repeat with --agent codex, opencode, gemini-cli…)
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply

# Everyday commands
ai-memory status        # server health
ai-memory search "auth refactor"   # quick terminal-only FTS5 lookup
ai-memory bootstrap     # adopt an existing project with months of history

# Optional managed workstreams: native resume + portable history across vendors
cd /path/to/project
ai-memory run claude            # start here…
ai-memory run codex --yolo      # …quit Claude, continue in Codex, nothing re-explained
ai-memory continue              # resume the newest managed checkout
ai-memory uninstall --apply     # removes everything it installed, only what it installed

That is it on Linux and macOS: start a Claude Code session as usual and every prompt and tool call lands in ai-memory. Open Codex in the same directory later and the next agent picks up a real handoff — where you left off, what failed, what is still open. On macOS the native release binary is recommended when you do not need Docker (see docs/macos.md); Windows runs via WSL2, with native Windows still experimental.

Tip: keep it loopback-first

The default quickstart binds to 127.0.0.1:49374 with no auth — nothing outside your machine can reach it, which is exactly what you want on a single-user laptop. Only add a bearer token (and TLS via the Caddy/Cloudflare Tunnel templates in docs/https-via-proxy.md) when you move the server to the LAN or a homelab box for teams and multiple machines.

4. Use Cases: Where ai-memory Earns Its Keep

Shared memory is not a feature — it is the difference between restarting every conversation and compounding knowledge. These are the scenarios the project documents in docs/use-cases.md, and they map cleanly to daily CLI work:

🔀

Vendor handoff mid-task

Quit Claude Code, continue the same workstream in Codex, Command Code, or OpenCode. The next harness gets pending handoffs plus searchable history — no more pasting context between vendors.

💻

Desktop-to-laptop continuity

Run the server on a homelab box and point every machine at it. The project you left on the desktop is the project you resume on the laptop: same knowledge, same open questions.

👥

Team-shared project memory

Point the whole team at one server and what one person's sessions learn, everyone's agents can retrieve — per-project sharing, per-person attribution, and a full audit log included.

🕰️

“What did we decide six weeks ago?”

Session-end consolidation turns raw transcripts into coherent decision pages. Ask the agent or run ai-memory search from the terminal instead of digging through dead sessions.

The pattern across all four: long-lived projects + repeated sessions + knowledge that must survive tool switches. If you touch the same repo with more than one CLI — or more than one machine — a shared memory server pays for itself the first time you skip the re-briefing.

5. When NOT to Use ai-memory: Honest Limits

I like ai-memory, but a memory server is infrastructure — it has an install, a process to keep alive, and a data directory to back up. Here is my honest checklist:

❌ Reach for something else when

• You use a single agent on a single machine and never switch — native session resume or the agent's own notes are simpler with zero moving parts.
• You need cited answers over your own documents — that is RAG's job; use a vector DB plus citations, not agent session memory.
• You cannot run one more always-on process — the server (Docker or systemd) must be up for capture; otherwise sessions silently record nothing.
• Native Windows without WSL2 — still experimental, with hook/MCP harness caveats documented in docs/windows.md.
• Regulated or adversarial inputs with no trust boundary — anyone who can talk to the agent can generate observations; set per-repo [capture] rules (exclude paths or allowlist mode) before production.

✅ ai-memory is a great fit when

• You switch between Claude Code, Codex, OpenCode, or Cursor on the same projects.
• You work from multiple machines or with a team sharing one server.
• You want memory as plain Markdown on disk — greppable, git-versioned, rebuildable — not a binary blob.
• You want zero-LLM capture with optional LLM upgrades (summaries, embeddings) later.

Golden rule

Memory is infrastructure, not a plugin. If you cannot answer “where does the server run, who can reach it, and how do I back up and purge the data directory”, you are not ready for a memory layer — set up the server lifecycle first (docs/deploy.md, docs/lifecycle-ops.md), then wire the agents.

Conclusion

ai-memory earns its 6,600+ stars honestly: it turns the hardest part of multi-CLI work — persistent, shared, vendor-neutral memory — into one Rust binary with serious engineering behind it. The Markdown-on-disk model, the silent hook capture, and handoffs-as-protocol make it the default I reach for when coding agents need to remember across vendors.

Start with Docker on loopback, wire one CLI, and prove the handoff (quit one agent mid-task, resume in another) before rolling it out to the team. If you ever re-explained your architecture to a second CLI in the same week, ai-memory will pay for itself within days.