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)
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):-
Session index (
ctx_sessions)- Maps an agent’s
sessionKeyto the currentSessionEntry. - Tracks the current session id, activity, toggles, and token counters.
- Reset/delete use new session identities or tombstones, not transcript-file operations.
- Maps an agent’s
-
Conversation log (
ctx_session_entries)- Append-only entries with
id+parentIdtree structure. - Stores the conversation, full tool output, custom entries, and compaction summaries.
- Hydration rebuilds the active model context from these rows.
- Append-only entries with
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/-shmsidecars. - Override:
session.storage.sqlitePath; Postgres usessession.storage.databaseUrl. - Online SQLite snapshots:
~/.openclaw/backups/viawednesdayai session-storage backup. - Legacy
agents/<agentId>/sessions/sessions.jsonand*.jsonlare import sources only. Imported sources move to~/.openclaw/legacy-session-archive/.
Store maintenance and disk controls
session.maintenance controls the SQL session index:
mode:warn(default) reports eligible index entries without retiring them;enforceenables index cleanup.pruneAfter: index-entry age cutoff (default30d).maxEntries: cap on the current session index (default500), not a transcript entry limit.
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(default24h) tombstones old isolated cron session index rows (falsedisables). Conversation entries are never deleted and stay readable.cron.runLog.maxBytes+cron.runLog.keepLinesprune~/.openclaw/cron/runs/<jobId>.jsonlfiles (defaults:2_000_000bytes and2000lines).
Session keys (sessionKey)
A sessionKey identifies which conversation bucket you’re in (routing + isolation).
Common patterns:
- Main/direct chat (per agent):
agent:<agentId>:<mainKey>(defaultmain) - 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)
Each sessionKey points at a current sessionId (the database identity that continues the conversation).
Rules of thumb:
- Reset (
/new,/reset) creates a newsessionIdfor thatsessionKey. - Daily reset (default 4:00 AM local time on the gateway host) creates a new
sessionIdon the next message after the reset boundary. - Idle expiry (
session.reset.idleMinutesor legacysession.idleMinutes) creates a newsessionIdwhen a message arrives after the idle window. When daily + idle are both configured, whichever expires first wins. - Thread parent fork guard (
session.parentForkMaxTokens, default100000) skips parent transcript forking when the parent session is already too large; the new thread starts fresh. Set0to disable.
initSessionState() in src/auto-reply/reply/session.ts.
Session index schema
The store’s value type isSessionEntry in src/config/sessions.ts.
Key fields (not exhaustive):
sessionId: current conversation idupdatedAt: last activity timestamplastReplyAt: last assistant reply activity timestamp, also exposed bywednesdayai sessions --jsonsessionFile: deprecated legacy path hint; not a live transcript pathchatType:direct | group | room(helps UIs and send policy)provider,subject,room,space,displayName: metadata for group/channel labelinggroupActivation: group activation mode (mention|always) for group sessions; also exposed bywednesdayai sessions --jsonalongsideproviderOverride/modelOverride- Toggles:
thinkingLevel,verboseLevel,reasoningLevel,elevatedLevelsendPolicy(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 keymemoryFlushAt: timestamp for the last pre-compaction memory flushmemoryFlushCompactionCount: compaction count when the last flush ran
Conversation entry structure
The gateway hydrates an in-memorySessionManager 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 messagescustom_message: extension-injected messages that do enter model context (can be hidden from UI)custom: extension state that does not enter model contextcompaction: persisted compaction summary withfirstKeptEntryIdandtokensBeforebranch_summary: persisted summary when navigating a tree branch
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,000text characters when the agent receives it. Oversized text keeps a head-and-tail excerpt plus a size note; capped error results also keep shortstatus/errorfields. - 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:- Model context window: hard cap per model (tokens visible to the model)
- Session index counters: rolling stats stored in SQL (used for /status and dashboards)
- The context window comes from the model catalog (and can be overridden via config).
contextTokensin the store is a runtime estimate/reporting value; don’t treat it as a strict guarantee.
Compaction: what it is
Compaction summarizes older conversation into a persistedcompaction entry in the transcript and keeps recent messages intact.
After compaction, future turns see:
- The compaction summary
- Messages after
firstKeptEntryId
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:- Overflow recovery: the model returns a context overflow error → compact → retry.
- Threshold maintenance: after a successful turn, when:
contextTokens > contextWindow - reserveTokens
Where:
contextWindowis the model’s context windowreserveTokensis headroom reserved for prompts + the next model output
Compaction settings (reserveTokens, keepRecentTokens)
Pi’s compaction settings live in Pi settings:
- If
compaction.reserveTokens < reserveTokensFloor, WednesdayAI bumps it. - Default floor is
20000tokens. - Set
agents.defaults.compaction.reserveTokensFloor: 0to disable the floor. - If it’s already higher, WednesdayAI leaves it alone.
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_REPLYto indicate “do not deliver a reply to the user”. - WednesdayAI strips/suppresses this in the delivery layer.
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:
- Monitor session context usage.
- When it crosses a “soft threshold” (below Pi’s compaction threshold), run a silent “write memory now” directive to the agent.
- Use
NO_REPLYso the user sees nothing.
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)
- The default prompt/system prompt include a
NO_REPLYhint 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.
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
sessionKeyin/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 (
reserveTokenstoo 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.