Context Compression Strategies
When agent sessions generate millions of tokens of conversation history, compression becomes mandatory. Optimize for tokens per task (total tokens to complete a task, including re-fetching costs), not tokens per request.
When to Activate
- Agent sessions exceeding context window limits
- Codebases exceeding context windows (5M+ token systems)
- Designing conversation summarization strategies
- Debugging cases where agents "forget" modified files
Three Approaches
Anchored Iterative Summarization: Maintain structured, persistent summaries with explicit sections for session intent, file modifications, decisions, and next steps. On compression, summarize only the newly-truncated span and merge with 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.
Regenerative Full Summary: Generate detailed structured summaries on each compression. Readable output but may lose details across repeated cycles due to full regeneration rather than incremental merging.
Key insight: structure forces preservation. Dedicated sections act as checklists the summarizer must populate.
The Artifact Trail Problem
Artifact trail integrity is the weakest dimension across all compression methods (2.2–2.5/5.0). Coding agents need to track:
- Which files were created or modified and what changed
- Which files were read but not changed
- Function names, variable names, error messages
This likely requires specialized handling beyond general summarization: a separate artifact index or explicit file-state tracking.
Structured Summary Template
## Session Intent
[What the user is trying to accomplish]
## Files Modified
- auth.controller.ts: Fixed JWT token generation
- config/redis.ts: Updated connection pooling
## Decisions Made
- Using Redis connection pool instead of per-request connections
## Current State
- 14 tests passing, 2 failing
## Next Steps
1. Fix remaining test failures
2. Run full test suite
Compression Trigger Strategies
| 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 |
Sliding window with structured summaries provides the best balance for most coding agent use cases.
Probe-Based Evaluation
Traditional metrics (ROUGE, embedding similarity) fail to capture functional quality. Use probe questions after compression:
| Probe Type |
What It Tests |
Example |
| Recall |
Factual retention |
"What was the original error message?" |
| Artifact |
File tracking |
"Which files have we modified?" |
| Continuation |
Task planning |
"What should we do next?" |
| Decision |
Reasoning chain |
"What did we decide about the Redis issue?" |
Six Evaluation Dimensions
- Accuracy: Technical details correct? File paths, function names, error codes
- Context Awareness: Response reflects current conversation state?
- Artifact Trail: Agent knows which files were read or modified?
- Completeness: Response addresses all parts of the question?
- Continuity: Work can continue without re-fetching information?
- Instruction Following: Response respects stated constraints?
Three-Phase Compression Workflow
For large codebases or agent systems exceeding context windows:
- Research Phase: Produce a research document from architecture diagrams, docs, and key interfaces. Output: single structured analysis.
- Planning Phase: Convert research into implementation spec with function signatures, type definitions, and data flow. A 5M token codebase compresses to ~2,000 words.
- Implementation Phase: Execute against the spec rather than raw codebase exploration.
Implementing Anchored Iterative Summarization
- Define explicit summary sections matching your agent's needs
- On first compression, summarize truncated history into sections
- On subsequent compressions, summarize only new truncated content
- Merge into existing sections rather than regenerating
- Track which information came from which compression cycle
When to Use Each Approach
| Approach |
Best when |
| Anchored iterative |
Long sessions (100+ messages), file tracking matters, need verifiability |
| Opaque |
Maximum token savings needed, short sessions, low re-fetching costs |
| Regenerative |
Summary interpretability critical, clear phase boundaries |
Compression Ratios
| Method |
Compression |
Quality (5.0) |
Notes |
| Anchored Iterative |
98.6% |
3.70 |
Best quality |
| Regenerative |
98.7% |
3.44 |
Good quality |
| Opaque |
99.3% |
3.35 |
Best compression, quality loss |
The 0.7% additional tokens retained by structured summarization buys 0.35 quality points — worthwhile when re-fetching costs matter.
Guidelines
- Optimize for tokens-per-task, not tokens-per-request
- Use structured summaries with explicit file tracking sections
- Trigger compression at 70–80% context utilization
- Use incremental merging rather than full regeneration
- Test compression quality with probe-based evaluation
- Track artifact trail separately when file tracking is critical
References
- Evaluation Framework Reference — probe types and scoring rubrics
- Related skills: context-degradation, context-optimization, evaluation, memory-systems
- Factory Research: Evaluating Context Compression for AI Agents (December 2025)
- Netflix Engineering: "The Infinite Software Crisis" — three-phase workflow (AI Summit 2025)
1---2name: context-compression3description: This skill should be used when the user asks to "compress context", "summarize conversation history", "implement compaction", "reduce token usage", or mentions context compression, structured summarization, tokens-per-task optimization, or long-running agent sessions exceeding context limits.4---56# Context Compression Strategies78When agent sessions generate millions of tokens of conversation history, compression becomes mandatory. Optimize for tokens per task (total tokens to complete a task, including re-fetching costs), not tokens per request.910## When to Activate1112- Agent sessions exceeding context window limits13- Codebases exceeding context windows (5M+ token systems)14- Designing conversation summarization strategies15- Debugging cases where agents "forget" modified files1617## Three Approaches18191. **Anchored Iterative Summarization**: Maintain structured, persistent summaries with explicit sections for session intent, file modifications, decisions, and next steps. On compression, summarize only the newly-truncated span and merge with existing summary. Structure forces preservation by dedicating sections to specific information types.20212. **Opaque Compression**: Produce compressed representations optimized for reconstruction fidelity. Achieves highest compression ratios (99%+) but sacrifices interpretability.22233. **Regenerative Full Summary**: Generate detailed structured summaries on each compression. Readable output but may lose details across repeated cycles due to full regeneration rather than incremental merging.2425**Key insight**: structure forces preservation. Dedicated sections act as checklists the summarizer must populate.2627## The Artifact Trail Problem2829Artifact trail integrity is the weakest dimension across all compression methods (2.2–2.5/5.0). Coding agents need to track:30- Which files were created or modified and what changed31- Which files were read but not changed32- Function names, variable names, error messages3334This likely requires specialized handling beyond general summarization: a separate artifact index or explicit file-state tracking.3536## Structured Summary Template3738```markdown39## Session Intent40[What the user is trying to accomplish]4142## Files Modified43- auth.controller.ts: Fixed JWT token generation44- config/redis.ts: Updated connection pooling4546## Decisions Made47- Using Redis connection pool instead of per-request connections4849## Current State50- 14 tests passing, 2 failing5152## Next Steps531. Fix remaining test failures542. Run full test suite55```5657## Compression Trigger Strategies5859| Strategy | Trigger Point | Trade-off |60|----------|---------------|-----------|61| Fixed threshold | 70–80% context utilization | Simple but may compress too early |62| Sliding window | Keep last N turns + summary | Predictable context size |63| Importance-based | Compress low-relevance sections first | Complex but preserves signal |64| Task-boundary | Compress at logical task completions | Clean summaries but unpredictable timing |6566Sliding window with structured summaries provides the best balance for most coding agent use cases.6768## Probe-Based Evaluation6970Traditional metrics (ROUGE, embedding similarity) fail to capture functional quality. Use probe questions after compression:7172| Probe Type | What It Tests | Example |73|------------|---------------|---------|74| Recall | Factual retention | "What was the original error message?" |75| Artifact | File tracking | "Which files have we modified?" |76| Continuation | Task planning | "What should we do next?" |77| Decision | Reasoning chain | "What did we decide about the Redis issue?" |7879## Six Evaluation Dimensions80811. **Accuracy**: Technical details correct? File paths, function names, error codes822. **Context Awareness**: Response reflects current conversation state?833. **Artifact Trail**: Agent knows which files were read or modified?844. **Completeness**: Response addresses all parts of the question?855. **Continuity**: Work can continue without re-fetching information?866. **Instruction Following**: Response respects stated constraints?8788## Three-Phase Compression Workflow8990For large codebases or agent systems exceeding context windows:91921. **Research Phase**: Produce a research document from architecture diagrams, docs, and key interfaces. Output: single structured analysis.932. **Planning Phase**: Convert research into implementation spec with function signatures, type definitions, and data flow. A 5M token codebase compresses to ~2,000 words.943. **Implementation Phase**: Execute against the spec rather than raw codebase exploration.9596## Implementing Anchored Iterative Summarization97981. Define explicit summary sections matching your agent's needs992. On first compression, summarize truncated history into sections1003. On subsequent compressions, summarize only new truncated content1014. Merge into existing sections rather than regenerating1025. Track which information came from which compression cycle103104## When to Use Each Approach105106| Approach | Best when |107|----------|-----------|108| Anchored iterative | Long sessions (100+ messages), file tracking matters, need verifiability |109| Opaque | Maximum token savings needed, short sessions, low re-fetching costs |110| Regenerative | Summary interpretability critical, clear phase boundaries |111112## Compression Ratios113114| Method | Compression | Quality (5.0) | Notes |115|--------|-------------|---------------|-------|116| Anchored Iterative | 98.6% | 3.70 | Best quality |117| Regenerative | 98.7% | 3.44 | Good quality |118| Opaque | 99.3% | 3.35 | Best compression, quality loss |119120The 0.7% additional tokens retained by structured summarization buys 0.35 quality points — worthwhile when re-fetching costs matter.121122## Guidelines1231241. Optimize for tokens-per-task, not tokens-per-request1252. Use structured summaries with explicit file tracking sections1263. Trigger compression at 70–80% context utilization1274. Use incremental merging rather than full regeneration1285. Test compression quality with probe-based evaluation1296. Track artifact trail separately when file tracking is critical130131## References132133- [Evaluation Framework Reference](./references/evaluation-framework.md) — probe types and scoring rubrics134- Related skills: context-degradation, context-optimization, evaluation, memory-systems135- Factory Research: Evaluating Context Compression for AI Agents (December 2025)136- Netflix Engineering: "The Infinite Software Crisis" — three-phase workflow (AI Summit 2025)
lidge-jun