Summary

Allow per-topic bootstrap context for Telegram Forum topics, enabling different "identities" or specialized contexts for each topic without requiring separate agents.

Motivation

Telegram Forums (topic-based supergroups) are increasingly used to organize conversations by domain (e.g., "Work", "Personal", "Study", "Trading"). Currently, OpenClaw treats all messages in a group chat as belonging to the same session context, regardless of topic.

Users want to:

• Have topic-specific instructions (e.g., "In the 'Study' topic, always use academic tone")
• Maintain separate memory contexts per topic
• Avoid cross-contamination between unrelated conversations

Currently, the only solution is creating multiple agents and binding them manually, which is cumbersome for lightweight use cases.

Current Behavior

1. Topics are already recognized: session files are stored as {sessionId}-topic-{topicId}.jsonl
2. Bootstrap files (AGENTS.md, SOUL.md, USER.md) are loaded per agent, not per topic
3. All topics in a group share the same bootstrap context

Proposed Solution

Option A: Topic-Scoped Bootstrap Directory (Preferred)

Allow topic-specific bootstrap files in a subdirectory structure:

~/.openclaw/agents/main/
├── AGENTS.md                    # Global fallback
├── SOUL.md                      # Global fallback  
├── USER.md                      # Global fallback
├── MEMORY.md                    # Global fallback
└── topics/                      # NEW: topic-specific overrides
    ├── 1/                       # Topic ID 1 (e.g., "General")
    │   ├── AGENTS.md            # Merged with or replaces global
    │   └── TOPIC.md             # Optional: topic description/instructions
    ├── 7/                       # Topic ID 7 (e.g., "Study Notes")
    │   ├── AGENTS.md
    │   ├── SOUL.md
    │   └── MEMORY.md
    └── trading/                 # Could support topic names too
        └── AGENTS.md

Merge strategy:

• If topic-specific file exists, use it (complete override)
• OR merge: global first, then topic-specific appended with higher precedence
• TOPIC.md could auto-generate from Telegram's topic description

Option B: Extended Binding Syntax

Allow bindings to specify topic IDs:

{
  "bindings": [
    {
      "match": {
        "channel": "telegram",
        "chatId": "-1003747897206",
        "topicId": "7"
      },
      "agentId": "study-agent"
    }
  ]
}

This routes topics to different agents entirely.

Option C: Dynamic Context Injection

Add a hook that injects topic context into the system prompt:

// In AGENTS.md or via hook
{{topicContext}}  // Replaced with content from topics/{topicId}/TOPIC.md

Implementation Notes

Looking at the codebase:

1. Session paths already support topics:

   // paths-Bn3zjTqJ.js
   function resolveSessionTranscriptPathInDir(sessionId, sessionsDir, topicId) {
     const safeTopicId = typeof topicId === "string" ? encodeURIComponent(topicId) : 
                        typeof topicId === "number" ? String(topicId) : void 0;
     return resolvePathWithinSessionsDir(sessionsDir, 
       safeTopicId !== void 0 ? `${safeSessionId}-topic-${safeTopicId}.jsonl` : `${safeSessionId}.jsonl`);
   }

2. Bootstrap loading happens in agent-scope:

   // agent-scope-*.js
   const DEFAULT_AGENTS_FILENAME = "AGENTS.md";
   const DEFAULT_SOUL_FILENAME = "SOUL.md";
   const DEFAULT_USER_FILENAME = "USER.md";

3. The topicId is available in the inbound context (as seen in session metadata)

Suggested Implementation Path (Option A)

Modify pi-embedded-helpers-WkKFkFQ7.js (bootstrap loading):

async function loadBootstrapFiles(agentId: string, topicId?: string | number): Promise<BootstrapFile[]> {
  const globalFiles = await loadGlobalBootstrap(agentId);
  
  if (topicId) {
    const topicFiles = await loadTopicBootstrap(agentId, topicId);
    // Strategy: topic files override global files of same name
    return mergeBootstrapFiles(globalFiles, topicFiles);
  }
  
  return globalFiles;
}

Benefits

1. Lightweight: No need to create multiple agents for simple use cases
2. Intuitive: Matches Telegram's mental model (topics = separate spaces)
3. Backward Compatible: Falls back to global bootstrap if no topic-specific files exist
4. Token Efficient: Only loads relevant context for the current topic

Use Cases

1. Study Group: Topic 1 = General chat, Topic 7 = Math notes (academic tone, LaTeX formatting)
2. Trading Community: Topic 1 = General, Topic 2 = Signals (specific trading rules), Topic 3 = Analysis
3. Personal Organization: Topic 1 = Random, Topic 5 = Work tasks (professional tone), Topic 6 = Personal journal

Related Issues

• Multi-agent support already exists but is heavyweight for this use case
• Session isolation by topic already works (separate .jsonl files)

Version

v2026.3.2