Praison AI

Context Compression

Intelligent compression of retrieved context to fit token budgets

Diagram

Context Compression

📋 User Request

⚙️ Context Compression

✅ Result

Diagram
Context CompressionAgentUserContext CompressionAgentUserRequestProcess requestResultResponse
python
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

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.

Diagram

Context Compression

📝 Retrieved Chunks

✂️ Deduplicate

🧠 Query Extract

🤖 Agent

✅ Fitted Context

How It Works

Diagram
KnowledgeCompressorAgentUserKnowledgeCompressorAgentUserAsk a questionRetrieve chunksLarge chunk setCompressed, query-focused textAnswer 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
    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
    praisonai knowledge search "query" --compress --max-context-tokens 2000

Compression Strategies

Deduplication

Removes duplicate or near-duplicate content:

python
compressor = ContextCompressor(
    deduplicate=True,
    similarity_threshold=0.9,
)

result = compressor.compress(chunks)

Query-Focused Extraction

Extracts sentences most relevant to the query:

python
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
compressor = ContextCompressor(
    max_tokens=1000,
    truncation_strategy="end",  # or "start", "middle"
)

result = compressor.compress(chunks)

LLM Summarization

Uses LLM for aggressive compression:

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

Enable LLM summarisation for long chats

llm_summarize=True preserves decisions and facts better than blunt truncation.

Hook memory before compress

Use on_pre_compress to persist important facts before messages are discarded.

Pair with smart retrieval

Re-fetch compressed-away details via hybrid search instead of keeping everything inline.

Log compression events

Review observability history to confirm compression helps rather than hurts answer quality.

API Reference

ContextCompressor

python
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
@dataclass
class CompressionResult:
    chunks: List[str]
    original_tokens: int
    compressed_tokens: int
    method_used: str
    metadata: dict = None

Related

Smart Retrieval

Hybrid search before compression

 Token Budgeting

Set budgets for retrieved context