Solutions
Stop re-explaining your project
You quit one agent, open another, and it already knows the architecture, the approaches that failed and what is still open. It works the same from your PC and your notebook, and it needs no API key.
Switch agents in the middle of a task
Hit a rate limit in Claude Code at 4 PM. Open Codex in the same directory and keep going.
Typed
A handoff carries a session summary, the next steps and the open questions. The next agent gets it at session start, before you type anything.
Claimed exactly once
The first session that starts in that directory takes the baton. A second one asking for it gets nothing, so two agents never resume the same work.
Automatic, with a manual override
Every session end writes one. Say "save context for the next session" to write your own, and yours outranks the automatic one.
Two agents, Grok Build CLI and Zero, ignore what hooks print at session start. Ask them to accept the handoff and they fetch it over MCP. The integrations page lists every agent and what each one supports.
What you say day to day
Most days you say nothing. Hooks capture the session, and the session end turns it into wiki pages. When you do want something, plain English is the interface.
- “Where did we leave off?”
- Reads the pending handoff: summary, next steps, open questions.
- “Have we discussed X?”
- Searches the wiki with full text, entities, links and vectors fused into one ranking.
- “Catch me up. I have been away.”
- Builds a digest that gets longer the longer you were gone. It is prose with an LLM configured, structured data without one.
- “Remember this permanently.”
- Writes a durable, git-versioned page. Pin it and it never decays.
- “Remember this until Friday.”
- Writes the page with an expiry date. The forget sweep deletes it after that.
- “That page is out of date.”
- Records feedback that lowers the page in future rankings. Feedback never deletes anything.
The usage guide on GitHub has the full list of phrases and the MCP tool behind each one.
One launcher, and a way in for old projects
Start your agent with ai-memory run
- The first launch installs that agent’s hooks and MCP entry if they are missing. It does this once per agent.
- Switching agents resumes the same workstream, with the visible history on top of the summary handoff.
ai-memory continuefinds your most recent checkout from any directory and resumes there.- It covers 12 agents today. Launching an agent directly keeps working, and hooks alone already carry the handoff.
cd /path/to/project
ai-memory run claude
# Quit Claude Code, then continue the same workstream in Codex.
ai-memory run codex --yolo
# From any directory: put me back where I was.
ai-memory continue
Adopt a project you already have
The first session in an empty project imports your local agent history once, capped at the newest 25 sessions. You can also run it by hand.
# See what would be imported, then import it
ai-memory backfill --dry-run
ai-memory backfill
Opt out of the automatic first-run import with AI_MEMORY_BACKFILL_ON_START=false.
# Needs an LLM provider on the server
ai-memory bootstrap --dry-run
ai-memory bootstrap
Bootstrap reads the git log, the README, docs/ and your rule files. The project measured a run at well under $0.20 with Kimi 2.6 through OpenRouter. It can write pages that sound right and are wrong, so read the dry run first.
The same memory on your PC and your notebook
Run one small server and point every machine at it. A project is identified by its checkout name, so different paths on each machine land in the same memory.
- Put the server on a homelab box, or on whichever machine stays on. It is one binary or one container.
- When the notebook is offline, hook events go to a local spool and drain when the server is reachable again. Each entry has an idempotency key, so nothing is stored twice.
ai-memory statusshows how many events are pending and how old the oldest is.- A server that listens beyond loopback requires a bearer token. The token does not encrypt traffic, so add TLS before leaving your LAN.
# On the PC and on the notebook
export AI_MEMORY_SERVER_URL="http://<server-ip>:49374"
export AI_MEMORY_AUTH_TOKEN="$TOKEN"
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
No API key, and files you can read
The default install costs nothing to run and stores everything as markdown in a git repository.
Zero LLM calls
Capture, session summaries, handoffs and search all run without a model. Summaries are rule based until you add a provider.
Embeddings run in the binary
A small local model (all-MiniLM-L6-v2, about 87 MB) downloads once in the background. Vector search turns on at the next restart. It needs no key and no GPU.
Loopback only
The default server listens on 127.0.0.1:49374 with no account and no telemetry. Nothing else on the network can reach it.
Take the files anywhere
The SQLite index is derived from the files and can be rebuilt from them. Back up with ai-memory backup, rsync, or a git push to your own remote.
# Copy the wiki out of the container and open it in Obsidian
docker cp ai-memory:/data/wiki ./my-ai-memory-wiki
# Or read its history
git -C /data/wiki log --oneline
Or browse it in a read-only web UI
One flag adds a browser view with the project list, the page tree, rendered markdown, search and clickable wiki links. It cannot edit anything.
ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web
# then open http://127.0.0.1:49374/web
Do you need this?
Questions and answers
Do I need an API key or an LLM to use ai-memory?
No. Capture, session summaries, handoffs and search work with zero LLM calls. Embeddings for vector search run in-process with a local model. An LLM provider is optional and adds richer consolidation, bootstrap and reranking.
Do I have to use ai-memory from the first day of a project?
No. Add it at any point. The first session in a project with no memory yet imports the agent sessions already on your machine, from every supported agent, up to the newest 25. It runs once, in the background, with no LLM. ai-memory bootstrap can also build pages from the git log, the README and your docs, and that one needs an LLM.
Can I use the same memory on a PC and a notebook?
Yes. Run one ai-memory server on a homelab box or on one of the machines and point both at it. There is no replication between servers. If the notebook is offline, hook events spool locally and drain when the server is reachable again.
Is Claude Code’s built-in memory enough?
For one developer on one machine who only uses Claude Code, it may be. It stops being enough when you add a second agent, a second machine or a second person.
Where is my memory stored?
In a git-versioned folder of plain markdown files in the ai-memory data directory. SQLite holds a search index that can be rebuilt from the files.
Give your agents a memory today.
Free and open source. You need no account and no API key, and the files stay yours.