picoclaw/docs/guides/session-guide.md

Session Guide

Back to README

PicoClaw sessions decide which messages share the same conversation history. If your bot "remembers too much" or "forgets too much", the first thing to check is the session configuration.

This guide is for users configuring session behavior in config.json. For implementation details, see the architecture docs instead.

What Sessions Control

A session controls:

• which previous messages are visible to the agent
• when summarization starts for that conversation
• whether two users in the same group share context
• whether different chats, threads, or spaces stay isolated

Session data is stored under your workspace, typically:

~/.picoclaw/workspace/sessions/

Quick Start

Default: one context per chat

This is the default and is the right choice for most bots.

{
  "session": {
    "dimensions": ["chat"]
  }
}

Use this when:

• each group/channel should have its own shared memory
• each direct message should have its own separate memory

Separate each user inside a group

If users in the same group should not share memory, add sender:

{
  "session": {
    "dimensions": ["chat", "sender"]
  }
}

Use this when:

• one shared assistant sits in a busy group
• each user should keep a private thread of context even inside the same room

Share one context across multiple rooms in the same workspace or guild

If your channel exposes a space value, you can route by workspace or guild instead of by room:

{
  "session": {
    "dimensions": ["space"]
  }
}

Use this when:

• a Slack workspace assistant should share context across channels
• a Discord guild assistant should share context across channels

Split by thread or forum topic

If your channel exposes topic, you can isolate per thread:

{
  "session": {
    "dimensions": ["chat", "topic"]
  }
}

Use this when:

• each forum topic should keep its own history
• each threaded discussion should stay separate

Available Dimensions

Dimension	What it means	Good for
space	Workspace, guild, or similar top-level container	One shared assistant across many rooms
chat	Direct chat, group, or channel	Default per-room isolation
topic	Thread, topic, or forum sub-channel	Keep threaded discussions separate
sender	The message sender after normalization	Per-user context inside shared rooms

Not every channel provides every field. If a channel does not supply space or topic, those dimensions simply have no effect for that message.

Important Behavior

Sessions are always separated by agent

Even if two agents receive messages from the same chat, they do not share one session.

Sessions are still separated by channel and account

session.dimensions adds finer-grained isolation, but PicoClaw still keeps a baseline separation by:

• agent
• channel
• account

That means an empty or very small dimensions list does not create one global memory across every platform.

Telegram forum topics already stay isolated in the default chat mode

Telegram forum messages keep topic isolation by default even when dimensions only contains chat. You usually do not need a special workaround for Telegram forums.

Summaries happen per session

summarize_message_threshold and summarize_token_percent apply inside each session independently. If you create smaller sessions, summarization also happens on smaller per-session histories.

Common Recipes

One shared assistant per group or direct chat

{
  "session": {
    "dimensions": ["chat"]
  }
}

One context per user inside each chat

{
  "session": {
    "dimensions": ["chat", "sender"]
  }
}

One context per sender across one workspace or guild

{
  "session": {
    "dimensions": ["space", "sender"]
  }
}

This is useful for workspace-wide assistants where each user should keep their own memory while moving across rooms in the same workspace.

Use a different session policy for one routed agent only

You can keep the global default and override it for one dispatch rule:

{
  "agents": {
    "list": [
      { "id": "main", "default": true },
      { "id": "support" }
    ],
    "dispatch": {
      "rules": [
        {
          "name": "support group",
          "agent": "support",
          "when": {
            "channel": "telegram",
            "chat": "group:-1001234567890"
          },
          "session_dimensions": ["chat", "sender"]
        }
      ]
    }
  },
  "session": {
    "dimensions": ["chat"]
  }
}

In this example:

• most traffic uses one shared context per chat
• the support group uses one context per user inside that chat

Identity Links

session.identity_links helps when the same user may appear under multiple raw sender IDs and you want PicoClaw to treat them as one sender identity.

Example:

{
  "session": {
    "dimensions": ["chat", "sender"],
    "identity_links": {
      "john": ["slack:u123", "u123", "legacy-user-42"]
    }
  }
}

This is mainly useful for:

• migrated sender IDs
• platform-specific ID aliases
• cleanup after changing channel adapters or account naming

Current limitation:

• identity_links does not make one user share memory across different channels automatically
• channel and account remain part of the baseline session scope

Troubleshooting

Users in one group are sharing memory

Your current session is probably keyed only by chat. Switch to:

{
  "session": {
    "dimensions": ["chat", "sender"]
  }
}

The same user does not share memory across Slack and Telegram

That is expected. PicoClaw still separates sessions by channel even if you use sender.

Threads are mixing together

Add topic when the channel provides one:

{
  "session": {
    "dimensions": ["chat", "topic"]
  }
}

Old sessions seem to use legacy keys

That is normal during migration. PicoClaw keeps compatibility with older agent:... session keys while moving runtime storage to opaque canonical keys.

Related Guides

• Configuration Guide
• Routing Guide
• Providers & Model Configuration