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

GitHub

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

  1. Read docs/memory/project-index.md and latest docs/memory/agent-handoffs.md if present.
  2. Inspect current session context and git status --short.
  3. Summarize only durable context: done, debated, decisions, blockers, deferred items, next steps, revisit triggers.
  4. Append the handoff to docs/memory/agent-handoffs.md.
  5. Update docs/memory/current-state.md if the project state changed.
  6. Update docs/memory/project-index.md with the handoff entry.
  7. 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.
  8. Append changes to docs/skill-outputs/SKILL-OUTPUTS.md.
  9. 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>