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

# Context Compaction

> Automatic context window management for long conversations

# Context Compaction

Automatically manage context window size by compacting conversation history. Prevent token limit errors while preserving important context.

## Quick Start

### Agent-Centric Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import ManagerConfig

# Agent with context compaction via context= param
agent = Agent(
    name="LongChat",
    instructions="You are a helpful assistant for extended conversations.",
    context=ManagerConfig(
        auto_compact=True,
        compact_threshold=0.8,  # Trigger at 80% usage
        strategy="smart",  # Options: truncate, sliding_window, summarize, smart
    )
)

# Context is automatically compacted during long conversations
response = agent.chat("Let's have a detailed discussion about AI history...")

# Strategies: truncate, sliding_window, prune_tools, summarize, smart
```

## Compaction Strategies

### Truncate

Remove oldest messages first:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents import ManagerConfig

agent = Agent(
    name="Assistant",
    instructions="You are helpful.",
    context=ManagerConfig(
        auto_compact=True,
        strategy="truncate",
    )
)
```

### Sliding Window

Keep most recent messages within token limit:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    name="Assistant",
    instructions="You are helpful.",
    context=ManagerConfig(
        auto_compact=True,
        strategy="sliding_window",
    )
)
```

### Summarize

Replace old messages with a summary:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    name="Assistant",
    instructions="You are helpful.",
    context=ManagerConfig(
        auto_compact=True,
        strategy="summarize",
    )
)
```

### Smart

Intelligently select which messages to keep:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
agent = Agent(
    name="Assistant",
    instructions="You are helpful.",
    context=ManagerConfig(
        auto_compact=True,
        strategy="smart",
    )
)
```

## Configuration Options

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.compaction import ContextCompactor, CompactionStrategy

compactor = ContextCompactor(
    max_tokens=4000,          # Target token limit
    strategy=CompactionStrategy.SLIDING,
    preserve_system=True,     # Keep system messages
    preserve_recent=3,        # Keep last N messages
    preserve_first=1          # Keep first N messages
)
```

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai compaction status        # Show settings
praisonai compaction set sliding   # Set strategy
praisonai compaction stats         # Show statistics
```

***

## Low-level API Reference

### ContextCompactor Direct Usage

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.compaction import (
    ContextCompactor, CompactionStrategy
)

compactor = ContextCompactor(
    max_tokens=4000,
    strategy=CompactionStrategy.SLIDING,
    preserve_system=True,
    preserve_recent=3
)

# Compact messages
messages = [
    {"role": "system", "content": "You are helpful."},
    {"role": "user", "content": "Hello"},
    {"role": "assistant", "content": "Hi there!"},
    # ... many more messages
]

compacted, result = compactor.compact(messages)
print(f"Reduced: {result.original_tokens} -> {result.compacted_tokens}")
```

### Checking Stats

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Check if compaction is needed
stats = compactor.get_stats(messages)
print(f"Total tokens: {stats['total_tokens']}")
print(f"Max tokens: {stats['max_tokens']}")
print(f"Needs compaction: {stats['needs_compaction']}")
```

### Compaction Results

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
compacted, result = compactor.compact(messages)

print(f"Original tokens: {result.original_tokens}")
print(f"Compacted tokens: {result.compacted_tokens}")
print(f"Tokens saved: {result.tokens_saved}")
print(f"Compression ratio: {result.compression_ratio:.1%}")
print(f"Messages kept: {result.messages_kept}")
print(f"Messages removed: {result.messages_removed}")
print(f"Was compacted: {result.was_compacted}")
print(f"Strategy used: {result.strategy_used.value}")
```

### Serialization

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Serialize result
data = result.to_dict()

# Contains all metrics
print(data['compression_ratio'])
```

## Zero Performance Impact

Compaction uses lazy loading:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Only loads when accessed
from praisonaiagents.compaction import ContextCompactor
```