context-compactor

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Context Compactor

Automatically summarizes and compacts context when approaching token limits while preserving critical information.

当上下文接近token限制时，自动对其进行摘要和压缩，同时保留关键信息。

Quick Start

快速开始

Check if Compaction Needed

检查是否需要压缩

python

from scripts.compactor import ContextCompactor

compactor = ContextCompactor()
if compactor.should_compact(context, limit=100000):
    compacted = compactor.compact(context)

python

from scripts.compactor import ContextCompactor

compactor = ContextCompactor()
if compactor.should_compact(context, limit=100000):
    compacted = compactor.compact(context)

Compact Context

压缩上下文

python

compacted = compactor.compact(context)

python

compacted = compactor.compact(context)

Preserves: architectural decisions, bugs, current state

保留：架构决策、bug、当前状态

Discards: stale tool outputs, redundant messages

丢弃：过期工具输出、冗余消息

undefined

undefined

Preservation Strategy

保留策略

┌─────────────────────────────────────────────────────────────┐
│                  PRESERVATION PRIORITY                       │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  MUST PRESERVE (Never remove)                               │
│  ├─ Architectural decisions                                 │
│  ├─ Unresolved bugs and blockers                           │
│  ├─ Current feature state                                   │
│  ├─ Recent file changes (last 5)                           │
│  └─ Error patterns and solutions                           │
│                                                              │
│  CAN SUMMARIZE (Compress to summary)                        │
│  ├─ Completed features (list of IDs)                       │
│  ├─ Resolved errors (brief mention)                        │
│  └─ Historical decisions (key points)                      │
│                                                              │
│  CAN DISCARD (Remove entirely)                              │
│  ├─ Redundant tool outputs                                 │
│  ├─ Stale search results                                   │
│  ├─ Superseded messages                                    │
│  └─ Verbose logging                                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│                  保留优先级                                   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  必须保留（绝不删除）                                       │
│  ├─ 架构决策                                               │
│  ├─ 未解决的bug和阻塞问题                                   │
│  ├─ 当前功能状态                                           │
│  ├─ 最近的文件变更（最近5次）                               │
│  └─ 错误模式与解决方案                                       │
│                                                              │
│  可摘要（压缩为摘要内容）                                    │
│  ├─ 已完成功能（ID列表）                                   │
│  ├─ 已解决错误（简要提及）                                   │
│  └─ 历史决策（关键点）                                       │
│                                                              │
│  可丢弃（完全移除）                                        │
│  ├─ 冗余工具输出                                           │
│  ├─ 过期搜索结果                                           │
│  ├─ 已被替代的消息                                           │
│  └─ 冗余日志                                               │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Compaction Process

压缩流程

Score Importance: Assign score to each message/content
Identify Critical: Mark must-preserve content
Summarize Middle: Compress can-summarize content
Discard Stale: Remove can-discard content
Validate: Ensure compacted context is coherent

重要性评分: 为每条消息/内容分配重要性评分
标记关键内容: 标记必须保留的内容
摘要中间内容: 压缩可摘要的内容
丢弃过期内容: 移除可丢弃的内容
验证: 确保压缩后的上下文连贯

Token Budgets

Token预算

Context Type	Limit	Action
< 50%	Normal	No action
50-75%	Warning	Prepare for compaction
75-90%	Compact	Trigger compaction
> 90%	Critical	Aggressive compaction

上下文类型	限制比例	操作
< 50%	正常	不执行操作
50-75%	警告	准备压缩
75-90%	执行压缩	触发压缩
> 90%	紧急	强制压缩

Integration Points

集成点

autonomous-session-manager: Triggers compaction check
memory-manager: Stores compacted summaries
handoff-coordinator: Uses compacted state for handoffs

autonomous-session-manager: 触发压缩检查
memory-manager: 存储压缩后的摘要
handoff-coordinator: 使用压缩后的状态进行交接

References

参考文档

```
references/COMPACTION-STRATEGY.md
```
- Detailed strategy
```
references/TOKEN-BUDGETS.md
```
- Budget management

```
references/COMPACTION-STRATEGY.md
```
- 详细策略文档
```
references/TOKEN-BUDGETS.md
```
- 预算管理文档

Scripts

脚本文件

```
scripts/compactor.py
```
- Core ContextCompactor
```
scripts/importance_scorer.py
```
- Message scoring
```
scripts/summarizer.py
```
- Content summarization
```
scripts/token_estimator.py
```
- Token counting

```
scripts/compactor.py
```
- 核心ContextCompactor模块
```
scripts/importance_scorer.py
```
- 消息评分模块
```
scripts/summarizer.py
```
- 内容摘要模块
```
scripts/token_estimator.py
```
- Token计数模块