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)

// ~/.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.

2.6 KiB Raw Blame History