Skip to main content

​
Context Compaction

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

​
Quick Start

from praisonaiagents.compaction import (
    ContextCompactor, CompactionStrategy
)

# Create compactor
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}")

​
Compaction Strategies

​
Truncate

Remove oldest messages first: 
compactor = ContextCompactor(
    max_tokens=4000,
    strategy=CompactionStrategy.TRUNCATE
)

​
Sliding Window

Keep most recent messages within token limit: 
compactor = ContextCompactor(
    max_tokens=4000,
    strategy=CompactionStrategy.SLIDING,
    preserve_recent=5  # Always keep last 5 messages
)

​
Summarize

Replace old messages with a summary: 
compactor = ContextCompactor(
    max_tokens=4000,
    strategy=CompactionStrategy.SUMMARIZE,
    preserve_system=True
)

​
Smart

Intelligently select which messages to keep: 
compactor = ContextCompactor(
    max_tokens=4000,
    strategy=CompactionStrategy.SMART
)

​
Configuration Options

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
)

​
Checking Stats

# 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

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

# Serialize result
data = result.to_dict()

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

​
Agent Integration

from praisonaiagents import Agent
from praisonaiagents.compaction import ContextCompactor, CompactionStrategy

compactor = ContextCompactor(
    max_tokens=8000,
    strategy=CompactionStrategy.SMART
)

agent = Agent(
    instructions="Research assistant",
    context_compactor=compactor
)

​
Zero Performance Impact

Compaction uses lazy loading: 
# Only loads when accessed
from praisonaiagents.compaction import ContextCompactor