What problem does it solve?
When agent sessions generate millions of tokens of conversation history, compression becomes mandatory. The naive approach is aggressive compression to minimize tokens per request. The correct optimization target is tokens per task: total tokens consumed to complete a task, including re-fetching costs when compression loses critical information.
Core Features & Use Cases
- Anchored Iterative Summarization: Maintain structured, persistent summaries with explicit sections for session intent, file modifications, decisions, and next steps. When compression triggers, summarize only the newly-truncated span and merge with the existing summary. Structure forces preservation by dedicating sections to specific information types.
- Opaque Compression: Produce compressed representations optimized for reconstruction fidelity. Achieves highest compression ratios (99%+) but sacrifices interpretability. Cannot verify what was preserved.
- Regenerative Full Summary: Generate detailed structured summaries on each compression. Produces readable output but may lose details across repeated compression cycles due to full regeneration rather than incremental merging.
The critical insight: structure forces preservation. Dedicated sections act as checklists that the summarizer must populate, preventing silent information drift.
The Artifact Trail Problem
Artifact trail integrity is the weakest dimension across all compression methods, scoring 2.2-2.5 out of 5.0 in evaluations. Even structured summarization with explicit file sections struggles to maintain complete file tracking across long sessions.
Coding agents need to know:
- Which files were created
- Which files were modified and what changed
- Which files were read but not changed
- Function names, variable names, error messages
This problem likely requires specialized handling beyond general summarization: a separate artifact index or explicit file-state tracking in agent scaffolding.
Structured Summary Sections
Effective structured summaries include explicit sections:
Session Intent
[What the user is trying to accomplish]
Files Modified
- auth.controller.ts: Fixed JWT token generation
- config/redis.ts: Updated connection pooling
- tests/auth.test.ts: Added mock setup for new config
Decisions Made
- Using Redis connection pool instead of per-request connections
- Retry logic with exponential backoff for transient failures
Current State
- 14 tests passing, 2 failing
- Remaining: mock setup for session service tests
Next Steps
- Fix remaining test failures
- Run full test suite
- Update documentation
Compression Trigger Strategies
When to trigger compression matters as much as how to compress:
| Strategy | Trigger Point | Trade-off |
|----------|---------------|-----------|
| Fixed threshold | 70-80% context utilization | Simple but may compress too early |
| Sliding window | Keep last N turns + summary | Predictable context size |
| Importance-based | Compress low-relevance sections first | Complex but preserves signal |
| Task-boundary | Compress at logical task completions | Clean summaries but unpredictable timing |
The sliding window approach with structured summaries provides the best balance of predictability and quality for most coding agent use cases.
Probe-Based Evaluation
Traditional metrics like ROUGE or embedding similarity fail to capture functional compression quality. A summary may score high on lexical overlap while missing the one file path the agent needs.
Probe-based evaluation
File: .claude/skills/context-compression/references/evaluation-framework.md
Context Compression Evaluation Framework
This document provides the complete evaluation framework for measuring context compression quality, including probe types, scoring rubrics, and LLM judge configuration.
Probe Types
Recall Probes
- Question: What was the original error or issue that started this session?
Expected: [Original error text]
Note: Tests factual retention of history.
Artifact Probes
- Question: Which files were created or modified?
Expected: [List of files and changes]
Continuation Probes
- Question: What should we do next?
Expected: [Actionable next steps]
Decision Probes
- Question: Why was a particular approach chosen?
Expected: [Reasoning and alternatives considered]
Scoring Rubrics
The rubric sections define how responses are evaluated across accuracy, context awareness, artifact trail, completeness, continuity, and instruction following.
Additional Notes
- This framework assumes access to a stable session history and deterministic evaluation probes to minimize variation.
Quick Start
Run an evaluation cycle on a long-running session history to produce a structured compression summary and verify consistency across iterations.
References
Evaluation framework and probing methodology for context compression.
End of File
