ai-memory: shared long-term memory for coding agents

The re-explaining problem ai-memory targets

The README states the case plainly: 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. That is the whole product thesis. The audience is engineers who keep more than one coding CLI installed and switch between them, not teams looking for a chat history archive.

The pain is specific. Each harness keeps its own session state, its own context window and its own idea of what happened in a directory. When you switch vendors, the new agent starts from the filesystem and your prompt. Everything you established in the previous session, including the approaches that did not work, has to be typed again or lost.

ai-memory sits underneath that rotation. It captures events from lifecycle hooks, stores them, and injects a handoff when a new session starts. The support matrix lists Claude Code, Codex, Command Code, Devin CLI, OpenCode, Cursor, Gemini CLI, Oh My Pi, Pi, Crush, Claude Desktop, OpenClaw, Antigravity CLI, Grok Build CLI, Swival CLI, Zero, Kimi Code and Kiro CLI. That breadth is the point, and it is also where the caveats live.

How capture, storage and handoff actually fit together

The workspace layout tells you the architecture before you read any prose. Cargo.toml declares members including ai-memory-core, ai-memory-store, ai-memory-wiki, ai-memory-mcp, ai-memory-hooks, ai-memory-llm, ai-memory-consolidate, ai-memory-web, ai-memory-cli and ai-memory-workstream. Capture, persistence, MCP serving, hook installation, summarisation and the managed workstream runner are separate crates, which means the hook layer does not have to link the summarisation layer.

Data flows through three surfaces. Lifecycle hooks fire inside the agent and hand events to the tool, with native commands enforcing capture exclusions so excluded paths never enter the store. The MCP server exposes memory operations to the agent, and several harnesses recover handoffs through the memory_handoff_accept call when their own hook stdout is ignored. The managed workstream path, enabled by ai-memory run, resumes a harness's own session and supplies portable context instead.

The support matrix is unusually candid about which harness supports which leg. Grok Build CLI captures events, but Grok ignores SessionStart stdout, so handoffs come back through MCP. Zero discards sessionStart stdout for the same reason. Kimi Code injects handoffs through UserPromptSubmit stdout because it discards SessionStart hook stdout. Devin CLI uses its PostCompaction event and injects via hookSpecificOutput.additionalContext, and omits subagent events because Devin does not expose them. These are not marketing footnotes; they are the operating conditions.

Installing ai-memory and running a first handoff

Installation is per agent rather than global. The README points to native macOS tarballs, Linux Docker images for linux/amd64 and linux/arm64, Arch/AUR packages with systemd units, a Windows zip, and source builds. Once the binary is on the path, the two installer families are MCP config and lifecycle hooks.

For a Claude Code setup, the documented path combines an MCP entry with hooks. The --session-aware flag optionally turns on per-session auto-scope isolation through a local stdio bridge:

ai-memory install-mcp --session-aware

Hooks are installed per agent. For Grok Build CLI the README gives the exact targets, an MCP entry in $GROK_HOME/config.toml (default ~/.grok/config.toml) and a hook bundle in $GROK_HOME/hooks/ai-memory.json:

ai-memory install-mcp --client grok
ai-memory install-hooks --agent grok

Swival CLI is MCP-only and merges into a project-root file rather than a home directory, preserving sibling servers:

ai-memory install-mcp --client swival --apply

After a session, the handoff step depends on the harness. Codex has no automatic true session-end hook, so the README tells you to run the finalize command yourself when you need a final summary or handoff:

ai-memory finalize-session

Command Code and Antigravity CLI need the agent named explicitly, because their Stop event is only a turn boundary:

ai-memory finalize-session --agent command-code
ai-memory finalize-session --agent antigravity-cli

What you should see is a stored session record for the directory and a handoff that the next agent can accept. On harnesses that ignore SessionStart stdout, that acceptance happens through the MCP memory_handoff_accept call instead of appearing in the new session's context automatically.

Where the hook model breaks down

The clearest limitation is the absence of a true session-end event in several harnesses. Codex, Command Code and Antigravity CLI all treat their stop signal as a turn boundary. If you close the terminal without running finalize-session, the summary and handoff for that work simply do not exist. Nothing in the README suggests a background process that recovers it.

A second constraint is that hook stdout is not a universal delivery channel. Grok Build CLI, Zero and Kimi Code each ignore SessionStart hook output, so the automatic injection that works on Claude Code does not work there. The README routes those users to MCP handoff acceptance, which is a manual step in practice.

Antigravity CLI adds a narrower rule: only PreInvocation with invocationNum = 0 maps to SessionStart, so later model calls cannot consume a next-session handoff. Conversation text for that harness is not decoded either, which means the ledger comes from hook capture alone. If your workflow depends on reconstructing what was said rather than what was done, this harness will not give you that.

Swival CLI is the hard boundary. The README states that lifecycle and managed-workstream support are not claimed because Swival's callback contract does not expose a stable session identifier. If Swival is your only harness, ai-memory reduces to an MCP memory server with no session continuity story. Crush is managed-only: ai-memory run resumes its project-local session database and supplies context through a temporary supported global-context file, with no lifecycle-hook installer provided at all.

Finally, native Windows is labelled Experimental. The supported path is WSL2, and the README notes that local supported profiles default to host-native hook commands, with PowerShell and Git Bash scripts as compatibility fallbacks. If your team runs agents natively on Windows without WSL, you are on the experimental branch of the support matrix.

How ai-memory differs from a single-vendor memory feature

The obvious alternative is the memory feature built into whichever agent you already use. Claude Code, Cursor and Gemini CLI all ship their own project context mechanisms, and they work without a second binary, a hook installer or an MCP server. The difference is scope. A vendor memory feature only knows about sessions from that vendor. ai-memory exists precisely because the README's opening scenario crosses that line: Claude Code first, Codex second, same directory.

A second alternative is a plain notes file committed to the repository. That is cheaper and has no installation surface, and for a solo engineer on one harness it is often enough. What it does not do is capture events automatically with exclusion rules, or produce a structured handoff that an agent can accept through a protocol call. ai-memory's value is proportional to how much you switch and how much you dislike writing the same context paragraph twice.

The managed workstream path is the third option inside the project itself. Rather than installing hooks, ai-memory run wraps the harness launch and provides transparent cross-harness continuity for a listed set of agents, with direct launches left unchanged. The README documents that Crush and Grok Build CLI get their context packets through this route, Grok natively via --rules. Choosing between hook installation and managed workstreams is a real decision, and the docs treat them as separate tracks rather than one replacing the other.

Maintenance, licence and the cost of a moving target

The repository is MIT licensed, declared in Cargo.toml and in the LICENSE file, with Fabio Akita listed as author. MIT is permissive: you can vendor it, modify it and ship it, provided the licence text travels with it. That is an observation about the licence identifier, not legal advice, and the usual obligations around attribution still apply.

The maintenance signal is strong but should be read precisely. The last push was on 2026-08-29, and the most recent tagged release is v1.35.0 on the same date, following v1.34.0 and v1.33.1 within a day of each other. The repository is not archived. A release cadence that produces three tags in two days suggests active work, but it also means the surface you integrate against moves quickly.

The upgrade cost is concentrated in the hook layer. Because each agent gets its own installer, its own config file and, in several cases, its own generated plugin or extension, an agent vendor changing its hook schema forces a change here. The support matrix already records two incompatible Kiro CLI engines, a Bedrock-compatible schema flavour, and exec-form versus shell-form command strings on Windows. The Rust toolchain is pinned in rust-toolchain.toml and the workspace declares rust-version 1.95 with edition 2024, so source builds track a recent compiler. Budget for re-running the installers after agent updates rather than assuming the wiring is permanent.

Editorial conclusion

Adopt ai-memory if you move between Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, Kiro CLI, OMP, Grok Build CLI or Antigravity CLI in the same repository and want the next agent to inherit the architecture notes and failed approaches. Skip it if you work inside a single harness, or if your agent is Swival CLI, where the callback contract exposes no stable session identifier and only MCP install is claimed. Before committing, verify the exact hook file your agent reads, and decide whether you will run ai-memory finalize-session yourself on harnesses that lack a true session-end event.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes