session-handoff

Session Handoff

Structured end-of-session capture that ensures the NEXT session starts with full context. Enforces "WHY not just WHAT" — every memory must include the reasoning, not just the fact.

Checklist (go through ALL categories)

Before storing anything, review the conversation for each category:

1. Decisions made: Technical choices, architecture decisions, tool selections

   • BAD: "Using PostgreSQL"
   • GOOD: "Using PostgreSQL over SQLite because we need concurrent writes from multiple workers and the data exceeds 10GB"

2. Preferences expressed: User's workflow preferences, style choices, communication preferences

   • BAD: "Prefers short commits"
   • GOOD: "Prefers atomic commits (one logical change per commit) because they review PRs commit-by-commit and need clean bisect history"

3. Corrections given: Things the user corrected — these are HIGH PRIORITY (prevents repeat mistakes)

   • BAD: "Don't use fmt.Println"
   • GOOD: "Corrected: use log.Printf not fmt.Println in Go services because stdout is not captured by the log aggregator (Alloy)"

4. Conventions established: Naming patterns, file organization, coding standards

   • BAD: "Use snake_case"
   • GOOD: "Convention: snake_case for Python files and functions, but PascalCase for Pydantic models. Established because the codebase mixes both and this was the cleanup decision"

5. Open questions: Unresolved items that need future attention

   • Store these explicitly so the next session can address them
   • Include what was already tried or considered

Storage Process

For each item identified above:

1. Store with context using memory(action="add", ...):

   • Content MUST include WHY, not just WHAT
   • Tag with category: decision, preference, correction, convention, open-question
   • Tag with project name for scoped retrieval
   • Include date context if time-sensitive

2. Verify retrieval (mandatory — do NOT skip):

   • memory(action="search", query="[natural terms someone would use to find this]")
   • If the memory does not appear in top results, either:
     • Rewrite content with better keywords
     • Add more specific tags
   • A memory that cannot be found is worthless