Session Isolation

Type: OpenClaw concurrency and memory model

Definition

Every conversation in OpenClaw runs in its own isolated session with a dedicated message history and agent instance. Sessions provide memory isolation between concurrent conversations and enable the multi-agent system where sub-agents run as independent sessions with their own context windows. The main session is labeled agent:main:main; sub-agents get agent:main:subagent:{id}. Sessions have finite context windows — older content gets automatically compacted when the window fills up.

How It Works

When you start a conversation, the Gateway creates a new session or resumes an existing one. Each session maintains a message history that fills the context window. When that window fills, older content is compacted (summarized and compressed) to make room. This is a fundamental design constraint: you cannot assume everything from early in a session is still available.

The subagents tool is the mechanism for creating child sessions: subagents spawn creates a labeled sub-agent session (agent:main:subagent:{id}); subagents list shows all running sessions; subagents steer sends additional instructions to a running agent; subagents kill stops one. Multiple sessions can run simultaneously, enabling true parallelism.

Session isolation means a sub-agent's context doesn't leak into the main session or other sub-agents. Each has its own context window, message history, and tool scope. This is what enables the parallel research pattern — three research agents simultaneously covering three competitors in 5 minutes instead of 15 sequentially, each running in its own isolated context.

Context overflow signs include: forgotten earlier instructions, repeated questions, and [compacted: tool output removed] messages. Recovery involves writing current state to a file and starting fresh with the file as context.

Key Properties

  • Session labeling — main session is agent:main:main; sub-agents are agent:main:subagent:{id}
  • Context window compaction — older content is automatically summarized when the window fills up
  • Isolated memory — each session has its own message history; no cross-contamination
  • Sub-agent lifecycle — spawn, list, steer, kill tools manage session creation and teardown
  • Parallel execution — multiple sessions run simultaneously enabling concurrent work
  • Recovery via files — when context overflows, write state to file and resume with file as context

Source Chapters