Agent Session State v2.1.4

Agents that serve multiple channels need structured per-channel state beyond what gateway transcripts capture. This skill provides curated agent-authored session files, a Write-Ahead Log (WAL) protocol for reliable decision capture, a working buffer for post-compaction context recovery, and a distillation workflow that promotes session-level state into topic files over time.

At a glance

OpenClaw already provides per-channel transcript isolation via session.dmScope, gateway-owned session history, automatic session maintenance and pruning, a silent memory flush before compaction, and sessions_history for reading prior transcripts. If that covers your needs — "keep different users' conversations separate" and "save durable facts before compaction summarizes the chat" — you do not need this skill.

This skill operates at a different layer. It adds curated agent-authored state files per channel at memory/sessions/{channel}.md, a Write-Ahead Log discipline that commits decisions and corrections to disk before the agent responds, a working buffer for post-compaction context recovery, and a distillation workflow that promotes session-level state into topic files over time. The files are notebooks the agent actively maintains, not transcripts of what was said. Transcripts tell you what was said; session state files tell you what was decided.

Install this skill if your agent needs structured, human-readable, long-lived notes about each channel's ongoing work; if you find yourself losing decisions mid-session because they are never committed anywhere durable; if you want continuity after compaction that goes beyond the memory flush's single-turn save; or if you need topic-aware recovery when working on projects that span multiple sessions. For multi-user agents, run it alongside session.dmScope = "per-channel-peer" — they are complementary, not redundant.

Relationship to OpenClaw native sessions

OpenClaw core handles transcript routing and raw history. The gateway owns session transcripts at ~/.openclaw/agents/<agentId>/sessions/ as JSONL per session, isolates them via session.dmScope, prunes them via session.maintenance, and exposes sessions_list, sessions_history, and session_status as agent tools. This skill does not replace any of that. If you run multiple users or channels, enable session.dmScope = "per-channel-peer" regardless of whether this skill is installed — that is what stops Alice's DMs from leaking into Bob's session at the routing level.

This skill handles curated agent-authored state in the workspace. memory/sessions/{channel}.md lives alongside topic files and daily notes in the agent workspace, is human-readable markdown, and is actively maintained by the agent with WAL entries and distillation rules. The paths do not collide with OpenClaw's transcript store. The two layers compose cleanly: transcripts are raw append-only history; session state files are curated decision logs the agent keeps on purpose.

OpenClaw's silent memory flush and this skill's WAL protocol also compose cleanly. Memory flush is reactive — a single turn that runs at the compaction boundary to save durable facts to MEMORY.md and daily notes. WAL is proactive — per-decision entries written throughout the session, before the agent responds. Different cadences, different granularities, no conflict. Run both.