context-compression
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseContext Compression
上下文压缩
Reduce context size while preserving information critical to task completion.
在保留任务完成所需关键信息的同时减小上下文规模。
Overview
概述
Context compression is essential for long-running agent sessions. The goal is NOT maximum compression—it's preserving enough information to complete tasks without re-fetching.
Key Metric: Tokens-per-task (total tokens to complete a task), NOT tokens-per-request.
上下文压缩对于长时间运行的Agent会话至关重要。我们的目标不是最大化压缩率,而是保留足够完成任务的信息,无需重新获取数据。
核心指标: Tokens-per-task(完成一项任务所需的总Token数),而非每请求Token数。
When to Use
使用场景
- Long-running conversations approaching context limits
- Multi-step agent workflows with accumulating history
- Sessions with large tool outputs
- Memory management in persistent agents
- 接近上下文限制的长时间对话
- 历史记录不断累积的多步骤Agent工作流
- 包含大量工具输出的会话
- 持久化Agent中的内存管理
Strategy Quick Reference
策略速查
| Strategy | Compression | Interpretable | Verifiable | Best For |
|---|---|---|---|---|
| Anchored Iterative | 60-80% | Yes | Yes | Long sessions |
| Opaque | 95-99% | No | No | Storage-critical |
| Regenerative Full | 70-85% | Yes | Partial | Simple tasks |
| Sliding Window | 50-70% | Yes | Yes | Real-time chat |
Recommended: Anchored Iterative Summarization with probe-based evaluation.
| Strategy | Compression | Interpretable | Verifiable | Best For |
|---|---|---|---|---|
| Anchored Iterative | 60-80% | Yes | Yes | Long sessions |
| Opaque | 95-99% | No | No | Storage-critical |
| Regenerative Full | 70-85% | Yes | Partial | Simple tasks |
| Sliding Window | 50-70% | Yes | Yes | Real-time chat |
推荐方案: 结合基于探针评估的Anchored Iterative Summarization。
Anchored Summarization (RECOMMENDED)
Anchored Summarization(推荐)
Maintains structured, persistent summaries with forced sections:
undefined通过强制划分的板块来维护结构化、持久化的摘要:
undefinedSession Intent
Session Intent
[What we're trying to accomplish - NEVER lose this]
[What we're trying to accomplish - NEVER lose this]
Files Modified
Files Modified
- path/to/file.ts: Added function X, modified class Y
- path/to/file.ts: Added function X, modified class Y
Decisions Made
Decisions Made
- Decision 1: Chose X over Y because [rationale]
- Decision 1: Chose X over Y because [rationale]
Current State
Current State
[Where we are in the task - progress indicator]
[Where we are in the task - progress indicator]
Blockers / Open Questions
Blockers / Open Questions
- Question 1: Awaiting user input on...
- Question 1: Awaiting user input on...
Next Steps
Next Steps
- Complete X
- Test Y
**Why it works:**
- Structure FORCES preservation of critical categories
- Each section must be explicitly populated (can't silently drop info)
- Incremental merge (new compressions extend, don't replace)
---- Complete X
- Test Y
**优势:**
- 结构化设计强制保留关键类别信息
- 每个板块都必须明确填充内容(不会静默丢失信息)
- 增量合并(新的压缩结果是扩展而非替换原有内容)
---Implementation
实现方案
python
from dataclasses import dataclass, field
from typing import Optional
@dataclass
class AnchoredSummary:
"""Structured summary with forced sections."""
session_intent: str
files_modified: dict[str, list[str]] = field(default_factory=dict)
decisions_made: list[dict] = field(default_factory=list)
current_state: str = ""
blockers: list[str] = field(default_factory=list)
next_steps: list[str] = field(default_factory=list)
compression_count: int = 0
def merge(self, new_content: "AnchoredSummary") -> "AnchoredSummary":
"""Incrementally merge new summary into existing."""
return AnchoredSummary(
session_intent=new_content.session_intent or self.session_intent,
files_modified={**self.files_modified, **new_content.files_modified},
decisions_made=self.decisions_made + new_content.decisions_made,
current_state=new_content.current_state,
blockers=new_content.blockers,
next_steps=new_content.next_steps,
compression_count=self.compression_count + 1,
)
def to_markdown(self) -> str:
"""Render as markdown for context injection."""
sections = [
f"## Session Intent\n{self.session_intent}",
f"## Files Modified\n" + "\n".join(
f"- `{path}`: {', '.join(changes)}"
for path, changes in self.files_modified.items()
),
f"## Decisions Made\n" + "\n".join(
f"- **{d['decision']}**: {d['rationale']}"
for d in self.decisions_made
),
f"## Current State\n{self.current_state}",
]
if self.blockers:
sections.append(f"## Blockers\n" + "\n".join(f"- {b}" for b in self.blockers))
sections.append(f"## Next Steps\n" + "\n".join(
f"{i+1}. {step}" for i, step in enumerate(self.next_steps)
))
return "\n\n".join(sections)python
from dataclasses import dataclass, field
from typing import Optional
@dataclass
class AnchoredSummary:
"""Structured summary with forced sections."""
session_intent: str
files_modified: dict[str, list[str]] = field(default_factory=dict)
decisions_made: list[dict] = field(default_factory=list)
current_state: str = ""
blockers: list[str] = field(default_factory=list)
next_steps: list[str] = field(default_factory=list)
compression_count: int = 0
def merge(self, new_content: "AnchoredSummary") -> "AnchoredSummary":
"""Incrementally merge new summary into existing."""
return AnchoredSummary(
session_intent=new_content.session_intent or self.session_intent,
files_modified={**self.files_modified, **new_content.files_modified},
decisions_made=self.decisions_made + new_content.decisions_made,
current_state=new_content.current_state,
blockers=new_content.blockers,
next_steps=new_content.next_steps,
compression_count=self.compression_count + 1,
)
def to_markdown(self) -> str:
"""Render as markdown for context injection."""
sections = [
f"## Session Intent\n{self.session_intent}",
f"## Files Modified\n" + "\n".join(
f"- `{path}`: {', '.join(changes)}"
for path, changes in self.files_modified.items()
),
f"## Decisions Made\n" + "\n".join(
f"- **{d['decision']}**: {d['rationale']}"
for d in self.decisions_made
),
f"## Current State\n{self.current_state}",
]
if self.blockers:
sections.append(f"## Blockers\n" + "\n".join(f"- {b}" for b in self.blockers))
sections.append(f"## Next Steps\n" + "\n".join(
f"{i+1}. {step}" for i, step in enumerate(self.next_steps)
))
return "\n\n".join(sections)Compression Triggers
压缩触发条件
| Threshold | Action |
|---|---|
| 70% capacity | Trigger compression |
| 50% capacity | Target after compression |
| 10 messages minimum | Required before compressing |
| Last 5 messages | Always preserve uncompressed |
| Threshold | Action |
|---|---|
| 70% capacity | Trigger compression |
| 50% capacity | Target after compression |
| 10 messages minimum | Required before compressing |
| Last 5 messages | Always preserve uncompressed |
CC 2.1.7: Effective Context Window
CC 2.1.7:有效上下文窗口
Calculate against effective context (after system overhead):
| Trigger | Static (CC 2.1.6) | Effective (CC 2.1.7) |
|---|---|---|
| Warning | 60% of static | 60% of effective |
| Compress | 70% of static | 70% of effective |
| Critical | 90% of static | 90% of effective |
基于有效上下文(扣除系统开销后)进行计算:
| Trigger | Static (CC 2.1.6) | Effective (CC 2.1.7) |
|---|---|---|
| Warning | 60% of static | 60% of effective |
| Compress | 70% of static | 70% of effective |
| Critical | 90% of static | 90% of effective |
Best Practices
最佳实践
DO
建议
- Use anchored summarization with forced sections
- Preserve recent messages uncompressed (context continuity)
- Test compression with probes, not similarity metrics
- Merge incrementally (don't regenerate from scratch)
- Track compression count and quality scores
- 使用带强制板块的Anchored Summarization
- 保留最近的消息不压缩(保证上下文连续性)
- 使用探针而非相似度指标测试压缩效果
- 增量合并(不要从头重新生成)
- 跟踪压缩次数和质量评分
DON'T
不建议
- Compress system prompts (keep at START)
- Use opaque compression for critical workflows
- Compress below the point of task completion
- Trigger compression opportunistically (use fixed thresholds)
- Optimize for compression ratio over task success
- 压缩系统提示词(应始终放在开头)
- 对关键工作流使用不透明压缩
- 压缩到影响任务完成的程度
- 随机触发压缩(应使用固定阈值)
- 为了压缩率而牺牲任务成功率
Target Metrics
目标指标
| Metric | Target | Red Flag |
|---|---|---|
| Probe pass rate | >90% | <70% |
| Compression ratio | 60-80% | >95% (too aggressive) |
| Task completion | Same as uncompressed | Degraded |
| Latency overhead | <2s | >5s |
| Metric | Target | Red Flag |
|---|---|---|
| Probe pass rate | >90% | <70% |
| Compression ratio | 60-80% | >95% (too aggressive) |
| Task completion | Same as uncompressed | Degraded |
| Latency overhead | <2s | >5s |
References
参考资料
For detailed implementation and patterns, see:
- Compression Strategies: Detailed comparison of all strategies (anchored, opaque, regenerative, sliding window), implementation patterns, and decision flowcharts
- Priority Management: Compression triggers, CC 2.1.7 effective context, probe-based evaluation, OrchestKit integration
如需详细的实现方案和模式,请参考:
- 压缩策略:所有策略(Anchored、Opaque、Regenerative Full、Sliding Window)的详细对比、实现模式和决策流程图
- 优先级管理:压缩触发条件、CC 2.1.7有效上下文、基于探针的评估、OrchestKit集成
Bundled Resources
配套资源
- - Template for structured compression summaries with forced sections
assets/anchored-summary-template.md - - Probe templates for validating compression quality
assets/compression-probes-template.md - - Detailed strategy comparisons
references/compression-strategies.md - - Compression triggers and evaluation
references/priority-management.md
- - 带强制板块的结构化压缩摘要模板
assets/anchored-summary-template.md - - 用于验证压缩质量的探针模板
assets/compression-probes-template.md - - 详细的策略对比文档
references/compression-strategies.md - - 压缩触发条件与评估文档
references/priority-management.md
Related Skills
相关技能
- - Attention mechanics and positioning
context-engineering - - Persistent storage patterns
memory-systems - - Context isolation across agents
multi-agent-orchestration - - Tracking compression metrics
observability-monitoring
Version: 1.0.0 (January )
Key Principle: Optimize for tokens-per-task, not tokens-per-request
Recommended Strategy: Anchored Iterative Summarization with probe-based evaluation
- - 注意力机制与定位
context-engineering - - 持久化存储模式
memory-systems - - Agent间上下文隔离
multi-agent-orchestration - - 压缩指标跟踪
observability-monitoring
版本: 1.0.0(1月)
核心原则: 优化每任务Token数,而非每请求Token数
推荐策略: 结合基于探针评估的Anchored Iterative Summarization
Capability Details
能力详情
anchored-summarization
anchored-summarization
Keywords: compress, summarize history, context too long, anchored summary
Solves:
- Reduce context size while preserving critical information
- Implement structured compression with required sections
- Maintain session intent and decisions through compression
关键词: compress, summarize history, context too long, anchored summary
解决问题:
- 在保留关键信息的同时减小上下文规模
- 实现带必填板块的结构化压缩
- 在压缩过程中保留会话意图与决策记录
compression-triggers
compression-triggers
Keywords: token limit, running out of context, when to compress
Solves:
- Determine when to trigger compression (70% utilization)
- Set compression targets (50% utilization)
- Preserve last 5 messages uncompressed
关键词: token limit, running out of context, when to compress
解决问题:
- 确定何时触发压缩(使用率达70%时)
- 设置压缩目标(使用率降至50%)
- 保留最后5条消息不压缩
probe-evaluation
probe-evaluation
Keywords: evaluate compression, test compression, probe
Solves:
- Validate compression quality with functional probes
- Test information preservation after compression
- Achieve >90% probe pass rate
关键词: evaluate compression, test compression, probe
解决问题:
- 使用功能性探针验证压缩质量
- 测试压缩后的信息保留情况
- 实现>90%的探针通过率