> ## 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
This page documents `praisonaiagents.rag.ContextCompressor` for compressing retrieved RAG chunks. For compressing *conversation history* in long agent runs, see [LLM Context Compression](/docs/features/llm-context-compression).
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
```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")
```
```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
`llm_summarize=True` preserves decisions and facts better than blunt truncation.
Use `on_pre_compress` to persist important facts before messages are discarded.
Re-fetch compressed-away details via hybrid search instead of keeping everything inline.
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
```
Memory backends can implement the `on_pre_compress` hook to extract and persist important facts before compression discards messages. See [Memory Lifecycle Hooks](/docs/features/memory-lifecycle-hooks) for details.
## Related
Hybrid search before compression
Set budgets for retrieved context