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

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:

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:

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

Summarize

Replace old messages with a summary:

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

Smart

Intelligently select which messages to keep:

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

Configuration Options

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

praisonai compaction status        # Show settings
praisonai compaction set sliding   # Set strategy
praisonai compaction stats         # Show statistics

---

Low-level API Reference

ContextCompactor Direct Usage

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

# 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'])

Zero Performance Impact

Compaction uses lazy loading:

# Only loads when accessed
from praisonaiagents.compaction import ContextCompactor