Docs / Concepts

Handovers

.hydrate/HANDOVER.md is the primary high-fidelity channel for resuming a session after /clear. It lives in your repo, is gitignored by default, and answers "what was I doing 90 seconds ago" with a complete prose note that the agent reads via its normal Read tool, bypassing the harness's ~2 KB additional-context cap. New in v0.6.0.

What it is

A single markdown file at .hydrate/HANDOVER.md, rewritten by /hydrate-distill at the end of every working session. The next session's /hydrate-last reads it silently into agent context and emits a one-line confirmation, instead of dumping the body verbatim into the user transcript. Visible-token cost dropped from ~2k to ~50; the agent still has the full content available.

Every write is also copied to a per-session archive at .hydrate/handovers/<UTC-ISO-compact>-<6hex-rand>.md. The random suffix eliminates same-second collisions when two sessions distill back-to-back. The latest archive is the source of truth for the next /hydrate-last; older archives feed cross-sprint mining.

When it beats canon and facts

Handovers and the structured store solve different problems:

Handover answers what was I doing 90 seconds ago. High fidelity, full prose, scoped to one session, lives in the working tree, ephemeral. Beats the chunker for short-term resume because the prose is hand-written by the outgoing agent at the moment it had full context.
Canon and facts answer what are the long-lived rules of this project. Lossless, structured, survive every /clear, sync across runtimes, queryable across the whole project history. The chunker rollups feed the same store.

The chunker-only resume failed a probe quiz on a 22-canon-item project (1.5 / 14, roughly 11%) because the harness truncates session-start additional-context payloads. After moving the primary channel to .hydrate/HANDOVER.md the same quiz scored 13 / 14 plus one partial (roughly 96%). Architectural rationale in thesis Chapter 30, docs/thesis/30_HANDOVER_PRIMARY_STORE_SECONDARY.md.

CLI surface: `hydrate handover`

The CLI owns the file layout so agents and slash commands never need to know about archive paths.

hydrate handover path                       # print absolute path
hydrate handover read [--json] [--archive=FILE]
hydrate handover write [--stdin] [--touch] [--no-archive]
hydrate handover clear
hydrate handover list [--json]
hydrate handover grep <pattern>
hydrate handover prune [--keep=N] [--older-than=DUR]

Exit codes are scripting-friendly: read exits 0 when the file is present and 2 when it is absent. grep exits 0 on a hit and 2 on no matches, so you can chain it into shell pipelines without spurious failures.

Archive layout

.hydrate/
├── HANDOVER.md                                 (latest, pointer)
└── handovers/
    ├── 20260527T091344Z-a1b2c3.md
    ├── 20260527T103022Z-d4e5f6.md
    └── 20260527T143811Z-789abc.md

Both .hydrate/HANDOVER.md and .hydrate/handovers/ are gitignored by default: this is per-developer ephemeral state, not something to check in. The dashboard's Handovers page browses the archive across every project on the machine.

How it fits the distill / resume cycle

/hydrate-distill runs a Phase 0 step that heredocs the agent's session notes into hydrate handover write --stdin. The CLI atomically writes the new archive entry, then atomically copies it to .hydrate/HANDOVER.md. After the next /clear, /hydrate-last reads the pointer file silently and renders a small briefing from hydrate_session_resume alongside it. The structured store still backs the session-resume briefing so cross-session canon, in-flight orchestrations, and key facts all surface underneath the handover.