A central decision in ai-memory is where it keeps the truth. Its source of truth is a git-backed wiki of ordinary .md files, and the database is a derived index you can rebuild from those files.
The walls around built-in memory
The README starts from a familiar complaint. Claude Code takes its own notes, Cursor remembers some things, and every platform keeps adding more. The problem is that those notes live on one machine, belong to one agent, and vanish from view when you switch tools or teammates.
ai-memory's answer is a server you run yourself, on your laptop, a homelab box, or a LAN host, which twenty-plus harnesses write into. The support matrix lists Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Kimi Code, Kiro CLI and a long tail of others. Some get both hooks and MCP registration, while others are marked MCP-only or hooks-only. The headline scenario is concrete. Quit Claude Code mid-task, open Codex in the same directory, and continue without re-explaining the architecture or the approaches that already failed.
Files first, index second
Because memory is plain markdown, it remains accessible through ordinary file tools. You can grep it, open it in Obsidian, edit a page by hand, or rsync it to another machine. The README states that the database is derived and "can always be rebuilt from the files," and that there is no vector store to babysit.
A four-stage loop feeds that wiki: capture, consolidate, recall, handoff. Lifecycle hooks record prompts, tool calls, and session boundaries while you work. Those observations are sanitized at what the README calls a typed privacy boundary before anything is stored. At session end they become readable pages in the project's wiki. An LLM can write those pages, but the project says they are useful without one.
Recall is where the index earns its keep. The next session, from any agent on any machine, gets a bounded brief and can search full-text, entities, links, and optionally vectors, fused into one ranking.
Zero LLM calls on the default path
That "optionally" matters. On the default path, capture, search, and handoffs all work with no API key at all. The Docker quick start spells it out: omit the LLM and embedding environment variables and FTS5 search still works. The example command shows where the keys go if you want them, with Anthropic as the LLM provider and OpenAI for embeddings, but the core loop does not depend on either.
Without LLM or embedding providers, the notes remain markdown files and FTS5 search still works.
Handoffs as a protocol
The piece I would test first is the handoff. The README describes handoffs as "a protocol here, not a convention," typed, owned, and claimed exactly once. Day to day, you ask the next agent "where did we leave off?" and it continues from the pending handoff. Asking "have we discussed X?" queries the wiki, and "catch me up" returns a prose digest of recent project activity.
For a project with months of existing history, you run ai-memory bootstrap once when adopting it. There is also an opt-in managed workstream mode that layers session continuity on top of shared memory: start a workstream with ai-memory run claude, pick it up later with ai-memory run codex --yolo, or resume the newest managed checkout with ai-memory continue.
Running it for more than one person
Point a team at one server and knowledge is shared per project, while personal handoffs stay personal. Multi-user auth, per-person attribution, and an audit log of every mutation are built in, and the README makes a point of saying they are not a paid tier. Since v1.39, the "current project" pointer is isolated per caller by default, so two agents in the same project at once, or teammates on one server, don't trample each other.
The README also gives specific operational details. The write ceiling is measured at around 700 per second rather than guessed. Purge commands state exactly what "deleted" means. The uninstall command removes only what ai-memory installed, and install commands are idempotent and write timestamped backups next to any file they touch. The deploy guidance carries one firm rule: one server per data directory, never two.
A few practical caveats before you install. Linux, macOS, and Windows via WSL2 are supported, while native Windows is listed as experimental. Arch users get AUR packages, and the Docker image ships linux/amd64 and linux/arm64 variants. The default Docker quick start has no authentication and binds to loopback only, which means nothing outside that machine can reach it, so add a bearer token before you expose the server on your LAN.
GitHub: https://github.com/akitaonrails/ai-memory
Curated by Agent Palisade — practical AI for small and mid-sized businesses.
Top comments (0)