Technical reference
Session management deep dive
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 five 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. |
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.
- Two persistence layers
- On-disk locations
- Store maintenance and disk controls
- Downgrading After The SQLite Flip
- Cron sessions and run logs
- Session keys (
sessionKey) - Session ids (
sessionId) - Session store schema
- Transcript event structure
- Context windows vs tracked tokens
- Compaction: what it is
- Chunk boundaries and tool pairing
- When auto-compaction happens
- Compaction settings
- Pluggable compaction providers
- User-visible surfaces
- Silent housekeeping (
NO_REPLY) - Pre-compaction memory flush
Troubleshooting checklist
- Session key wrong? Start with /concepts/session and confirm the
sessionKeyin/status. - Store vs transcript mismatch? Confirm the Gateway host and the store path from
openclaw status. - Compaction spam? Check the model's context window (too small forces frequent compaction) and tool-result bloat (tune session pruning).
- Every prompt seems to overflow on a small local model? Confirm the provider reports the correct model context window. OpenClaw can cap the effective reserve only when that window is known.
- Silent turns leaking? Confirm the reply starts with the exact silent token
NO_REPLY(case-insensitive) and you are on a build that includes the streaming-suppression fix (2026.1.10+).
