Memory Handoff

Memory Handoff defines a cross-CLI contract for preserving project context in one plaintext Markdown file per project. The file is read at session start and rewritten at session end, allowing a different CLI to resume work from recorded decisions and pointers. It requires no daemon or database, and its file format serves as the interface between tools.

The contract works across Claude Code, Cursor, Gemini CLI, OpenCode, Codex and aider. Rather than preserving a transcript, it records what matters for continuing the project: its current state, unresolved work, irreversible choices and the most useful next action.

Use it when starting work on a project with an existing handoff at ~/.agent/handoffs/<project-slug>.md, when asked to hand off or save context, or when a long session contains more decisions than can reliably be recalled later. The project slug comes from the directory name; for ~/dev/src/crawlkit, the slug is crawlkit.

Before work that would be expensive to reverse, check the dated Decisions entries for anything contradicting the proposed action. A stale file must be identified as stale when read. This is a plaintext home-directory record, often synced by dotfile tooling, so it must never contain secrets, tokens or credentials. Native Windows paths require WSL.

The default location is ~/.agent/handoffs, with AGENT_HANDOFF_DIR available to override it. At the beginning of a session, read the entire file. Use Next step as the default first action and Open threads as the agenda. State the recovered context aloud so the person working with the CLI can correct stale information before it affects the work.

At the end, rewrite whole sections instead of continually appending. The fixed structure is:

# handoff: <project-slug>

One paragraph: what this project is and where it stands. A stranger should be able to act after reading only this.

Bulleted, newest first. Each item names the branch, file, or command needed to resume it.

Dated, one line each, irreversible choices only.

The single most useful thing to do first, with the exact command.

ISO timestamp of the last write and which agent wrote it.

Writes stay inside the handoffs directory, including its configured override. The skill never deletes files or changes anything outside that directory. Keeping the record limited to decisions and actionable pointers preserves its purpose as a handoff rather than a dump of the session's conversation.