A single Gateway process owns session state end-to-end. UIs (macOS app, web Control UI, TUI) query the Gateway for session lists and token counts. In remote mode, the per-agent SQLite database lives on the remote host, so checking your local Mac's state will not reflect what the Gateway is using.

Overview docs first: Session management, Compaction, Memory overview, Memory search, Session pruning, Transcript hygiene, full config reference at Agent config.

This page is an index. The deep dive is documented on six pages, one per reader job. Open the page that matches your task and stay there.

Page Read it when
Session state on disk The two persistence layers and the per-agent paths on the Gateway host.
Store maintenance and retention session.maintenance keys, disk-budget cleanup, cron retention, and the SQLite downgrade path.
Session keys, ids, and transcript events sessionKey patterns, sessionId lifecycle, SessionEntry fields, and transcript entry types.
Compaction behavior and settings What compaction does, when it runs, its settings and providers, and where it surfaces.
Silent turns and the memory flush The NO_REPLY contract and agents.defaults.compaction.memoryFlush.
Session transcript working sets Proposed worker-owned acquisition, resident budgets, and history-reader migrations.

Where each section moved

Every section heading from the previous single-page version keeps its anchor here, so an existing link such as /reference/session-management-compaction#when-auto-compaction-happens still resolves. Each entry points at the page that now holds the content.

Troubleshooting checklist

Related