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.
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.
Area
Status
Linux
Supported
macOS
Supported
Windows via WSL2
Supported
Native Windows
Experimental
Claude Code
Supported
Codex
Supported
Command Code
Supported
Devin CLI
Supported
OpenCode
Supported
OpenCode 2 (opencode2 beta)
Supported
Cursor
Supported
Gemini CLI
Supported
Oh My Pi / OMP
Supported
Pi
Supported
Crush
Managed-only
Managed workstreams
Opt-in
Claude Desktop
MCP-only
OpenClaw
Supported
Antigravity CLI
Supported
Grok Build CLI
Supported
Swival CLI
MCP-only
Zero
Supported
ZCode
Supported
Kimi Code
Supported
Kiro CLI
Supported
Pool
Hooks-only
VS Code Copilot
MCP-only
Zed
MCP-only
Hermes Agent
Community
LLM/auth providers
Supported
Embedding providers
Supported
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
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.
# 1. Install the ai-memory CLI wrapper (a small shell script that
# runs the binary inside a container with your $HOME mounted). This is
# the only thing that needs to live on the host filesystem.
mkdir -p ~/.local/bin
wrapper_tmp="$(mktemp -d)"
trap 'rm -rf "$wrapper_tmp"' EXIT
wrapper_base=https://github.com/akitaonrails/ai-memory/releases/latest/download/ai-memory-wrapper
curl -fsSL "$wrapper_base" -o "$wrapper_tmp/ai-memory-wrapper"
curl -fsSL "$wrapper_base.sha256" -o "$wrapper_tmp/ai-memory-wrapper.sha256"
expected="$(awk 'NR == 1 { print $1 }' "$wrapper_tmp/ai-memory-wrapper.sha256")"
if command -v sha256sum >/dev/null 2>&1; then
actual="$(sha256sum "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
else
actual="$(shasum -a 256 "$wrapper_tmp/ai-memory-wrapper" | awk '{ print $1 }')"
fi
[ -n "$expected" ] && [ "$actual" = "$expected" ] || { echo "wrapper checksum mismatch" >&2; exit 1; }
install -m 0755 "$wrapper_tmp/ai-memory-wrapper" ~/.local/bin/ai-memory
rm -rf "$wrapper_tmp"
trap - EXIT
# Most distros put ~/.local/bin on PATH automatically. If `which
# ai-memory` comes up empty, add this to ~/.bashrc / ~/.zshrc:
# export PATH="$HOME/.local/bin:$PATH"
# 2. Start the server. `--restart unless-stopped` makes it come back
# on docker daemon restart and on machine boot (provided your
# docker service is enabled at boot — `sudo systemctl enable
# docker` on most distros). Loopback-only bind (`127.0.0.1:49374`)
# so nothing outside this machine can reach it. Omit the LLM /
# EMBEDDING lines for zero-LLM mode — FTS5 search still works
# without any keys.
docker run -d --name ai-memory \
--restart unless-stopped \
-p 127.0.0.1:49374:49374 \
-v ai-memory-data:/data \
-e AI_MEMORY_LLM_PROVIDER=anthropic \
-e ANTHROPIC_API_KEY=sk-ant-... \
-e AI_MEMORY_EMBEDDING_PROVIDER=openai \
-e OPENAI_API_KEY=sk-... \
docker.io/akitaonrails/ai-memory:latest
# 3. Wire your agent CLI in two commands. The wrapper takes care of
# mounts and each client's config-path detection. Re-run with
# `--agent codex`, `--agent command-code`, `--agent devin`, `--agent opencode`, `--agent opencode2`, `--agent gemini-cli`,
# `--agent grok`, `--agent kimi-code`, `--agent kiro-cli`, `--agent omp`,
# `--agent oh-my-pi`, `--client cursor`,
# `--client gemini-cli`, `--client grok`, `--client kiro-cli`, etc.
# for additional agents; full list in docs/install.md.
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
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.
Managed workstreams are optional and add cross-harness session continuity
on top of shared memory:
ai-memory run claude
ai-memory run codex --yolo # later: same workstream, different harness
ai-memory continue # resume the newest managed checkout
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.
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.
Optional. Everything works with zero LLM calls; adding a provider
upgrades session summaries and enables semantic search. Anthropic,
OpenAI (incl. OAuth/Codex), 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.
Installation cookbook. Every agent CLI, every alternative (curl, source build, no-docker, no-auth), and the server-on-a-different-machine (homelab/LAN) walkthrough. Read after the Quick start if your setup doesn't match the happy path.
Windows install modes: full WSL2, native Windows with Docker Desktop, prebuilt native release zip, native source builds, and current hook/MCP harness caveats.
HTTPS via a reverse proxy. When you need TLS (multi-user, non-loopback) and when you don't (loopback / stdio). Copy-paste docker compose templates for Caddy + Let's Encrypt, Caddy + internal CA (LAN-only), Cloudflare Tunnel (no open ports), and external cert files; plus native-Caddy + nginx recipes. The "thinking you're secure when you're not" failure modes explicitly called out.
Read before running purge / rename / backup / restore / reset / reindex / restore-page. Safety matrix for state-touching commands, per-project disk layout (how isolation actually works), checkpoint-based page recovery, and operator workflows for "fresh start", "snapshot before risky op", "drop one project", and rebuilding SQLite from wiki files.
Boundary and implementation plan for optional companion projects, including the standalone importer at companions/ai-memory-importer, without widening core ai-memory.
一个面向 AI 编程 agent 的长期记忆服务。你在任务中途退出 Claude Code,在同一目录里启动 Codex 或 Cursor,下一个 agent 就能接上交接:你做到哪了、哪里失败了、还有什么没做完。