Session Management

xopc provides comprehensive session management for conversation history via CLI and Web UI.

---

Overview

Feature	CLI	Web UI
List sessions	✅	✅
Search sessions	✅	✅
View details	✅	✅
Archive/Unarchive	✅	✅
Pin/Unpin	✅	✅
Export (JSON)	✅	✅
Delete	✅	✅
Search in session	❌	✅

---

Session Storage

Property	Value
Storage directory	agents/<agentId>/sessions/ (under the state directory; sharded transcript files)
Index file	agents/<agentId>/sessions/index.json
File format	JSON
Archive directory	agents/<agentId>/sessions/archive/
Session overrides	agents/<agentId>/sessions/config/<sanitized-session-key>.json

---

Session States

Status	Description
active	Currently active session (default)
pinned	Pinned to top for quick access
archived	Archived and moved to archive folder

---

CLI Usage

List Sessions

# List all sessions
xopc session list

# Filter by status
xopc session list --status active
xopc session list --status archived
xopc session list --status pinned

# Search by name or content
xopc session list --query "project"

# Sort and limit
xopc session list --sort updatedAt --order desc --limit 50

View Session Details

# Show session info and recent messages
xopc session info telegram:123456

# Search within a session
xopc session grep telegram:123456 "API design"

Manage Sessions

# Rename a session
xopc session rename telegram:123456 "Project Discussion"

# Add tags
xopc session tag telegram:123456 work important

# Remove tags
xopc session untag telegram:123456 important

# Archive a session
xopc session archive telegram:123456

# Unarchive a session
xopc session unarchive telegram:123456

# Pin a session
xopc session pin telegram:123456

# Unpin a session
xopc session unpin telegram:123456

# Delete a session
xopc session delete telegram:123456

# Export session to JSON
xopc session export telegram:123456 \
  --format json \
  --output backup.json

Bulk Operations

# Delete multiple sessions by filter
xopc session delete-many --status archived --force

# Archive old sessions (30+ days inactive)
xopc session cleanup --days 30

Statistics

xopc session stats

Sample output:

📊 Session Statistics

  Total Sessions:     42
  Active:             28
  Archived:           12
  Pinned:             2
  Total Messages:     1,847
  Total Tokens:       452.3k

  By Channel:
    telegram: 35
    gateway: 5
    cli: 2

---

Web UI

The Web UI provides a visual interface for session management at the gateway root (hash router; sessions live under #/sessions).

Features

1. Session List: Grid/list view with filtering
2. Search: Real-time search across sessions
3. Filters: Filter by status (All/Active/Pinned/Archived)
4. Statistics: Visual stats cards
5. Detail Drawer: Click any session to view:
   • Full message history
   • In-session search with highlighting
   • Archive/Pin/Export/Delete actions

Accessing the UI

# Start the gateway
xopc gateway start

# Open in browser
open http://localhost:18790/#/sessions

---

Session Structure

interface SessionMetadata {
  key: string;              // Unique identifier
  name?: string;            // Optional custom name
  status: 'active' | 'idle' | 'archived' | 'pinned';
  tags: string[];           // User-defined tags
  createdAt: string;        // ISO timestamp
  updatedAt: string;
  lastAccessedAt: string;
  messageCount: number;
  estimatedTokens: number;
  compactedCount: number;   // Number of compressions
  sourceChannel: string;    // telegram, gateway, cli
  sourceChatId: string;
}

interface SessionDetail extends SessionMetadata {
  messages: Message[];
}

interface Message {
  role: 'system' | 'user' | 'assistant' | 'tool' | 'toolResult';
  content: string;
  timestamp?: string;
  tool_call_id?: string;
  tool_calls?: ToolCall[];
  name?: string;
}

---

Session Index

The index.json file maintains a cache of all session metadata:

{
  "version": "1.0",
  "lastUpdated": "2026-02-14T10:00:00Z",
  "sessions": [
    {
      "key": "telegram:123456",
      "status": "active",
      "tags": ["work"],
      "messageCount": 42,
      ...
    }
  ]
}

---

Automatic Maintenance

Compaction

When a session exceeds the context window limit:

1. Early messages are summarized using LLM
2. Recent messages are preserved (default: last 10)
3. System messages are always kept

Configure in config.json:

{
  "agents": {
    "defaults": {
      "compaction": {
        "enabled": true,
        "mode": "abstractive",
        "triggerThreshold": 0.8,
        "keepRecentMessages": 10
      }
    }
  }
}

Compaction Modes:

• extractive - Summarize using key sentences
• abstractive - LLM-based summarization
• structured - Preserve structured data

Sliding Window

To prevent memory issues:

• Maximum messages: 100
• Keeps recent messages when limit exceeded
• Preserves system context

---

Best Practices

1. Use Tags: Tag sessions by project or topic
2. Pin Important Sessions: Keep frequently accessed sessions pinned
3. Archive Old Sessions: Archive sessions you don't need regularly
4. Regular Cleanup: Use session cleanup for old inactive sessions
5. Export Before Delete: Export important sessions before deletion

---

Troubleshooting

Sessions Not Loading in Web UI

1. Check gateway is running: xopc gateway status
2. Verify WebSocket connection in browser console
3. Check for errors in gateway logs

Session Index Corrupted

The index will be automatically rebuilt on next access. To force rebuild:

# Delete index file (replace <agentId> with your agent id, e.g. main)
rm ~/.xopc/agents/<agentId>/sessions/index.json

# It will be rebuilt on next session list
xopc session list

Missing Sessions

If sessions exist on disk under agents/<agentId>/sessions/ but don't appear:

# Force index rebuild
xopc session list --limit 1000

---

API Reference

WebSocket API Methods

Method	Description
session.list	List sessions with pagination
session.get	Get session details
session.delete	Delete a session
session.rename	Rename a session
session.tag	Add tags
session.untag	Remove tags
session.archive	Archive session
session.unarchive	Unarchive session
session.pin	Pin session
session.unpin	Unpin session
session.search	Search sessions
session.searchIn	Search within session
session.export	Export session
session.stats	Get statistics