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

# Context Compression

> Intelligent compression of retrieved context to fit token budgets

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Compression"
        Request[📋 User Request] --> Process[⚙️ Context Compression]
        Process --> Result[✅ Result]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Request input
    class Process process
    class Result output
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Feature as Context Compression

    User->>Agent: Request
    Agent->>Feature: Process request
    Feature-->>Agent: Result
    Agent-->>User: Response
```

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

agent = Agent(
    name="compress-agent",
    instructions="Compress conversation history to save context space.",
    compress_context=True,
)
agent.start("Summarise older messages to free context window space.")
```

# Context Compression

> [!NOTE]
>
> This page documents `praisonaiagents.rag.ContextCompressor` for compressing retrieved RAG chunks. For compressing *conversation history* in long agent runs, see [LLM Context Compression](https://praison.ai/docs/features/llm-context-compression.md).

Context compression reduces retrieved content to fit within token budgets while preserving query-relevant information.

The user retrieves large knowledge chunks; compression deduplicates and trims text to fit the token budget.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Context Compression"
        In[📝 Retrieved Chunks] --> Dedup[✂️ Deduplicate]
        Dedup --> Extract[🧠 Query Extract]
        Extract --> Agent[🤖 Agent]
        Agent --> Out[✅ Fitted Context]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class In input
    class Dedup,Extract process
    class Agent agent
    class Out output
```

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Compressor
    participant Knowledge

    User->>Agent: Ask a question
    Agent->>Knowledge: Retrieve chunks
    Knowledge-->>Compressor: Large chunk set
    Compressor-->>Agent: Compressed, query-focused text
    Agent-->>User: Answer within budget
```

## Overview

The ContextCompressor provides:

* **Deduplication** of similar content
* **Query-focused extraction** of relevant sentences
* **Token-aware truncation** to fit budgets
* **LLM summarization fallback** for aggressive compression

## Quick Start

**1. Compress retrieved chunks**

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.rag import ContextCompressor

compressor = ContextCompressor(max_tokens=4000, target_ratio=0.5)
chunks = ["Long document content here...", "Another document..."]

result = compressor.compress(chunks, query="API authentication")
print(f"Saved {result.original_tokens - result.compressed_tokens} tokens")
```

**2. Search with compression via CLI**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai knowledge search "query" --compress --max-context-tokens 2000
```

## Compression Strategies

### Deduplication

Removes duplicate or near-duplicate content:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
compressor = ContextCompressor(
    deduplicate=True,
    similarity_threshold=0.9,
)

result = compressor.compress(chunks)
```

### Query-Focused Extraction

Extracts sentences most relevant to the query:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
compressor = ContextCompressor(
    max_tokens=2000,
    extraction_method="query_focused",
)

result = compressor.compress(
    chunks,
    query="How do I authenticate with the API?",
)
```

### Truncation

Simple truncation to fit token budget:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
compressor = ContextCompressor(
    max_tokens=1000,
    truncation_strategy="end",  # or "start", "middle"
)

result = compressor.compress(chunks)
```

### LLM Summarization

Uses LLM for aggressive compression:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
compressor = ContextCompressor(
    max_tokens=500,
    use_llm_summarization=True,
    summarization_model="gpt-4o-mini",
)

result = compressor.compress(chunks, query=query)
```

## Compression Results

### CompressionResult Structure

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from dataclasses import dataclass
from typing import List

@dataclass
class CompressionResult:
    chunks: List[str]
    original_tokens: int
    compressed_tokens: int
    method_used: str
    metadata: dict = None
```

### Working with Results

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
result = compressor.compress(chunks, query=query)

print(f"Method used: {result.method_used}")
print(f"Original: {result.original_tokens} tokens")
print(f"Compressed: {result.compressed_tokens} tokens")
print(f"Ratio: {result.compressed_tokens / result.original_tokens:.2%}")

# Use compressed chunks
for chunk in result.chunks:
    print(chunk[:200] + "...")
```

## CLI Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Search with compression
praisonai knowledge search "query" --compress

# Specify compression ratio
praisonai knowledge search "query" --compress --compression-ratio 0.3

# Specify max tokens
praisonai knowledge search "query" --compress --max-context-tokens 2000

# Verbose output
praisonai knowledge search "query" --compress --verbose
```

## Integration with Agents

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

agent = Agent(
    name="CompressedRetriever",
    instructions="Answer questions using the knowledge base.",
    knowledge={
        "sources": ["./docs"],
        "retrieval_k": 10,
    }
)

response = agent.chat("Summarize the authentication methods")
```

## Best Practices

> [accordion] Enable LLM summarisation for long chats
>
> `llm_summarize=True` preserves decisions and facts better than blunt truncation.

> [accordion] Hook memory before compress
>
> Use `on_pre_compress` to persist important facts before messages are discarded.

> [accordion] Pair with smart retrieval
>
> Re-fetch compressed-away details via hybrid search instead of keeping everything inline.

> [accordion] Log compression events
>
> Review observability history to confirm compression helps rather than hurts answer quality.

## API Reference

### ContextCompressor

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
class ContextCompressor:
    def __init__(
        self,
        max_tokens: int = 4000,
        target_ratio: float = 0.5,
        deduplicate: bool = True,
        similarity_threshold: float = 0.9,
        use_llm_summarization: bool = False,
        summarization_model: str = "gpt-4o-mini",
    ):
        """Initialize context compressor."""
    
    def compress(
        self,
        chunks: List[str],
        query: str = None,
    ) -> CompressionResult:
        """Compress chunks to fit token budget."""
    
    def estimate_tokens(self, text: str) -> int:
        """Estimate token count for text."""
```

### CompressionResult

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
@dataclass
class CompressionResult:
    chunks: List[str]
    original_tokens: int
    compressed_tokens: int
    method_used: str
    metadata: dict = None
```

> [!NOTE]
>
> Memory backends can implement the `on_pre_compress` hook to extract and persist important facts before compression discards messages. See [Memory Lifecycle Hooks](https://praison.ai/docs/features/memory-lifecycle-hooks.md) for details.

## Related

> [card] [Smart Retrieval](https://praison.ai/docs/features/smart-retrieval.md)
>
> Hybrid search before compression

> [card] [Token Budgeting](https://praison.ai/docs/features/token-budgeting.md)
>
> Set budgets for retrieved context


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.