memory-handoff

Memory Handoff

Overview

A cross-CLI session handoff contract: one plaintext markdown file per project, read at session start and rewritten at session end, so any agent CLI (Claude Code, Cursor, Gemini CLI, OpenCode, Codex, aider) picks up the work mid-thought instead of cold. No daemon, no database, no lock-in — the file is the memory, and the format is the API.

When to Use This Skill

• Use when starting a session on a project that has a handoff file at ~/.agent/handoffs/<project-slug>.md.
• Use when the user asks to "hand off", "save context", or "pick up where we left off".
• Use when a session is long enough that losing it would hurt (more decisions made than fit in what you can reliably recall later).

How It Works

Step 1: Locate the file

# Default directory is ~/.agent/handoffs; $AGENT_HANDOFF_DIR overrides it.
# For ~/dev/src/crawlkit, the slug is "crawlkit".
printf '%s\n' "${AGENT_HANDOFF_DIR:-$HOME/.agent/handoffs}/crawlkit.md"

Step 2: Read it at session start

Read the whole file. Treat Next step as the default first action and Open threads as the agenda. State out loud what you picked up, so the human can correct stale context before it misleads you.

Step 3: Rewrite it at session end

Rewrite whole sections rather than appending; stale handoffs are worse than none. The five fixed sections:

# handoff: <project-slug>

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

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

## Decisions
Dated, one line each, irreversible choices only.

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

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

Step 4: Check decisions before irreversible work

Before doing anything expensive to reverse, check Decisions for a dated line that contradicts what you are about to do.

Limitations

• Writes only inside the handoffs directory; it never deletes files and never touches anything outside ~/.agent/handoffs (or $AGENT_HANDOFF_DIR).
• Plaintext in a home directory, often synced by dotfile tooling: never put secrets, tokens, or credentials in the file.
• Only as good as the last write: a handoff that was not updated after a session is stale and must be said out loud as stale when read.
• No Windows-native paths without WSL (the slug comes from the directory name; mount paths differ).
• Do not dump session transcripts into the file: handoff is decisions and pointers, not history.