Implementing Guild-Scoped Sessions for Discord Channels

Current Behavior: Channel Isolation

With default configuration, each Discord channel operates with a completely isolated session. Users observe the following symptoms:

Context Loss When Switching Channels

// User in #general
User: "Hey, can you help me set up the CI pipeline?"
Bot:  "Sure! I'll help you configure the CI pipeline. You'll need..."

// User immediately moves to #requests
User: "What's the status of my CI pipeline setup?"
Bot:  "I don't have any record of discussing a CI pipeline setup. Could you provide more context?"

Session Key Isolation Evidence

# Active session keys in Redis/Memory
agent:abc123:discord:channel:1000000001  // #general
agent:abc123:discord:channel:1000000002  // #requests
agent:abc123:discord:channel:1000000003  // #logs
// Each channel has independent context - no cross-pollination

Bot-to-Bot Communication Breakdown

// #requests bot receives request
[requests-bot]: "Creating issue for CI pipeline setup..."
[requests-bot]: "@general-bot Can you confirm the user's access level?"

// #general bot responds
[general-bot]: "I don't see any recent CI-related discussion in this channel."

Long-Running Multi-Channel Workflows Require Repetition

• Users must restate context when moving between workflow channels
• Bot mentions in different channels provide no awareness of prior mentions
• Thread continuations lose parent channel context
• Memory file writes become a manual workaround instead of automatic behavior

Architectural Analysis

The session isolation occurs at the session key generation layer. The current implementation constructs session identifiers using a strict hierarchy:

// Current session key construction (simplified pseudocode)
function buildDiscordSessionKey(agentId, guildId, channelId, threadId) {
    if (threadId) {
        return `agent:${agentId}:discord:thread:${threadId}`;
    }
    return `agent:${agentId}:discord:channel:${channelId}`;
}

Why This Design Exists

1. Security Isolation: Channel-level permissions are enforced through separate session contexts
2. Message Filtering: Only messages from the current channel are included in context
3. Historical Behavior: Original Discord implementation assumed single-purpose bot usage
4. Storage Efficiency: Smaller per-session memory footprint

The Multi-Channel Workflow Gap

The architecture fails to account for guilds designed around collaborative workflows:

// Typical multi-channel guild structure
MyGuild/
├── #welcome          // Onboarding, rules
├── #general          // Casual chat, quick questions
├── #requests         // Task submissions, formal requests
├── #code-review      // PR discussions
├── #logs             // Automated outputs, notifications
└── #devops           // Infrastructure discussions

// User journey that breaks with channel isolation:
1. Discuss architecture in #devops
2. Create formal request in #requests (references #devops discussion)
3. Bot processes request without #devops context
4. User frustrated: "I just explained this 5 minutes ago!"

Configuration Gap

The current configuration schema lacks a mechanism to scope session boundaries:

// Current config structure - NO sessionScope option
{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "requireMention": true,
          "threadBindings": { "enabled": true },
          // sessionScope option does NOT exist
        }
      }
    }
  }
}

Memory Files as Inadequate Workaround

Users resort to memory files, but this creates additional problems:

Phase 1: Configuration Update

Step 1: Locate or create the guild configuration file

# Typical locations
config/channels/discord/guilds/{guildId}.json
config/discord/guilds/{guildId}.yaml
.env (for environment variable overrides)

Step 2: Add sessionScope to the guild configuration

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "requireMention": true,
          "threadBindings": {
            "enabled": true
          }
        }
      }
    }
  }
}

Step 3: Verify session scope is recognized (pre-flight check)

# Check if configuration is loaded correctly
node -e "
const config = require('./config/channels/discord/guilds/1234567890.json');
console.log('sessionScope:', config.sessionScope);
console.log('Valid values:', ['channel', 'guild']);
console.log('Is valid:', ['channel', 'guild'].includes(config.sessionScope));
"

Phase 2: Session Key Migration (If Upgrading)

Step 4: Migrate existing channel sessions to guild scope

# Backup existing sessions before migration
redis-cli KEYS "agent:*:discord:channel:*" > channel_sessions_backup.txt

# Or for file-based storage
cp -r sessions/ sessions_backup/

# Migrate command (if CLI tool available)
openclaw session migrate --guild 1234567890 --from channel --to guild

# Manual migration script example
node << 'EOF'
const { Redis } = require('ioredis');
const redis = new Redis();

async function migrateToGuildScope(guildId, agentId) {
    const channelKeys = await redis.keys(`agent:${agentId}:discord:channel:*`);
    const guildKey = `agent:${agentId}:discord:guild:${guildId}`;
    
    let migratedCount = 0;
    for (const key of channelKeys) {
        const data = await redis.get(key);
        if (data) {
            // Merge into guild session
            await redis.append(guildKey, '\n' + data);
            await redis.del(key);
            migratedCount++;
        }
    }
    console.log(`Migrated ${migratedCount} channel sessions to guild scope`);
}

migrateToGuildScope('1234567890', 'your-agent-id');
EOF

Phase 3: Channel-Specific Overrides

Step 5: Preserve channel-specific behaviors with overrides

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "requireMention": false,
          "threadBindings": {
            "enabled": true
          },
          // Per-channel overrides
          "channels": {
            "1000000001": {
              // #general - relaxed rules
              "requireMention": false
            },
            "1000000002": {
              // #requests - strict mention requirement
              "requireMention": true
            },
            "1000000003": {
              // #logs - read-only, no responses needed
              "requireMention": false,
              "sessionScope": "channel"
            }
          }
        }
      }
    }
  }
}

Phase 4: Compaction Configuration

Step 6: Configure aggressive compaction for guild-scoped sessions

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890": {
          "sessionScope": "guild",
          "compaction": {
            "strategy": "aggressive",
            "maxMessages": 100,
            "maxAgeMinutes": 60,
            "summarizeThreshold": 50,
            "preserveRecent": 10
          }
        }
      }
    }
  }
}

Verification 1: Session Key Structure

# Check that session keys now use guild scope
redis-cli KEYS "agent:*:discord:guild:*"

# Expected output (should show guild-scoped keys, not channel-scoped)
agent:abc123:discord:guild:1234567890
agent:abc123:discord:guild:9876543210

# Confirm channel keys are NOT present for the configured guild
redis-cli KEYS "agent:abc123:discord:channel:*"
# Should return: (empty list or only unrelated channels)

Verification 2: Cross-Channel Context Persistence

# Step 1: Send message in #general
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000001",
    "userId": "1111111111",
    "content": "I need to set up the production database connection"
  }'

# Step 2: Verify session contains this message
redis-cli GET "agent:abc123:discord:guild:1234567890" | grep -i "database"

# Step 3: Send message in #requests (different channel)
curl -X POST http://localhost:3000/api/test/simulate-message \
  -H "Content-Type: application/json" \
  -d '{
    "guildId": "1234567890",
    "channelId": "1000000002",
    "userId": "1111111111",
    "content": "What's the status of my database setup?"
  }'

# Step 4: Bot should respond WITH context from #general
# Check bot response includes reference to database conversation
# Expected: Response mentions "production database" conversation from #general

Verification 3: Channel-Specific Overrides Still Work

# Test mention requirement in #requests (configured as requireMention: true)
# Send DM (no mention) to #requests
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "Status?"}'

# Expected: Bot does NOT respond (mention required)
# OR
# Send with mention
curl -X POST http://localhost:3000/api/test/simulate-message \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "content": "@Bot Status?"}'

# Expected: Bot DOES respond

Verification 4: Thread Bindings Independence

# Create a thread in #requests
curl -X POST http://localhost:3000/api/test/create-thread \
  -d '{"guildId": "1234567890", "channelId": "1000000002", "parentMessageId": "xxx"}'

# Verify thread has its own session key (independent of guild scope)
redis-cli KEYS "agent:*:discord:thread:*"
# Expected: Thread sessions remain separate from guild session

Verification 5: Compaction Triggered Appropriately

# Enable debug logging
DEBUG=openclaw:session:compaction node index.js

# Generate enough messages to trigger compaction
# (Set maxMessages to a low number like 10 for testing)

# Monitor logs for compaction events
# Expected log entries:
# [DEBUG] openclaw:session:compaction - Compacting guild session (1234567890)
# [DEBUG] openclaw:session:compaction - Retained 10 recent messages
# [DEBUG] openclaw:session:compaction - Summary generated

Automated Integration Test

# Run the session scope integration tests
npm test -- --grep "guild-scoped-session"

# Expected test results:
# ✓ Guild session key generated correctly
# ✓ Cross-channel context preserved
# ✓ Channel-specific overrides respected
# ✓ Thread bindings remain independent
# ✓ Compaction triggers at threshold
# ✓ Session migration preserves history

Session-Related Errors

Configuration Errors

Memory/Storage Errors

Related GitHub Issues

• #847: "Memory files not persisting across bot restarts" - Memory file workaround limitations
• #1203: "Cross-channel context for multi-channel workflows" - Original feature request (superseded by this implementation)
• #1562: "Session compaction causing context loss" - Compaction configuration issues
• #1891: "Thread bindings ignore guild session scope" - Thread independence from session scope
• #2104: "Guild-scoped sessions cause privacy leaks" - Privacy zone implementation requests
• #2233: "Performance degradation with large guilds" - Memory and performance optimization

Related Configuration Options

# These options interact with sessionScope behavior:
sessionScope              // Primary configuration (channel | guild)
threadBindings.enabled    // Should remain independent of session scope
compaction.*              // Must be tuned for guild-scoped sessions
privacyZones              // Proposed option for excluding channels
messageWindow             // Limits messages pulled from session context