52 lines
2.6 KiB
Markdown
52 lines
2.6 KiB
Markdown
---
|
|
summary: "Session management rules, keys, and persistence for chats"
|
|
read_when:
|
|
- Modifying session handling or storage
|
|
---
|
|
# Session Management
|
|
|
|
Clawdis treats **one session as primary**. By default the canonical key is `main` for every direct chat; no configuration is required. You can rename it via `inbound.reply.session.mainKey` if you really want, but there is still only a single primary session. Older/local sessions can stay on disk, but only the primary key is used for desktop/web chat and direct agent calls.
|
|
|
|
## Where state lives
|
|
- Store file: `~/.clawdis/sessions/sessions.json` (legacy: `~/.clawdis/sessions.json`).
|
|
- Transcripts: `~/.clawdis/sessions/<SessionId>.jsonl` (one file per session id).
|
|
- The store is a map `sessionKey -> { sessionId, updatedAt, ... }`. Deleting entries is safe; they are recreated on demand.
|
|
|
|
## Mapping transports → session keys
|
|
- Direct chats (WhatsApp, Telegram, desktop Web Chat) all collapse to the **primary key** so they share context.
|
|
- Multiple phone numbers can map to that same key; they act as transports into the same conversation.
|
|
- Group chats still isolate state with `group:<jid>` keys; do not reuse the primary key for groups.
|
|
|
|
## Lifecyle
|
|
- Idle expiry: `inbound.reply.session.idleMinutes` (default 60). After the timeout a new `sessionId` is minted on the next message.
|
|
- Reset triggers: exact `/new` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through.
|
|
- Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
|
|
|
|
## Configuration (optional rename example)
|
|
```json5
|
|
// ~/.clawdis/clawdis.json
|
|
{
|
|
inbound: {
|
|
reply: {
|
|
session: {
|
|
scope: "per-sender", // keep group keys separate
|
|
idleMinutes: 120,
|
|
resetTriggers: ["/new"],
|
|
store: "~/.clawdis/sessions/sessions.json",
|
|
mainKey: "main" // optional rename; still a single primary
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Inspecting
|
|
- `pnpm clawdis status` — shows store path and recent sessions.
|
|
- `pnpm clawdis sessions --json` — dumps every entry (filter with `--active <minutes>`).
|
|
- Send `/status` 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).
|
|
- 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.
|