Headroom：为 AI Agent 打造的上下文压缩中间层，Token 最高省 90%，还支持跨代理记忆

跑一次 Claude Code，稍微大一点的项目，一个长任务下来几万 token 就没了。Codex 调试日志时，光日志本身就把上下文吃掉一大半。赶上月底限流、超额警告，那种感觉就像电脑在烧钱。更难受的是，这些消耗掉的 token 里夹杂着大量无用信息——一百行 grep 结果，真正有价值的就那三行，但模型必须全部读完；日志里大片无关的 INFO，可你又不敢删，生怕漏掉关键报错。直到我发现了 Headroom，它为 AI Agent 装了一层上下文压缩层，所有东西在送进 LLM 之前先被“拧干”。一段 10144 token 的内容，压完只剩 1260。

开源项目快速预览

Headroom 是嵌在 AI Agent 和 LLM 之间 的一个中间层。你平时喂给模型的所有信息——工具输出、命令行结果、代码搜索结果、RAG 检索片段、文件内容、对话历史——在进入 LLM 之前都会被 Headroom 拦截并压缩一遍。

开源地址：https://github.com/chopratejas/headroom

压缩后的内容几乎不影响最终效果，但 token 数量却大幅下降。项目提供了四种接入方式，几乎覆盖所有使用场景：

① 库（Library）：在 Python 或 TypeScript 代码中直接调用 compress(messages)，几行就能集成。
② 代理（Proxy）：通过 headroom proxy --port 8787 在本地启动一个代理，零代码改动，任何兼容 OpenAI 的客户端都能立刻套用。
③ Agent 包装器：一条命令 headroom wrap claude | codex | cursor | aider | copilot，就能把主流的编程 Agent 直接包裹起来，无需额外配置。
④ MCP server：注册三个工具 headroom_compress、headroom_retrieve、headroom_stats，Claude Code、Cursor 这类原生 MCP 客户端开箱即用。

无论你是自己开发 AI 应用，还是天天跟现成的编程 Agent 打交道，都能找到一种几乎无痛的接入路径。

六种压缩算法，按内容类型精准匹配

Headroom 并没有一招鲜地处理所有内容。很多同类工具要么粗暴截断，要么用小模型统一压缩。Headroom 则会先对内容进行路由分类——判断这段数据是 JSON、代码、日志还是自然语言——然后再选择最合适的压缩算法。

目前内置了六种压缩方案。例如 SmartCrusher，专门针对 JSON 设计，能对数组、嵌套对象、混合类型进行统计式压缩，README 中提到的节省幅度高达 70–90%。还有一个 CodeCompressor，基于语法树进行代码压缩，支持 Python、JS、Go、Rust、Java、C++，它的特点是会保留 import、函数签名和类型信息，所以模型阅读压缩后的代码时仍能准确理解结构，不会凭空猜测。对于自然语言，作者训练了一个专门的模型 Kompress-v2-base，该模型用大量 agentic trace 训练而成，清楚知道在 Agent 场景下哪些话可以丢掉。

压缩后还能找回来

我认为这是 Headroom 最亮眼的设计。几乎所有市面上的压缩方案都有一个通病：压完就没了。信息一旦被截断或摘要化，模型如果发现关键信息缺失，就再无补救办法。Headroom 设计了一套叫做 CCR (Compressed Context Retrieval) 的机制。

原始数据会在本地完整保留，永不删除。压缩后的精简版送进 LLM，如果模型觉得信息不够用，可以直接调用 headroom_retrieve 工具，像翻备忘录一样把原文按需捞回来。这等于给模型装备了一个外挂记忆库：日常对话用压缩版省钱，需要细节时随时调取原文档。作者也将 Headroom 和几款同类工具做了一张对比表，差异一目了然。

Headroom 对所有内容类型（工具输出、RAG、日志、文件、历史）都能压缩，数据完全留在本地，并且过程可逆。在覆盖范围、部署方式、本地化和可逆性四个维度上，Headroom 是唯一做到全面支持的方案。

实际节省效果与准确度

作者在 README 中公布了两组测试数据。

在代码搜索和 SRE 排障这类充斥着大量结构化噪声的场景下，效果最为显著，Token 直接砍掉九成。代码库探索因为代码本身信息密度高，压缩空间小一些，但仍有近一半的节省。数学题准确率毫无损失，事实类问答反而提升了 3 个百分点（很可能是压缩后模型的注意力更加集中），工具调用的准确度保持在 97%。这说明 省 token 并不是以牺牲答案质量为代价。

跨 Agent 共享记忆 + 自动学习教训

除了压缩，Headroom 还附带了两个极为实用的功能。第一个是跨 Agent 共享记忆。如今很多人手上不止一个 Agent，如果 Claude Code、Codex 等各自独立学习一遍项目背景，会造成重复的 token 消耗。Headroom 构建了一个基于本地 SQLite 和向量库的记忆层，让不同 Agent 之间共享同一份记忆并自动去重——Claude 学过的项目结构，Codex 可以直接拿来使用，无需再次读取。

第二个功能是 headroom learn，让 Agent 自动总结经验教训。这个功能会扫描你运行失败的会话，分析哪里出了岔子、原因是什么，并自动将约束和调整规则写入 CLAUDE.md 或 AGENTS.md。相当于 Agent 在帮你维护规则文件，越用越聪明。

快速上手指南

上手非常简单，三步即可：

# 1. 安装
pip install "headroom-ai[all]"          # Python
npm install headroom-ai                 # Node / TypeScript  

# 2. 选择一种接入方式
headroom wrap claude                    # 直接包裹 Claude Code
headroom proxy --port 8787              # 启动本地代理，任何客户端都能套用  
# 或者: from headroom import compress  # 写自己的应用时直接调用

# 3. 查看省了多少 token
headroom perf

要求 Python 3.10+。如果不想在本地安装，也可以使用 Docker 镜像：

docker pull ghcr.io/chopratejas/headroom:latest

在 token 仍是 AI Coding 主要成本和瓶颈的当下，上下文压缩的重要性不言而喻。Headroom 将其打造成了一个 本地化、可逆、覆盖全内容类型 的完整方案，且接入方式灵活。再加上跨 Agent 记忆和自动学习教训这两项加分能力，尤其适合那些深度使用 AI Coding Agent 的开发者。