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 key agent:<agentId>:main (for example agent:main:main). 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.

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. Group and room sessions stay isolated (see below), but under the default DM scope 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. The agent can also read the sessions it watches, so "what did I miss in the family group?" works.
  • 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, not an immortal one

The main session rolls forward through resets and compaction rather than growing forever:

  • By default the session resets daily at 04:00 local time (configurable, or idle-based; 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.
  • When the conversation approaches the context window, compaction summarizes and continues in place — the transcript history stays in the session store.
  • The per-agent session store keeps archived transcripts until a disk budget (default 10 GB) evicts the oldest ones.

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, group watching from the main session is disabled, and cross-conversation memory recall defaults off. openclaw security audit recommends isolation when it detects multiple DM senders. The full scope matrix, identity linking, and per-route overrides are covered in Session management and Channel routing.

Was this useful?
On this page

On this page