What Actually Survives a Claude Code to Codex Handoff: ai-memory Review
· 12 min read

What Actually Survives a Claude Code to Codex Handoff: ai-memory Review

A beginner-friendly review of the open-source ai-memory tool and what actually carries over when you hand a coding task from Claude Code to Codex mid-build.

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:

  1. The last prompt ends with ”?” → “Unresolved question: …” — your own sentence, re-quoted.
  2. 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.
  3. Stop fired but no SessionEnd → a mid-task exit; the last substantive prompt is reused.
  4. A normal end → “Continue from: …”.
  5. 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.

  1. 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.
  2. If [handoff detail omitted to fit this harness's startup limit] appears, treat the handoff as partial and fill the gaps yourself.
  3. Run git status and git diff to see the real state of your files; CodeIntell collects working-tree and code-quality habits worth borrowing.
  4. Never treat files_touched as a change list — it is a touch list, as the code comment above states.
  5. On harnesses that need it — older Codex builds and the Seam 1 list — run finalize-session before switching agents.
  6. 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.

OptionWhat survives a switchBeginner setup effortPricing / licenceBest for
ai-memoryFour typed fields injected at startup; optional projected native history via ai-memory runLow on supported pairs: one binary plus hooks; manual finalize-session on older CodexFree, MIT licenceSwitchers between supported harnesses
Claude Code built-in memory (CLAUDE.md plus session resume)Your instructions file and a resumable session, all inside Claude CodeNone — features ship with the agentIncluded with Claude Code; no separate chargeSingle-agent users who stay in Claude Code
Codex CLI same-agent session historyFull previous-session context, but only while you stay inside CodexNoneIncluded with Codex CLICodex-only workflows
Copy-paste recap into a fresh chatWhatever you remember to paste, right nowNone, but every switch costs writing timeFreeOne-off jumps you did not plan for
Hand-written HANDOFF.md in the repoExactly what you wrote — decisions, diffs, open questionsLow: a file plus disciplineFreeTeams and any harness, including the no-inject list
Team wiki or notes fileDurable, searchable knowledge, but nothing injected automaticallyDepends on the wiki you already runDepends on the platform you chooseLong-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.

CriterionScoreWhy it earns this
Promise vs payload honesty9/10The README claims handoffs; the payload is a typed four-field struct, documented down to the literal omission marker
What actually carries over8/10Summary, open questions, next steps and touched files survive a switch; diffs, contents and reasoning deliberately do not
Beginner accessibility7/10One Rust binary helps, but SessionEnd, capture flags and the marker file demand code-adjacent reading
Harness coverage and friction5/10Twenty-plus harnesses feed the memory, yet eight-plus lack a true session end and six cannot auto-inject
Documentation quality8/10Support matrix, architecture notes and data-handling doc answer the hard questions in the project’s own words
Overall Score7/10An honest, well-built continuity layer whose automatic promise holds only where harness events allow it

📊 See how ai-memory compares →

  • 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