Issue Station
Sign In
Tools hereToolbox

openclaw - 💡(How to fix) Fix [RFC] Multi-Session Architecture: Shared LLM + Isolated Sessions + Public Knowledge Base [4 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#48874•Fetched 2026-04-08 00:51:36
View on GitHub
Comments
4
Participants
2
Timeline
16
Reactions
0
Author
KilimiaoSixKilimiaoSix
Participants
ArtyomkunArtyomkunKilimiaoSixKilimiaoSix
Timeline (top)
mentioned ×5subscribed ×5commented ×4referenced ×2

Proposing a new Session management architecture:

  • Shared LLM Layer: All sessions share the same model inference instance, saving resources
  • Isolated Session Layer: Each channel/task has independent context and short-term memory, isolated from each other
  • Public Knowledge Base Layer: Shared knowledge via RAG, accessible by all sessions

Additionally, extending WebUI session management capabilities to support creating, archiving, and restoring sessions.

Root Cause

Proposing a new Session management architecture:

  • Shared LLM Layer: All sessions share the same model inference instance, saving resources
  • Isolated Session Layer: Each channel/task has independent context and short-term memory, isolated from each other
  • Public Knowledge Base Layer: Shared knowledge via RAG, accessible by all sessions

Additionally, extending WebUI session management capabilities to support creating, archiving, and restoring sessions.

Code Example

┌─────────────────┐
                      │   Shared LLM    │
                      │    (Inference)  │
                      └────────┬────────┘
                               │
          ┌────────────────────┼────────────────────┐
          │                    │                    │
          ▼                    ▼                    ▼
   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
   │  Session A  │      │  Session B  │      │  Session C  │
   │  (Feishu)   │      │  (Webchat)  │      │   (Cron)    │
   │             │      │             │      │             │
   │ Independent │      │ Independent │      │ Independent │
   │  Context    │      │  Context    │      │  Context    │
   └──────┬──────┘      └──────┬──────┘      └──────┬──────┘
          │                    │                    │
          └────────────────────┼────────────────────┘
                               │
                      ┌────────▼────────┐
                      │ Public Knowledge │
                      │    Base (RAG)    │
                      │  MEMORY.md etc.  │
                      └─────────────────┘

---

type SessionEntry = {
  // ... existing fields
  status?: 'active' | 'archived' | 'pinned';
  archivedAt?: number;
  archivedReason?: string;
  tags?: string[];           // User-defined tags
  title?: string;            // User-defined title
  channelBinding?: string;   // Bound channel identifier
};

---

# Configuration example
channels:
  feishu:
    sessionBinding: isolated    # Independent session
    
  telegram:
    sessionBinding: isolated
    
  cron:
    sessionBinding: ephemeral   # Temporary session, destroyed after task completion

session:
  isolation:
    enabled: true
    defaultScope: per-channel   # per-channel | per-sender | global

---

~/.openclaw/agents/main/
├── session-store.json          # Active sessions only
├── sessions/
│   └── *.jsonl                 # Active session transcripts
└── archived/
    ├── archived-store.json     # Archive metadata
    └── sessions/
        └── *.jsonl             # Archived transcripts

---

┌─────────────────────────────────────────────────────────────┐
│  Sessions                                    [+ New] [Archive]│
├─────────────────────────────────────────────────────────────┤
│  [Active] [Archived] [All]                    🔍 Search...   │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 📌 Feishu Bot Config     direct   2026-03-17  pinned   │    │
│  │ 📝 Webchat Daily Chat    direct   2026-03-17  active   │    │
│  │ 📝 Telegram Chat         direct   2026-03-16  active   │    │
│  │ 📦 Old Project Discussion direct   2026-03-10  archived│    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  [Load] [Archive] [Restore] [Delete]                        │
└─────────────────────────────────────────────────────────────┘

---

POST /api/sessions/create
  - Create new session, returns sessionKey
  - Body: { label?, tags?, scope? }

POST /api/sessions/:key/archive
  - Archive session (move to archived/)

POST /api/sessions/:key/restore
  - Restore archived session

GET /api/sessions/archived
  - List archived sessions

POST /api/sessions/:key/pin
  - Pin session (exempt from auto-cleanup)
RAW_BUFFERClick to expand / collapse

[RFC] Multi-Session Architecture: Shared LLM + Isolated Sessions + Public Knowledge Base

Summary

Proposing a new Session management architecture:

  • Shared LLM Layer: All sessions share the same model inference instance, saving resources
  • Isolated Session Layer: Each channel/task has independent context and short-term memory, isolated from each other
  • Public Knowledge Base Layer: Shared knowledge via RAG, accessible by all sessions

Additionally, extending WebUI session management capabilities to support creating, archiving, and restoring sessions.

Motivation

Current Problems

  1. Insufficient Session Isolation

    • All channels (Feishu, Telegram, Webchat, Cron) share the same main session
    • A long-running task blocking affects all channels
    • Context from different channels gets mixed, affecting user experience

  2. Multi-Channel Routing Issues (Related issues: #41790, #45514)

    • session.mainKey config exists but is overridden by hardcoded values
    • When using dmScope: "per-channel-peer", heartbeats and cron tasks are sent to the wrong session
    • Replies may be sent to wrong channel (lastChannel issue)

  3. Missing WebUI Session Management

    • Cannot create new sessions
    • Cannot archive/restore sessions
    • Reset session history is not visible

  4. Resource Utilization Issues

    • Each session has independent context, but LLM instance is shared - lacks clear architectural layering
    • Public knowledge (MEMORY.md, etc.) has no unified RAG integration mechanism

Proposed Solution

Architecture Design

                      ┌─────────────────┐
                      │   Shared LLM    │
                      │    (Inference)  │
                      └────────┬────────┘
                               │
          ┌────────────────────┼────────────────────┐
          │                    │                    │
          ▼                    ▼                    ▼
   ┌─────────────┐      ┌─────────────┐      ┌─────────────┐
   │  Session A  │      │  Session B  │      │  Session C  │
   │  (Feishu)   │      │  (Webchat)  │      │   (Cron)    │
   │             │      │             │      │             │
   │ Independent │      │ Independent │      │ Independent │
   │  Context    │      │  Context    │      │  Context    │
   └──────┬──────┘      └──────┬──────┘      └──────┬──────┘
          │                    │                    │
          └────────────────────┼────────────────────┘
                               │
                      ┌────────▼────────┐
                      │ Public Knowledge │
                      │    Base (RAG)    │
                      │  MEMORY.md etc.  │
                      └─────────────────┘

Layer Responsibilities

LayerContentCharacteristics
LLM LayerModel inferenceShared, resource-efficient, consistent knowledge/capabilities
Session LayerContext + short-term memoryIsolated, non-interfering, concurrent
Public LayerKnowledge base / RAGShared, accessible by all sessions

Session Entry Extension

type SessionEntry = {
  // ... existing fields
  status?: 'active' | 'archived' | 'pinned';
  archivedAt?: number;
  archivedReason?: string;
  tags?: string[];           // User-defined tags
  title?: string;            // User-defined title
  channelBinding?: string;   // Bound channel identifier
};

Channel-to-Session Binding

# Configuration example
channels:
  feishu:
    sessionBinding: isolated    # Independent session
    
  telegram:
    sessionBinding: isolated
    
  cron:
    sessionBinding: ephemeral   # Temporary session, destroyed after task completion

session:
  isolation:
    enabled: true
    defaultScope: per-channel   # per-channel | per-sender | global

Archive Mechanism

~/.openclaw/agents/main/
├── session-store.json          # Active sessions only
├── sessions/
│   └── *.jsonl                 # Active session transcripts
└── archived/
    ├── archived-store.json     # Archive metadata
    └── sessions/
        └── *.jsonl             # Archived transcripts

WebUI Enhancement

New Features

  1. Create New Session

    • Click [+ New] button to create a new session
    • Optional: Label, Tags, Scope
    • Auto-redirect to Chat page after creation

  2. Session State Management

    • [Active] / [Archived] / [All] tab switching
    • Archive/Restore/Pin action buttons
    • Auto-generated session title (from first message) or manual setting

  3. Archive Visibility

    • Archived sessions are viewable and restorable
    • Archives don't occupy active session list
    • Searchable archive history

UI Mockup

┌─────────────────────────────────────────────────────────────┐
│  Sessions                                    [+ New] [Archive]│
├─────────────────────────────────────────────────────────────┤
│  [Active] [Archived] [All]                    🔍 Search...   │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────────────────────────────────────────────┐    │
│  │ 📌 Feishu Bot Config     direct   2026-03-17  pinned   │    │
│  │ 📝 Webchat Daily Chat    direct   2026-03-17  active   │    │
│  │ 📝 Telegram Chat         direct   2026-03-16  active   │    │
│  │ 📦 Old Project Discussion direct   2026-03-10  archived│    │
│  └─────────────────────────────────────────────────────┘    │
│                                                             │
│  [Load] [Archive] [Restore] [Delete]                        │
└─────────────────────────────────────────────────────────────┘

API Changes

New Endpoints

POST /api/sessions/create
  - Create new session, returns sessionKey
  - Body: { label?, tags?, scope? }

POST /api/sessions/:key/archive
  - Archive session (move to archived/)

POST /api/sessions/:key/restore
  - Restore archived session

GET /api/sessions/archived
  - List archived sessions

POST /api/sessions/:key/pin
  - Pin session (exempt from auto-cleanup)

Implementation Phases

Phase 1: Data Layer Refactoring

  • SessionEntry type extension
  • Archive storage logic
  • Archive/restore API

Phase 2: Gateway Routing Refactoring

  • Channel → Session auto-binding
  • Make session.mainKey config effective
  • Fix multi-channel message routing

Phase 3: WebUI Enhancement

  • New Session button + dialog
  • Archived tab view
  • Archive/Restore/Pin action buttons

Phase 4: Public Knowledge Base Integration

  • RAG retrieval integration
  • Session-level vs public memory separation

Related Issues

  • #41790 - Allow session.mainKey to designate any channel session as the main session
  • #45514 - Multi-channel session routing - replies go to wrong channel
  • #40017 - Designate a channel session as the primary/main session
  • #45501 - Session.resetPrompt — configurable session startup message

Open Questions

  1. Cross-Session Collaboration: How to implement Session A triggering Session B to execute a task?

    • Suggestion: Message passing mechanism, similar to existing sessions_send

  2. Memory Sync Strategy: When to write to public knowledge base?

    • Suggestion: Only write to public when explicitly marked "remember this", default to session-level only

  3. Resource Limits: How to control GPU/memory usage with concurrent sessions?

    • Suggestion: Queue mechanism + max concurrent sessions config

  4. Backward Compatibility: How to migrate existing configurations?

    • Suggestion: Keep default behavior, enable new features via explicit config options

cc @steipete @sebslight

extent analysis

Fix Plan

To address the issues with the current session management architecture, we will implement the proposed multi-session architecture with a shared LLM layer, isolated session layer, and public knowledge base layer. Here are the concrete steps:

  • Phase 1: Data Layer Refactoring
    • Extend the SessionEntry type to include status, archivedAt, archivedReason, tags, title, and channelBinding fields.
    • Implement archive storage logic and archive/restore API.
  • Phase 2: Gateway Routing Refactoring
    • Implement channel-to-session auto-binding using the sessionBinding configuration.
    • Make the session.mainKey config effective and fix multi-channel message routing issues.
  • Phase 3: WebUI Enhancement
    • Add a new session button and dialog to create new sessions.
    • Implement archived tab view and archive/restore/pin action buttons.
  • Phase 4: Public Knowledge Base Integration
    • Integrate RAG retrieval and separate session-level and public memory.

Example code for extending the SessionEntry type:

type SessionEntry = {
  // ... existing fields
  status?: 'active' | 'archived' | 'pinned';
  archivedAt?: number;
  archivedReason?: string;
  tags?: string[];
  title?: string;
  channelBinding?: string;
};

Example code for implementing archive storage logic:

// Archive storage logic
const archiveSession = (sessionKey: string) => {
  // Move session to archived directory
  const archivedSessionPath = `archived/sessions/${sessionKey}.jsonl`;
  const activeSessionPath = `sessions/${sessionKey}.jsonl`;
  fs.renameSync(activeSessionPath, archivedSessionPath);
};

// Restore archived session
const restoreSession = (sessionKey: string) => {
  // Move session back to active directory
  const archivedSessionPath = `archived/sessions/${sessionKey}.jsonl`;
  const activeSessionPath = `sessions/${sessionKey}.jsonl`;
  fs.renameSync(archivedSessionPath, activeSessionPath);
};

Verification

To verify that the fix worked, we can test the following scenarios:

  • Creating a new session and verifying that it is isolated from other sessions.
  • Archiving and restoring a session and verifying that the session is correctly moved between the active and archived directories.
  • Testing multi-channel message routing and verifying that messages are correctly routed to the intended session.

Extra Tips

To prevent regressions, we should:

  • Thoroughly test the new architecture and features.
  • Monitor resource usage and adjust the queue mechanism and max concurrent sessions config as needed.
  • Implement backward compatibility and migrate existing configurations to the new architecture.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#GPU setup#container setup#orchestration issue#cache issue

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING