Sessions

Overview

A session is a continuous conversation between a user and the agent. Sessions maintain the full message history within a context window and persist across channel reconnections and gateway restarts.

Session Lifecycle

1. Created: When a new user first messages the agent (or manually via the dashboard)
2. Active: Receiving and processing messages
3. Idle: No recent activity but context preserved
4. Compacted: Context window was full, older messages summarized

Context Windows

Each session has a context window -- the amount of conversation history the model can see. This is limited by the model's maximum context length (typically 200K tokens for Claude).

As conversations grow, ArgentOS monitors the context usage and triggers compaction when approaching the limit.

Compaction

When a session's context approaches the model's limit, ArgentOS compacts the conversation:

1. Older messages are summarized into a compact representation
2. The summary replaces the detailed message history
3. Recent messages are preserved in full
4. The agent continues with the summarized context

This allows conversations to continue indefinitely without losing important context.

[Session Start]
  ├── System prompt
  ├── Compacted summary of messages 1-500
  ├── Full messages 501-520 (recent)
  └── New incoming message

Session Storage

Sessions are stored in the gateway's state directory:

~/.argentos/agents/main/sessions/
├── user-jason/
│   ├── history.json
│   └── metadata.json
├── user-richard/
│   └── ...

Cross-Channel Sessions

A single session can receive messages from multiple channels. When a user is paired across Telegram and Discord, both channels route to the same session. The agent sees one continuous conversation.

Session Configuration

{
  "agents": {
    "defaults": {
      "session": {
        "maxContextTokens": 180000,
        "compactionThreshold": 0.85,
        "channelScope": "collapsed"
      }
    }
  }
}

Channel Scope

The channelScope option controls how Discord guild channels map to sessions:

• "collapsed" -- All channels in a guild share one session
• "per-channel" -- Each channel gets its own separate session

Managing Sessions

Via CLI

# List active sessions
argent sessions list

# View session details
argent sessions info <session-id>

# Clear a session's context
argent sessions clear <session-id>

Via Dashboard

The dashboard shows all active sessions with their last activity time and context usage. You can switch between sessions and clear context from the UI.