<!-- source: https://deepwiki.com/openclaw/openclaw/2.4-session-and-state-management -->

# Session & State Management

- extensions/codex/src/app-server/native-execution-policy.test.ts
- extensions/codex/src/app-server/native-execution-policy.ts
- extensions/codex/src/app-server/transcript-mirror.test.ts
- extensions/codex/src/app-server/transcript-mirror.ts
- src/agents/agent-command.compaction-rotation.test.ts
- src/agents/cli-backends.ts
- src/agents/command/attempt-execution.cli.test.ts
- src/agents/command/attempt-execution.ts
- src/agents/command/session-store.test.ts
- src/agents/command/session-store.ts
- src/agents/embedded-agent-runner/types.ts
- src/agents/live-model-switch.test.ts
- src/agents/live-model-switch.ts
- src/agents/model-picker-visibility.ts
- src/agents/model-runtime-aliases.test.ts
- src/agents/model-runtime-aliases.ts
- src/agents/tools/media-tool-shared.test.ts
- src/auto-reply/fallback-state.test.ts
- src/auto-reply/fallback-state.ts
- src/commands/doctor-session-snapshots.test.ts
- src/commands/doctor-session-snapshots.ts
- src/config/sessions.cache.test.ts
- src/config/sessions/disk-budget.test.ts
- src/config/sessions/disk-budget.ts
- src/config/sessions/lifecycle.ts
- src/config/sessions/sessions.test.ts
- src/config/sessions/skill-prompt-blobs.ts
- src/config/sessions/store-cache.ts
- src/config/sessions/store-load.ts
- src/config/sessions/store.skills-stripping.test.ts
- src/config/sessions/store.ts
- src/config/sessions/targets.test.ts
- src/config/sessions/transcript-append.ts
- src/config/sessions/transcript-write-context.ts
- src/config/sessions/transcript.test.ts
- src/config/sessions/transcript.ts
- src/config/sessions/types.ts
- src/cron/isolated-agent/run.interim-retry.test.ts
- src/cron/isolated-agent/run.skill-filter.test.ts
- src/cron/isolated-agent/session.test.ts
- src/cron/isolated-agent/subagent-followup.test.ts
- src/gateway/server.sessions.store-rpc.test.ts
- src/gateway/session-utils.search.test.ts
- src/gateway/session-utils.single-row-cache.test.ts
- src/gateway/session-utils.test.ts
- src/gateway/session-utils.ts
- src/gateway/session-utils.types.ts
- src/infra/json-files.test.ts
- src/infra/json-files.ts
- src/plugins/session-entry-slot-keys.ts
- src/shared/session-types.ts
- src/tui/gateway-chat.ts
- src/tui/tui-backend.ts
- ui/src/ui/chat/slash-command-executor.node.test.ts
- ui/src/ui/chat/slash-command-executor.ts

This page documents OpenClaw's session and state management system, including session scoping models, storage formats, directory organization, and lifecycle management. Sessions control conversation continuity and isolation across channels, peers, and agents.

## Session Scoping Models

OpenClaw supports multiple session scoping strategies to control conversation isolation. The scoping model determines whether conversations are shared across channels or isolated per sender.

### Scoping Modes

The system identifies sessions using a `sessionKey`. The Gateway distinguishes between persistent user sessions and synthetic runtime sessions like `cron`, `subagent`, or `acp` (Agent Control Protocol) [src/routing/session-key.js86-91](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.js#L86-L91)

### Session Key Resolution

The system resolves a unique `sessionKey` for every inbound message. This key typically follows the pattern `agent:<agentId>:<channel>:<kind>:<id>` [src/routing/session-key.js72-73](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.js#L72-L73) Keys are parsed and categorized using utility functions like `parseAgentSessionKey` [src/routing/session-key.js90](https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.js#L90-L90)

**Code Entity Space: Session Key Resolution**

```

```

Sources: `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/routing/session-key.js#L72-L91" min=72 max=91 file-path="src/routing/session-key.js">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/session-utils.ts#L72-L77" min=72 max=77 file-path="src/gateway/session-utils.ts">Hii</FileRef>`

## Session Storage

OpenClaw persists sessions in two distinct layers to balance performance and durability.

### 1. Metadata Store ( sessions.json )

The `sessions.json` file (the "Store") maps a `sessionKey` to a `SessionEntry` object. It is managed by `SessionManager` and accessed via `loadSessionStore` [src/config/sessions/store.ts42-46](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L42-L46)

### 2. Transcript ( .jsonl )

Transcripts are append-only **JSONL** files containing the full conversation history, tool calls, and metadata.

- Structure: Each line is a JSON object representing an AgentMessage or metadata entry src/config/sessions/transcript.ts 62-75
- Persistence: Messages are appended via appendSessionTranscriptMessage src/config/sessions/transcript.ts 19 which ensures sequential writes using runWithOwnedSessionTranscriptWriteLock src/config/sessions/transcript.ts 25
- User Turn Persistence: appendUserTurnTranscriptMessage manages the recording of user messages, ensuring metadata is attached before writing to disk src/agents/command/attempt-execution.ts 21-23
- Tail Reading: The system uses readTailAssistantTextFromSessionTranscript to verify the last message in a transcript before appending new turns, preventing duplicates src/config/sessions/transcript.ts 172-180

Sources: `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L42-L46" min=42 max=46 file-path="src/config/sessions/store.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/types.ts#L33-L34" min=33 max=34 file-path="src/config/sessions/types.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/transcript.ts#L19-L180" min=19 max=180 file-path="src/config/sessions/transcript.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/attempt-execution.ts#L21-L23" min=21 max=23 file-path="src/agents/command/attempt-execution.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store-load.ts#L173-L181" min=173 max=181 file-path="src/config/sessions/store-load.ts">Hii</FileRef>`

## State Directory Organization

OpenClaw organizes state by Agent ID to ensure isolation. The `resolveAgentWorkspaceDir` function determines the root workspace for an agent [src/gateway/session-utils.ts17](https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/session-utils.ts#L17-L17)

```

```

Sources: `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/gateway/session-utils.ts#L17-L169" min=17 max=169 file-path="src/gateway/session-utils.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/sessions.test.ts#L57-L57" min=57  file-path="src/config/sessions/sessions.test.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L19-L19" min=19  file-path="src/config/sessions/store.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/transcript.ts#L31-L41" min=31 max=41 file-path="src/config/sessions/transcript.ts">Hii</FileRef>`

## Session Lifecycle & Maintenance

### Initialization & Run Flow

When an agent run starts, `resolveSessionTranscriptFile` resolves the session context [src/config/sessions/transcript.ts105-113](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/transcript.ts#L105-L113) This involves checking for session existence and resolving the session file path [src/config/sessions/transcript.ts118-130](https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/transcript.ts#L118-L130)

**Code Entity Space: Lifecycle Implementation**

```

```

Sources: `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/transcript.ts#L105-L148" min=105 max=148 file-path="src/config/sessions/transcript.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/attempt-execution.ts#L21-L41" min=21 max=41 file-path="src/agents/command/attempt-execution.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L59-L59" min=59  file-path="src/config/sessions/store.ts">Hii</FileRef>`

### Maintenance & Pruning

Sessions undergo periodic maintenance to manage disk usage and performance:

- Disk Budget: enforceSessionDiskBudget performs sweeps to ensure session files do not exceed allocated space src/config/sessions/store.ts 17
- Stale Entry Pruning: pruneStaleEntries removes session metadata for sessions that have not been updated within a specific threshold src/config/sessions/store.ts 53
- Write Locking: All transcript writes are guarded by acquireSessionWriteLock to prevent corruption during concurrent agent turns src/agents/command/attempt-execution.ts 41
- Cache Management: invalidateSessionStoreCache ensures that in-memory session metadata stays synchronized with disk during multi-process operations src/config/sessions/store.ts 33
- In-Memory Interning: Large strings (like skill prompts) are interned using internSessionStoreLargeStrings to reduce memory pressure during store loading src/config/sessions/store-cache.ts 121-125

### Reliability & Failover

If a session becomes corrupted or an agent execution fails, the system uses `FailoverError` to classify the reason (e.g., `AbortError`) and determines if the reused CLI session should be cleared [src/agents/command/attempt-execution.ts59-64](https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/attempt-execution.ts#L59-L64)

Sources: `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L17-L53" min=17 max=53 file-path="src/config/sessions/store.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/agents/command/attempt-execution.ts#L41-L64" min=41 max=64 file-path="src/agents/command/attempt-execution.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store.ts#L33-L33" min=33  file-path="src/config/sessions/store.ts">Hii</FileRef>`, `<FileRef file-url="https://github.com/openclaw/openclaw/blob/fbdf5937/src/config/sessions/store-cache.ts#L121-L125" min=121 max=125 file-path="src/config/sessions/store-cache.ts">Hii</FileRef>`
