OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Sessions and memory

The main session

OpenClaw is a personal agent first. Out of the box, every direct message you send it — from Telegram, WhatsApp, iMessage, Slack DMs, the web app, anywhere — lands in one rolling conversation: the main session. Ask something on your phone, follow up from your laptop, and the agent has the same context in both places. There is one brain, and this is where it thinks.

Under the hood the main session is an ordinary session with the canonical key agent:<agentId>:main (for example agent:main:main). The suffix is fixed; custom session.mainKey values are ignored. What makes it special is that the default DM scope collapses all direct messages into it, and that the rest of the system treats it as the agent's root: heartbeats wake it, background work reports back to it, and activity elsewhere flows up to it.

Home

In the web app, the main session is the Home page — the first entry in the sidebar. The identity row at the top is your agent (click it for the agent menu); Home is where you talk to it. Sessions that fork off the main conversation appear under Threads, group chats under Groups, and coding/CLI sessions under Coding.

Talk to Home while working

Select Talk to your Home agent in the sidebar footer (or press Cmd/Ctrl+Shift+H) to open Home beside your current page. The assistant sidebar can dock on the right or bottom. It follows the agent selected in the sidebar's agent switcher, so there is one place to change agents. Ask OpenClaw remains a separate system-care conversation in the same sidebar.

The dock uses your real Home conversation, including its history, tools, approvals, and message queue. Open Home full page opens that conversation in the main area and temporarily hides its dock to avoid duplicate composers.

Expand Working on to inspect the small reference snapshot accompanying your next message: the current page and, when available, the work session, workspace, and visible file path. Select text in the work area and use Attach selected text to include a bounded excerpt. Use Remove work context to send without the snapshot. It becomes part of the sent message and remains unchanged through queueing and retries; slash commands do not include it. References do not grant the Home agent additional access to another agent's sessions or files.

What flows into the main session

The main session is not just a chat log; it is the place where your agent's world converges:

  • Group activity. Under session.groupScope: "per-group" (the default), group and room sessions stay isolated while the main session automatically watches them. Activity queues up as compact notices — coalesced per conversation, never one wake-up per message — and the agent sees them the next time it runs: on your next message or on a scheduled heartbeat. Under the default agent visibility, the main session can use session tools across every session of the same agent; its system prompt names watched groups so it knows where recent activity happened.
  • Background work. Sub-agents and spawned sessions announce their results back to the session that started them, so work the agent kicked off from Home reports back to Home.
  • Heartbeats. Scheduled heartbeats target the main session, which is what turns queued notices into awareness even when you have not written anything.

Memory across resets and conversations

The rolling conversation is bounded by the model's context window, so continuity comes from layers around it:

  • MEMORY.md, the agent's curated long-term memory, is loaded into every fresh session. Daily notes (memory/YYYY-MM-DD.md) are searchable on demand and recent ones are re-primed after a /new or /reset. Before compaction, the agent flushes durable facts into the daily notes so long conversations do not silently lose them.
  • Memory recall across conversations lets the agent recall content from its other private sessions. On personal setups — global session.dmScope resolving to main with no per-binding DM overrides — it is enabled by default; any configured DM isolation turns it off unless you opt in explicitly. See Memory configuration.

A rolling session with durable history

The main session rolls forward through resets and compaction rather than making the model carry its entire history at once:

  • By default there is no automatic reset; compaction keeps the active context bounded while preserving the rolling session. Daily and idle resets are opt-in (see Session management). On /new and /reset, the tail of the ending conversation is saved to daily memory notes, and the next session re-primes recent notes. Reset assigns a new live session id but keeps the previous SQLite transcript searchable under the same main-session key.
  • When the conversation approaches the context window, compaction summarizes and continues in place — the transcript history stays in the session store.
  • Session lists show the current live conversation, not every historical session id behind it.
  • When the per-agent store's physical database, WAL, and session artifacts exceed the disk budget (default 10 GB), OpenClaw extracts the oldest unreferenced history to a verified compressed archive before removing its database rows. Live, routed, and in-flight sessions are never budget victims.

When you want isolation instead

The shared main session is the right default for an agent that only you talk to. If several people can message your agent, isolate DMs:

json5
{  session: {    dmScope: "per-channel-peer",  },}

With an isolating scope, each sender gets their own session and cross-conversation memory recall defaults off. Group watching remains controlled independently by session.groupScope: per-group keeps ambient main-session visibility, while main puts the room in the main conversation directly. openclaw security audit recommends DM isolation when it detects multiple senders. The full scope matrix, identity linking, and per-route overrides are covered in Session management and Channel routing.

Groups and rooms use separate sessions by default. To make selected trusted team rooms part of the rolling main conversation, set bindings[].session.groupScope: "main" on their route bindings. This changes the session key and shared context; mention gating and reply routing still use the originating room. See Session management.

Was this useful?
On this page

On this page