c415ccaed5
* feat(sessions): add channelIdleMinutes config for per-channel session idle durations
Add new `channelIdleMinutes` config option to allow different session idle
timeouts per channel. For example, Discord sessions can now be configured
to last 7 days (10080 minutes) while other channels use shorter defaults.
Config example:
sessions:
channelIdleMinutes:
discord: 10080 # 7 days
The channel-specific idle is passed as idleMinutesOverride to the existing
resolveSessionResetPolicy, integrating cleanly with the new reset policy
architecture.
* fix
* feat: add per-channel session reset overrides (#1353) (thanks @cash-echo-bot)
---------
Co-authored-by: Cash Williams <cashwilliams@gmail.com>
Co-authored-by: Peter Steinberger <steipete@gmail.com>
151 lines
8.9 KiB
Markdown
151 lines
8.9 KiB
Markdown
---
|
||
summary: "Session management rules, keys, and persistence for chats"
|
||
read_when:
|
||
- Modifying session handling or storage
|
||
---
|
||
# Session Management
|
||
|
||
Clawdbot treats **one direct-chat session per agent** as primary. Direct chats collapse to `agent:<agentId>:<mainKey>` (default `main`), while group/channel chats get their own keys. `session.mainKey` is honored.
|
||
|
||
Use `session.dmScope` to control how **direct messages** are grouped:
|
||
- `main` (default): all DMs share the main session for continuity.
|
||
- `per-peer`: isolate by sender id across channels.
|
||
- `per-channel-peer`: isolate by channel + sender (recommended for multi-user inboxes).
|
||
Use `session.identityLinks` to map provider-prefixed peer ids to a canonical identity so the same person shares a DM session across channels when using `per-peer` or `per-channel-peer`.
|
||
|
||
## Gateway is the source of truth
|
||
All session state is **owned by the gateway** (the “master” Clawdbot). UI clients (macOS app, WebChat, etc.) must query the gateway for session lists and token counts instead of reading local files.
|
||
|
||
- In **remote mode**, the session store you care about lives on the remote gateway host, not your Mac.
|
||
- Token counts shown in UIs come from the gateway’s store fields (`inputTokens`, `outputTokens`, `totalTokens`, `contextTokens`). Clients do not parse JSONL transcripts to “fix up” totals.
|
||
|
||
## Where state lives
|
||
- On the **gateway host**:
|
||
- Store file: `~/.clawdbot/agents/<agentId>/sessions/sessions.json` (per agent).
|
||
- Transcripts: `~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl` (Telegram topic sessions use `.../<SessionId>-topic-<threadId>.jsonl`).
|
||
- The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
|
||
- Group entries may include `displayName`, `channel`, `subject`, `room`, and `space` to label sessions in UIs.
|
||
- Session entries include `origin` metadata (label + routing hints) so UIs can explain where a session came from.
|
||
- Clawdbot does **not** read legacy Pi/Tau session folders.
|
||
|
||
## Session pruning
|
||
Clawdbot trims **old tool results** from the in-memory context right before LLM calls by default.
|
||
This does **not** rewrite JSONL history. See [/concepts/session-pruning](/concepts/session-pruning).
|
||
|
||
## Pre-compaction memory flush
|
||
When a session nears auto-compaction, Clawdbot can run a **silent memory flush**
|
||
turn that reminds the model to write durable notes to disk. This only runs when
|
||
the workspace is writable. See [Memory](/concepts/memory) and
|
||
[Compaction](/concepts/compaction).
|
||
|
||
## Mapping transports → session keys
|
||
- Direct chats follow `session.dmScope` (default `main`).
|
||
- `main`: `agent:<agentId>:<mainKey>` (continuity across devices/channels).
|
||
- Multiple phone numbers and channels can map to the same agent main key; they act as transports into one conversation.
|
||
- `per-peer`: `agent:<agentId>:dm:<peerId>`.
|
||
- `per-channel-peer`: `agent:<agentId>:<channel>:dm:<peerId>`.
|
||
- If `session.identityLinks` matches a provider-prefixed peer id (for example `telegram:123`), the canonical key replaces `<peerId>` so the same person shares a session across channels.
|
||
- Group chats isolate state: `agent:<agentId>:<channel>:group:<id>` (rooms/channels use `agent:<agentId>:<channel>:channel:<id>`).
|
||
- Telegram forum topics append `:topic:<threadId>` to the group id for isolation.
|
||
- Legacy `group:<id>` keys are still recognized for migration.
|
||
- Inbound contexts may still use `group:<id>`; the channel is inferred from `Provider` and normalized to the canonical `agent:<agentId>:<channel>:group:<id>` form.
|
||
- Other sources:
|
||
- Cron jobs: `cron:<job.id>`
|
||
- Webhooks: `hook:<uuid>` (unless explicitly set by the hook)
|
||
- Node bridge runs: `node-<nodeId>`
|
||
|
||
## Lifecycle
|
||
- Reset policy: sessions are reused until they expire, and expiry is evaluated on the next inbound message.
|
||
- Daily reset: defaults to **4:00 AM local time on the gateway host**. A session is stale once its last update is earlier than the most recent daily reset time.
|
||
- Idle reset (optional): `idleMinutes` adds a sliding idle window. When both daily and idle resets are configured, **whichever expires first** forces a new session.
|
||
- Legacy idle-only: if you set `session.idleMinutes` without any `session.reset`/`resetByType` config, Clawdbot stays in idle-only mode for backward compatibility.
|
||
- Per-type overrides (optional): `resetByType` lets you override the policy for `dm`, `group`, and `thread` sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
|
||
- Per-channel overrides (optional): `resetByChannel` overrides the reset policy for a channel (applies to all session types for that channel and takes precedence over `reset`/`resetByType`).
|
||
- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. `/new <model>` accepts a model alias, `provider/model`, or provider name (fuzzy match) to set the new session model. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
|
||
- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
|
||
- Isolated cron jobs always mint a fresh `sessionId` per run (no idle reuse).
|
||
|
||
## Send policy (optional)
|
||
Block delivery for specific session types without listing individual ids.
|
||
|
||
```json5
|
||
{
|
||
session: {
|
||
sendPolicy: {
|
||
rules: [
|
||
{ action: "deny", match: { channel: "discord", chatType: "group" } },
|
||
{ action: "deny", match: { keyPrefix: "cron:" } }
|
||
],
|
||
default: "allow"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
Runtime override (owner only):
|
||
- `/send on` → allow for this session
|
||
- `/send off` → deny for this session
|
||
- `/send inherit` → clear override and use config rules
|
||
Send these as standalone messages so they register.
|
||
|
||
## Configuration (optional rename example)
|
||
```json5
|
||
// ~/.clawdbot/clawdbot.json
|
||
{
|
||
session: {
|
||
scope: "per-sender", // keep group keys separate
|
||
dmScope: "main", // DM continuity (set per-channel-peer for shared inboxes)
|
||
identityLinks: {
|
||
alice: ["telegram:123456789", "discord:987654321012345678"]
|
||
},
|
||
reset: {
|
||
// Defaults: mode=daily, atHour=4 (gateway host local time).
|
||
// If you also set idleMinutes, whichever expires first wins.
|
||
mode: "daily",
|
||
atHour: 4,
|
||
idleMinutes: 120
|
||
},
|
||
resetByType: {
|
||
thread: { mode: "daily", atHour: 4 },
|
||
dm: { mode: "idle", idleMinutes: 240 },
|
||
group: { mode: "idle", idleMinutes: 120 }
|
||
},
|
||
resetByChannel: {
|
||
discord: { mode: "idle", idleMinutes: 10080 }
|
||
},
|
||
resetTriggers: ["/new", "/reset"],
|
||
store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
|
||
mainKey: "main",
|
||
}
|
||
}
|
||
```
|
||
|
||
## Inspecting
|
||
- `clawdbot status` — shows store path and recent sessions.
|
||
- `clawdbot sessions --json` — dumps every entry (filter with `--active <minutes>`).
|
||
- `clawdbot gateway call sessions.list --params '{}'` — fetch sessions from the running gateway (use `--url`/`--token` for remote gateway access).
|
||
- Send `/status` as a standalone message in chat to see whether the agent is reachable, how much of the session context is used, current thinking/verbose toggles, and when your WhatsApp web creds were last refreshed (helps spot relink needs).
|
||
- Send `/context list` or `/context detail` to see what’s in the system prompt and injected workspace files (and the biggest context contributors).
|
||
- Send `/stop` as a standalone message to abort the current run, clear queued followups for that session, and stop any sub-agent runs spawned from it (the reply includes the stopped count).
|
||
- Send `/compact` (optional instructions) as a standalone message to summarize older context and free up window space. See [/concepts/compaction](/concepts/compaction).
|
||
- JSONL transcripts can be opened directly to review full turns.
|
||
|
||
## Tips
|
||
- Keep the primary key dedicated to 1:1 traffic; let groups keep their own keys.
|
||
- When automating cleanup, delete individual keys instead of the whole store to preserve context elsewhere.
|
||
|
||
## Session origin metadata
|
||
Each session entry records where it came from (best-effort) in `origin`:
|
||
- `label`: human label (resolved from conversation label + group subject/channel)
|
||
- `provider`: normalized channel id (including extensions)
|
||
- `from`/`to`: raw routing ids from the inbound envelope
|
||
- `accountId`: provider account id (when multi-account)
|
||
- `threadId`: thread/topic id when the channel supports it
|
||
The origin fields are populated for direct messages, channels, and groups. If a
|
||
connector only updates delivery routing (for example, to keep a DM main session
|
||
fresh), it should still provide inbound context so the session keeps its
|
||
explainer metadata. Extensions can do this by sending `ConversationLabel`,
|
||
`GroupSubject`, `GroupChannel`, `GroupSpace`, and `SenderName` in the inbound
|
||
context and calling `recordSessionMetaFromInbound` (or passing the same context
|
||
to `updateLastRoute`).
|