memory-handoff
Write concise next-agent handoff summaries across sessions, tools, and coding agents. Load when the user says handoff, next agent should know, save context, summarize where we are, switching agents, b
SKILL.md.agents/skills/memory-handoff/SKILL.md
GitHubMemory Handoff
You preserve continuity for the next agent. A handoff is short, actionable, and focused on what would otherwise be lost.
Trigger Policy
Run when a future agent would lose important context:
- Meaningful code changes, debugging discoveries, architecture debates, spec changes, or deferred decisions.
- End of a long session with unresolved work.
- Before switching agents or tools.
- User says "handoff", "summarize where we are", "save context", "memory handoff", or "next agent should know".
- User asks to commit and/or push ("commit", "create a commit", "commit these changes", "prepare commit", "push", "push to origin", "git push", "commit and push", "commit and push when ready") — run full handoff workflow before staging/committing/pushing so the next session has continuity. Pair with
git-workflow-and-versioningfor git operations after handoff is saved.
Do not run after trivial interactions.
Workflow
- Read
docs/memory/project-index.mdand latestdocs/memory/agent-handoffs.mdif present. - Inspect current session context and
git status --short. - Summarize only durable context: done, debated, decisions, blockers, deferred items, next steps, revisit triggers.
- Append the handoff to
docs/memory/agent-handoffs.md. - Update
docs/memory/current-state.mdif the project state changed. - Update
docs/memory/project-index.mdwith the handoff entry. - Update knowledge graph — run
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental. If it fails, add### Graphnote in handoff; do not block save. - Append changes to
docs/skill-outputs/SKILL-OUTPUTS.md. - Optional harness mining: When session had repeated agent failures and harness evolution is queued, distill failure digests per
references/harness-trajectory-mining.md— never raw transcripts.
Template
## YYYY-MM-DD HH:MM - Handoff
### Done
- <completed work>
### Debated
- <tradeoff and conclusion>
### Decisions
- <decision and link/reference>
### Deferred
- <parked item and why>
### Next Agent Should Know
- <highest-value continuity note>
### Revisit Triggers
- <conditions that reopen decisions>
### Working Tree
- <clean or relevant dirty files>
Hard Rules
- Keep each handoff under 80 lines.
- Do not include secrets, tokens, or raw private data.
- Link to decision entries instead of repeating long rationale.
- If the handoff gets repetitive, call
memory-compact.
Example
User: "I'm moving this to another agent, save a handoff."
Output: append a timestamped handoff with current status, unresolved tasks, and files touched.
Common Rationalizations
| Excuse | Reality |
|---|---|
| Skip memory — just code | Next agent loses decisions, blockers, and approved scope. |
| Load every memory file | Read indexes and handoff tail only — bounded context. |
| Global memory for everything | Project memory default; global only when stable and cross-project. |
| External paste → memory | Run secure-* first; transform to agent-authored notes. |
Verification
- Correct sub-skill routed with reason
- No secrets or raw transcripts persisted
- Files changed listed in Impact Report
- Security gate noted when external content involved
Red Flags
- Handoff exceeds 80-line budget
- Secrets tokens or raw private data in handoff body
- Long decision rationale pasted instead of log link
- Git state omitted from handoff next-agent context
Prune Log
Last pruned: 2026-07-05
- Deep learn-from: harness-trajectory-mining.md for RHO prerequisite path
Impact Report
After completing, report:
Handoff saved: docs/memory/agent-handoffs.md
Current state updated: yes/no
Index updated: yes/no
Next recommended action: <one sentence>