Two persistence layers
- Session rows (per-agent SQLite) - key/value map
sessionKey -> SessionEntry. Mutable runtime state owned by the Gateway. Tracks metadata: current session id, last activity, toggles, token counters. - Transcript events (per-agent SQLite) - append-only, tree-structured (entries have
id+parentId). Stores the conversation, tool calls, and compaction summaries; rebuilds model context for future turns. Compaction summaries and available token measurements remain in the transcript without a separate checkpoint record or snapshot copy.
sessions.json files under the agent sessions/
directory. Treat those files as legacy session-row migration inputs or explicit
offline-maintenance targets. Gateway startup does not import them. Stop the
Gateway, back up its state, and use openclaw doctor --fix to import legacy rows
and transcript history into the per-agent SQLite store. Run
openclaw doctor --session-sqlite inspect --session-sqlite-all-agents, then
follow the Doctor migration sequence
for inspection and validation. If a migration fails after legacy transcript
artifacts were archived, use the Doctor recovery mode from that sequence.
Recovery uses migration manifests, restores only the affected archived support
artifacts, prepares a sanitized GitHub issue report when requested, and does not
make active runtime read JSONL files again.
Gateway history readers avoid materializing the whole transcript unless the surface needs arbitrary historical access. First-page history, embedded chat history, restart recovery, and token/usage checks use bounded tail reads from SQLite.
Disk-backed history pages run their SQLite reads and display preparation in a dedicated session-transcript worker. Equivalent requests can share a queued read until worker execution starts; completed pages are not cached. The Gateway applies current profile display and rechecks session identity and access before publishing. Cold restoration and projection rebuilds remain with the existing Gateway storage owner. Incognito history stays in the Gateway process, and bound external CLI imports retain their local import owner. The HTTP history endpoint still returns the complete history when no limit is supplied.
On-disk locations
Per agent, on the Gateway host (resolved viasrc/config/sessions.ts):
- Runtime session row store:
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite - Runtime transcript rows:
~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite - Legacy/archive transcript artifacts:
~/.openclaw/agents/<agentId>/sessions/ - Legacy row migration input:
~/.openclaw/agents/<agentId>/sessions/sessions.json