What ai-memory promises when you switch agents
Yes — the README promise answers this review’s question word for word: “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.” That sentence sits under the tagline “Long-term memory for AI coding agents” in the ai-memory repository, which also links the project site.
The tool comes from Fabio Akita, is written in Rust, and ships as a single binary — one executable file you download and run, with nothing else to install — under the MIT licence. The latest release is v3.3.3, dated 2026-11-03. More than twenty coding-agent harnesses — harness meaning the agent CLI itself, such as Claude Code or Codex — feed one shared memory, and the README frames the mechanics precisely: handoffs, packaged summaries one agent leaves behind for the next, are “a typed protocol: each one has an owner and is claimed exactly once.”
This review is based on official documentation, pricing pages, and community reports — we did not run the tool hands-on. Community numbers are point-in-time: the repository showed 15,078 stars, 1,090 forks and 23 open issues when checked on 2026-11-04.
What actually crosses the boundary: four fields, nothing else
Four fields. The struct HandoffContent — struct being Rust’s word for a data structure that groups named values — defined in handoff.rs contains exactly summary, open_questions, next_steps and files_touched, and every other field on a handoff is metadata about ownership, origin or acceptance rather than content.
struct HandoffContent {
summary: String,
open_questions: Vec<String>,
next_steps: Vec<String>,
files_touched: Vec<String>,
}
“Typed” means the fields have fixed names and shapes, so whatever consumes a handoff always knows what it is reading. Each Vec is simply a list of strings: the three list fields carry bullet-sized items while summary holds one string of prose. What never crosses: no diffs — the differences between file versions — no file contents, no verbatim tool output, and no model reasoning. Those four fields are the whole handoff. The remaining fields sort into identity (workspace_id, project_id, owner_user), origin (from_session_id, from_agent, to_agent, cwd, the directory the session ran in) and lifecycle (state, created_at, plus the accepted_by family recording who claimed the handoff).
What your next agent actually sees
The Summary bullet comes last. A hook — a small script the agent runs automatically at fixed moments, such as session start — injects a block that opens with ”> 📥 ai-memory: pending handoff from previous session”, names the source agent and timestamp, shows a security line, then lists Open questions, Next steps and Files touched before the summary.
> 📥 ai-memory: pending handoff from previous session
<source agent and timestamp>
Security boundary: <untrusted-memory notice>
<untrusted-history start marker>
- Open questions: <heuristic-derived bullets>
- Next steps: <planned actions>
- Files touched: <paths the session touched>
- Summary: <prose paragraph, deliberately last>
The order is deliberate. A code comment in router.rs recalls that the older shape “put a paragraph-long ## Summary first, which made the hook output look like a wall of text in Codex’s completed block AND let the agent miss that this is the answer to ‘where did we leave off’ questions.” Short, actionable bullets first; narrative last; an agent hunting for “where did we leave off” finds it flagged, not buried.
One literal string outranks the rest: [handoff detail omitted to fit this harness's startup limit]. If it appears, the brief was clipped and part of the handoff never reached your agent. The block also carries a “Security boundary” line with an untrusted-memory notice, a reminder that this text came from another session rather than a trusted system prompt. Claude Code’s side of the machinery is documented in its hooks documentation and in our Claude Code review; for how hooks are engineered elsewhere, Niteagent covers agent development in depth.
Where continuity silently breaks: five seams
Five seams are documented in the support matrix and the code, and none produces an error message. They span missing session-end events — session end is the signal that an agent has finished its whole job, not just one reply — plus opt-in capture, fire-and-forget saves, a byte budget, and harnesses that cannot auto-inject.
Seam 1 — no session end, no handoff. Codex wires a SessionEnd event only from CLI version 0.145.0; on older builds you must run the manual command ai-memory finalize-session --agent codex. Claude Code’s Stop event marks the end of one reply, never the end of the job. Kiro CLI, Pool, Zero, Grok Build CLI, DeepSeek Harness, Cline CLI, Kimi Code and Hermes Agent lack a true end as well: Kimi Code discards the startup injection’s output, and on Hermes Agent the session-end hook fires every turn while an idle-expired gateway session is never finalized. Hermes Tutorials walks through that hook model, and our Hermes Agent review covers the agent itself.
Seam 2 — assistant capture is double opt-in. Recording the assistant’s own final prose requires both a --capture-assistant flag and a server-side capture_assistant setting, both off by default, so the default memory is built from prompts and tool calls only. Both switches appear in the usage docs.
Seam 3 — saving is fire-and-forget, meaning saves never block or retry. The code states it plainly: “Hook scripts hard-timeout at ≤200 ms; server returns 202 immediately or 429 when saturated.” A save that would slow your session is abandoned; a saturated server rejects it rather than queueing it. Reads do wait, but only within a 1-second shell or 3-second native timeout — miss it, and your agent starts with no handoff at all.
Seam 4 — the startup brief has a byte budget. 4,000 bytes by default, clamped between 1,500 and 20,000, at most 24 core pages plus 10 recent titles. Overflow is what summons the omission marker, and the tiered-brief design doc treats the brief as a budget problem rather than a dump.
Seam 5 — some harnesses cannot auto-inject. Kiro, Pool, Zero, Grok Build CLI, DeepSeek Harness and Cline CLI accept a handoff only through MCP — the Model Context Protocol, a standard way for an agent to call tools a server exposes — by running memory_handoff_list and then memory_handoff_accept by hand.
What fits in the budget. Since v3.1, content is tiered: L0, an abstract, is clipped to 256 bytes; L1, a summary, to 500 bytes, per excerpt.rs; full bodies survive only while budget remains. ARCHITECTURE.md records what this replaced: a packer that gave full bodies to the first pages and then omitted an entire suffix of standing-rule pages, silently dropping the rules rather than the trivia.
Where everything lives. The markdown wiki is the git-backed source of truth; SQLite, a single-file database, is a derived index built on FTS5, its built-in full-text search module (FTS5 docs), plus an entity graph and optional vectors. Running ai-memory run <harness> carries a private temporary local projection of the previous harness’s visible native history, and DATA_HANDLING.md states the remote server receives only the harness and session identity — never the local transcript path or body.
Two fields beginners misread
open_questions is a heuristic — a rule-of-thumb guess derived from how your session ended, not a window into the model’s real uncertainty. files_touched is the second trap: it lists files the session touched, and because reads and writes are indistinguishable, a session that only browsed looks identical to one that edited.
The decision list inside router.rs’s derive_open_questions routine, first match wins:
- The last prompt ends with ”?” → “Unresolved question: …” — your own sentence, re-quoted.
- The last tool was a file-family tool with no Stop after → “Session ended without a normal stop while working with files”, plus “Check the working tree for uncommitted or unverified changes”; the working tree is the current state of your files on disk.
- Stop fired but no SessionEnd → a mid-task exit; the last substantive prompt is reused.
- A normal end → “Continue from: …”.
- No prompts at all → an empty field.
So the “open questions” you see may be your own last sentence, a canned warning, or a continue-marker — never a measured confidence score.
A code comment is equally blunt about files_touched: read and write are indistinguishable in the file tool family, whose outcomes are only success, error or unknown, so “this cannot honestly claim changes were made — only that the session touched files.”
The same restraint applies to the “Last failed tool call” line. Claude Code fires a PostToolUseFailure event — its signal that a tool call errored — and ai-memory records that outcome with bounded error text. The line means one tool call failed and its message was captured; it is a clue, not a verdict that the session broke.
Your 60-second checklist after any handoff
Six steps take about a minute, and step one is non-negotiable: read the entire injected block before acting on anything in it, because every later step only matters if you saw what actually arrived. The other five catch truncation, uncommitted work, and the manual-finalize traps.
- Read the whole injected block, including the fence — the delimiting lines around the block — and the security line; do not skim past the untrusted-memory notice.
- If
[handoff detail omitted to fit this harness's startup limit]appears, treat the handoff as partial and fill the gaps yourself. - Run
git statusandgit diffto see the real state of your files; CodeIntell collects working-tree and code-quality habits worth borrowing. - Never treat
files_touchedas a change list — it is a touch list, as the code comment above states. - On harnesses that need it — older Codex builds and the Seam 1 list — run
finalize-sessionbefore switching agents. - Remember that a plain harness launch carries no projected local history; only
ai-memory run <harness>projects the previous harness’s native history.
Setup details, including the marker-file convention, live in the usage docs and the marker-file page.
ai-memory vs alternatives: which should you pick?
Yes, pick ai-memory if you genuinely alternate between Claude Code and a Codex CLI at 0.145.0 or newer in the same repository; no, skip it if you live inside a single agent or run one of the no-session-end harnesses and refuse manual commands. Everyone else should pick from the table by how much setup they tolerate.
| Option | What survives a switch | Beginner setup effort | Pricing / licence | Best for |
|---|---|---|---|---|
| ai-memory | Four typed fields injected at startup; optional projected native history via ai-memory run | Low on supported pairs: one binary plus hooks; manual finalize-session on older Codex | Free, MIT licence | Switchers between supported harnesses |
| Claude Code built-in memory (CLAUDE.md plus session resume) | Your instructions file and a resumable session, all inside Claude Code | None — features ship with the agent | Included with Claude Code; no separate charge | Single-agent users who stay in Claude Code |
| Codex CLI same-agent session history | Full previous-session context, but only while you stay inside Codex | None | Included with Codex CLI | Codex-only workflows |
| Copy-paste recap into a fresh chat | Whatever you remember to paste, right now | None, but every switch costs writing time | Free | One-off jumps you did not plan for |
| Hand-written HANDOFF.md in the repo | Exactly what you wrote — decisions, diffs, open questions | Low: a file plus discipline | Free | Teams and any harness, including the no-inject list |
| Team wiki or notes file | Durable, searchable knowledge, but nothing injected automatically | Depends on the wiki you already run | Depends on the platform you choose | Long-lived team knowledge rather than per-task continuity |
Use ai-memory if you are either of these two readers. The daily switcher, who starts in Claude Code and finishes in Codex 0.145.0 or newer within one repo several times a week — that pair works automatically, end to end. The self-hosting tinkerer, who wants a git-backed markdown wiki as the source of truth, an MIT licence and a single Rust binary, and accepts that memory tools are a category of their own — our Supermemory review covers the wider category.
Skip it if you are either of these two. The no-inject harness user — Kiro, Pool, Zero, Grok Build CLI, DeepSeek Harness or Cline CLI — who wants automatic handoffs: keep a hand-written HANDOFF.md in the repo instead, or accept calling memory_handoff_list and memory_handoff_accept manually every time. The single-agent beginner who has never installed a coding agent: install nothing, write a CLAUDE.md — the instructions file Claude Code reads at startup — and use session resume; we compare coding agents head-to-head in the Arena and list the field in the tools directory.
The Bottom Line
ai-memory earns 7/10 by turning “continue without re-explaining” into a typed, four-field protocol that behaves exactly as the README claims on supported harness pairs. It is the most honest memory layer we have read, and the honesty sits in the code rather than the marketing: every byte that crosses the boundary is documented, including the marker printed when bytes are dropped.
The strongest caveat is coverage: on Codex builds older than 0.145.0 and on the eight harnesses without a true session-end event, the automatic promise degrades to manual commands — or to nothing at all.
| Criterion | Score | Why it earns this |
|---|---|---|
| Promise vs payload honesty | 9/10 | The README claims handoffs; the payload is a typed four-field struct, documented down to the literal omission marker |
| What actually carries over | 8/10 | Summary, open questions, next steps and touched files survive a switch; diffs, contents and reasoning deliberately do not |
| Beginner accessibility | 7/10 | One Rust binary helps, but SessionEnd, capture flags and the marker file demand code-adjacent reading |
| Harness coverage and friction | 5/10 | Twenty-plus harnesses feed the memory, yet eight-plus lack a true session end and six cannot auto-inject |
| Documentation quality | 8/10 | Support matrix, architecture notes and data-handling doc answer the hard questions in the project’s own words |
| Overall Score | 7/10 | An honest, well-built continuity layer whose automatic promise holds only where harness events allow it |
📊 See how ai-memory compares →
📖 Related Reads
- ToolBrain — tool reviews, LLM comparisons, and AI workflow guides
- Hermes Tutorials — Hermes Agent setup, configuration, and advanced workflows
Cross-links automatically generated from None.
Back to all posts