Skip to main content

Session Management & Compaction (Deep Dive)

This document explains how WednesdayAI manages sessions end-to-end:
  • Session routing (how inbound messages map to a sessionKey)
  • Session index (SQL) and what it tracks
  • Conversation persistence (append-only SQL entries) 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)
If you want a higher-level overview first, start with:

Source of truth: the Gateway

WednesdayAI is designed around a single Gateway process that owns session state.
  • UIs (macOS app, web Control UI, TUI) should query the Gateway for session lists and token counts.
  • CLI storage commands use gateway RPC while it runs; without a gateway, the CLI takes storage ownership for the command. In remote mode, local files do not reflect the gateway’s database.

Two persistence layers

Both layers live in the same SQL database (SQLite by default, Postgres optional):
  1. Session index (ctx_sessions)
    • Maps an agent’s sessionKey to the current SessionEntry.
    • Tracks the current session id, activity, toggles, and token counters.
    • Reset/delete use new session identities or tombstones, not transcript-file operations.
  2. Conversation log (ctx_session_entries)
    • Append-only entries with id + parentId tree structure.
    • Stores the conversation, full tool output, custom entries, and compaction summaries.
    • Hydration rebuilds the active model context from these rows.
Compaction events and context projections have their own indexed tables. Plugins use getConversationReadQuery from wednesdayai/plugin-sdk, including listCompactions and loadLatestProjection, rather than opening database or transcript files.

On-disk locations

On the gateway host:
  • Default SQLite database: ~/.openclaw/sessions.db, with -wal / -shm sidecars.
  • Override: session.storage.sqlitePath; Postgres uses session.storage.databaseUrl.
  • Online SQLite snapshots: ~/.openclaw/backups/ via wednesdayai session-storage backup.
  • Legacy agents/<agentId>/sessions/sessions.json and *.jsonl are import sources only. Imported sources move to ~/.openclaw/legacy-session-archive/.
See Upgrading from JSON session files for automatic import, archive retention, and safe rollback.

Store maintenance and disk controls

session.maintenance controls the SQL session index:
  • mode: warn (default) reports eligible index entries without retiring them; enforce enables index cleanup.
  • pruneAfter: index-entry age cutoff (default 30d).
  • maxEntries: cap on the current session index (default 500), not a transcript entry limit.
Conversation history is never deleted: session.maintenance only retires idle or over-cap sessions from the session index (tombstones, based on the index entry’s last update), and the conversation rows stay readable. Compaction, tool trimming, and reset/delete do not erase stored conversation entries. The old file rotation and disk-budget settings are retired. Archive-only and rejected-line legacy sources are kept indefinitely; only fully imported copies with zero rejected lines can be purged. Run maintenance on demand:

Cron sessions and run logs

Isolated cron runs also create SQL sessions:
  • cron.sessionRetention (default 24h) tombstones old isolated cron session index rows (false disables). Conversation entries are never deleted and stay readable.
  • cron.runLog.maxBytes + cron.runLog.keepLines prune ~/.openclaw/cron/runs/<jobId>.jsonl files (defaults: 2_000_000 bytes and 2000 lines).

Session keys (sessionKey)

A sessionKey identifies which conversation bucket you’re in (routing + isolation). Common patterns:
  • 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)
The canonical rules are documented at /concepts/session.

Session ids (sessionId)

Each sessionKey points at a current sessionId (the database identity that continues the conversation). Rules of thumb:
  • 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.
  • Thread parent fork guard (session.parentForkMaxTokens, default 100000) skips parent transcript forking when the parent session is already too large; the new thread starts fresh. Set 0 to disable.
Implementation detail: the decision happens in initSessionState() in src/auto-reply/reply/session.ts.

Session index schema

The store’s value type is SessionEntry in src/config/sessions.ts. Key fields (not exhaustive):
  • sessionId: current conversation id
  • updatedAt: last activity timestamp
  • lastReplyAt: last assistant reply activity timestamp, also exposed by wednesdayai sessions --json
  • sessionFile: deprecated legacy path hint; not a live transcript path
  • chatType: direct | group | room (helps UIs and send policy)
  • provider, subject, room, space, displayName: metadata for group/channel labeling
  • groupActivation: group activation mode (mention | always) for group sessions; also exposed by wednesdayai sessions --json alongside providerOverride / modelOverride
  • 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
Update metadata through gateway APIs or owner-routed CLI commands, not direct database edits.

Conversation entry structure

The gateway hydrates an in-memory SessionManager from SQL and persists appended entries through the database write interceptor. Entries retain their id + parentId ancestry, including branches. Live derived event timestamps are monotonic even if the wall clock moves backwards; raw source timestamps are unchanged. Notable entry types:
  • 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
Provider-specific fixups and tool-output trimming are request projections, never rewrites of stored rows. Once a pruning decision is recorded, the trimmed view is sticky for the rest of the session: later requests keep the trimmed bytes instead of re-sending the original output. JSONL remains an export/import format: sessions.export synthesizes a session header and pages complete entries; it does not restore file-backed serving.

Tool output caps

Tool output is bounded before it ever reaches long-lived memory or storage:
  • In-memory source cap: a single tool result is truncated to at most 400,000 text characters when the agent receives it. Oversized text keeps a head-and-tail excerpt plus a size note; capped error results also keep short status/error fields.
  • Raw storage fallback: when database write-through is enabled, the full raw bytes are stored out-of-band, so the storage layer keeps the original output even though the model view is capped. Tool results are never unbounded in memory.
  • Pruning projection: on top of the source cap, session pruning can further trim old tool results in the request view. These trims are sticky per session (see Session pruning).

Context windows vs tracked tokens

Two different concepts matter:
  1. Model context window: hard cap per model (tokens visible to the model)
  2. Session index counters: rolling stats stored in SQL (used for /status and dashboards)
If you’re tuning limits:
  • 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.
For more, see /token-use.

Compaction: what it is

Compaction summarizes older conversation into a persisted compaction entry in the transcript and keeps recent messages intact. After compaction, future turns see:
  • The compaction summary
  • Messages after firstKeptEntryId
Compaction is persistent (unlike request-only session pruning): it appends a summary and a compaction event while retaining every earlier raw entry. sessions.compact runs model compaction; its deprecated maxLines parameter is ignored with a warning. See /concepts/session-pruning.

When auto-compaction happens (Pi runtime)

In the embedded Pi agent, auto-compaction triggers in two cases:
  1. Overflow recovery: the model returns a context overflow error → compact → retry.
  2. Threshold maintenance: after a successful turn, when:
contextTokens > contextWindow - reserveTokens Where:
  • contextWindow is the model’s context window
  • reserveTokens is headroom reserved for prompts + the next model output
These are Pi runtime semantics (WednesdayAI consumes the events, but Pi decides when to compact).

Compaction settings (reserveTokens, keepRecentTokens)

Pi’s compaction settings live in Pi settings:
WednesdayAI also enforces a safety floor for embedded runs:
  • If compaction.reserveTokens < reserveTokensFloor, WednesdayAI bumps it.
  • Default floor is 20000 tokens.
  • Set agents.defaults.compaction.reserveTokensFloor: 0 to disable the floor.
  • If it’s already higher, WednesdayAI leaves it alone.
Why: leave enough headroom for multi-turn “housekeeping” (like memory writes) before compaction becomes unavoidable.

User-visible surfaces

You can observe compaction and session state via:
  • /status (in any chat session)
  • wednesdayai status (CLI)
  • wednesdayai sessions / sessions --json
  • Verbose mode: 🧹 Auto-compaction complete + compaction count

Silent housekeeping (NO_REPLY)

WednesdayAI supports “silent” turns for background tasks where the user should not see intermediate output. Convention:
  • The assistant starts its output with NO_REPLY to indicate “do not deliver a reply to the user”.
  • WednesdayAI strips/suppresses this in the delivery layer.
As of 2026.1.10, WednesdayAI also suppresses draft/typing streaming when a partial chunk begins with NO_REPLY, so silent operations don’t leak partial output mid-turn.

Pre-compaction “memory flush” (implemented)

Goal: before auto-compaction happens, run a silent agentic turn that writes durable state to disk (e.g. memory/YYYY-MM-DD.md in the agent workspace) so compaction can’t erase critical context. WednesdayAI uses the pre-threshold flush approach:
  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.
Config (agents.defaults.compaction.memoryFlush):
  • enabled (default: true)
  • softThresholdTokens (default: 4000)
  • prompt (user message for the flush turn)
  • systemPrompt (extra system prompt appended for the flush turn)
Notes:
  • The default prompt/system prompt include a NO_REPLY hint to suppress delivery.
  • The flush runs once per compaction cycle (tracked in SQL session metadata).
  • 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.
Pi also exposes a session_before_compact hook in the extension API, but WednesdayAI’s flush logic lives on the Gateway side today.

Troubleshooting checklist

  • Session key wrong? Start with /concepts/session and confirm the sessionKey in /status.
  • Missing history? Confirm the gateway host and storage/import status with wednesdayai session-storage 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.