Headroom 深度实战：当上下文窗口成为 AI Agent 的成本黑洞——从 Token 爆炸到 60-95% 压缩率的生产级完全指南（2026）

序言：你的 AI Agent 在「吃」Token，你在「烧」钱

2026 年，AI 编码助手已经从「尝鲜玩具」进化成了「生产力基础设施」。Claude Code、Cursor、Windsurf、GitHub Copilot、Codex CLI……每个工程师的手机和电脑上或多或少都装了一两个。但有一个问题，大多数人要么选择性忽视，要么假装这不是自己的问题：Token 账单每个月都在涨，而你付的钱里，很大一部分是让 AI 去读「废话」。

举个真实的例子。你让 Claude Code 去排查一个线上故障，它执行了这些命令：

kubectl get pods -n production
docker logs --tail=500 my-service-7d9f4b-xkm2p
git log --oneline -n 50
grep -r "ERROR" ./logs/
curl -s http://api.internal/health

每一次工具调用，AI Agent 都要把完整输出塞进上下文。你知道这加起来是多少 Token 吗？一个中等规模的故障排查场景，工具输出轻松突破 50,000 Token。如果你的 Agent 每小时跑 10 次这样的任务，光工具输出一天就要烧掉 数美元。一个月下来，Token 开销轻松破百——这还只是一个工程师的使用量。

更隐蔽的问题是：KV Cache 失效。 Anthropic 和 OpenAI 的推理优化依赖于稳定的前缀缓存——如果两次请求的前缀完全相同，第二次推理会快得多。但工具输出里充满了时间戳、进程 ID、容器名、哈希值，每次都不同。前缀在变，Cache 命中率为零。你付的是全价推理速度，但享受到的却是零缓存加速。

这就是 Headroom 要解决的问题。

一、Headroom 是什么：从「塞更多」到「看更少」

Headroom（GitHub: chopratejas/headroom）是一个开源的上下文压缩中间层，运行在你的机器本地，在数据到达 LLM 之前进行智能压缩。它的核心理念非常清晰：

不改变 Agent 的行为，只压缩它「看到」的内容。

Agent → [Headroom 压缩层] → LLM Provider
  ↓
 原文存入本地 CCR 仓库（可逆，随时可查）

Headroom 做到了一件所有竞品都没做到的事：有损压缩 + 零信息丢失。它通过 CCR（Context Compression with Retrieval，可逆压缩）机制，在压缩发送给 LLM 的上下文的同时，完整保留原始数据在本地存储中。如果 LLM 需要某个具体信息，只需调用 headroom_retrieve 工具，原始内容立即还原。

当前版本 v0.25.0，Apache 2.0 许可证，完全可商用。支持四种接入方式：

实测压缩效果（来自官方 README）：

• 17,765 Token 的代码搜索结果 → 1,408 Token，节省 92%
• 6 万 Token 的日志文件 → 3,000 Token，节省 95%
• 工具输出平均节省 60-95%

而且，Headroom 运行在本地。你的数据不经过任何第三方服务器，不存在隐私泄露风险。这是它区别于所有 Provider 原生压缩方案的根本差异。

二、架构拆解：10 阶段管线与六大压缩引擎

理解 Headroom 的架构，需要从两个维度入手：压缩管线生命周期和核心压缩引擎。

2.1 压缩管线：10 阶段生命周期

Headroom 的压缩不是一次性的「截断+发送」，而是一个完整的 10 阶段生命周期：

Setup → Pre-Start → Post-Start → Input Received → Input Cached
→ Input Routed → Input Compressed → Input Remembered
→ Pre-Send → Post-Send → Response Received

每个阶段都有明确的职责：

• Setup / Pre-Start / Post-Start：初始化阶段，配置加载、模型预热、连接建立
• Input Received：接收原始数据（工具输出、日志文件、RAG 片段、对话历史）
• Input Cached：原文存入 CCR 本地仓库（可逆存储）
• Input Routed：ContentRouter 根据内容类型分发到对应压缩引擎
• Input Compressed：各压缩引擎执行智能压缩
• Input Remembered：跨 Agent 记忆同步（如果启用）
• Pre-Send / Post-Send：发送前最终处理、统计记录
• Response Received：接收 LLM 响应，可能触发后续压缩任务

这个管线的设计非常巧妙：原文永远保留在本地，只有压缩后的摘要发给 LLM。如果 LLM 在推理过程中发现某个信息缺失，它可以通过 MCP 工具 headroom_retrieve 按需获取原始内容。

2.2 ContentRouter：智能内容分发中枢

ContentRouter 是整个压缩管线的「调度中心」，负责检测输入内容的类型，将不同数据分发到最适合的压缩引擎：

JSON 数据（API 响应、工具输出）  → SmartCrusher
代码文件（Python/JS/Go/Rust...） → CodeCompressor
自然语言文本（对话、文档）       → Kompress-base
图片/多模态内容                 → Image Compressor
通用混合内容                    → IntelligentContext

这种按内容类型选择压缩策略的设计，比「一刀切」的通用压缩效果好得多。JSON 有 JSON 的冗余模式，代码有代码的结构特征，通用压缩器很难同时处理好所有类型。ContentRouter 正是利用了这个领域知识。

2.3 SmartCrusher：JSON 专用压缩引擎

AI Agent 的工具输出大量是 JSON 格式——kubectl 的输出、API 响应、数据库查询结果、测试报告，全部都是结构化 JSON。SmartCrusher 专门处理这类数据，推测的压缩策略包括：

结构扁平化：将深层嵌套的 JSON 压平为更紧凑的表示。例如：

// 原始 JSON（工具输出中常见的结构）
{
  "metadata": {
    "timestamp": "2026-06-15T12:30:00Z",
    "request_id": "req_8f3k2j1h9g",
    "version": "v2.1.0"
  },
  "data": {
    "items": [
      {"id": 1, "name": "item_a", "status": "running"},
      {"id": 2, "name": "item_b", "status": "completed"}
    ],
    "pagination": {"page": 1, "total": 50}
  }
}

压缩后可能变成：

// SmartCrusher 压缩后
{
  "_meta": {"req": "req_8f3k2j1h9g", "ts": "2026-06-15T12:30:00Z", "v": "v2.1.0"},
  "items[0]": {"id": 1, "name": "item_a", "status": "running"},
  "items[1]": {"id": 2, "name": "item_b", "status": "completed"},
  "_pgn": {"page": 1, "total": 50}
}

类型感知编码：根据值类型选择最优编码。数字保留为数字（不转字符串），布尔值保持单字符，去掉冗余的键名。

去重与摘要：对重复的键值模式进行合并或摘要。50 个结构相同的 Pod 对象，不需要把每个对象的完整字段都发送一遍，可以只发字段名 + 类型信息 + 差异摘要。

实测：100 条代码搜索结果从 17,765 Token 压缩到 1,408 Token，节省 92%。

2.4 CodeCompressor：AST 感知的代码压缩

这是 Headroom 最精巧的设计。CodeCompressor 不是简单地截断代码，而是基于 AST（抽象语法树）进行结构感知压缩，支持 Python、JavaScript/TypeScript、Go、Rust、Java、C++ 六种语言。

传统的代码压缩要么截断（丢失上下文），要么去注释（丢失意图），效果都很粗暴。AST 感知压缩的核心思路是：保留代码的结构骨架，对实现细节进行摘要。

以一个 Python 函数为例：

# 原始代码（假设 AI 读取了一个 500 行的 Python 文件）
def process_user_request(user_id: int, request_data: dict) -> dict:
    """
    Process incoming user request with validation and transformation.
    Handles edge cases and logs all operations.
    """
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise UserNotFoundError(f"User {user_id} not found")
    
    validated_data = validate_schema(request_data)
    transformed = transform_payload(validated_data)
    
    result = db.execute(
        text("INSERT INTO processed_requests ...")
    )
    
    audit_log.info(f"Processed request for user {user_id}")
    return {"status": "success", "result_id": result.inserted_primary_key}

AST 压缩后可能变成：

def process_user_request(user_id: int, request_data: dict) -> dict:
    # DB: User query by id
    # Validation: validate_schema(request_data)
    # Transform: transform_payload(validated_data)
    # DB: INSERT INTO processed_requests
    # Log: audit_log.info(...)
    return {"status": "success", "result_id": result.inserted_primary_key}

函数签名保留——Agent 知道这个函数接受什么参数、返回什么类型。类/函数调用关系保留——Agent 知道这个函数依赖哪些其他函数。实现细节被摘要——Agent 知道「这里查了数据库」「这里做了验证」，但不需要逐行阅读所有 SQL 语句。

更重要的是，这种压缩是可逆的。通过 headroom_retrieve，Agent 可以随时还原某一行代码的完整内容。

2.5 Kompress-base：专为 Agent 场景训练的压缩模型

Headroom 团队在 HuggingFace 上发布了一个专用压缩模型：chopratejas/kompress-v2-base，在 Agent 交互轨迹数据上训练（原文："trained on agentic traces"）。

与通用文本压缩不同，Kompress-base 针对 Agent 的对话模式进行了专门优化。AI Agent 的交互有其独特的结构特征：

• 工具调用模式：tool_use、tool_result 这样的标记是固定的
• 中间推理过程：Agent 的思维链（Chain-of-Thought）有固定的模式
• 状态更新模式：对话中反复出现的「环境状态」「文件状态」是相似的

通用压缩器会把这些固定模式当成普通文本重复压缩，而 Kompress-base 学会了识别这些模式并做专门处理。

2.6 CacheAligner：被忽视的 KV Cache 加速器

这是 Headroom 中最容易被忽视但实际价值极高的组件。

LLM 推理服务使用 KV Cache 来加速推理：如果请求的前缀和之前一样，就不需要重新计算这部分内容的向量，直接复用即可。但问题是：

# 第一次请求
kubectl get pods -n production
# 输出中有时间戳：2026-06-15T12:30:00Z

# 第二次请求（10秒后）
kubectl get pods -n production
# 输出中有时间戳：2026-06-15T12:30:10Z

两次请求的前缀都是 kubectl get pods -n production\n，但因为输出内容中包含动态时间戳，整个前缀哈希值都变了，KV Cache 完全失效。

CacheAligner 的做法是：稳定化前缀。它将动态值（时间戳、UUID、进程 ID、容器名哈希）替换为固定占位符，让相同的请求结构产生相同的前缀：

# CacheAligner 处理前
kubectl get pods -n production
2026-06-15T12:30:00Z  pod/my-service-7d9f4b-xkm2p Running
2026-06-15T12:30:00Z  pod/my-service-7d9f4b-jk3lp Running

# CacheAligner 处理后
kubectl get pods -n production
<TIMESTAMP>  pod/my-service-7d9f4b-xkm2p Running
<TIMESTAMP>  pod/my-service-7d9f4b-jk3lp Running

在高频调用场景下（这恰恰是 AI Agent 的典型使用模式），KV Cache 命中率提升带来的不仅是 Token 节省，还有推理延迟的显著降低——理论上最高可降低 3 倍（参考 ContextPilot 论文数据）。

2.7 CCR：可逆压缩的核心机制

CCR（Context Compression with Retrieval）是 Headroom 区别于所有竞品的核心特性，也是它能做到「有损压缩 + 零信息丢失」的底层保障。

传统压缩是不可逆的——信息一旦压缩就丢失了。CCR 的设计哲学是：原文永远在，摘要发给 LLM，按需还原。

# CCR 工作原理伪代码
from headroom import compress, retrieve

# Step 1: 原始数据存入本地仓库（这里模拟）
original_log = open("app.log").read()  # 10万 Token

# Step 2: 压缩后发给 LLM
compressed = compress(original_log, strategy="smart")
print(f"压缩后 Token 数: {compressed.token_count}")
# 输出: 压缩后 Token 数: 3200

# Step 3: LLM 在推理中发现需要看第 42 行的完整内容
retrieved = retrieve(compressed.id, line=42)
print(retrieved)
# 输出: "2026-06-15 12:30:42 ERROR [PaymentService] Transaction failed: timeout after 30s"

CCR 本地仓库默认使用 SQLite 存储，支持配置自定义存储后端。所有数据都在本地，不经过任何第三方——这是 Headroom 能做到真正隐私保护的底层原因。

2.8 headroom learn：从失败中学习的闭环

headroom learn 是 Headroom 最具「Agent 味」的功能，也是我认为最有长期价值的设计。

headroom learn --analyze-failed ./sessions/failed-2026-06-15/

它会：

1. 分析 Agent 的失败会话（比如代码修改后测试失败、部署报错）
2. 提取失败原因和修正方案
3. 自动写入 CLAUDE.md / AGENTS.md / GEMINI.md

这相当于给 Agent 一个「错题本」。下次遇到类似问题，Agent 会自动参考之前记录的教训，而不需要你再重复解释一遍。

<!-- CLAUDE.md 自动追加内容 -->
## 已知陷阱 (from headroom learn, 2026-06-15)

- 不要在生产环境直接运行 `rm -rf ./dist`——应该先检查 .gitignore
- `docker build` 时加上 `--no-cache` 否则会用到旧的依赖
- PostgreSQL 迁移前先备份：pg_dump > backup.sql

三、基准测试：压缩率与精度的真实数据

Headroom 官方提供了一套基准测试，覆盖四个维度：

关键发现：

• 数学推理：精度完全不降，压缩不影响逻辑推理能力
• 事实准确性：甚至略有提升（+3pp）——这可能是因为压缩去除了干扰信息，让模型更专注于关键事实
• 阅读理解和工具调用：精度几乎不降（仅损失约 3pp），但压缩率显著（19-32%）

这组数据说明：Headroom 的压缩是有选择性的智能压缩，不是粗暴的「砍掉后半段」。它优先去除的是对推理无用的冗余信息（重复的键名、格式噪声、时间戳），而保留对任务完成至关重要的语义内容。

四、实战接入：从 0 到生产级部署

4.1 安装

# 完整安装（推荐）
pip install "headroom-ai[all]"

# 基础安装（仅 Python 库）
pip install headroom-ai

# TypeScript SDK
npm install headroom-ai

# CLI（独立安装）
curl -fsSL https://get.headroom.sh | sh

4.2 方式一：Agent Wrap（推荐，零配置）

# 一行命令，自动接管 Claude Code
headroom wrap claude

# 查看压缩统计
headroom stats

# 输出示例：
# Total tokens:     234,567
# Compressed to:     45,231
# Saved:            189,336 (80.7%)
# Estimated cost:   $0.23 → $0.04

Wrap 模式的工作原理是：替换掉 Agent 的 LLM 调用入口，所有请求先经过 Headroom 压缩层，处理后再发往实际的 LLM Provider。对于 Claude Code 来说，这个过程完全透明——它以为自己还在直接和 LLM 通信。

4.3 方式二：Proxy 模式（零代码，任意语言）

# 启动本地代理
headroom proxy --port 8787 --upstream https://api.anthropic.com

# 配置环境变量
export ANTHROPIC_API_BASE="http://localhost:8787"

# 现在所有 Anthropic API 请求都经过 Headroom 压缩
claude --dangerously-skip-permissions

Proxy 模式的优势是零代码侵入。任何通过 HTTP API 调用 LLM 的应用，不需要修改一行代码，只要把请求发到 localhost:8787 即可。Headroom 会自动处理请求/响应拦截、压缩、统计。

4.4 方式三：Python Library（生产集成）

from headroom import Headroom, CompressionStrategy
from headroom.config import HeadroomConfig

# 初始化
config = HeadroomConfig(
    model="claude-sonnet-4-20250514",
    strategies=[
        CompressionStrategy.SMART_CRUSHER,  # JSON 工具输出
        CompressionStrategy.CODE_COMPRESSOR, # 代码文件
        CompressionStrategy.KOMPRESS_BASE,   # 自然语言文本
    ],
    ccr_enabled=True,  # 启用可逆压缩
    cache_align=True,  # 启用 KV Cache 加速
)

h = Headroom(config)

# 模拟一个 AI Agent 的消息流
messages = [
    {
        "role": "user",
        "content": "帮我排查这个 API 的问题，日志在下面。"
    },
    {
        "role": "tool_result",
        "tool_use_id": "tool_01",
        "content": open("api_server.log").read()  # 假设是 8 万 Token 的日志
    },
    {
        "role": "assistant",
        "content": "我来分析日志..."
    }
]

# 压缩
result = h.compress(messages)

print(f"原始 Token: {result.original_tokens}")
print(f"压缩后 Token: {result.compressed_tokens}")
print(f"节省: {result.savings_percent:.1f}%")
print(f"CCR ID: {result.ccr_id}")  # 用于后续按需还原

# 发送压缩后的消息
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=result.messages,  # 直接用压缩后的消息
    max_tokens=4096
)

# 按需还原：如果 LLM 需要看日志的某一行
if "line 4237" in response.content:
    original_line = h.retrieve(result.ccr_id, line=4237)
    print(original_line)

4.5 方式四：MCP Server（跨客户端标准协议）

# 安装 MCP 服务器
headroom mcp install

# Claude Desktop 配置（~/.claude/settings.json）
{
  "mcpServers": {
    "headroom": {
      "command": "headroom",
      "args": ["mcp", "start"]
    }
  }
}

MCP Server 提供三个标准工具：

• headroom_compress：压缩任意内容
• headroom_retrieve：按 ID 还原原始内容
• headroom_stats：查看压缩统计

4.6 跨 Agent 记忆：Claude + Codex + Gemini 共享上下文

这是 Headroom 另一个非常实用的功能。如果你在多个 Agent 之间协作（比如用 Claude Code 写代码，用 Codex CLI 做代码审查，用 Gemini 做文档生成），每个 Agent 都会积累自己的上下文。

# 配置跨 Agent 记忆存储
headroom memory --shared --backend sqlite

# 启用跨 Agent 自动去重
headroom dedup --agents claude,codex,gemini

Headroom 会自动在多个 Agent 的记忆之间进行交叉去重——如果 Claude Code 已经读过某个文件，Codex 就不需要再读一遍。实测在多 Agent 协作场景下，这能额外节省 20-40% 的 Token。

4.7 Dashboard：可视化监控

headroom dashboard --port 3000

启动一个本地 Dashboard，可以看到：

• 实时 Token 节省曲线
• 按模型分组的节省明细
• 预期 vs 实际成本对比图表
• 压缩率分布直方图

对于团队管理员来说，这个 Dashboard 是向老板证明「Headroom 确实在省钱」的最佳工具。

五、生产级配置：不同场景的最优策略

5.1 高频工具调用场景（SRE 故障排查、CI/CD）

这类场景的特点是：工具输出多、实时性要求高、Token 消耗大。

config = HeadroomConfig(
    model="claude-haiku-4-20250514",  # 用更小的模型做摘要推理
    strategies=[
        CompressionStrategy.SMART_CRUSHER,  # 强制启用 JSON 压缩
        CompressionStrategy.INTELLIGENT_CONTEXT,  # 重要性评分
    ],
    ccr_enabled=True,
    cache_align=True,  # 关键：启用 KV Cache 对齐
    aggressive_mode=True,  # 更激进的压缩（适合工具输出）
    token_budget=4096,  # 硬上限：任何输入不超过 4096 Token
)

关键配置：

• aggressive_mode=True：启用更高压缩率，允许小幅精度损失换取 Token 节省
• token_budget=4096：硬上限，防止任何单次请求超过上下文窗口的 50%
• cache_align=True：KV Cache 对齐，高频调用场景收益最大

5.2 代码审查场景（多文件、长上下文）

config = HeadroomConfig(
    strategies=[
        CompressionStrategy.CODE_COMPRESSOR,  # AST 感知代码压缩
        CompressionStrategy.KOMPRESS_BASE,    # 对话文本压缩
    ],
    ccr_enabled=True,
    preserve_imports=True,  # 保留所有 import 语句
    preserve_signatures=True,  # 保留所有函数签名
    summary_depth="detailed",  # 摘要详细程度：detailed > normal > brief
)

关键配置：

• preserve_imports=True：代码审查中，依赖关系是核心上下文
• preserve_signatures=True：Agent 需要知道每个函数的签名才能做有效审查
• summary_depth="detailed"：代码审查需要更详细的摘要，不能过度压缩

5.3 RAG 检索增强场景

config = HeadroomConfig(
    strategies=[
        CompressionStrategy.INTELLIGENT_CONTEXT,  # 重要性评分选择
    ],
    ccr_enabled=True,
    retrieval_top_k=20,  # 从压缩上下文中保留最重要的 20 条
    rerank=True,  # 启用重排序
)

RAG 场景的特殊性在于：检索结果通常已经经过了一次相关性筛选，Headroom 的任务是在这些结果中进一步精选——保留最相关的信息，去掉冗余的格式噪声和重复内容。

六、竞品对比：Headroom 的差异化定位

值得注意的一点：Headroom 并不排斥竞品。它内置了 RTK 作为 CLI 输出的预处理器，并支持 lean-ctx 作为替代上下文工具。这种「组合优于替代」的思路很务实——在 AI 工具链中，兼容性往往比技术领先更重要。

七、局限性与使用边界

Headroom 很强，但它不是银弹。在以下场景中，你可能需要更谨慎地评估：

7.1 不适合的场景

需要全文精读的任务：如果你的 Agent 任务本质上需要逐行阅读所有代码（比如 security audit、detailed code review），压缩会丢失关键细节。Headroom 的 AST 感知压缩保留了结构骨架，但确实会丢失某些长注释和复杂实现细节。

无法运行本地进程的环境：Headroom 需要在本地启动一个服务（Proxy 或 MCP Server）。在某些严格的沙箱环境（无网络访问、无进程创建权限）中无法使用。

Provider 已经做了充分压缩：如果你使用的是 OpenAI 的 compact 参数或 Anthropic 的原生上下文优化，Headroom 的边际收益会降低——虽然 CCR 和跨 Agent 记忆功能仍然有价值。

7.2 精度损失的边界情况

根据基准测试数据，Headroom 的精度损失主要出现在以下场景：

• 长距离依赖的代码：AST 压缩可能在截断长函数时丢失跨越多行的上下文依赖
• 高度动态的 JSON：某些 schema 不断变化的 API 响应，SmartCrusher 的类型推断可能出错
• 多模态内容：图片压缩的质量损失可能在视觉任务中产生影响

这些边界情况的发生概率较低，但开发者需要了解。建议在首次使用时，用 headroom stats 观察实际压缩率和任务完成质量，确认没有问题后再全面推广。

八、技术展望：上下文压缩的下一步

从学术前沿看，2025-2026 年上下文压缩领域有几个重要趋势，Headroom 的设计恰好踩中了这些方向：

ACON 框架（微软研究院，ICML 2026）：提出 Agent Context Optimization，在自然语言空间中迭代优化压缩策略，而非一次性压缩。在 AppWorld、OfficeBench 和 Multi-objective QA 上实现了 26-54% 的峰值 Token 削减，同时提升任务成功率。更有意思的是：蒸馏到小模型后，小模型作为长周期 Agent 的性能最高提升 46%。

SWE-Pruner（2026.01）：针对编码 Agent 的自适应上下文裁剪框架，基于 0.6B 参数的 Qwen3-Reranker骨干，使用 CRF 层进行行级保留决策。在 SWE-Bench Verified 上实现最高 54% Token 减少，交互轮次减少最高 26%。

ContextPilot（MLSys 2026）：引入上下文复用机制，通过最大化前缀复用和去重来加速 LLM 预填充阶段，将推理延迟降低最高 3 倍。

Headroom 的 CCR（可逆压缩）和跨 Agent 记忆设计，恰好处于这些研究方向的交汇点。它的野心不只是做一个「Token 削减器」，而是一个上下文管理系统——这让它的上限比单纯的压缩工具高得多。

九、总结：上下文管理的范式转变

Headroom 的核心价值可以浓缩为一句话：

让 AI Agent 在更少的 Token 里看到同样多的信息。

但我认为这个价值背后，还有一个更深层的范式转变：从「塞更多上下文」到「管理上下文」。

过去几年，整个行业都在追求更大的上下文窗口——GPT-4 的 128K、Claude 的 200K、Gemini 的 2M。更大的窗口当然有价值，但它解决的是上限问题，不是效率问题。当你花更多钱让 AI 读它不需要读的内容时，大窗口反而成了成本放大器。

Headroom 代表的思路是：上下文不是越多越好，有价值的信息密度才是关键。

它的六大压缩引擎覆盖了 Agent 日常遇到的所有内容类型，CCR 可逆机制解决了「压缩后信息丢失」的行业痛点，跨 Agent 记忆则为多 Agent 协作场景提供了基础设施。

在 Token 成本仍是 AI Agent 规模化瓶颈的 2026 年，Headroom 提供了一个务实且工程化的解决方案。它的本地运行特性（数据不离开你的机器）让隐私敏感的企业也能放心使用，而 Apache 2.0 许可证则确保了它在商业项目中的可用性。

项目信息：

• GitHub: https://github.com/chopratejas/headroom
• 文档: https://headroom-docs.vercel.app/docs
• 模型: https://huggingface.co/chopratejas/kompress-v2-base
• 当前版本: v0.25.0
• 许可证: Apache 2.0

附：快速参考命令卡

# 安装
pip install "headroom-ai[all]"

# 一键接管 Claude Code
headroom wrap claude

# 启动本地代理
headroom proxy --port 8787

# 安装 MCP 服务器
headroom mcp install

# 查看压缩统计
headroom stats

# 启动 Dashboard
headroom dashboard --port 3000

# 从失败中学习
headroom learn --analyze-failed ./sessions/

# 配置跨 Agent 记忆
headroom memory --shared --backend sqlite
headroom dedup --agents claude,codex,gemini