Headroom：给 AI 智能体装上的上下文压缩层
Headroom 是一个面向 AI 智能体和 LLM 的上下文压缩层，在工具输出、日志、RAG 片段、文件与对话历史真正进入模型之前先把它们压缩，做到答案不变、token 锐减。官方数据显示 JSON 类数据可压缩 60–95%，编码类智能体可省 15–20%。它提供四种接入形态：Python 或 TypeScript 库、零代码代理、一键包裹编码智能体的 wrap 命令，以及面向 MCP 客户端的服务。产品坚持本地优先、数据不出本机，采用可逆压缩，原始内容本地缓存按需取回，适合长对话、多工具调用、RAG 检索与跨智能体共享记忆场景。
在 AI 智能体快速普及的当下，一个越来越突出的痛点是上下文迅速膨胀。智能体在运行中会不断读取工具输出、日志、RAG 检索结果、文件内容和整段对话历史，这些数据大量涌入模型，既推高了 token 成本，也容易逼近甚至撑满上下文窗口。Headroom 正是为此而生，它把自己定位为「AI 智能体的上下文压缩层」，在数据真正到达 LLM 之前先做一层压缩，让智能体用更少的 token 拿到同样的答案。从行业生态看，它处于 agent 框架与模型提供商之间的中间层，不替换你的智能体，也不替换模型，而是作为一条管道，把「喂给模型的内容」做瘦身。项目以 Python 为主实现，GitHub 上已积累近七万星，被归类为 agent、compression、context-engineering、context-window 等方向，说明它切中的是社区普遍关心的效率命题。它的核心主张很直接：同样的答案，fraction of the tokens——成本与窗口压力随之下降，而这是几乎所有长期运行的智能体都会遇到的现实约束。 Headroom 的核心能力体现在它提供的多种接入形态与一套内容感知的压缩管线。接入上，它给出四种路径：作为库，可以在 Python 或 TypeScript 中以 compress(messages) 的形式内联进任意应用；作为代理，一条 headroom proxy --port 8787 即可，无需改动代码、不限语言；作为智能体包裹，headroom wrap 后面可以接 claude、codex、grok、copilot、cursor、aider、opencode、cline、continue、goose、openhands、openclaw、vibe、omp、zcode 等，一条命令完成包裹，再用 headroom unwrap 解除；此外还提供 MCP 服务，暴露 headroom_compress、headroom_retrieve、headroom_stats 等工具给任意 MCP 客户端。这些形态覆盖了从「自己写代码」到「几乎零改动接入」的完整光谱。在压缩原理上，它内部由 CacheAligner、ContentRouter 与 CCR 三段组成：ContentRouter 负责识别内容类型并选择对应的压缩器——SmartCrusher 处理 JSON、CodeCompressor 基于 AST 处理代码、Kompress-v2-base 处理文本；CacheAligner 则检测那些会破坏供应商 KV 缓存前缀的易变内容并发出警告，且明确不会改写 prompt；CCR 是可逆压缩层，把原始内容缓存在本地，需要时由模型调用 headroom_retrieve 取回。这种设计的关键差异在于它不只是压缩「发出去的内容」，还通过输出削减 trim 模型「写回来」的部分，比如删掉客套、重复代码，并在常规步骤上跳过深度思考，从而同时压低输入与输出两端的 token。本地优先与可逆也是其差异化所在：数据不出本机，原始内容可随时取回，兼顾了隐私与可用性。 从使用场景与上手体验看，Headroom 的四种接入方式让不同技术栈的团队都能找到合适路径。如果你在自己的应用里跑智能体，直接引入库调用 compress 即可；如果想让已有系统零成本受益，代理模式几乎无需改动代码；如果你日常使用 Cursor、Claude Code、Codex 这类编码工具，一条 headroom wrap 命令就能让智能体在读取工具输出、日志、RAG 片段、文件与对话历史时自动走压缩管线。文档方面项目提供了 Docs、Install、Proof、Agents 等入口，并给出示例，如一段内容从 10,144 个 token 压缩到 1,260 个却保留同样的 FATAL 信息，用来直观说明压缩效果。社区层面，它设有 Discord 并维护了 llms.txt 与可获取的完整文档，方便智能体与开发者直接查阅。此外还有几个值得关注的增强能力：跨智能体记忆允许在 Claude、Codex、Gemini、Grok 之间共享存储并自动去重；headroom learn 可以挖掘失败的会话，把修正写入 CLAUDE.local.md（默认且被 gitignore）或 CLAUDE.md、AGENTS.md、GEMINI.md、GROK.md 等文件，帮助智能体从错误中学习。整体上手门槛不高，从库到代理到 wrap 命令层层递进，团队可以根据改造成本灵活选择。 从行业意义与展望看，Headroom 代表了一个正在成型的品类：把上下文工程从「靠提示词技巧和经验调优」变成一层可复用、可标准化的基础设施。对开发者社区而言，它把压缩、可逆取回、缓存对齐、跨智能体记忆等能力打包成开箱即用的组件，让团队把精力集中在智能体行为本身而非上下文管理这类重复劳动上。对工程团队而言，它直接指向成本与窗口的双重约束，尤其在长对话、多工具调用、RAG 检索增强等场景下，能显著降低单次调用的 token 消耗。不过仍有需要观察的方向：压缩是否在所有内容类型与边界场景下都保持「答案不变」的承诺，可逆压缩带来的本地缓存与取回开销如何，跨智能体记忆的共享与去重在隐私与一致性上的权衡，以及它对不同模型供应商 KV 缓存的实际影响是否稳定。这些是项目从「能省 token」走向「可信赖的基础设施」需要持续回答的问题。但就其定位而言，Headroom 已经清晰地指出了一条路径：让智能体在更少的上下文里做更多的事，同时把数据留在本地。