compaction

Context Compaction Example

When conversations get long, LocalHarness can automatically summarize older messages to stay within the LLM's context window.

How It Works

1. The engine checks token usage before each LLM call
2. If over the threshold, older messages are summarized by the LLM
3. The summary replaces old messages — recent messages are kept intact

Default Behavior

Compaction is enabled by default with a threshold of 100,000 tokens. You don't need to set anything — all sessions get compaction automatically.

SDK Usage

cfg := adk.NewLocalAgentConfig()
cfg.GeminiAPIKey = os.Getenv("GEMINI_API_KEY")

// CompactionThreshold controls context window compaction:
//   0  = use default (100K tokens) — this is the default
//   -1 = disable compaction entirely
//   >0 = custom threshold

cfg.CompactionThreshold = 50000  // Custom: compact at 50K tokens
cfg.CompactionThreshold = -1     // Disable compaction entirely
cfg.CompactionThreshold = 0      // Use default (100K) — same as not setting it

CLI Usage

go run ./cmd/testclient \
  --compaction-threshold=50000 \
  --prompt "Analyze all files in this large project"

What Gets Preserved

During compaction, the engine keeps the last 10 messages intact and summarizes everything before that. The summary preserves:

• Key decisions made
• File paths and their purposes
• Tool calls and outcomes
• User goals and progress
• Errors and resolutions

Observing Compaction

When compaction occurs, you'll see a StepUpdate with an ActionCompaction action:

{
  "action": "compaction",
  "original_tokens": 85000,
  "compacted_tokens": 12000,
  "messages_removed": 45,
  "summary": "The user asked to refactor the authentication module..."
}

If using the streaming SDK, you'll receive an EventCompaction event.

Disabling Compaction

Set CompactionThreshold = -1 to explicitly disable compaction.

Note: In previous versions, 0 meant "disabled". Starting from this release, 0 means "use default (100K tokens)" and -1 means "disabled".

Recommendations for Agent Builders (Zenith)

If you're building agents with the SDK (e.g., Zenith agents), consider:

1. Use the default — 100K is a good balance for most use cases
2. Set a lower threshold (e.g., 50K) for cost-sensitive agents
3. Monitor EventCompaction events to tune the threshold
4. Never disable compaction for production agents with long-running conversations