Skip to main content

​
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

Summarize

Older messages are summarized into a compact representation
2

Replace

The summary replaces the detailed message history
3

Preserve

Recent messages are preserved in full
4

Continue

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:
ModeBehavior
"collapsed"All channels in a guild share one session
"per-channel"Each channel gets its own separate session

​
Managing Sessions

# List active sessions
argent sessions list

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

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