​

Session Management & Compaction (Deep Dive)

• Session routing (how inbound messages map to a sessionKey)
• Session store (sessions.json) and what it tracks
• Transcript persistence (*.jsonl) and its structure
• Transcript hygiene (provider-specific fixups before runs)
• Context limits (context window vs tracked tokens)
• Compaction (manual + auto-compaction) and where to hook pre-compaction work
• Silent housekeeping (e.g. memory writes that shouldn’t produce user-visible output)

• /concepts/session
• /concepts/compaction
• /concepts/session-pruning
• /reference/transcript-hygiene

​

Source of truth: the Gateway

• UIs (macOS app, web Control UI, TUI) should query the Gateway for session lists and token counts.
• In remote mode, session files are on the remote host; “checking your local Mac files” won’t reflect what the Gateway is using.

​

Two persistence layers

1. Session store (sessions.json)
   • Key/value map: sessionKey -> SessionEntry
   • Small, mutable, safe to edit (or delete entries)
   • Tracks session metadata (current session id, last activity, toggles, token counters, etc.)
2. Transcript (<sessionId>.jsonl)
   • Append-only transcript with tree structure (entries have id + parentId)
   • Stores the actual conversation + tool calls + compaction summaries
   • Used to rebuild the model context for future turns

​

On-disk locations

• Store: ~/.clawdia/agents/<agentId>/sessions/sessions.json
• Transcripts: ~/.clawdia/agents/<agentId>/sessions/<sessionId>.jsonl
  • Telegram topic sessions: .../<sessionId>-topic-<threadId>.jsonl

​

Session keys (sessionKey)

• Main/direct chat (per agent): agent:<agentId>:<mainKey> (default main)
• Group: agent:<agentId>:<channel>:group:<id>
• Room/channel (Discord/Slack): agent:<agentId>:<channel>:channel:<id> or ...:room:<id>
• Cron: cron:<job.id>
• Webhook: hook:<uuid> (unless overridden)

​

Session ids (sessionId)

• Reset (/new, /reset) creates a new sessionId for that sessionKey.
• Daily reset (default 4:00 AM local time on the gateway host) creates a new sessionId on the next message after the reset boundary.
• Idle expiry (session.reset.idleMinutes or legacy session.idleMinutes) creates a new sessionId when a message arrives after the idle window. When daily + idle are both configured, whichever expires first wins.

​

Session store schema (sessions.json)

• sessionId: current transcript id (filename is derived from this unless sessionFile is set)
• updatedAt: last activity timestamp
• sessionFile: optional explicit transcript path override
• chatType: direct | group | room (helps UIs and send policy)
• provider, subject, room, space, displayName: metadata for group/channel labeling
• Toggles:
  • thinkingLevel, verboseLevel, reasoningLevel, elevatedLevel
  • sendPolicy (per-session override)
• Model selection:
  • providerOverride, modelOverride, authProfileOverride
• Token counters (best-effort / provider-dependent):
  • inputTokens, outputTokens, totalTokens, contextTokens
• compactionCount: how often auto-compaction completed for this session key
• memoryFlushAt: timestamp for the last pre-compaction memory flush
• memoryFlushCompactionCount: compaction count when the last flush ran

​

Transcript structure (*.jsonl)

• First line: session header (type: "session", includes id, cwd, timestamp, optional parentSession)
• Then: session entries with id + parentId (tree)

• message: user/assistant/toolResult messages
• custom_message: extension-injected messages that do enter model context (can be hidden from UI)
• custom: extension state that does not enter model context
• compaction: persisted compaction summary with firstKeptEntryId and tokensBefore
• branch_summary: persisted summary when navigating a tree branch

​

Context windows vs tracked tokens

1. Model context window: hard cap per model (tokens visible to the model)
2. Session store counters: rolling stats written into sessions.json (used for /status and dashboards)

• The context window comes from the model catalog (and can be overridden via config).
• contextTokens in the store is a runtime estimate/reporting value; don’t treat it as a strict guarantee.

​

Compaction: what it is

• The compaction summary
• Messages after firstKeptEntryId

​

When auto-compaction happens (Pi runtime)

1. Overflow recovery: the model returns a context overflow error → compact → retry.
2. Threshold maintenance: after a successful turn, when:

• contextWindow is the model’s context window
• reserveTokens is headroom reserved for prompts + the next model output

​

Compaction settings (reserveTokens, keepRecentTokens)

{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000
  }
}

• If compaction.reserveTokens < reserveTokensFloor, Clawdia bumps it.
• Default floor is 20000 tokens.
• Set agents.defaults.compaction.reserveTokensFloor: 0 to disable the floor.
• If it’s already higher, Clawdia leaves it alone.

​

User-visible surfaces

• /status (in any chat session)
• clawdia status (CLI)
• clawdia sessions / sessions --json
• Verbose mode: 🧹 Auto-compaction complete + compaction count

​

Silent housekeeping (NO_REPLY)

• The assistant starts its output with NO_REPLY to indicate “do not deliver a reply to the user”.
• Clawdia strips/suppresses this in the delivery layer.

​

Pre-compaction “memory flush” (implemented)

1. Monitor session context usage.
2. When it crosses a “soft threshold” (below Pi’s compaction threshold), run a silent “write memory now” directive to the agent.
3. Use NO_REPLY so the user sees nothing.

• enabled (default: true)
• softThresholdTokens (default: 4000)
• prompt (user message for the flush turn)
• systemPrompt (extra system prompt appended for the flush turn)

• The default prompt/system prompt include a NO_REPLY hint to suppress delivery.
• The flush runs once per compaction cycle (tracked in sessions.json).
• The flush runs only for embedded Pi sessions (CLI backends skip it).
• The flush is skipped when the session workspace is read-only (workspaceAccess: "ro" or "none").
• See Memory for the workspace file layout and write patterns.

​

Troubleshooting checklist

• Session key wrong? Start with /concepts/session and confirm the sessionKey in /status.
• Store vs transcript mismatch? Confirm the Gateway host and the store path from clawdia status.
• Compaction spam? Check:
  • model context window (too small)
  • compaction settings (reserveTokens too high for the model window can cause earlier compaction)
  • tool-result bloat: enable/tune session pruning
• Silent turns leaking? Confirm the reply starts with NO_REPLY (exact token) and you’re on a build that includes the streaming suppression fix.