handoff

name	handoff
description	Save a session handoff to Engram for future sessions. Captures decisions, todos, blockers, mental model, and next steps as a structured memory. Use when the user wants to preserve session context before ending work.
disable-model-invocation	true

Capture session state into Engram via the mcp__engram__handoff_create MCP tool. Engram is now the canonical store; no markdown file is written.

Steps

1. Gather working state (skip if not in a git repo). Run in parallel:

   • git branch --show-current
   • git log --oneline -5
   • git status --short
   • git diff --stat
   • gh pr view --json url,number,state 2>/dev/null

2. Build the handoff payload. Map session content to these sections. summary is required; everything else is optional. Omit sections with nothing real to say; do not pad.

   • summary (string): 1–3 sentences naming what was worked on.
   • decisions (string array): architectural / design choices made this session, one per item, with rationale.
   • todos (string array): remaining tasks. Specific: file path, function name, the next concrete action.
   • blockers (string array): approaches tried that did not work, with why each failed. So the next agent does not retry them.
   • mental_model (string): prose paragraph describing how the system / problem fits together right now. Use when the next agent needs the model in their head.
   • next_steps (string array): ordered/prioritized actions, closely related to todos. Use next_steps for "what to do next"; use todos for "what's still open".
   • notes (string, optional): open questions for the user, env quirks, pre-existing failures, anything that doesn't fit the other sections.

3. Detect continues_from. If the read-handoffs skill or mcp__engram__handoff_resume ran earlier this session and returned a latest_handoff_id, pass that id as continues_from. Otherwise omit.

4. Sensitive data filter. Before calling the tool, scrub: API tokens, passwords, private URLs, customer data, internal hostnames. If unsure, ask the user.

5. Call mcp__engram__handoff_create with the payload. Defaults: pinned: true, importance: 0.85, auto_link: true. Branch is auto-detected from git; pass an explicit branch only if you want to override.

6. Report to the user. Print the new handoff id, the auto-linked memory count (decisions/patterns/debug memories Engram associated by similarity), and the continues_from link if one was set. Ask if any section should be revised; if so, the user can dictate edits and you can call mcp__engram__memory_update on the just-created handoff.

7. Escalate single insights worth keeping outside the handoff. Only do this for content that should surface in memory_context queries on unrelated future tasks. Call mcp__engram__memory_store separately for:

   • type: decision — architectural choice with rationale (importance 0.7)
   • type: pattern — recurring gotcha / convention discovered (importance 0.7)
   • type: debug — root cause of a tricky bug (importance 0.6) The handoff already captures session-level context; only escalate insights with cross-session value.

Failure modes

• Detached HEAD / non-git workspace: handoff_create rejects with MemoryError::InvalidType because branch is required. Ask the user for a branch name and pass it explicitly via the branch argument.
• Empty payload: at least one section must be non-empty. If you have nothing real to say, do not call the tool — tell the user the session has no state worth handing off.

Viewing handoffs later

• engram-cli handoff show <id> — render a specific handoff
• engram-cli handoff resume — load context for the current branch
• engram-cli handoff search "query" — semantic search across handoff sections
• /mcp__engram__resume — same as handoff resume, via slash command in Claude Code