ai-memory

Long-term memory for AI coding agents. Quit Claude Code mid-task, start OpenAI Codex in the same directory, continue without re-explaining the architecture, the failed approaches, or the open questions.

Why ai-memory

Your coding agent already has a memory feature. Claude Code takes its own notes, Cursor remembers some things, and every platform is adding more. All of them share the same walls: the notes live on one machine, belong to one agent, and vanish from view the moment you switch tools — or teammates.

ai-memory is what's on the other side of those walls.

• It follows you across agents. Twenty-plus harnesses — Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, and more — feed one shared memory. Quit Claude Code mid-task, open Codex in the same directory, and the next agent picks up a real handoff: where you left off, what failed, what's still open. Handoffs are a protocol here, not a convention — typed, owned, claimed exactly once.

• It follows you across machines. Memory lives in a server you run — on the same laptop, a homelab box, or wherever — so the project you left on the desktop is the project you resume on the laptop. Same knowledge, same open questions.

• It works for a team. Point everyone at one server and what one person's sessions learn, everyone's agents can retrieve. Knowledge is shared per project; personal handoffs stay personal. Multi-user auth, per-person attribution, and an audit log are built in — not a paid tier.

• Your memory is plain markdown. The source of truth is a git-backed wiki of ordinary .md files: grep it, open it in Obsidian, edit it by hand, rsync it. The database is a derived index that can always be rebuilt from the files. No vector store to babysit, nothing held hostage in a binary blob.

• It captures the work itself, silently. Lifecycle hooks record what actually happened — prompts, tool calls, session boundaries — sanitized at a typed privacy boundary before anything is stored, then consolidated into readable pages. No "remember this" ceremony. And the default path uses zero LLM calls: capture, search, and handoffs all work with no API key at all.

• It tells you the truth about itself. One self-contained binary. Purge commands that say exactly what "deleted" means. A measured write ceiling (~700/s) instead of a guessed one. An audit log of every mutation. Boring, in the way infrastructure should be.

Coming from Mem0, Zep, mcp-memory-service, Hindsight, OpenViking, or Claude Code's built-in memory? How ai-memory compares is a fair, specific rundown — where each approach wins, where ai-memory differs, the published benchmark, and how the field has independently validated the file-first, pages-over-facts bet.

How it works

capture ──▶ consolidate ──▶ recall ──▶ handoff
 hooks        session-end      search     next agent,
 observe      summaries as     + brief    any harness
 silently     wiki pages       injection

Agents emit sanitized observations through lifecycle hooks as you work. At session end, observations become coherent markdown pages in the project's wiki (optionally LLM-written; useful even without). The next session — any agent, any machine — gets a bounded brief and can search everything: full-text, entities, links, and (optionally) vectors, fused into one ranking. Cross-agent handoffs carry the baton explicitly.

The full design, including the invariants that keep multi-user and multi-session use safe, is in docs/ARCHITECTURE.md.

Support matrix

Every row below is a first-party integration — MCP registration, lifecycle hooks, or both — kept honest by CI. The full matrix with per-agent notes and caveats is in docs/support-matrix.md.

Quick start

Arch Linux (AUR)

For native Arch installs, use the AUR packages. They install /usr/bin/ai-memory, packaged hook sources, and both system-level and user-level systemd units.

yay -S ai-memory-bin    # prebuilt Linux x86_64/aarch64 binary
yay -S ai-memory        # builds from source

Single-user workstation:

mkdir -p ~/.config/ai-memory ~/.local/share/ai-memory
ai-memory --data-dir ~/.local/share/ai-memory \
  --config ~/.config/ai-memory/config.toml init
systemctl --user enable --now ai-memory.service
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply

System service installs use /var/lib/ai-memory and /etc/ai-memory/ via the packaged unit. Full user-service, system-service, auth, and provider setup is in docs/install.md#arch-linux-native-packages-aur.

Docker

You need: Docker or Podman + an agent CLI from the Support Matrix, or anything else that speaks MCP.

The published Docker image includes linux/amd64 and linux/arm64 variants, so Apple Silicon Macs and ARM64 Linux hosts can pull akitaonrails/ai-memory without --platform linux/amd64 emulation.

The default quick-start has no authentication - the server binds to loopback only, so on a single-user laptop nothing else can reach it. Adding a bearer token is a one-line change once you're ready to expose the server on the LAN; see Security below.

…

The examples use docker; replace it with podman on a Podman host. The wrapper automatically uses Podman when Docker is not installed. Set AI_MEMORY_DOCKER=podman to force Podman when both engines are available.

On Linux/macOS, that's it. Start a Claude Code session as usual - every prompt and tool call now lands in ai-memory, and the next session you open in this project will see a handoff with where you left off. On macOS, the native release binary is also supported and recommended when you do not need Docker; see docs/macos.md.

Wiring another agent is the same two commands with a different name — --client codex, --agent codex, and so on for every row of the support matrix. The full per-agent guide, including Windows and remote servers, is docs/install.md.

Two agents in the same project at once, or teammates on one server? That works out of the box: the "current project" pointer is isolated per caller by default (v1.39+). See docs/auto-scope.md for the optional session-aware Claude Code bridge and the details.

If in doubt, start your harness with ai-memory run. It is the preferred way to launch: the first time it runs a harness it auto-installs that harness's ai-memory hooks + MCP if they are missing (so capture and recall just work — no separate install-hooks/install-mcp step to forget), it wires the right project scope by construction, and it adds cross-harness session continuity on top of shared memory. Everything is idempotent and one-time per harness.

ai-memory run claude
ai-memory run codex --yolo   # later: same workstream, different harness
ai-memory continue           # resume the newest managed checkout

Auto-wiring is on by default; opt out with ai-memory run --no-autowire or AI_MEMORY_RUN_AUTOWIRE=false. You can still wire agents by hand with install-hooks / install-mcp (e.g. for a harness you never launch through ai-memory run).

ai-memory uninstall --apply removes everything ai-memory installed, and only what it installed. Install commands are idempotent and write timestamped backups next to any file they touch.

Everyday use

Day to day, you mostly do not think about ai-memory. Hooks capture prompts, tool calls, and session boundaries; session end turns them into readable wiki pages; the next session starts with a handoff.

• Ask "where did we leave off?" to continue from the pending handoff.
• Ask "have we discussed X?" or "search memory for Y" to query the wiki.
• Ask "catch me up" for a prose digest of recent project activity.
• Run ai-memory bootstrap once when adopting an existing project with months of history.
• Start the server with --enable-web for a read-only browser view of the wiki and a JSON API under /api/v1.

The full tour — search modes, entities, feedback, briefings, the web API — is in docs/usage.md and docs/use-cases.md.

Teams and multiple machines

Run the server somewhere reachable — a homelab box, a LAN host — and point every machine and every teammate at it. Knowledge is shared per project; personal handoffs stay personal; every write is attributed and audited. Multi-user auth (passwords, API credentials) is built in.

Start with docs/users.md for accounts and ownership, and docs/deploy.md for the server itself — including capacity numbers measured rather than guessed, and the one rule that matters: one server per data directory, never two.

Security

The quick-start default is loopback-only with no auth — nothing outside your machine can reach it. From there, hardening is incremental: a bearer token for the LAN, per-user accounts, OIDC device auth for hooks, TLS via a reverse proxy. Capture is sanitized at a typed privacy boundary before anything is stored, and per-repository [capture] rules can exclude paths or invert to allowlist mode.

The full model is in docs/security.md, docs/users.md, and docs/https-via-proxy.md.

LLM providers

Optional. Everything works with zero LLM calls; adding a provider upgrades session summaries and enables semantic search. Anthropic, OpenAI (including OAuth), Codex CLI credential reuse, GitHub Copilot, Gemini, OpenCode (Go and Zen), and any OpenAI-compatible endpoint (Ollama, LM Studio, vLLM) are supported for consolidation; OpenAI, Voyage, Gemini, and keyless OpenAI-compatible endpoints for embeddings. Configuration lives in docs/llm-providers.md.

Architecture

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 managed-workstream transcript segments
├── db/      # SQLite indexes, including FTS5, entities, and embeddings
├── models/  # reserved for local embedding models
└── logs/    # rolling tracing output

Hooks POST observations to the server. The server serializes writes through one SQLite writer, compiles session observations into markdown pages, and serves retrieval through FTS5, entity-match and graph-neighbor RRF, optional vector RRF, bounded source-authority adjustment, and bounded raw-observation fallback for non-global searches.

See docs/ARCHITECTURE.md for the data-flow diagram, crate breakdown, schema notes, and invariants.

Docs