/handoff — Session State Persistence
When invoked, write a comprehensive memory dump so future Claude sessions can resume w/o losing knowledge.
When to use
- User about to /clear and wants knowledge to persist
- Context window getting heavy (>50% used)
- End of long working session
- Before switching projects
- After major shipped milestone
What to capture (in this order)
- Identity — who user is, contacts, current location/situation
- Active project — repo path, stack, deployed URL, recent changes
- Roadmap / locked plan — phases, priority order, blockers
- Live state snapshots — any numbers or system state the next session must not re-derive
- Decisions still open — pending actions, choices waiting on user
- User patterns — communication style preferences, tools used, do/don't rules
- Resume protocol — exact files to read first when context restored
Where to write
Primary: <repo>/.claude/SESSION_MEMORY.md
Secondary (if applicable): append a summary to your long-term notes store
Tertiary: insert priority rows into Supabase action_queue (or equivalent task DB) so plan visible on phone/PWA
Output format
Use markdown w/ numbered sections. Heavy use of bold + tables for scannability. End w/ explicit "How to resume from clear context" checklist.
After writing
- List files written
- Tell user: "Context dumped. Clear safely. Next session reads
<path>first." - Suggest the 3-5 line bootstrap message user pastes to next Claude:
Read .claude/SESSION_MEMORY.md before doing anything else. Then read ROADMAP.md. Then ask me what to work on.
Auto-trigger conditions
Suggest /handoff proactively when:
- Conversation exceeds ~40 turns
- User mentions "context", "clear", "remember", "save"
- Major work session winding down
- Multiple tools loaded but mostly stale
Constraints
- Do NOT include secret values (API keys, tokens, passwords). Reference names only.
- Do NOT bloat — every line earns its place. Future Claude reads this in one pass.
- Do NOT speculate — only document what shipped or what's locked. Speculation = noise.
- Mark caveman-mode active/inactive so future session knows tone preference.
Example invocation
User: "context is getting big, save it" You:
- Identify active project (recent file edits / cwd)
- Pull live state (curl prod endpoints, query DB for current snapshot)
- Write SESSION_MEMORY.md w/ everything above
- Confirm + provide bootstrap message