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.

Website: aimemory.sh

Why ai-memory

Your coding agent probably has a memory feature already. Claude Code takes its own notes, Cursor remembers some things, and every platform is adding more. They all have the same limits: the notes live on one machine, belong to one agent, and drop out of view when you switch tools or hand the work to a teammate.

ai-memory removes those limits.

• It follows you across agents. More than twenty harnesses (Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro, and others) feed one shared memory. Quit Claude Code mid-task, open Codex in the same directory, and the next agent picks up a handoff that says where you left off, what failed, and what is still open. Handoffs are a typed protocol: each one has an owner and is claimed exactly once.

• It follows you across projects. A small profile of how you usually work (your package manager, test layout, architecture habits) reaches every new repository at session start, so you stop re-explaining yourself. It sits below each repository's rules file as a default. It is on by default for a single user, and on a shared server it is opt-in and private per person. See docs/cross-project-profile.md.

• It follows you across machines. Memory lives in a server you run, on the same laptop, a homelab box, or anywhere else, so the project you left on the desktop is the project you resume on the laptop, with the same knowledge and the 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 and are 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. There is no vector store to maintain and no content locked in a binary blob.

• It captures the work itself, silently. Lifecycle hooks record what happened (prompts, tool calls, session boundaries), sanitize it at a typed privacy boundary before anything is stored, and the server consolidates it into readable pages. You do not have to ask it to remember anything. The default path uses zero LLM calls: capture, search, and handoffs all work with no API key.

• It ages memory without an LLM. Memory decays on a schedule you can tune per tier, and memory you use decays slower: opening a page, searching it, or reaching it through a link counts as use. When episodic notes go cold they can be compacted down to their durable facts (file paths, error codes, decisions) instead of dropped. Near-duplicates collapse into one, and likely contradictions get flagged, all with zero API calls. Nothing is hard-deleted: the original stays in git and the version chain (restore-page brings it back). Access-weighted retention is always on because it can only keep memory longer. The parts that rewrite or drop content (compaction, dedup, per-tier curves) stay off by default until you turn them on.

• It can also "dream", if you let it. With an LLM configured, an opt-in background pass rewrites whole clusters of cold notes into single coherent pages while you are idle, and cancels as soon as you come back to work. It never deletes a source (the pre-merge versions stay reachable), it is off by default, and it has to pass a recall eval before it could become default behavior. Unless you ask for more, the zero-LLM path above is what runs.

• It is honest about itself. It ships as one self-contained binary. Purge commands say exactly what "deleted" means. The write ceiling (~700/s) is measured, not guessed. An audit log records every mutation.

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, in any agent on any machine, gets a bounded brief and can search everything: full-text, entities, links, and (optionally) vectors, fused into one ranking. Cross-agent handoffs pass 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) checked by CI. The full matrix with per-agent notes and caveats is in docs/support-matrix.md.

Area	Status
Linux	Supported
NixOS module	Supported
macOS	Supported
Windows via WSL2	Supported
Native Windows	Experimental
Claude Code	Supported
Codex	Supported
Command Code	Supported
Devin CLI	Supported
OpenCode (V1/V2 auto-detected)	Supported
OpenCode V2 compatibility aliases (opencode2, opencode-v2, open-code2)	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
GitHub Copilot CLI	Supported
Factory Droid	Supported
Meta Muse Code	Supported
VS Code Copilot	MCP-only
Zed	MCP-only
DeepSeek Harness (DSH)	MCP-only
Prime Agent	MCP-only
Hermes Agent	Supported
GrizzyBot	Supported
LLM/auth providers	Supported
Embedding providers	Supported

Coming from another tool?

Most agent-memory tools optimize for one thing: extracting atomic facts per turn, a temporal knowledge graph, an agent-editable memory OS, or a hosted context API. ai-memory is built around a git-backed markdown wiki as the source of truth, with a derived index for retrieval. It captures automatically from lifecycle hooks, is shared across agents, machines, and people, and works with zero LLM calls by default. This table shows what carries over from each tool and what you gain:

Coming from…	What's similar	What you gain
Mem0 / fact extractors (LangMem)	Automatic per-turn capture	Memory compiles into readable pages you own and edit, not opaque fact rows; retrieval fuses FTS + entity + graph (+ local vectors) with no cloud API key
Zep / Graphiti (temporal KG)	Temporal reasoning, typed relations	Bi-temporal-lite (as_of, version-filtered search) and typed edges without standing up a graph database, in one binary
mcp-memory-service (fact rows, SQLite)	SQLite + local embeddings, hook capture, typed edges, honest numbers, and, on 2.4, per-tier decay curves, extractive compression, DBSCAN cold-cluster dedup, access reinforcement, and contradiction flagging	Human-editable markdown pages instead of fact-rows, cross-agent claim-once handoffs, and the same aging machinery done zero-LLM by default, reversibly (supersede-not-delete + restore-page), and off by default
basic-memory (file-first markdown)	Markdown-on-disk as the source of truth	Automatic lifecycle capture and a derived FTS/entity/graph index on top, cross-agent handoffs, and multi-user sharing built in
Claude Code built-in memory	"Remember my project" convenience, zero setup	Synced across machines and agents, searchable, team-capable, and captures tool lifecycle, unlike a per-laptop MEMORY.md
Hindsight / OpenViking (LLM or VLM in the loop)	Living pages / document memory with a background consolidation loop, plus, on 2.4, belief-strength confidence plus an opt-in LLM "dream" rewrite of cold clusters	A self-contained binary that runs zero-LLM by default and keeps memory in markdown files that are the source of truth, not a mirror; claim-once handoffs; the dream/belief features are opt-in, off by default, and never delete a source (vs a mandatory LLM loop)
Supermemory / LiquidLM (hosted memory API)	A managed second brain with automatic ingestion	Git-versioned markdown you own, no required API spend, offline operation, and per-project team sharing; ai-memory remembers this repo, not a general vault

Across all of these, ai-memory gives you files you own (git-backed markdown), a zero-LLM default, one self-contained binary, sharing across agents, machines, and teams, automatic lifecycle capture, and typed, claim-once handoffs. Opt-in features (LLM consolidation, vector search, the "dream" consolidation pass, belief-strength in ranking) stay opt-in, and the zero-LLM aging path (per-tier decay, extractive compaction, dedup, contradiction flagging, access-weighted retention) works with no API key at all.

Built on the shoulders of: the Karpathy LLM Wiki (compile-not-retrieve), agentmemory (hook capture for coding agents), basic-memory (markdown-on-disk truth), cognee (pipeline composition and triplet embeddings), Hermes Agent (the self-improvement loop), and A-MEM (Zettelkasten-style atomic notes).

The full comparison, covering where each approach wins, where ai-memory differs, and the published benchmark, is in How ai-memory compares.

Quick start

Linux and macOS (two commands, no root)

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup

install.sh downloads the release for your OS and CPU, checks it against the release's published SHA-256 checksum (it refuses to install without a match), and links ~/.local/bin/ai-memory. ai-memory setup then creates the data directory with a bearer token in an owner-only file, starts a per-user service (systemd --user or a launchd LaunchAgent), and wires MCP, hooks and Agent Skills for every agent it finds, or the ones you name with --agent. It shows the plan and asks first; --yes skips the question, and running it again changes nothing. Restart your agents afterwards. Details, the environment variables and how to verify the script before running it are in docs/install.md. An AI agent installing ai-memory for you can follow INSTALL_FOR_AGENTS.md.