session-handoff

End-of-session knowledge capture — decisions, preferences, corrections, conventions, open questions

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

  3. Produce handoff summary for the user:

    ## Session Handoff — [date]

### Stored
- [N] decisions, [N] preferences, [N] corrections, [N] conventions

### Open Questions (carried forward)
- [list unresolved items]

### Key Context for Next Session
- [1-3 sentence summary of where things stand]

Quality Rules

  • WHY not WHAT: Every memory must answer "why was this decided/preferred/corrected?"
  • Specific over generic: "Use Polars for dataframes" is useless without "because pandas is banned per project rules and Polars handles our 50M row dataset in 2s vs 45s"
  • One insight per memory: Do not cram multiple unrelated facts into one entry
  • Verify or discard: If retrieval verification fails after 2 rewrites, the content is too vague to be useful
  • No ephemeral facts: Do not store things that will be outdated next session (e.g., "currently on line 42 of file X")

When to Use

  • End of any productive session (before the conversation closes)
  • When explicitly asked to "remember this" or "save for next time"
  • After debugging sessions — capture root cause and fix
  • After architecture or design discussions with decisions