docs: The main session concept page and shipped-sidebar updates (#110905)

* docs: add The main session concept page and cross-links

* docs: precise memory-priming wording on the main-session page

* docs: update Control UI sidebar description to the Home and zones model

docs/channels/channel-routing.md

@@ -9,7 +9,8 @@ title: "Channel routing"
 
 OpenClaw routes replies **back to the channel where a message came from**. The
 model does not choose a channel; routing is deterministic and controlled by the
-host configuration.
+host configuration. Under the default DM scope, direct messages from every
+channel converge on the agent's [main session](/concepts/main-session).
 
 ## Key terms
 

docs/concepts/main-session.md

@@ -0,0 +1,102 @@
+---
+summary: "One rolling conversation across all your channels: the personal-agent default"
+read_when:
+  - You want to understand where your agent "lives"
+  - You expect the same context whether you write on Telegram, WhatsApp, or the web
+  - You want your agent to know what happens in groups and side threads
+title: "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](/reference/memory-config).
+
+## 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](/concepts/session)). 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](/concepts/session) and
+[Channel routing](/channels/channel-routing).
+
+## Related
+
+- [Session management](/concepts/session) — routing, scopes, resets
+- [Channel routing](/channels/channel-routing) — how agents and sessions are selected
+- [Memory](/concepts/memory) — durable memory layers
+- [Multi-agent](/concepts/multi-agent) — running several isolated agents

docs/concepts/session.md

@@ -11,6 +11,10 @@ OpenClaw routes every inbound message to a **session** based on where it came
 from: DMs, group chats, cron jobs, etc. All session state is owned by the
 **gateway**; UI clients query the gateway for session data.
 
+For the personal-agent default — one rolling conversation shared by all your
+DM channels, with group activity and background work flowing into it — see
+[The main session](/concepts/main-session).
+
 ## How messages are routed
 
 | Source          | Behavior                  |
@@ -42,12 +46,12 @@ visible to Bob.
 
 `session.dmScope` options:
 
-| Value                      | Behavior                                  |
-| -------------------------- | ----------------------------------------- |
-| `main` (default)           | All DMs share one session                 |
-| `per-peer`                 | Isolate by sender, across channels        |
-| `per-channel-peer`         | Isolate by channel + sender (recommended) |
-| `per-account-channel-peer` | Isolate by account + channel + sender     |
+| Value                      | Behavior                                                 |
+| -------------------------- | -------------------------------------------------------- |
+| `main` (default)           | All DMs share the [main session](/concepts/main-session) |
+| `per-peer`                 | Isolate by sender, across channels                       |
+| `per-channel-peer`         | Isolate by channel + sender (recommended)                |
+| `per-account-channel-peer` | Isolate by account + channel + sender                    |
 
 <Tip>
 If the same person contacts you from multiple channels, use

docs/docs.json

@@ -1232,6 +1232,7 @@
               {
                 "group": "Sessions and memory",
                 "pages": [
+                  "concepts/main-session",
                   "concepts/session",
                   "concepts/session-search",
                   "concepts/channel-docking",

docs/docs_map.md

@@ -2472,6 +2472,17 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
   - H2: Full list
   - H2: Related
 
+## concepts/main-session.md
+
+- Route: /concepts/main-session
+- Headings:
+  - H2: Home
+  - H2: What flows into the main session
+  - H2: Memory across resets and conversations
+  - H2: A rolling session, not an immortal one
+  - H2: When you want isolation instead
+  - H2: Related
+
 ## concepts/managed-worktrees.md
 
 - Route: /concepts/managed-worktrees

docs/web/control-ui.md

@@ -192,7 +192,7 @@ and [Linux](/platforms/linux) desktop apps, the
 
 ## Sidebar navigation
 
-The sidebar pins navigation above a scrollable session list. In multi-agent setups every agent appears as a collapsible top-level section; expanding an agent browses its sessions without navigating away from the open chat, and collapsed agents show an unread indicator. Within an agent the list splits into **Pinned**, one built-in section per connected channel (Telegram, Slack, WhatsApp, ...), a built-in **Work** section for sessions bound to a managed worktree or exec node (rows show a `repo ⎇ branch` line plus the node host), custom groups (the session `category`), and **Chats** for the rest. Channel and Work sections classify rows automatically; assigning a session to a custom group always wins. Opening a session moves the selection highlight without reordering the rows. Parent sessions with recent child runs show a disclosure and child count; expand it to inspect nested child sessions, live or terminal status, and runtime without leaving the sidebar. Selecting a child opens its chat and automatically reveals its ancestor path. Child rows stay outside root grouping, pinning, dragging, multi-select, and pagination. Sessions with new activity since they were last read show an unread dot, and opening one marks it read. Cloud-worker lifecycle states use a globe badge; local and reclaimed sessions omit a placement badge because local execution is the default. Each root session row has a context menu (kebab button or right-click) with Pin/Unpin, Mark as unread/read, Rename, Fork, Move to group (including New group and Remove from group), Archive, and Delete; touch layouts keep the direct pin and menu controls visible. Cmd/Ctrl-click toggles root rows into a multi-select and Shift-click extends it across the visible order; opening the menu on a selected row then offers batch actions (Mark N as unread/read, Move N to group, Archive N, Delete N) that apply to every selected session, with a single confirmation for batch delete. Drag a root session onto **Pinned** to pin it, or onto a custom group or **Chats** to move it. Custom group headers can be collapsed, expanded, or dragged to reorder them; group names and their order live in the gateway (`sessions.groups.*`), so they follow you across browsers, while the collapsed state stays in the browser profile. Group headers also have a menu (kebab button or right-click) with Rename group, New group, and Delete group; renaming or deleting a group updates every member session server-side, including archived ones, and deleting a group keeps its sessions and moves them back to Chats. The single **+** in the session-list header opens the New session page (see below). The sort control also has a Group by toggle: Grouped (default) or None for one flat list (Pinned stays separate); the choice is stored in the current browser profile. **Usage**, **Automations**, and **Plugins** are pinned by default; the **More** row opens a menu with every other destination, including plugin-provided tabs. Select **Edit pinned items** in that menu, or right-click the navigation area, to pin or unpin destinations and restore the defaults. The pinned set is stored in the current browser profile and survives reloads.
+The sidebar organizes everything around the agent. The identity row at the top is the active agent; below it, the **Pages** section starts with **Home** — the agent's rolling main session, badged with its unread or running state — followed by the pinned destinations (**Usage**, **Automations**, and **Plugins** by default). The customize control on the Pages header opens a menu with every other destination, including plugin-provided tabs, plus **Edit pinned items**; right-clicking the navigation area opens the pin editor directly. The session list below splits into zones: **Threads** for the agent's chat sessions (the main session stays behind Home; sessions it spawned appear here as top-level threads, and named threads show without a type prefix), **Groups** for group and room conversations, and **Coding** for sessions bound to a managed worktree or exec node (rows show a `repo ⎇ branch` line plus the node host), ACP-backed harness sessions, and the Codex/Claude CLI catalogs. Coding starts collapsed on first run and remembers your choice; its collapsed header keeps the true count and shows a running indicator while contained sessions work. Custom groups (the session `category`) and **Pinned** rows sit above Threads, and assigning a session to a custom group always wins over the automatic zone classification. The Threads header holds the sort control (Created or Last updated, plus a Group by toggle) and the **+** that opens the New session page. Opening a session moves the selection highlight without reordering rows. Parent sessions with recent child runs show a disclosure and child count; expand it to inspect nested child sessions, live or terminal status, and runtime without leaving the sidebar. Selecting a child opens its chat and automatically reveals its ancestor path. Child rows stay outside root grouping, pinning, dragging, multi-select, and pagination; collapsed zones do not consume the visible page budget. Sessions with new activity since they were last read show an unread dot, and opening one marks it read. Cloud-worker lifecycle states use a globe badge; local and reclaimed sessions omit a placement badge because local execution is the default. Each root session row has a context menu (kebab button or right-click) with Pin/Unpin, Mark as unread/read, Rename, Fork, Move to group (including New group and Remove from group), Archive, and Delete; touch layouts keep the direct pin and menu controls visible. Cmd/Ctrl-click toggles root rows into a multi-select and Shift-click extends it across the visible order; opening the menu on a selected row then offers batch actions (Mark N as unread/read, Move N to group, Archive N, Delete N) that apply to every selected session, with a single confirmation for batch delete. Drag a root session onto **Pinned** to pin it, or onto a custom group to move it. Custom group headers can be collapsed, expanded, or dragged to reorder them; group names and their order live in the gateway (`sessions.groups.*`), so they follow you across browsers, while collapsed state stays in the browser profile. Group headers also have a menu (kebab button or right-click) with Rename group, New group, and Delete group; renaming or deleting a group updates every member session server-side, including archived ones, and deleting a group keeps its sessions and moves them back to Threads.
 
 ## New session page
 
@@ -200,7 +200,7 @@ The **+** in the sidebar session-list header opens a full-page draft at `/new`:
 
 Inside **Settings**, the dedicated sidebar starts with a **Search settings** field for quickly finding settings sections.
 
-A **Search** field at the top of the sidebar opens the command palette (⌘K). Clicking the OpenClaw brand in the sidebar header opens the clean New session start screen. When something needs action — failed or overdue cron jobs, expiring or expired model auth — compact attention chips appear above the sidebar footer and click through to the owning page. The footer shows the active agent as a chip — avatar (identity image or emoji), name, connection dot, and a live subtitle — with a **+** for a new session. Clicking the chip opens the agent menu: an agent switcher (multi-agent setups), "What can this agent do?", **Agent settings**, **Settings**, mobile pairing, **Docs**, the build chip, and the color-mode toggle. Rosters above ten agents get a filter field and list pinned agents first; pin or unpin agents from the Agents settings page, with the pinned set stored in the browser profile. Choosing an agent scopes Chat plus Usage, Automations, Tasks, Workboard, and Sessions to that agent. Each scoped page exposes an **Agent** control with **All agents** as an escape; this widens the shared page scope without changing the concrete chat agent, while direct session links still open their target. The Agents settings page keeps its own `?agent=` selection and does not follow the shared page scope. When the gateway runs from a source checkout on a branch other than `main`, the footer also shows that branch name in red so a non-release gateway is obvious at a glance (release installs never show it). Shift-Command-Comma opens **Settings** without overriding the browser's Command-Comma shortcut. The sidebar header also holds the collapse toggle (⌘B); collapsing hides the sidebar entirely for a full-width workspace, and a floating expand control (or ⌘B) brings it back; the macOS app hosts that toggle natively in the titlebar instead. The sidebar is the only navigation chrome on desktop, with no top bar. Narrow viewports swap the sidebar for a slide-over drawer behind a compact header row holding the drawer toggle, brand, and command-palette search; on phones, Chat absorbs that navigation row into its title bar, with the menu and search controls beside the session title. In the macOS app the separate header row folds the titlebar clearance into a single compact strip beside the window controls. Navigation uses regular browser history, so the browser's back/forward buttons traverse it; the macOS app adds a native sidebar toggle next to the window controls plus trackpad swipe gestures, with back/forward buttons at the sidebar's right edge while it is expanded and native search (command palette) and new-session buttons while it is collapsed.
+A **Search** field at the top of the sidebar opens the command palette (⌘K). Clicking the agent identity row at the top of the sidebar opens the agent menu; **Home** opens the main session. When something needs action — failed or overdue cron jobs, expiring or expired model auth — compact attention chips appear above the sidebar footer and click through to the owning page. The identity row shows the agent's avatar (identity image or emoji), name, connection dot, and a live subtitle. Clicking it opens the agent menu: an agent switcher (multi-agent setups), "What can this agent do?", **Agent settings**, **Settings**, mobile pairing, **Docs**, the build chip, and the color-mode toggle. Rosters above ten agents get a filter field and list pinned agents first; pin or unpin agents from the Agents settings page, with the pinned set stored in the browser profile. Choosing an agent scopes Chat plus Usage, Automations, Tasks, Workboard, and Sessions to that agent. Each scoped page exposes an **Agent** control with **All agents** as an escape; this widens the shared page scope without changing the concrete chat agent, while direct session links still open their target. The Agents settings page keeps its own `?agent=` selection and does not follow the shared page scope. The footer bar holds the product logo, the build chip, a gateway connection dot, and a Settings shortcut. When the gateway runs from a source checkout on a branch other than `main`, the footer also shows that branch name in red so a non-release gateway is obvious at a glance (release installs never show it). Shift-Command-Comma opens **Settings** without overriding the browser's Command-Comma shortcut. The sidebar header also holds the collapse toggle (⌘B); collapsing hides the sidebar entirely for a full-width workspace, and a floating expand control (or ⌘B) brings it back; the macOS app hosts that toggle natively in the titlebar instead. The sidebar is the only navigation chrome on desktop, with no top bar. Narrow viewports swap the sidebar for a slide-over drawer behind a compact header row holding the drawer toggle, brand, and command-palette search; on phones, Chat absorbs that navigation row into its title bar, with the menu and search controls beside the session title. In the macOS app the separate header row folds the titlebar clearance into a single compact strip beside the window controls. Navigation uses regular browser history, so the browser's back/forward buttons traverse it; the macOS app adds a native sidebar toggle next to the window controls plus trackpad swipe gestures, with back/forward buttons at the sidebar's right edge while it is expanded and native search (command palette) and new-session buttons while it is collapsed.
 
 ## What it can do (today)