Context Compaction Policy

Proactive, policy-based protection against context overflow with token-budget routing

Context Compaction Policy proactively routes long agent runs through token-budget checks before each LLM call, picking the right compaction strategy before context overflow happens.

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="LongRunner",
    instructions="Handle long multi-turn research sessions.",
    execution=ExecutionConfig(context_compaction=True),
)
agent.start("Continue our three-hour research thread.")

The user runs long sessions; policy checks token budgets before each LLM call and compacts when needed.

Quick Start

1. Enable with defaults (one line)

   from praisonaiagents import Agent, ExecutionConfig
   
   agent = Agent(
       name="LongRunner",
       instructions="Handle long multi-turn research sessions.",
       execution=ExecutionConfig(context_compaction=True),
   )
   
   agent.start("Research the entire history of large language models...")

2. Pick a preset

   Conservative

   from praisonaiagents import Agent, ExecutionConfig, CONSERVATIVE_POLICY
   
   agent = Agent(
       name="CautiousAgent",
       execution=ExecutionConfig(context_compaction=CONSERVATIVE_POLICY),
   )

   Balanced (Default)

   from praisonaiagents import Agent, ExecutionConfig, BALANCED_POLICY
   
   agent = Agent(
       name="StandardAgent",
       execution=ExecutionConfig(context_compaction=BALANCED_POLICY),
   )

   Aggressive

   from praisonaiagents import Agent, ExecutionConfig, AGGRESSIVE_POLICY
   
   agent = Agent(
       name="ToolHeavyAgent",
       execution=ExecutionConfig(context_compaction=AGGRESSIVE_POLICY),
   )

3. Custom policy

   from praisonaiagents import Agent, ExecutionConfig, ContextCompactionPolicy
   
   agent = Agent(
       name="CustomAgent",
       execution=ExecutionConfig(
           context_compaction=ContextCompactionPolicy(
               trigger_at=0.85,
               strategy="summarise",
               preserve_last_n_turns=8,
               target_utilization=0.65,
           )
       ),
   )

How It Works

Under the hood, the underlying ContextCompactor now periodically re-tests its anti-thrashing guard as conversations grow — see Anti-Thrashing Protection.

Compaction also runs inside a turn-protection window, so a bot in busy_mode="interrupt" queues a mid-compaction message instead of discarding the compaction — see Turn Protection Window.

Choose Your Policy

Configuration Options

Presets

CONSERVATIVE_POLICY

CONSERVATIVE_POLICY = ContextCompactionPolicyAdapter(
    trigger_at=0.80,
    strategy=CompactionStrategy.DROP_OLDEST_TOOLS,
    preserve_last_n_turns=8,
    target_utilization=0.60,
)

When to use: Short conversations, cheap models where early compaction doesn’t impact cost significantly.

BALANCED_POLICY (Default)

BALANCED_POLICY = ContextCompactionPolicyAdapter(
    trigger_at=0.90,
    strategy=CompactionStrategy.DROP_OLDEST_TOOLS,
    preserve_last_n_turns=5,
    target_utilization=0.70,
)

When to use: Most agents and standard use cases.

AGGRESSIVE_POLICY

AGGRESSIVE_POLICY = ContextCompactionPolicyAdapter(
    trigger_at=0.95,
    strategy=CompactionStrategy.SUMMARISE,
    preserve_last_n_turns=3,
    target_utilization=0.75,
    aggressive_tool_truncation=True,
)

When to use: Long tool-heavy loops or token-limited models where maximum context utilization is critical.

Routes (CompactionRoute enum)

Strategies (CompactionStrategy enum)

Tool Output Truncation

When aggressive_tool_truncation=True and any tool message content exceeds 1000 characters:

• Threshold: 1000 chars
• Keep: Head 300 chars + tail 200 chars
• Marker: ...[truncated N chars for context budget]...

Set aggressive_tool_truncation=False to disable this behavior.

Model Overrides

Use model_overrides to apply different settings per model:

ContextCompactionPolicy(
    trigger_at=0.90,
    model_overrides={
        "gpt-4o-mini": {"trigger_at": 0.80, "target_utilization": 0.60},
        "claude-haiku-4-5": {"trigger_at": 0.85},
    },
)

The override values take precedence over the base configuration for the specified models.

YAML / dict configuration

Policies serialize via to_dict() / from_dict() for CLI/YAML support:

execution:
  context_compaction:
    trigger_at: 0.85
    strategy: drop_oldest_tools
    preserve_last_n_turns: 5
    target_utilization: 0.65
    aggressive_tool_truncation: true

Strategy accepts a plain string in dict/YAML form.

Deprecation Notice

Common Patterns

Use BALANCED for most agents

from praisonaiagents import Agent, ExecutionConfig

agent = Agent(
    name="StandardAgent",
    execution=ExecutionConfig(context_compaction=True),  # Uses BALANCED_POLICY
)

Use AGGRESSIVE for token-tight models

from praisonaiagents import Agent, ExecutionConfig, AGGRESSIVE_POLICY

agent = Agent(
    name="TokenTightAgent", 
    llm="gpt-4o-mini",
    execution=ExecutionConfig(context_compaction=AGGRESSIVE_POLICY),
)

Per-model overrides for multi-model agents

from praisonaiagents import Agent, ExecutionConfig, ContextCompactionPolicy

policy = ContextCompactionPolicy(
    trigger_at=0.90,
    model_overrides={
        "gpt-4o-mini": {"trigger_at": 0.75},
        "gpt-4o": {"trigger_at": 0.95},
    }
)

agent = Agent(
    name="MultiModelAgent",
    execution=ExecutionConfig(context_compaction=policy),
)

Best Practices

= 3″> This ensures the agent doesn’t lose the active sub-task or recent conversation context that’s critical for coherent responses.

Related