Session Management & Compaction (Deep Dive)

Scope

This page is a placeholder generated from the official source file structure.

What to verify

• TODO: Add prerequisites and validation checklist.

Outline (from official headings)

• Source of truth: the Gateway
• Two persistence layers
• On-disk locations
• Session keys (sessionKey)
• Session ids (sessionId)
• Session store schema (sessions.json)
• Transcript structure (*.jsonl)
• Context windows vs tracked tokens
• Compaction: what it is
• When auto-compaction happens (Pi runtime)
• Compaction settings (reserveTokens, keepRecentTokens)
• User-visible surfaces
• Silent housekeeping (NO_REPLY)
• Pre-compaction “memory flush” (implemented)
• Troubleshooting checklist

Further reading

• Official source file: reference/session-management-compaction.md