Your Next Coding Agent Shouldn't Start From Zero

The most expensive thing about switching coding agents isn't the subscription. It's the hour you spend explaining your project again.

Which files matter, which approach already failed, why the tests are structured that way, what the half-finished branch is doing. Claude Code doesn't know any of it. Neither does Codex, Cursor or Gemini CLI. Each one starts from an empty context window and a polite willingness to help.

ai-memory is a Rust binary that tries to fix that, and its design choices are more interesting than the feature list.

One memory, many harnesses

The pitch is that twenty-odd agent harnesses — Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro and the rest — read from one shared memory store. You work in one, stop mid-task, open another in the same directory, and it picks up where the first one left off.

The mechanism is a typed handoff. Not a summary the agent generates and hopes is accurate, but an explicit record with an owner that can only be claimed once. That last constraint is the useful bit: it means two agents can't both think they're continuing the work, and it means an abandoned handoff is visible rather than silently lost.

There's also a cross-project layer. Your working preferences — package manager, test layout, how you like modules organized — follow you into new repositories, so a fresh checkout doesn't start from zero on the things that are true everywhere.

Markdown as the source of truth

Here's the design decision worth arguing about.

Memory systems for agents usually mean embeddings. Chunk the history, embed it, store it in a vector database, retrieve by similarity. It works, and it has three problems: you can't read it, you can't diff it, and the retrieval is opaque enough that when it returns the wrong thing you have no idea why.

ai-memory inverts that. The truth source is a plain Markdown wiki, versioned with git. The SQLite index — full-text search, entities, embeddings — is derived and rebuildable. Delete the database and you lose nothing.

That single choice buys a lot. You can grep the wiki. You can open it in Obsidian. You can edit a wrong entry by hand. You can rsync it. You can read a diff and see that the agent's understanding of your architecture changed on Tuesday. And there's no vector store to get locked into.

It also means memory is auditable in a way that matters for teams. "Why does the agent think we use pnpm" is a question with a file as the answer.

Aging without deletion

The project describes a memory aging system: tier-based decay, access-weighted retention, deduplication, and contradiction flagging. Notes that aren't used fade in priority without disappearing, and conflicting entries get marked rather than silently overwritten.

The important detail is that nothing gets hard-deleted. Old pages stay in git, and a restore command brings them back. Given how often an agent's "stale" note turns out to be the only record of why a decision was made, this is the right default.

There's an optional feature called dreaming, which uses an LLM to rewrite clusters of cold notes during idle time. It's off by default, and the README is explicit that it never deletes source material. Default-off is the correct call for anything that rewrites your notes with a model.

Setup is genuinely short

Two commands on Linux or macOS: a curl-to-shell installer that verifies a SHA-256 checksum, then ai-memory setup, which creates the data directory, starts a user-level service and wires up whichever agents it detects. There's a PowerShell equivalent for Windows, plus AUR, RPM, Nix, Docker, and plugin marketplace entries for Claude Code and Codex.

Daily use is built around one wrapper: ai-memory run claude instead of claude. It installs the right hooks and MCP server on first run and scopes the session to the current project. From there, ai-memory continue resumes the latest managed checkout, and resume --search auth picks from your workflows by name.

There's a bootstrap command that imports existing project history in one pass, which is the difference between a tool you adopt and a tool you keep meaning to adopt.

The uncomfortable parts

Silent capture via lifecycle hooks means the system records prompts, tool calls and session boundaries as you work. That's the only way this can function — you're not going to manually journal — but it's worth being clear-eyed about. A record of every prompt you typed against a client codebase is sensitive material, and it's now in a directory that's git-versioned.

The mitigations are reasonable: it binds to loopback only by default, and setup generates a bearer token written to an owner-only file rather than into your agent config. But the Docker quickstart runs without authentication, which the README flags as local-use only. If you expose that port without a TLS reverse proxy, you've published your work history.

The team story is more mature than I expected for a project this young: a shared server, per-project sharing, private handoffs, multi-user auth, attribution and an audit log, all outside the paid tier. That's the feature set that decides whether this survives contact with a real engineering org.

If you don't want to run a server

Fair objection: "my own server" is a phrase that loses half its audience instantly.

It doesn't have to be a server. The setup command starts a user-level service on the same machine, bound to loopback, and that's the default path — no homelab, no VPS, no DNS. The cross-machine and team features only matter once you want them, and they're separable from the core loop.

There's also a menu bar app for macOS built from the repo, and a read-only web view if you'd rather browse your wiki in a browser than in an editor. The Docker route exists mostly for people who already think in containers.

So the honest adoption ladder is: install it on your laptop, let it capture one project, and see whether the wiki it produces is something you'd actually read. If it is, the rest follows. If the wiki is noise, no amount of team features will save it.

Why this matters more than it sounds

The agent market is currently organized around vendors, and vendors have no incentive to make it easy to leave. Your context is the lock-in. It's why switching costs feel higher than the subscription price suggests.

A tool that sits underneath all of them and holds the memory in a format you own is a small act of user-side standardization. Whether ai-memory is the one that wins is almost beside the point — the shape of the solution, portable plain text with a rebuildable index, is obviously right, and it's the shape that every proprietary memory feature will eventually have to compete with.

Also, it's a single binary with no API key required for the core loop. That's a rare thing in a category where "memory" usually means "another subscription".