让编码 Agent 共享长期记忆，跨工具无缝交接工作流

ai-memory is a long-term memory layer for AI coding agents. It is a single Rust binary that runs an MCP/HTTP server and installs small lifecycle hooks into your agent CLI. Those hooks send sanitized observations about prompts, tool calls, and session boundaries to the server. When a session ends, the server compiles the observations into a concise wiki page and produces a bounded handoff for the next session. The wiki is plain Markdown stored in a git repository — grep-able, openable in Obsidian, and backup-friendly. No vector database is required unless you opt into embedding-based retrieval.

The project targets individuals and teams who switch between coding agents (Claude Code, Codex, Command Code, etc.) and want continuity without re-explaining architecture, failed approaches, or open questions every time.

LLM coding agents are stateless in practice. End a session and the model loses everything it knew about your codebase: the architecture you explained, the failed approaches you ruled out, the open questions you were about to resolve. When you come back, you either re-explain everything or accept a slow, degraded start.

Crossing vendors makes it worse. Claude Code's session memory does not transfer to Codex, and neither carries into Command Code. The classic pain is concrete: quit at 4 PM, pick up at 9 AM in a different agent, and spend the first hour reorienting. ai-memory treats the project, not the agent, as the durable unit: observations land in a per-project wiki and the next agent receives a typed 'where you left off' block before its first prompt.

Three ideas carry most of the design.

Capture. Lifecycle hooks fire-and-forget bounded, sanitized observations to the server — prompts, tool lifecycle events, and session boundaries. No manual write_note ceremony, no need to remember to save.

Compile. At session end (or before compaction), the server compiles observations into coherent Markdown pages. Retrieval works over those pages, not raw logs. Pages are git-versioned and carry a supersession chain, so you can time-travel with ai-memory checkpoints or plain git log.

Hand off. The next session's SessionStart hook fetches a pending handoff — a typed block with open questions, next steps, and a session summary. Recall is hybrid: FTS5 fused with entity-match and graph-neighbor RRF, plus optional vector reranking. An LLM is never required: zero-LLM mode still gives you rule-based summaries, full-text search, entity and graph retrieval.

The basic handoff is a summary. If you want higher-fidelity continuity, opt into managed workstreams with ai-memory run. It launches the real agent binary on your host, keeps a portable visible-event ledger, and resumes the same logical workstream natively inside each harness.

cd /path/to/project
ai-memory run claude
# ... work, then quit Claude Code ...
ai-memory run codex --yolo
ai-memory run command-code
# Later, omit the name to continue the newest usable managed session.
ai-memory run

Direct claude / codex launches are unaffected. Managed mode currently covers Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI v2/v3, OMP, Grok Build CLI, and Antigravity CLI.

One Rust binary runs an MCP/HTTP server and owns one data directory:

<data_dir>/
├── wiki/      # Markdown source of truth, git-versioned
├── raw/       # immutable sanitized transcript segments
├── db/        # SQLite indexes, including FTS5, entities, embeddings
├── models/    # reserved for local embedding models
└── logs/      # rolling tracing output

Agent hooks POST observations to the server. The server serializes all writes through a single SQLite writer, compiles session observations into Markdown pages, and answers reads through FTS5, entity-match / graph-neighbor RRF, optional vector RRF, and bounded source-authority adjustments. The CLI (ai-memory status, bootstrap, checkpoints, …) is a thin HTTP client — it never touches SQLite or wiki files directly. The server is the single source of truth.

The fastest path is Docker plus two wiring commands. The published image includes linux/amd64 and linux/arm64 variants.

docker run -d --name ai-memory --restart unless-stopped -p 127.0.0.1:49374:49374 -v ai-memory-data:/data akitaonrails/ai-memory:latest
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply

Start a Claude Code session as usual — every prompt and tool call is now captured, and the next session in this project sees a handoff. Add other agents by repeating the install commands with --agent codex, --agent command-code, --client cursor, etc. By default the server binds to loopback only and has no auth, which is safe for a single-user laptop. For LAN or multi-user access, add a bearer token (and put TLS in front of it). Native installs on Arch (AUR), macOS, and Windows/WSL2 are documented.

A few recurring patterns:

• Quit Claude Code, continue in Codex: ai-memory run claude, then ai-memory run codex --yolo.
• Ask 'what did we decide about X?': the agent calls memory_query for a hybrid FTS5 + entity + graph search.
• Save something permanently: tell the agent to write a permanent note, or run ai-memory write-page --path decisions/0007-db.md --body $'# Standardised on Postgres\n\n...' --pinned.
• Give a new project months of history: cd /path/to/project && ai-memory bootstrap digests git log, README, docs, and module headers into seed wiki pages.
• Undo one bad page edit: ai-memory checkpoints then ai-memory restore-page --path notes/foo.md --from <rev>.
• Drop an experiment entirely: ai-memory purge-project --project experimental --confirm.

For day-to-day use you mostly don't think about ai-memory: hooks capture, SessionStart injects handoffs, and you just ask 'where did we leave off?'.

Read the support matrix before adopting. Linux and macOS are first-class; Windows is supported via WSL2, while native Windows is experimental. Some clients are MCP-only: VS Code Copilot, Zed, Claude Desktop, and Swival have no lifecycle hooks, so they cannot inject or produce handoffs themselves. Grok and Zero ignore SessionStart stdout, so they recover handoffs through memory_handoff_accept instead. Clients without a true session-end event (Codex, Grok, Kiro CLI, Antigravity CLI, Command Code) need a manual ai-memory finalize-session --agent <agent> to close a session.

Security defaults are conservative: loopback-only with no auth. Expose the server beyond localhost only with a bearer token, and terminate TLS with a reverse proxy (Caddy or Cloudflare Tunnel templates are provided). Retrieved historical text is untrusted evidence — verify code claims against the current checkout. LLM use is opt-in; without a provider, search and summaries still work via deterministic rules.