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

# Lossless Context Management (LCM)

> DAG-based context compression that preserves every message with full recall via grep, describe, and expand tools.

LCM is a DAG-based context compression engine that ships with ArgentOS Core. It replaces flat compaction with hierarchical summarization — every message is stored permanently in an immutable database, and agents can search and recall any past message even after compaction.

## Why LCM Exists

Standard context management has a fundamental problem: when the context window fills up, old messages are summarized into a flat blob and the originals are discarded. The agent loses access to details discussed earlier in the conversation.

LCM solves this by maintaining a **hierarchical summary DAG** (directed acyclic graph) alongside an **immutable message store**. Summaries compress the history for the model's context window, but the originals are always available for recall via agent tools.

<CardGroup cols={2}>
  <Card title="Within-session" icon="comments">
    **LCM** keeps the agent coherent during long conversations via DAG compression with full recall.
  </Card>

  <Card title="Across sessions" icon="brain">
    **MemU** provides persistent memory across months and years of interaction.
  </Card>
</CardGroup>

## How It Works

### Immutable Message Store

Every user message, assistant response, and tool result is persisted verbatim in a SQLite database (`~/.argentos/lcm.db`). Messages are never modified or deleted. This is the ground truth that everything else builds on.

### The Summary DAG

As the context window fills, LCM compresses older messages into a hierarchical tree of summaries:

```mermaid theme={null}
flowchart TD
    D2["Condensed Summary (depth 2)"] --> D1A["Summary 1 (depth 1)"]
    D2 --> D1B["Summary 2 (depth 1)"]
    D1A --> L1["Leaf ~1200 tok"]
    D1A --> L2["Leaf ~1200 tok"]
    D1B --> L3["Leaf ~1200 tok"]
    D1B --> L4["Leaf ~1200 tok"]
    L1 --> M1["Raw messages (immutable)"]
    L2 --> M2["Raw messages (immutable)"]
    L3 --> M3["Raw messages (immutable)"]
    L4 --> M4["Raw messages (immutable)"]
```

* **Leaf summaries** (depth 0): Created from chunks of \~20,000 tokens of raw messages, compressed to \~1,200 tokens each
* **Condensed summaries** (depth 1+): Created when 4+ same-depth summaries accumulate, merged into \~2,000 token nodes
* **Fresh tail**: The 32 most recent messages are always kept raw (configurable)

### Context Assembly

Each turn, the agent sees compressed history summaries followed by the fresh tail of recent raw messages. The summaries provide continuity while the fresh tail preserves full detail for the active conversation.

### Three-Level Escalation

Compaction always converges, guaranteed:

| Level             | Strategy                            | Temperature | When                                  |
| ----------------- | ----------------------------------- | ----------- | ------------------------------------- |
| **Normal**        | Narrative summary, preserve details | 0.2         | Default                               |
| **Aggressive**    | Bullet points only, half tokens     | 0.1         | Normal summary too large              |
| **Deterministic** | Mechanical truncation, no LLM       | N/A         | LLM fails or returns oversized output |

## Agent Tools

LCM registers three tools that give agents recall capabilities over compacted history:

<CardGroup cols={3}>
  <Card title="aos_lcm_grep" icon="magnifying-glass">
    Full-text search across the **entire** conversation history, including messages compacted out of context.
  </Card>

  <Card title="aos_lcm_describe" icon="file-lines">
    Retrieve the full content of a specific message or summary node by ID.
  </Card>

  <Card title="aos_lcm_expand_query" icon="expand">
    Expand a summary back to its original source messages by walking the DAG.
  </Card>
</CardGroup>

**Example workflow**: Agent needs to recall something from hours ago that was compacted out:

1. Agent calls `aos_lcm_grep` with a search query
2. Gets ranked results with snippets and message IDs
3. Calls `aos_lcm_describe` to read the full message
4. Or calls `aos_lcm_expand_query` to expand a summary back to its originals

## Configuration

LCM is enabled by default. Configuration is in `argent.json`:

```json theme={null}
{
  "plugins": {
    "entries": {
      "aos-lcm": {
        "enabled": true,
        "config": {
          "freshTailCount": 32,
          "contextThreshold": 0.75,
          "summaryModel": "auto"
        }
      }
    }
  }
}
```

### Options

| Option                    | Default              | Description                                             |
| ------------------------- | -------------------- | ------------------------------------------------------- |
| `enabled`                 | `true`               | Enable LCM context management                           |
| `freshTailCount`          | `32`                 | Recent messages kept raw (not summarized)               |
| `contextThreshold`        | `0.75`               | Trigger compaction at this fraction of context window   |
| `summaryModel`            | `"auto"`             | Model for summarization. `"auto"` uses the model router |
| `leafChunkTokens`         | `20000`              | Token target per leaf compaction chunk                  |
| `leafTargetTokens`        | `1200`               | Token target for leaf summary output                    |
| `condensedTargetTokens`   | `2000`               | Token target for condensed summaries                    |
| `incrementalMaxDepth`     | `-1`                 | Maximum DAG depth (-1 = unlimited)                      |
| `largeFileTokenThreshold` | `25000`              | Files above this are stored externally                  |
| `databasePath`            | `~/.argentos/lcm.db` | Custom database path                                    |

### Disabling LCM

```json theme={null}
{
  "plugins": {
    "entries": {
      "aos-lcm": { "enabled": false }
    }
  }
}
```

## Large File Handling

Files over 25,000 tokens (configurable) are automatically stored externally with compact exploration summaries injected into context. The full content remains accessible via `aos_lcm_describe`.

## Database

LCM uses its own standalone SQLite database at `~/.argentos/lcm.db`, separate from MemU's PostgreSQL. The database uses WAL mode for concurrent reads and includes FTS5 full-text indexes for fast grep searches.

| Table              | Purpose                                   |
| ------------------ | ----------------------------------------- |
| `messages`         | Immutable message store                   |
| `messages_fts`     | FTS5 full-text search index               |
| `summaries`        | DAG summary nodes                         |
| `summary_messages` | Leaf summary to source message links      |
| `summary_sources`  | Condensed summary to source summary links |
| `context_items`    | Active context window state               |
| `large_files`      | Externally stored large file metadata     |

## Attribution

LCM is adapted from the Lossless Context Management architecture by Clint Ehrlich and Theodore Blackman at Voltropy PBC. The original lossless-claw OpenClaw plugin is MIT licensed. The ArgentOS adaptation adds integration with the gateway, model router, plugin hook system, and agent tool registration.