Memory 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-versioning for git operations after handoff is saved.
Do not run after trivial interactions.
Workflow
- Read
docs/memory/project-index.md and latest docs/memory/agent-handoffs.md if 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.md if the project state changed.
- Update
docs/memory/project-index.md with the handoff entry.
- Update knowledge graph — run
python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental. If it fails, add ### Graph note 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
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>
1---2name: memory-handoff3description: 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, before ending a meaningful session, or when the user asks to commit, push, commit and push, create a git commit, push to origin, or publish commits — commit/push requests MUST run this skill first to prepare handoff docs, then proceed with git operations.4license: MIT5---67# Memory Handoff89You preserve continuity for the next agent. A handoff is short, actionable, and focused on what would otherwise be lost.1011## Trigger Policy1213Run when a future agent would lose important context:14- Meaningful code changes, debugging discoveries, architecture debates, spec changes, or deferred decisions.15- End of a long session with unresolved work.16- Before switching agents or tools.17- User says "handoff", "summarize where we are", "save context", "memory handoff", or "next agent should know".18- **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-versioning` for git operations after handoff is saved.1920Do not run after trivial interactions.2122## Workflow23241. Read `docs/memory/project-index.md` and latest `docs/memory/agent-handoffs.md` if present.252. Inspect current session context and `git status --short`.263. Summarize only durable context: done, debated, decisions, blockers, deferred items, next steps, revisit triggers.274. Append the handoff to `docs/memory/agent-handoffs.md`.285. Update `docs/memory/current-state.md` if the project state changed.296. Update `docs/memory/project-index.md` with the handoff entry.307. **Update knowledge graph** — run `python3 .agents/skills/knowledge-graph/scripts/build_graph.py --incremental`. If it fails, add `### Graph` note in handoff; do not block save.318. Append changes to `docs/skill-outputs/SKILL-OUTPUTS.md`.329. **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.3334## Template3536```markdown37## YYYY-MM-DD HH:MM - Handoff3839### Done40- <completed work>4142### Debated43- <tradeoff and conclusion>4445### Decisions46- <decision and link/reference>4748### Deferred49- <parked item and why>5051### Next Agent Should Know52- <highest-value continuity note>5354### Revisit Triggers55- <conditions that reopen decisions>5657### Working Tree58- <clean or relevant dirty files>59```6061## Hard Rules6263- Keep each handoff under 80 lines.64- Do not include secrets, tokens, or raw private data.65- Link to decision entries instead of repeating long rationale.66- If the handoff gets repetitive, call `memory-compact`.6768## Example6970User: "I'm moving this to another agent, save a handoff."7172Output: append a timestamped handoff with current status, unresolved tasks, and files touched.7374## Common Rationalizations7576| Excuse | Reality |77|--------|---------|78| Skip memory — just code | Next agent loses decisions, blockers, and approved scope. |79| Load every memory file | Read indexes and handoff tail only — bounded context. |80| Global memory for everything | Project memory default; global only when stable and cross-project. |81| External paste → memory | Run secure-* first; transform to agent-authored notes. |8283## Verification8485- [ ] Correct sub-skill routed with reason86- [ ] No secrets or raw transcripts persisted87- [ ] Files changed listed in Impact Report88- [ ] Security gate noted when external content involved8990## Red Flags9192- Handoff exceeds 80-line budget93- Secrets tokens or raw private data in handoff body94- Long decision rationale pasted instead of log link95- Git state omitted from handoff next-agent context9697## Prune Log98Last pruned: 2026-07-0599- Deep learn-from: harness-trajectory-mining.md for RHO prerequisite path100101102## Impact Report103104After completing, report:105```markdown106Handoff saved: docs/memory/agent-handoffs.md107Current state updated: yes/no108Index updated: yes/no109Next recommended action: <one sentence>110```
dvy1987