Session Summaries That Survive Compaction

The route

4 steps to Done

1. 01

   Define what deserves to survive

   Durable memory is a curation problem before it is a storage problem.

   Preview prompt + verify gate ▾ Hide ▴

   Define the session-summary schema for durable knowledge. Sections: OUTCOME (what was accomplished, shipped, or abandoned), WORKING RECIPES (commands, configurations, and approaches that worked, exactly as used), FAILED APPROACHES (what was tried and failed, with the failure reason - so it is not repeated), USER PREFERENCES (style, tools, constraints the user expressed), PROJECT FACTS (architecture notes, key file locations, gotchas discovered). Exclusions: greetings, reasoning meander, anything reconstructible by reading the code. Write the extraction prompt that fills this schema from a session transcript, and test it on two saved transcripts - grade whether someone could resume the project from the summary alone.

   • ✓ Failed approaches captured with reasons
   • ✓ Exclusion list keeps summaries lean
   • ✓ Resume-from-summary test performed
2. 02

   Write at the moments that matter

   End-of-session and pre-compaction are the two death points for knowledge.

   Preview prompt + verify gate ▾ Hide ▴

   Implement summary writing at both trigger points. (1) Session end: on completion, cancellation, or escalation, run the extraction prompt over the session and write the summary to the project's memory directory as a dated file. (2) Pre-compaction: before history is compacted, run extraction over the about-to-be-compacted region and merge findings into the session's running summary file (so compaction never destroys unexported knowledge). Make writes atomic and crash-safe. Add a manual 'checkpoint' command for users who want to force a summary mid-session. Verify both triggers by inspecting the files after a normal session and after a forced compaction.

   • ✓ Both triggers implemented
   • ✓ Pre-compaction merge preserves earlier content
   • ✓ Atomic writes verified
3. 03

   Load summaries into new sessions

   Memory only exists if it comes back.

   Preview prompt + verify gate ▾ Hide ▴

   Implement summary loading. At session start in a project directory: find the latest session summaries (default: last 3), render them into a compact 'PROJECT MEMORY' block (merge overlapping facts, most recent wins on conflicts), and include it in the system context. Cap the block at a token budget (default ~800 tokens) - if over, prioritize USER PREFERENCES and FAILED APPROACHES, then WORKING RECIPES, then the rest. Verify with the acceptance test: in session 1 establish a preference ('always use yarn, never npm') and a failure ('approach X breaks the build'); start session 2 fresh and confirm the agent respects the preference and avoids the failed approach without being told.

   • ✓ Latest summaries merged with recency priority
   • ✓ Token budget enforced with priority ordering
   • ✓ Acceptance test passes across a restart
4. 04

   Prune and prove long-term health

   A memory store that only grows becomes noise.

   Preview prompt + verify gate ▾ Hide ▴

   Add store maintenance and run the longevity test. Maintenance: cap the memory directory (default: keep the 10 most recent session summaries plus one rolling 'project digest' file); when over cap, merge the oldest summaries into the digest (same schema, deduplicated) and delete the originals. Longevity test: simulate 12 short sessions in a project (script them), each adding a fact or preference; verify after all 12 that (a) the store is within cap, (b) the digest holds the early facts, (c) a fresh session still answers questions about session-1 decisions correctly. Fix any knowledge that failed to survive the merge chain.

   • ✓ Cap and merge-to-digest implemented
   • ✓ Early facts survive into the digest
   • ✓ Fresh session recalls session-1 knowledge

Research-backed

Sources behind this flow