Coding agents forget. Close a Claude Code session, open Codex in the same folder, and you start by re-explaining the architecture, the approaches that failed and the questions still open. ai-memory is a trending GitHub project that tries to remove that step: a shared, long-term memory that many agents read from and write to, so one can pick up where another stopped.
This guide covers what it does, how the pieces fit, how to install it, what it records, and what to check first. Everything comes from the project's README and releases page as read on October 17, 2026. We did not install or benchmark it, so treat capabilities as the project's claims and check the numbers it publishes before relying on them.
TL;DR: questions people ask first
| Question | Answer from the README |
|---|---|
| What does it do? | Captures agent work through hooks, compiles it into markdown wiki pages, and injects a bounded brief at the next session start |
| Which agents? | 20+ harnesses including Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, Copilot CLI |
| Needs an LLM or API key? | No: the default path makes zero LLM calls; LLM features are opt-in |
| Where is memory stored? | A server you run; the source of truth is a git-backed wiki of plain .md files with a derived index |
| Team use? | Yes: one server, shared per-project knowledge, personal handoffs stay personal, with multi-user auth and an audit log |
| Latest release | v3.1.0, published October 16, 2026 |
| License | MIT, per the README |
What problem is it solving?
The README opens with the pitch: quit Claude Code mid-task, start OpenAI Codex in the same directory, and continue without re-explaining. It argues that each tool's built-in memory has the same limits: notes live on one machine, belong to one agent, and drop out of view when you switch tools or hand work to a teammate.
We have covered the built-in layer already. CLAUDE.md and MEMORY.md are per-tool, per-repo files. ai-memory sits underneath them as a shared store that follows you across agents, projects and machines.
How it works
The README describes a four-step loop: capture, consolidate, recall, handoff.
- Capture. Lifecycle hooks record prompts, tool calls and session boundaries, then sanitize them at a typed privacy boundary before anything is stored. You do not have to ask the agent to remember.
- Consolidate. At session end the server turns observations into readable markdown pages in the project's wiki. LLM writing is optional; the README says it is useful without.
- Recall. The next session gets a bounded brief and can search everything: full-text, entities, links and, optionally, vectors, fused into one ranking.
- Handoff. A handoff is a typed protocol with an owner, claimed exactly once, so a second agent does not repeat the first agent's work.
Two details stand out. The first is ai-memory run: start agents through it, and when you switch from Claude Code to Codex, Codex receives the shared workstream plus a private, temporary local projection of Claude's visible native history, for exact details the startup packet left out. The README says the remote server only receives harness and session identity, never the local transcript path or body.
The second is the storage choice. The source of truth is ordinary markdown in git; the database is a derived index that can be rebuilt. You can grep it, open it in Obsidian, or edit it by hand. That makes it inspectable in a way many memory layers are not.
Memory that ages
The README describes an aging system that avoids LLM calls by default:
- Decay on a schedule you can tune per tier, with memory you use decaying slower. Opening, searching or linking to a page counts as use.
- Cold episodic notes can be compacted down to durable facts such as file paths, error codes and decisions.
- Near-duplicates collapse, and likely contradictions are flagged.
- Nothing is hard-deleted: originals stay in git and a
restore-pagecommand brings them back. - Access-weighted retention is on by default because it can only keep memory longer; the parts that rewrite or drop content stay off until you turn them on.
With an LLM configured, an opt-in background pass the README calls "dreaming" rewrites clusters of cold notes into single coherent pages while you are idle. It never deletes a source, is off by default, and, according to the README, has to pass a recall eval before it could become default. This echoes ideas in Cognition's dreaming memory spec, though the implementations differ.
How it compares
The README includes a table of what carries over from other tools. Its framing: most memory tools optimize for one thing, such as per-turn fact extraction, a temporal knowledge graph, an agent-editable memory OS or a hosted API, while ai-memory is built around a git-backed markdown wiki with a derived index. The comparison covers Mem0 and LangMem, Zep and Graphiti, mcp-memory-service, basic-memory, Claude Code's built-in memory, Hindsight and OpenViking, and Supermemory.
This is the project's own comparison, so weigh it accordingly. For independent context, see our coverage of Hindsight, Supermemory's continual learning work, and the argument that agents need documentation rather than memory. The README also says the write ceiling of about 700 writes per second is measured, not guessed, and links a published benchmark; we have not reproduced either.
How to install it
Per the README, on Linux and macOS (no root):
curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup
The installer checks the release against a published SHA-256 checksum and refuses to install without a match. ai-memory setup creates a data directory with a bearer token in an owner-only file, starts a per-user service (systemd user unit or a launchd LaunchAgent), and wires MCP, hooks and Agent Skills for every agent it finds. It shows the plan first and asks. --plan prints it without changing anything. Afterward, restart your agents and ask one "What do you remember about this project?"
Other routes: Windows PowerShell with install.ps1, Arch AUR packages, a Fedora RPM, a macOS menu-bar app built from source, Docker, and Claude Code or Codex marketplace plugins. As with any curl | sh, read the script or follow the README's verification steps first.
What it records, and why you should check
Hooks capture prompts, tool calls and session boundaries. That is the feature, and it is also the risk surface.
- Secrets in prompts. The README says observations are sanitized at a privacy boundary before storage. Test that on your own patterns before trusting it with real credentials. The repo includes a
DATA_HANDLING.md; read it. - Docker defaults. The Docker quick start has no authentication because the container never runs
init. The server binds to loopback only, so nothing outside the machine can reach it, but local processes and browser pages can. Native installs that runinitget a bearer token. - Shared servers. On a team server, the cross-project profile is opt-in and private per person, and the README says multi-user auth, attribution and an audit log are built in. Decide who gets access to shared project knowledge.
- Capture controls. The Docker wrapper's hooks enforce client-side controls such as
ignore_pathsand allowlist mode before events reach the spool or network, according to the README. - Young project. Releases are frequent: v3.0.0 on October 14, v3.0.1 on October 15 and v3.1.0 on October 16. Expect change, and pin versions.
If agents act on your machines, an independent guard against dangerous actions is worth having alongside memory. AgentBeam, the agent security platform from the explainx.ai team, is built to stop AI agents before they take dangerous actions.
What the support matrix actually says
Not every agent gets the same depth of integration. The README's support matrix, which it says CI checks, marks Linux, macOS, NixOS and Windows via WSL2 as supported and native Windows as experimental. Among agents, Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Devin CLI, Kimi Code, Kiro CLI, GitHub Copilot CLI and Factory Droid are listed as supported, while others are narrower: Claude Desktop, VS Code Copilot, Zed and DeepSeek Harness are MCP-only (the agent can query memory but hooks do not capture automatically), CodeBuddy Code is hooks-only, and Crush is managed-only. That distinction matters for the central promise. A handoff is only as good as capture on the source side, so an MCP-only agent can read what others wrote but will not feed the wiki on its own.
It also helps to know what the hooks and MCP pieces are doing. MCP, the Model Context Protocol, lets an agent call tools such as search over the wiki; our MCP guide explains the protocol. Hooks run at lifecycle points such as session start and end, which is how capture happens without the agent deciding to save anything.
Should you use it?
It fits if you switch between Claude Code, Codex and others on the same repos, if you work across several machines, or if a team wants shared project knowledge without a hosted service. Skip it if you use a single agent in one repo, where CLAUDE.md or AGENTS.md may be enough, or if you cannot allow session recording on the machine.
A cautious trial: install it on a throwaway repository, run a session in one agent, open another agent and ask what it remembers, then inspect the markdown pages it wrote and what the hooks stored. Only then point it at real work.
Related reading
- What is CLAUDE.md? Persistent memory for Claude Code
- What is MEMORY.md? Long-term memory for AI agents
- Cognition's dreaming memory spec
- Hindsight agent memory system
- Supermemory Learner-1 and continual learning
- Agents don't need memory, they need documentation
Sources: akitaonrails/ai-memory README and releases.
Version details are accurate as of October 17, 2026.