Sessions

A session is a conversation context. Each session has its own message history, working memory, and title. The agent maintains separate sessions for different chats, so conversations don't mix.

Session identity

Each session is identified by a combination of:

• Platform -- always telegram for now
• Chat ID -- the Telegram chat (DM, group, etc.)
• Thread ID -- the topic/thread within a forum-style group (if applicable)

This means each Telegram chat gets its own session automatically. In forum groups with topics, each topic gets its own session.

Main session

The first chat you message the bot from becomes the main session. It's special in a few ways:

• Messaging tools (send_message, list_known_chats) are only available here
• Long-term memory extraction only runs after main session conversations
• The agent reads MEMORY.md at the start of main sessions

This keeps personal context isolated from other chats.

Reply chain mode

BabyClaw supports two modes for session scoping:

Default mode

Sessions are scoped by chat (and thread, if in a forum group). All messages in a chat share the same session.

Reply-chain mode

When session.replyChainMode is "reply-chain", replying to a specific bot message continues that session's context. This is useful in groups where you might have multiple unrelated conversations.

{
  "session": {
    "replyChainMode": "reply-chain"
  }
}

Message history

Two settings control how much history the agent works with:

session.historyLimit

How many recent messages are included in the agent's context for each turn. Default is 40. Lower values mean less context but fewer tokens per turn.

session.maxMessagesPerSession

The maximum number of messages stored in a session before old ones are pruned. Default is 120. This is the total stored -- the agent only sees the most recent historyLimit messages.

Title generation

BabyClaw auto-generates a title for new sessions based on the first message. This helps identify sessions in logs and status output.

You can customize the model and prompt used for title generation:

{
  "session": {
    "titleGeneration": {
      "model": "anthropic:claude-haiku-3",
      "prompt": "Generate a short title for this conversation"
    }
  }
}

Both fields are optional. If not set, the chat model and a default prompt are used.

Session configuration