Session handover engine for AI coding agents: checkpointed, resumable, backend-agnostic persistent memory.
AI coding agents (Claude Code, Codex, OpenCode, Cline, ...) are stateless between
sessions. Every new session starts with re-explaining the project, the decisions
already made, and what was left half-done. agent-handover is the small piece of
infrastructure that fixes this: at the end of a session the agent writes a
structured handover; at the start of the next one, it resumes from it — even if
the previous handover crashed halfway.
Extracted from a personal "AI Team OS" that has run daily handovers across multiple machines and agents since 2025.
- Context loss: the next session doesn't know what the last one decided.
- Half-written state: a handover that dies mid-run silently corrupts memory. The next session boots from a state that is partly updated — worse than stale.
- Remote memory is fragile: vector DBs and hosted notebooks go down. If your agent's memory has no local fallback, your agent has no memory.
┌─ session ends ──────────────────────────────────────────────┐
│ HandoverEngine(steps, checkpoint, pause_file) │
│ step 1: collect session facts ── checkpointed │
│ step 2: MemoryStore.write(layer=1...) ── checkpointed │
│ step 3: MemoryStore.write(layer=2...) ── checkpointed │
│ step 4: GitBackend.publish(...) ── checkpointed │
└──────────────────────────────────────────────────────────────┘
┌─ next session starts ───────────────────────────────────────┐
│ $ agent-handover check # 0=clean 1=RESUME 2=completed │
│ read layer2/current-state.md → agent has context again │
└──────────────────────────────────────────────────────────────┘
Three memory layers, all plain Markdown (git-friendly, diff-able, readable by humans and any agent that can read a file):
| Layer | File pattern | Semantics |
|---|---|---|
| 1 | layer1/YYYY-MM/<tag>-<date>.md |
session notes (append, dated) |
| 2 | layer2/current-state.md |
"where are we now" (always overwritten) |
| 3 | layer3/YYYY-MM-<tag>-archive.md |
monthly compaction of old notes |
Three rules learned in production:
- Every step is checkpointed. An interrupted handover is detected
(
agent-handover check→ exit 1) and resumed without re-running done steps. - A
PAUSEfile is an absolute kill-switch. Agents that write to your repos need a brake a human can pull withtouch PAUSE. - The filesystem is the source of truth. Remote layers (NotebookLM, vector stores) are optional accelerators; the local copy is always enough to boot.
pip install agent-handover # or: pip install -e . from a clonefrom pathlib import Path
from agent_handover import Checkpoint, HandoverEngine, MemoryStore, Step, GitBackend
store = MemoryStore("memory/")
cp = Checkpoint(".agent-handover/checkpoint.json")
git = GitBackend(".", paths=["memory/"])
engine = HandoverEngine(
steps=[
Step("session_note", lambda: store.write(1, notes, tag="refactor")),
Step("current_state", lambda: store.write(2, snapshot)),
Step("publish", lambda: git.publish("handover: session sync")),
],
checkpoint=cp,
pause_file=Path.home() / ".agent_handover" / "PAUSE",
)
engine.run() # resumes pending steps automatically after a crashIn your agent's bootstrap (CLAUDE.md / AGENTS.md):
agent-handover check # exit 1 → finish the interrupted handover firstDon't want to write Python? Describe the handover in a TOML file and run it from the CLI — same checkpointed engine, as data:
agent-handover run --config .agent-handover/handover.toml --note "what happened"
# local only (no git push):
agent-handover run --config .agent-handover/handover.toml --note "wip" --no-pushCLI flags (--note, --current-state, --no-push, --checkpoint) override the
file, so one config serves every session. See
examples/run/ for a starter handover.toml.
A first-class adapter for the OpenAI Codex CLI.
Install the bootstrap block into your repo's AGENTS.md (idempotent, preserves
your other rules) and write a handover at the end of each session:
from agent_handover.adapters.codex import install_agents_md, build_codex_handover_engine
install_agents_md("AGENTS.md") # Codex runs `agent-handover check` on start
engine = build_codex_handover_engine( # one call for the end-of-session hook
session_note="reviewed PR #42; released v0.2.0",
current_state="parser refactor merged; next: TOML step config",
)
engine.run() # writes memory/, publishes, checkpointedSee examples/codex-cli/ for a runnable end-of-session
script and the AGENTS.md block.
A first-class adapter for Cline, the autonomous coding
agent for VS Code. Cline reads a directory of rule files (.clinerules/),
so the adapter installs a dedicated, idempotent rule file that never touches
your other rules:
from agent_handover.adapters.cline import install_clinerules, build_cline_handover_engine
install_clinerules(".clinerules") # writes .clinerules/00-agent-handover.md
engine = build_cline_handover_engine( # one call for the end-of-session hook
session_note="reviewed PR #42; released v0.3.0",
current_state="parser refactor merged; next: TOML step config",
)
engine.run() # writes memory/, publishes, checkpointedSee examples/cline/ for a runnable end-of-session script
and the .clinerules/ rule file.
A first-class adapter for OpenCode. OpenCode reads
AGENTS.md as its rules file (the same mechanism as Codex), so this adapter
shares its block and installer with the Codex adapter — only the example path
and engine tag differ:
from agent_handover.adapters.opencode import install_agents_md, build_opencode_handover_engine
install_agents_md("AGENTS.md") # OpenCode runs `agent-handover check` on start
engine = build_opencode_handover_engine( # one call for the end-of-session hook
session_note="reviewed PR #42; released v0.4.0",
current_state="parser refactor merged; next: TOML step config",
)
engine.run() # writes memory/, publishes, checkpointedSee examples/opencode/ for a runnable end-of-session
script and the AGENTS.md block.
- checkpointed engine, 3-layer Markdown store, git backend, pause guardrail
- adapter: Codex CLI (
AGENTS.mdbootstrap + end-of-session handover) - adapter: Cline (
.clinerules/rule file + end-of-session handover) - adapter: OpenCode (
AGENTS.mdbootstrap + end-of-session handover) -
agent-handover runwith declarative step config (TOML) - handover quality scoring (was the note actually useful next session?)
- adapters: NotebookLM, sqlite-vec
Issues and PRs welcome — especially reports from other agent stacks (Codex CLI, Cline, OpenCode).
MIT