Sessions

A session is one conversation thread, identified by sessionKey. It can span channels, fork into branches, and survive gateway restarts.

Anatomy

{
  "id": "s_173...",
  "sessionKey": "telegram:12345",
  "agent": "bags-hunter",
  "messages": [
    { "role": "user", "content": "...", "timestamp": ..., "channel": "telegram" },
    { "role": "assistant", "content": "...", "timestamp": ..., "channel": "telegram" }
  ],
  "createdAt": ...,
  "updatedAt": ...,
  "metadata": { ... }
}

Storage

Each session is one JSON file at ~/.openvesper/workspace/sessions/<safe-key>.json with file mode 0600. Last 200 messages kept; older auto-trimmed.

Reset

# From inside chat
/reset

# Or API
curl -X POST http://127.0.0.1:18789/sessions/user-123/reset

Switch agent

# From inside chat
/agent defi-strategist

# Or API
curl -X POST http://127.0.0.1:18789/sessions/user-123/agent \
  -d '{"agent":"defi-strategist"}'

Fork — duplicate at current point

Create a new session with the same message history. Both can diverge from here independently:

curl -X POST http://127.0.0.1:18789/sessions/user-123/fork \
  -d '{"newSessionKey": "user-123-experiment-a"}'

Branch — fork at a specific message

Create a new session with only messages 0..N from the parent:

curl -X POST http://127.0.0.1:18789/sessions/user-123/branch \
  -d '{"newSessionKey": "user-123-rewind", "messageIndex": 5}'

Useful when you want to "rewind" — try a different path from message N without losing the original.

Token budget check

curl http://127.0.0.1:18789/sessions/user-123/tokens
# { "messageCount": 87, "estimatedTokens": 24530, "shouldAutoCompact": false }

Privacy

All session data on your machine. Not transmitted. See Security policy.