openclaw/docs/reference/session-management-compaction.md at main

mirror of https://github.com/openclaw/openclaw.git synced 2026-09-28 05:54:09 +08:00

Files

T

Vincent Koc 873a52f8f1 docs(reference): split the session management deep dive by reader job (#143082 )

The single page was 44,159 characters and 18 H2 sections mixing on-disk
reference, a disk-budget maintenance procedure, a downgrade runbook, four
key/default tables, compaction explanation, and a troubleshooting
checklist. It is now a short index over five child pages, one per reader
job, so a reader can finish one lookup on one page.

Children under docs/reference/session-management-compaction/:

- store.md - the two persistence layers and the per-agent on-disk paths
- maintenance.md - session.maintenance keys, the disk-budget cleanup
  tiers, cron run retention, and downgrading after the SQLite flip
- schema.md - sessionKey patterns, sessionId lifecycle, SessionEntry
  fields, and the transcript event stream
- compaction.md - what compaction is, when auto-compaction runs, its
  settings, pluggable providers, and its user-visible surfaces
- housekeeping.md - the NO_REPLY silent-turn contract and the
  pre-compaction memory flush

The index keeps the original lede, the Troubleshooting checklist, and
Related verbatim: the checklist is cross-cutting (its five bullets route
to four different children), so it belongs on the router.

Anchor strategy: per-anchor redirects are impossible (redirectSource()
throws on any source containing [?#]), so all 24 heading ids from the
previous single-page version stay alive on the index. 22 are authored
<a id="..." /> stubs linking to the child that now holds the content; the
remaining two (troubleshooting-checklist, related) are still published by
the index itself and are deliberately not stubbed, which would be a
duplicate authored/canonical id. Ids were computed with
parseDocsDocument, not a slug approximation. Four punctuated headings
each mint an encoded and a cleaned id (for example
compaction%3A-what-it-is and compaction-what-it-is); both members of every
pair are stubbed. Collisions are empty on the index and all five children,
and all 18 stub link targets resolve on their child.

Losslessness: the page has no intra-page ](#...) links, so no link
rewrites were needed and the split is byte-identical with no exceptions.
The shipped index lede + the five child bodies + the shipped
Troubleshooting and Related sections, concatenated in original order,
reproduce the previous body exactly:
sha256 1ee73287c171a5af95d4b50867bc035d54dd5e4b8039418780726fa113d33d14
(43,778 chars in, 43,778 out). 3 code fences in, 3 out, matching
one-for-one on info string and body sha256 (ee97c8dc34752b81,
2425950a4be6c02b, 30578e99ae85a0e4), so every command and config example
is character-identical. Table rows 22 -> 29 (+7 is the new routing
table). Body words 5,708 -> 5,999; the entire increase is index
scaffolding. The prose diff is empty: check-orphan-refs.py flags four
directional references, and all four are fine - three have same-page
antecedents ("the maintenance owner above", "the flush logic above") and
two are numeric comparisons ("above the cap", "below the compaction
threshold"), so none was rewritten.

docs.json gains a nested group following the reference/full-release-validation
precedent, which is the sibling split actually on main.
zh-Hans-navigation.json needs no change; it is a label overlay cloned
from the English nav. The zh-CN glossary needed five new sources for the
new child titles, inserted next to the existing "Session management deep
dive" entry rather than appended, so concurrent splits touch different
regions of the file.

Closes audit finding r3-0707; also addresses r3-2221.

2026-09-09 21:03:41 +09:00

6.4 KiB

Raw Permalink Blame History

summary, read_when, title

summary

read_when

title

Deep dive: session store + transcripts, lifecycle, and (auto)compaction internals

You need to debug session ids, transcript events, or session row fields

You are changing auto-compaction behavior or adding "pre-compaction" housekeeping

You want to implement memory flushes or silent system turns

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.

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 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+).

6.4 KiB Raw Permalink Blame History

Where each section moved

Troubleshooting checklist

Related

6.4 KiB

Raw Permalink Blame History