> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Session Management Deep Dive

# 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:

* [/concepts/session](https://docs.wednesdayai.dev/next/developers/concepts/session.md)
* [/concepts/compaction](https://docs.wednesdayai.dev/next/developers/concepts/compaction.md)
* [/concepts/session-pruning](https://docs.wednesdayai.dev/next/developers/concepts/session-pruning.md)
* [/reference/transcript-hygiene](https://docs.wednesdayai.dev/next/developers/reference/transcript-hygiene.md)

***

## 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](https://docs.wednesdayai.dev/next/developers/concepts/session.md#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:

```bash theme={"dark"}
wednesdayai sessions cleanup --dry-run
wednesdayai sessions cleanup --enforce
```

***

## 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](https://docs.wednesdayai.dev/next/developers/concepts/session.md).

***

## 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](https://docs.wednesdayai.dev/next/developers/concepts/session-pruning.md)).

***

## 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](https://docs.wednesdayai.dev/next/developers/reference/token-use.md).

***

## 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](https://docs.wednesdayai.dev/next/developers/concepts/session-pruning.md).

***

## 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:

```json5 theme={"dark"}
{
  compaction: {
    enabled: true,
    reserveTokens: 16384,
    keepRecentTokens: 20000,
  },
}
```

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](https://docs.wednesdayai.dev/next/developers/concepts/memory.md) 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](https://docs.wednesdayai.dev/next/developers/concepts/session.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.