在 AI 代码编写中，token 成本和限流警告总是让人抓狂。跑 Claude Code 一个大项目，几万 token 就被“吃掉”；调试日志、命令行输出、搜索结果…，这些看似无用的 INFO 也会被模型一次性吞进上下文，导致真正有价值的三行信息被淹没。更糟的是大量无关噪声占据了宝贵的 token。你不敢删掉它们，却又担心漏掉关键报错。

Headroom：为 AI Agent 提供上下文压缩层

Headroom 是一个介于 AI Agent 与 LLM 之间的中间层，专门在把任何内容送入 LLM 前先做一次压缩：

• 工具输出
• 命令行结果与代码搜索
• RAG 检索片段、文件内容
• 对话历史记录

四种接入方式。低成本快速落地

① Library: 在 Python 或 TypeScript 项目中直接调用 compress,几行代码就可以使用。

② Proxy: 运行 headroom proxy --port 8000。启动本地代理后任何 OpenAI 兼容客户端都能自动使用压缩功能，无需改动原有代码。不过，

③ Agent 包装器: 一条命令 headroom wrap claude | codex | cursor | aider | copilot。即可将主流编程 Agent 包住无需手动配置。

④ MCP Server: 注册三个工具 headroom_compress / headroom_retrieve / headroom_stats,Claude Code、Cursor 等 MCP 客户端可直接使用。

多种智能压缩算法，按类型挑选合适方案

Headroom 并不是单一模型或截断，而是先做内容路由，再按数据类型应用专属算法：

• SmartCrusher : 针对嵌套对象、混合数组进行统计式压缩。README 报告可节省约-60%.
• CodeCompressor : 基于语法树，对 Python/JS/Go/Rust/Java/C++ 做结构化压缩。保留 import、函数签名、类型信息，让模型仍能正确理解代码结构。
• Kompress‑v2‑base : 用大量 agentic trace 训练的模型。识别并丢弃非关键句子，仅保留对任务很关键的信息。

说到CCR，可逆检索机制。让压缩不等于丢失信息

MCP 压缩方案普遍存在“一次性截断”问题——一旦摘要后若干信息被删去，LLM 就无法再找回。Headroom 使用Coding Context Retrieval 所有原始数据永久保存在本地数据库。当模型发现上下文不足时可调用工具 headroom_retrieve ,按需拉取原文。于给 LLM 装了个"备忘录"-日常对话省 token，需要细节再翻阅原文。

从对比表来看，Headroom 与同类工具的优势概览

	覆盖范围 & 可逆性 & 部署方式 & 本地化支持
Headroom	✔︎ 所有类型均可压缩 ✔︎ 原始数据本地存储 ✔︎ 四种接入方式 ✔︎ 可逆检索	❌ 部分只支持截断或单一模型 ❌ 无法恢复原始信息	✔︎ 本地部署或 Docker 镜像	✔︎ 数据完全本地化。无外部传输

说到实际节省效果，多场景实测数据揭晓真相？

• 结构化噪声高场景: Token 大幅削减约-70%.
• 代码库探索: 因码量高且密度大，压缩空间有限，但仍能减少约-45%.
• 数学题解答: 意外提高约-10%。或许是因为注意力更集中.
• ——所有实验显示省 token 且回答质量无明显下降.

跨 Agent 记忆 + 自动学教训 — 两大实用特性揭秘

#1 跨 Agent 共享记忆 : 当你同时使用 Claude Code 和 Codex 时两者共享同一份项目背景记忆。老实说，Claude 学到的目录结构、关键文件直接供 Codex 调用。避免重复读取耗费大量 token。#2 Auto‑Learning Rules : Headroom 能扫描失败会话。分析失误原因，并生成更新规则文件（CLAUDE.md / AGENTS.md)。就像让 Agent 在帮你维护自己的规则集，让程序随时间愈加智能。

快速上手三步走

# 安装
pip install \"headroom-ai\" # Python
npm install headroom-ai # Node / TypeScript
# 接入方式任选其一
headroom wrap claude # 包住 Claude Code
headroom proxy --port 8000 # 本地代理模式
from headroom import compress # 自己写应用时直接调用 compress
# 查看效果
tokensaved=$ # 打印当前节省率与绝对 token 数量
echo $tokensaved\end{c"
}

---