handoff

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.