> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> How ArgentOS manages conversation sessions, context windows, and compaction.

## 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

```mermaid theme={null}
stateDiagram-v2
    [*] --> Created: First message
    Created --> Active: Processing messages
    Active --> Idle: No recent activity
    Idle --> Active: New message
    Active --> Compacted: Context window full
    Compacted --> Active: Continues with summary
```

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:

<Steps>
  <Step title="Summarize">Older messages are summarized into a compact representation</Step>
  <Step title="Replace">The summary replaces the detailed message history</Step>
  <Step title="Preserve">Recent messages are preserved in full</Step>
  <Step title="Continue">The agent continues with the summarized context</Step>
</Steps>

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

<Tip>
  A single session can receive messages from multiple channels. When a user is [paired](/channels/pairing) across Telegram and Discord, both channels route to the same session. The agent sees one continuous conversation.
</Tip>

## Session Configuration

```json theme={null}
{
  "agents": {
    "defaults": {
      "session": {
        "maxContextTokens": 180000,
        "compactionThreshold": 0.85,
        "channelScope": "collapsed"
      }
    }
  }
}
```

### Channel Scope

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

| Mode            | Behavior                                   |
| --------------- | ------------------------------------------ |
| `"collapsed"`   | All channels in a guild share one session  |
| `"per-channel"` | Each channel gets its own separate session |

## Managing Sessions

<Tabs>
  <Tab title="Via CLI">
    ```bash theme={null}
    # List active sessions
    argent sessions list

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

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

  <Tab title="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.
  </Tab>
</Tabs>