CompactionConfig

CompactionConfig controls server-side context compaction across direct Anthropic, Azure Anthropic, AWS Bedrock, direct OpenAI, and Azure OpenAI. Appam maps the same high-level setting onto each provider's wire format underneath.

Most callers use AgentBuilder::enable_auto_compaction(trigger_tokens) instead of constructing this struct directly; use the struct form when you need custom summarization instructions or the provider-default trigger.

Struct Definition

pub struct CompactionConfig {
    pub enabled: bool,
    pub trigger_tokens: Option<u64>,
    pub instructions: Option<String>,
}

Fields

enabled

Whether provider-side compaction is requested. Defaults to false.

trigger_tokens

Token threshold at which the provider triggers compaction. None uses 150,000 tokens (Anthropic's server default, applied to both providers for predictability).

Provider minimums are enforced by clamping with a warning:

• Anthropic (all transports): 50,000 tokens
• OpenAI (direct, Azure): 1,000 tokens

instructions

Custom summarization prompt (Anthropic only — OpenAI ignores it). Completely replaces Anthropic's default prompt when set. Useful to pin what must survive compaction or to forbid tool use during the internal summarization step.

Constructors

// Enabled with the provider-default trigger threshold
let config = CompactionConfig::enabled();

// Enabled with an explicit trigger threshold
let config = CompactionConfig::with_trigger_tokens(100_000);

// With custom Anthropic summarization instructions
let config = CompactionConfig::with_trigger_tokens(80_000)
    .instructions("Preserve code snippets and open TODOs. Do not call tools.");

Usage with AgentBuilder

use appam::prelude::*;

// Shorthand
let agent = AgentBuilder::new("agent")
    .model("claude-sonnet-4-6")
    .system_prompt("You are a coding agent.")
    .enable_auto_compaction(100_000)
    .build()?;

// Full config form
let agent = AgentBuilder::new("agent")
    .model("claude-sonnet-4-6")
    .system_prompt("You are a coding agent.")
    .compaction(CompactionConfig::with_trigger_tokens(80_000))
    .build()?;

disable_auto_compaction() undoes a previous call on the same builder.

Provider Mapping

Providers without server-side compaction (OpenRouter, Vertex, OpenAI Codex) ignore the configuration; appam logs a warning at session start.

Usage Tracking

Anthropic bills the compaction pass separately from the response (usage.iterations). Appam surfaces those tokens on UnifiedUsage::compaction_input_tokens / compaction_output_tokens and aggregates them into AggregatedUsage::total_compaction_input_tokens / total_compaction_output_tokens, billed at the model's standard input/output rates.

See the Context Compaction guide for threshold guidance, streaming hooks, and runnable examples.