memento

The Memento pattern for coding agents: capture a session's state, restore it in another. When Claude Code (or Codex, Gemini, Pi) runs out of context mid-task, memento captures the live session — task, plan, decisions, recent tool results — and the exact git state including a snapshot of your uncommitted and untracked files, then hands it to the next agent as a session you can continue from immediately.

Most handoff tools pass notes. memento passes executable state: memento restore materializes the prior agent's actual working tree into the new checkout, and memento verify confirms it landed.

The automatic flow

Set it up once:

npm install -g @samjurnio_/memento
memento install-hooks claude-code      # capture automatically when context runs low
claude mcp add memento -- memento mcp    # let the agent call memento itself

Now you don't type anything during work. When Claude Code runs low on context, memento captures the whole session on its own. Move it to the next agent with one command and open that agent — the handed-off session is already in your Recent list, mid-task, with your workspace intact:

memento inject codex

Claude Code runs out of context  →  memento captures (auto)  →  memento inject codex  →  open Codex: "Memento: continue …" is waiting

No copy-paste, no re-explaining what you were doing.

By hand

One command does it — compile the source session and inject it into the target:

memento handoff codex claude-code      # move your Codex session into Claude Code
memento handoff claude-code codex      # ...or the other way

Or run the steps individually:

memento compile             # capture the current session into a packet
memento inject codex        # write it as a native Codex session
memento resume | pbcopy     # or paste the resume prompt into Gemini, Pi, anything
memento restore             # materialize the captured working tree into this checkout
memento verify              # check the workspace hasn't drifted from the packet
memento status              # one-line summary

Supported agents

| agent | read session | inject natively | |---|---|---| | Claude Code | yes | yes | | Codex | yes | yes | | Antigravity | yes | yes | | Gemini CLI | yes | paste | | Pi | yes | paste | | opencode | yes | paste |

Adapters are lenient: unknown event types are skipped, never fatal. Pi and opencode are read sources today — memento handoff pi claude-code or memento resume to move their work into any native target.

Examples per agent

memento handoff <from> <to> compiles the source session and injects it into the target in one step; memento resume prints a prompt to paste into an agent with no native injector.

Claude Code

# Hand the current session to Codex when context runs low:
memento handoff claude-code codex --reason context_exhaustion

# Continue in another Claude Code workspace (compile here, inject there):
memento compile --agent claude-code
memento inject claude-code --workspace ../other-checkout

Codex

# Move a Codex session into Claude Code:
memento handoff codex claude-code

# Or pipe the resume prompt straight into a fresh Codex run:
memento compile --agent codex && codex exec "$(memento resume)"

Antigravity

memento handoff claude-code antigravity   # native session (transcript + SQLite)

Gemini CLI

# Gemini has no native injector — paste the resume prompt:
memento compile --agent gemini-cli
memento resume | pbcopy

What carries over

Task and constraints, the plan with per-step status, decisions (so the next agent doesn't relitigate them), recent tool results with in-flight calls flagged as not applied, operator-blocked tools, and the workspace: branch, HEAD, dirty files, and a full git snapshot including uncommitted work — plus the handoff chain so a long relay stays reconstructable.

Git state and tool outcomes are read from the real session, never invented. The narrative parts (objective, next steps) come from a pluggable summarizer — heuristic and fully offline by default; swap in an LLM one if you want.

The working-tree snapshot is the part most tools skip. memento restore brings those uncommitted and untracked files back into the receiving checkout (it refuses to clobber diverging local edits unless you pass --force), so the next agent picks up your literal in-progress files — not a description of them.

Develop

git clone https://github.com/younggeeks/memento && cd memento
pnpm install && pnpm build && npm link
pnpm test          # 64 tests, offline
memento bench        # 5 scenarios, 25 fidelity checks

License: Apache-2.0 © Samwel Charles