Who ai-memory is for#
Developers switching between AI coding agents mid-project
Quit Claude Code mid-task, open Codex in the same directory hours later, and receive a brief covering the open decisions and failed approaches from the previous session. ai-memory bridges the context gap without manual note-taking, making multi-tool workflows practical instead of friction-filled.
Skip if:
You use a single AI coding agent exclusively and never switch tools mid-project. If you work in one harness from start to finish, the cross-agent handoff feature does not apply and the overhead of running a memory server is not justified.
Engineering teams running shared AI coding infrastructure
Deploy ai-memory as a shared server on a LAN or homelab box with bearer-token auth. Per-operator memory slots keep each developer's context in a bounded namespace while shared rules, decisions, and procedures pages remain project-wide. The /admin/activity endpoint shows which MCP clients are active across the team.
Skip if:
Your team does not use AI coding agents, or each developer uses their own isolated agent with no shared project context. Shared deployment only adds value when multiple people contribute to the same codebase using AI tools.
Solo developers on long-running projects
On projects spanning weeks or months, ai-memory accumulates a structured wiki of architectural decisions, dead ends, and open questions. The _rules/, decisions/, and procedures/ page types receive retrieval priority, so the agent surfaces the reasoning behind past choices instead of rediscovering them from scratch.
Skip if:
Your projects are short-lived or one-off scripts where session context does not accumulate across days. For single-session work, the memory server adds overhead without meaningful benefit.
AI infrastructure developers building multi-agent pipelines
Use the MCP server interface to wire ai-memory into custom orchestration pipelines. The authority-aware retrieval stack (FTS5 + entity-match RRF + graph-neighbor RRF + optional vector RRF) is configurable. LLM provider support covers Anthropic, OpenAI, Gemini, and OpenAI-compatible endpoints including Ollama and LM Studio.
Skip if:
You need a fully managed memory service with an enterprise SLA, usage-based billing, and no server to maintain. ai-memory requires self-hosting a Rust server; teams without infrastructure capacity should evaluate managed commercial alternatives like Mem0 or Zep.
The problem it solves#
AI coding agents like Claude Code and Codex are productive within a single session, but they have no memory of what came before. Every session starts cold: you re-explain the architecture, re-list the approaches you already ruled out, and re-establish the context that took you an hour to build last time. On complex projects that span days or weeks, this is a constant friction point.
The pain is compounded when you switch tools. A Codex session cannot pick up where a Claude Code session left off. There is no standard way to hand off context across agent vendors, so teams either maintain manual notes (which fall out of date) or repeat themselves every session. Long-running projects accumulate context debt: decisions made for reasons no longer obvious, dead ends not recorded, gotchas rediscovered.
How it solves it#
Cross-agent handoffs
When a session ends, ai-memory compiles observations into a bounded handoff. The next agent sees a summary before its first prompt, covering open questions, failed approaches, and pending decisions. Supports Claude Code, Codex, Cursor, Gemini CLI, Devin CLI, Kimi Code, OpenCode, Command Code, Kiro CLI, and more. Optional managed workstream mode adds native per-harness session resume for higher-fidelity continuity.
Plain markdown git wiki
Context is stored as plain markdown in a git repo on your own infrastructure. No proprietary format, no database to manage. You can grep the wiki, open it in Obsidian, back it up with rsync, and time-travel through past states with git log. A built-in web browser mounted on the same axum server as MCP provides FTS5 search and markdown rendering.
Zero-friction lifecycle capture
Lifecycle hooks fire-and-forget at session boundaries: user prompts retain up to 16 KiB, tool events and notifications retain up to 2 KB per observation. Capture exclusions via a nearest-marker .ai-memory.toml file drop matching file-tool events before they reach the server. No manual note-taking or write_note ceremony required.
LLM-optional recall
Zero-LLM mode provides FTS5 full-text search, manually declared entity matching, and graph-neighbor retrieval without any API calls or costs. Add a provider when you want consolidated pages, contradiction linting, or auto-improvement proposals. Entity-assisted recall stores up to 10 specific nouns per page in canonical frontmatter for lexical matching alongside FTS5.
Opt-in managed workstreams
Run 'ai-memory run claude' then 'ai-memory run codex' to continue one logical workstream across tools with a portable visible-event ledger and native per-harness sessions. Supports transparent cross-harness continuity for Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, Command Code, and Kiro CLI. Direct launches remain unchanged; the wrapper only owns --yolo and --fresh flags.
Per-project isolation by construction
Each project lives at a stable UUID-keyed path: wiki_root/workspace_id/project_id. CLI subcommands walk to the main git repo root so all worktrees of the same repo share one project identity. Drop a .ai-memory.toml marker file in any ancestor directory to override workspace or project fields, enabling multi-client consultancies, mono-repos, and work/personal splits.
Strengths and trade-offs#
Strengths
- MIT license with full self-hostingThe tool is MIT licensed, so you can run it on your own infrastructure without licensing fees, modify the source, and use it commercially. Unlike paid commercial platforms (Mem0, Zep, Letta), your context data stays in a git repo you own and back up with standard tools. No vendor can change pricing, deprecate an API, or access your agent history.
- Broad agent compatibilitySupports Claude Code, Codex, Cursor, Gemini CLI, Devin CLI, Kimi Code, OpenCode, Command Code, Kiro CLI, OpenClaw, Grok Build CLI, Antigravity CLI, and more, with first-party lifecycle hooks for most. VS Code GitHub Copilot and Zed work via MCP without hooks. You are not locked into a single agent vendor now or in the future.
- No vector database requiredThe storage layer is plain markdown files in a git repo. Zero-LLM mode uses FTS5 full-text search plus entity and graph-neighbor retrieval with no external dependencies. Optional vector search works with OpenAI, Voyage, Google Gemini, and keyless OpenAI-compatible endpoints like Ollama and LM Studio. You choose the complexity level you actually need.
- Authority-aware retrievalFTS5, entity-match RRF, graph-neighbor RRF, and optional vector RRF generate candidates by relevance. A bounded adjustment favors maintained _rules/, decisions/, procedures/, and gotchas/ pages over episodic session evidence, so architectural decisions surface before individual session notes. Retrieved text stays untrusted historical evidence and never gains instruction authority.
Trade-offs
- -Young project with a large support matrixai-memory was created in May 2026 and already supports 20+ agent harnesses, each with distinct hook schemas and session-routing logic. With only 7 open issues at time of writing, the tracker may not yet reflect all edge cases. Teams should expect some rough edges when using less-documented harnesses like Kiro CLI v3, Antigravity CLI, or experimental native Windows paths.
- -Manual finalization required for some agentsSeveral agents (Codex, Command Code, Antigravity CLI, Kiro CLI) have no automatic true session-end hook. You must run 'ai-memory finalize-session --agent' after the final turn to trigger the summary and handoff. Missing this step means the session's context is not compiled into the wiki. The README documents which agents require manual finalization.
- -Native Windows is experimentalNative Windows support outside of WSL2 is listed as experimental. The tool publishes a Windows binary, but lifecycle hook integration with Claude Code's Windows exec form and other agents requires additional configuration. Teams on Windows should use the WSL2 path, which is fully supported and is the recommended setup.
ai-memory vs alternatives#
ai-memory vs Mem0
Mem0 is one of the paid commercial memory platforms that ai-memory targets as an alternative. The key architectural difference is control: ai-memory stores agent context as plain markdown in a git repo on your own server, MIT licensed and free to run. Paid platforms like Mem0 manage storage on their infrastructure, which introduces a dependency on a commercial API and removes the ability to grep, version-control, or back up context files directly.
ai-memory is the stronger choice when data ownership, offline operation, cost certainty on high-volume agent workloads, or the ability to inspect and modify context files directly are priorities. A managed commercial platform is worth considering when you want zero infrastructure to maintain, enterprise SLA coverage, or an out-of-the-box hosted retrieval API with no server to run.
ai-memory vs Zep
Zep is a commercial memory layer for AI applications. Where Zep targets application developers who need per-user memory APIs, ai-memory is built specifically for coding agent CLI workflows: Claude Code, Codex, Cursor, and similar tools. The handoff mechanism, lifecycle hooks, and per-project isolation are designed around how developers actually switch between coding sessions, not how application backends store end-user memory.
For developer tooling, ai-memory's file-based approach (grep, Obsidian, rsync, git log) is more ergonomic and keeps data local. For production applications serving end users that need managed memory APIs at scale with enterprise support, a commercial platform like Zep is a more natural fit than a self-hosted developer session tool.
ai-memory vs Letta
Letta is a paid platform for building stateful LLM agents. ai-memory is a different category of tool: a session-memory layer you add to existing CLI coding agents via MCP and lifecycle hooks, not a framework for constructing agents from scratch. You do not rewrite how Claude Code or Codex work; you layer ai-memory on top of them.
For teams augmenting existing AI coding tools with persistent context, ai-memory is the simpler and more focused path. Letta is worth evaluating when you are building a new stateful agent application from scratch and need a full agent framework rather than a session-memory layer for CLI tools you already use.
What it's built on#
- Languages
- Rust
FAQ#
Does ai-memory work with Claude Code?
Yes. ai-memory has first-party support for Claude Code with MCP config and lifecycle hooks. The optional --session-aware flag on install-mcp adds per-session auto-scope isolation through a local stdio bridge. The tool can also capture the assistant's final turn on Stop when installed with --capture-assistant, though this is a double opt-in and off by default.
What happens if I switch from Claude Code to Codex mid-task?
ai-memory compiles a handoff from the Claude Code session observations when the session ends. When you open Codex in the same directory, it receives a summary before its first prompt, covering the open questions, pending decisions, and failed approaches from the Claude Code session. The optional managed workstream feature ('ai-memory run') adds native per-harness session resume for higher-fidelity cross-tool continuity.
Does ai-memory require a vector database or LLM API?
No. Zero-LLM mode provides FTS5 full-text search, entity-match, and graph-neighbor retrieval with no API calls or external dependencies. Adding an LLM provider (Anthropic, OpenAI, Gemini, or compatible endpoints) enables page consolidation, contradiction linting, and auto-improvement proposals. Adding an embedding provider enables optional vector search alongside the lexical stack.
Is ai-memory suitable for team use, or is it only for solo developers?
Both. Run it locally on loopback for solo use, or deploy it on a LAN or homelab box with bearer-token auth for teams. Per-operator memory slots keep each developer's context in a bounded namespace. Shared rules, decisions, and procedures pages are project-wide, so the team's institutional knowledge is accessible to every agent. The /admin/activity endpoint shows which MCP clients are actively reading and writing.
Where is the context data stored, and can I back it up?
Context is stored as plain markdown files in a git repo at a configurable wiki root. Standard git tools handle versioning and history; you can time-travel with 'ai-memory checkpoints' or 'restore-page', or with raw git log. Back it up with rsync, push it to a private remote, or open individual pages in Obsidian. The CLI's backup subcommand provides an additional backup path. No proprietary formats, no locked storage.
Similar open-source tools#
mex
Persistent memory and code graph for AI coding agents
OpenCode
OpenCode is an open-source AI coding agent that assists developers in
omlx
Fast LLM inference for Apple Silicon with persistent SSD KV caching
llmfit
One command to rank every LLM against your hardware.
Soup
Fine-tune any LLM on a 4 GB GPU, one YAML config
Switchyard
LLM proxy with API translation and multi-backend routing