<img alt="ai-memory" src="https://github.com/akitaonrails/ai-memory/raw/v1.8.0/docs/logo-light.png" width="480">

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.

Support Matrix

What it is

LLM coding agents lose all context when a session ends. ai-memory gives them a shared, persistent wiki: every prompt, tool call, and decision is captured automatically; when a session ends, the relevant pages get rewritten as a coherent narrative; when the next agent starts (Claude Code, Codex, OpenCode, …) it sees a handoff with "where you left off" already prepended.

The wiki is plain markdown in a git repo - grep-able, openable in Obsidian, backed up with rsync. No vector database to babysit, no write_note ceremony, no manual context-loading. The full design is in docs/ARCHITECTURE.md; the influences and priors are at the bottom.

Key features

• Zero-friction capture. Lifecycle hooks fire-and-forget every prompt + tool call + session boundary. You never type write_note.
• Cross-agent handoffs. Quit Claude Code mid-task, start Codex in the same directory hours later - the next agent sees a "where you left off" block before its first prompt.
• Per-project isolation by construction. Each project lives at <wiki_root>/<workspace_id>/<project_id>/… keyed by stable UUIDs. Workspace defaults to "default". Project is derived from $cwd: CLI subcommands (bootstrap, write-page, lint, …) walk to the main git repo root so all worktrees of the same repo share one project identity; the hook router defaults to basename($cwd) and can opt into the repo-root rule. Drop a .ai-memory.toml marker file in any ancestor directory to override either field explicitly — perfect for multi-client consultancies, work/personal split, mono-repos, or linked git worktrees. Same page path can exist in two projects without collision; a rename is one column update; a purge is one rm -rf.
• Karpathy-style LLM wiki. Pages are compiled from observations at session-end (or PreCompact; Codex can use ai-memory finalize-session for a manual final close), not retrieved over raw logs. Supersession chain + git-versioned markdown means you can time-travel with ai-memory checkpoints, restore-page, or raw git log.
• Built-in /web browser. Read-only HTML UI for the wiki - project list, folder tree, FTS5 search, markdown rendering, dark mode. Mounted on the same axum server as MCP.
• Multi-agent + multi-machine ready. Supported clients: Claude Code, Codex, OpenCode, Cursor, Claude Desktop (via mcp-remote), Gemini CLI, Antigravity CLI, Grok Build CLI, OpenClaw, Oh My Pi / OMP (omp / oh-my-pi), Pi via generated bridge extension, and VS Code GitHub Copilot agent mode (MCP-only, workspace .vscode/mcp.json). Server runs local (loopback) OR on a homelab box (LAN/VPN/cloud) with bearer-token auth. Shared servers can opt into [auto_scope] modes for per-user or session-aware current-project routing.
• Thin-client CLI. ai-memory status, bootstrap, checkpoints, restore-page, purge-project, rename-project, move-project, audit-contamination, lint, curator, auto-improve, auto-improve-report, pending-writes, embed, forget-sweep, backup are all HTTP clients of the running server - never touch SQLite or wiki files directly. status also reports passive LLM/embedding provider health from the last real provider call. Server is the single source of truth. finalize-session is the exception: it reads the local SQLite index only to find matching open sessions, then posts synthetic session-end hooks back to the server.
• LLM is opt-in. Zero-LLM mode still gives you FTS5 search + rule-based summarisation. Add a provider when you want consolidated pages, lint contradictions, or staged auto-improvement proposals.

Use cases

• "Quit at 4 PM, pick up at 9 AM in a different agent." The classic. SessionStart hook in the next supported hook client prepends a typed handoff with open questions, next steps, and a session summary. Grok captures lifecycle events but ignores SessionStart stdout, so ask it to call memory_handoff_accept when resuming from a handoff.
• "What did we decide about X six weeks ago?" Type memory_query X from the agent (or ai-memory search X from a terminal) - FTS5 over the wiki. Pages are LLM-consolidated, so the hit is a coherent decision page, not a raw chat log.
• "Remember this permanently." When something is worth keeping beyond auto-captured session logs - a decision, a convention, a gotcha - tell the agent "save a permanent note that we standardised on Postgres for X" or "annotate this as a project rule" and it calls memory_write_page to write a durable, git-versioned wiki page. From a terminal it's ai-memory write-page --path decisions/0007-db.md --body $'# Standardised on Postgres\n\n...' --pinned. --pinned exempts it from the decay sweep; the H1 on the first line of --body becomes the page title (omit --title — it's still accepted, but LLM callers trip over JSON-escaping their way through it, see issue #67). Unlike a handoff (single-use) or an auto-synthesised session page (rewritten on consolidation), a write-page note is yours: it shows up in memory_query, renders in /web, and stays until you change it.
• "This new project has months of history before ai-memory." cd /path/to/my-project && ai-memory bootstrap collects git log, README, docs/, module headers, project rules and one-shot-summarises them into seed wiki pages. Future sessions build on top.
• "What durable lesson did that session teach?" When an LLM provider is configured, ai-memory runs a background auto-improvement scheduler for newly completed sessions in every project. It records proposed wiki edits in the pending-writes audit trail, then approves them immediately through the normal wiki write path by default. Scheduler ticks are non-overlapping: if reviewing all projects takes longer than the interval, the next tick is delayed until the current one finishes. Scheduling and approval are separate: set [auto_improve.scheduler] enabled = false to stop automatic review, or set [auto_improve] require_approval = true to keep both scheduled and manual proposals pending for human review. ai-memory auto-improve --session-id <uuid> and MCP memory_auto_improve remain available for manual catch-up or targeted reruns. `ai-memory auto-improve-report --workspace --project

returns a read-only telemetry report for recent auto-improvement outcomes without staging or creating proposals; add--stageto create one pending report page for audit/approval. See [docs/auto-improve-eval-gates.md`](docs/auto-improve-eval-gates.md) for example executable eval scorers.

Existing installs do not need per-project migration. The scheduler initializes a per-project first-run watermark so historical sessions are not reviewed automatically on upgrade, then records per-session claims so failed scheduled reviews do not retry forever; use manual auto-improve for old sessions or failed scheduled sessions you want to catch up. Older configs may still contain an [auto_improve] mode = ... line; current ai-memory ignores that legacy key, so you can remove it when convenient. - "What housekeeping should I consider?" ai-memory curator runs a no-LLM, rule-based maintenance report over cold episodic pages, stale slots, duplicate exact normalized titles, and dangling cross-project links. It is report-only unless --stage is passed; staging queues one report page for approval and still performs no maintenance actions itself. - "Run one ai-memory for the whole household." Stand the server up on a homelab box at 0.0.0.0:49374 with a bearer token; every laptop/desktop talks to it. Per-cwd routing keeps each project's pages cleanly separated; the /web UI is reachable from a browser anywhere on the LAN. - "Audit what landed before sharing with a teammate." Browse the wiki at http://<server>:49374/web - HTTP Basic dialog if auth is on, paste the token as password. Per-project tree view, rendered markdown, supersession chain visible per page. - "Undo one bad page edit without rolling back the whole server." ai-memory checkpoints shows recent wiki commits, then ai-memory restore-page --path notes/foo.md --from <rev> restores that one markdown file and reindexes it into SQLite. Full backup / restore is still the answer for DB-only state such as sessions, observations, handoffs, users, audit rows, and embeddings. - "Drop an experiment, keep the rest." ai-memory purge-project --project experimental --confirm. Atomic: that project's DB rows cascade away, its wiki subdir gets rm -rf'd, every sibling project is untouched by construction.

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 + an agent CLI (Claude Code, Codex, OpenCode, OMP, Cursor, Antigravity CLI, Grok Build CLI, 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.

```bash

1. Install the ai-memory CLI wrapper (a ~3 KB shell script that

runs the binary inside docker with your $HOME mounted). This is

the only thing that needs to live on the host filesystem.

mkdir -p ~/.local/bin curl -