ai-memory: A cross-agent memory layer for coding CLIs, judged on its own claims
Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors.
At a glance
- What is it?
- ai-memory is a Rust-based daemon that gives coding agents long-term memory and handoff files, spanning Claude Code, Codex, and a dozen other CLIs. The project is ambitious and well documented, but its breadth creates real integration risk.
- Who is it for?
- Adopt ai-memory if you regularly switch between multiple agent CLIs in the same repository and need to preserve architectural context, failed attempts, and open questions across sessions. Skip it if you use a single agent exclusively, because the abstraction layer adds setup and hook complexity without clear benefit.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem: agent amnesia and vendor lock-in
Coding agents like Claude Code and OpenAI Codex are stateless by default. Each session starts with a blank slate, so you spend time re-explaining the architecture, the failed approaches, and the open questions. This is the core problem ai-memory addresses. The README's pitch is direct: quit Claude Code mid-task, start Codex in the same directory, and continue without re-explaining. The project targets engineers who run multiple agents in the same repository, either because they evaluate vendors or because different agents are better at different tasks. It is not a tool for a single-agent workflow, and the README makes no claim to be one. The value is in the handoff, not in the memory itself.
How it works: hooks, MCP, and a session ledger
The mechanism is a daemon that sits between the agent and the filesystem. It uses lifecycle hooks to capture events: session start, user prompts, tool calls, and session end. Each agent exposes a different hook schema, and ai-memory installs the correct hooks for each. It also configures an MCP (Model Context Protocol) server so the agent can query memory directly. The captured events are stored in a session ledger, which is then used to generate a handoff document. The README describes a specific flow: on session start, ai-memory injects pending handoffs into the agent's context. On session end, it finalizes the summary. For agents without a true session-end hook, like Codex and Antigravity CLI, you must run `ai-memory finalize-session` manually. This is a key design choice: the project does not try to fake a session boundary; it tells you when you need to act.
Supported agents: a matrix with honest caveats
The support matrix is the heart of the README. It lists 18 agent harnesses, from Claude Code and Codex to niche tools like Crush and Swival CLI. Each entry specifies the exact integration method: MCP config, lifecycle hooks, or both. The level of detail is unusual. For Grok Build CLI, the README notes that Grok ignores `SessionStart` stdout, so handoffs must be recovered via MCP `memory_handoff_accept`. For Zero, it says the same: no handoff injection, use MCP. For Kimi Code, handoffs inject via `UserPromptSubmit` because Kimi discards `SessionStart` hook stdout. These are not generic claims; they are specific behavioral facts that the maintainers have observed. The matrix also marks Crush as managed-only, meaning no hook installer is provided at all. This honesty is a strength, but it also reveals the integration cost: every agent is a bespoke adaptation.
Getting it running: install commands and config paths
The README provides concrete install commands. For most agents, you run `ai-memory install-mcp --client <name>` and `ai-memory install-hooks --agent <name>`. For example, Grok uses `install-mcp --client grok` which writes to `$GROK_HOME/config.toml`, and `install-hooks --agent grok` which writes to `$GROK_HOME/hooks/ai-memory.json`. Kimi Code uses `install-mcp` for `~/.kimi-code/mcp.json` and `install-hooks` for `~/.kimi-code/config.toml`. The commands are agent-specific, and the project ships binaries for macOS (aarch64 and x86_64), Windows (x86_64 zip), and Linux (Docker images for amd64 and arm64). Native Windows is experimental, with PowerShell and Git Bash fallback scripts. The README recommends the native binary on Apple Silicon. There is no single universal install; you must match the command to your agent, which is a barrier but also a sign of precision.
Limitations and failure modes
The most obvious limitation is the lack of true session-end hooks for several agents. Codex, Antigravity CLI, and Kiro CLI have no automatic session end, so the handoff is only as good as your habit of running `ai-memory finalize-session`. If you forget, the memory is incomplete. The README also notes that conversation text is not decoded for Antigravity CLI, so the ledger for that harness comes only from hook capture. That means the memory may miss context that was never captured as a hook event. Another limitation is the experimental status of native Windows. The README says Claude Code may use its Windows exec form while other agents use native single command strings, and PowerShell/Git Bash scripts are fallbacks. This is a recipe for subtle breakage. Finally, the project does not support Swival CLI for lifecycle hooks because Swival's callback contract does not expose a stable session identifier. So the tool is not universal, and the README says so plainly.
Alternatives: what else does this job?
The direct alternative is not another memory tool; it is the built-in session management of each agent. Claude Code has its own CLAUDE.md file, and Codex has AGENTS.md. These are static context files that you maintain manually. The difference in approach is that ai-memory captures events automatically and generates a handoff, whereas CLAUDE.md requires you to write the context yourself. The trade-off is control versus automation. With CLAUDE.md, you decide exactly what the agent sees, but you must remember to update it. With ai-memory, the handoff is generated from actual session events, which may include noise or omit things you would have written. Another alternative is to use a single agent exclusively and rely on its native memory features, which avoids the integration complexity entirely. The README does not mention any competitors, but the comparison is implicit in the support matrix: the tool exists because agent-native memory is either absent or not portable.
Maintenance and upgrade cost
The project is actively maintained, with three releases on consecutive days in the sample data: v1.35.0, v1.34.0, and v1.33.1. That cadence suggests a fast-moving codebase, which is a double-edged sword. On one hand, bugs and agent schema changes are addressed quickly. On the other hand, you will need to update frequently to keep pace with agent updates. The README does not specify an upgrade path, but the install commands suggest that re-running `install-mcp` and `install-hooks` after an update is the likely method. The license is MIT, which means you can vendor the tool and modify it, but you must maintain your own fork if you do. The support matrix itself is a maintenance burden: every new agent version that changes its hook schema will require a new ai-memory release. The project's own docs, like `docs/macos.md` and `docs/windows.md`, indicate that platform-specific issues are tracked separately. Before adopting, check the last push date and the release notes for your agent's support status, because a stale version will silently fail to capture memory.
Editorial conclusion
Adopt ai-memory if you regularly switch between multiple agent CLIs in the same repository and need to preserve architectural context, failed attempts, and open questions across sessions. Skip it if you use a single agent exclusively, because the abstraction layer adds setup and hook complexity without clear benefit. Before adopting, verify that the specific agent version you run matches the hook schema ai-memory targets, especially for agents like Codex and Grok that lack true session-end hooks. Test a handoff from one agent to another in a scratch directory first, because the documented per-agent quirks suggest that real-world behavior may vary. The project's own support matrix is the most honest source of truth: read the docs for your agent before trusting the generic install command.
Community notes