Headroom 怎么在本地压缩 AI 上下文

编码 agent 跑起来之后，上下文里占位置最多的往往不是用户那几句提问，而是它自己读回来的东西：一次代码搜索的上百条结果、几万 token 的日志、整个仓库的文件清单、RAG 召回的片段。这些内容重复度高，却要按原文计费，同时挤压可用的上下文窗口。

Headroom 是一个跑在本地的上下文压缩层，由 Python 写成，把工具输出、日志、文件与 RAG 片段压小之后再交给模型，输出压缩后的消息和一份按需取回原文的检索工具。

接入方式有四种：在 Python 或 TypeScript 里直接调用压缩函数、启动一个零代码改动的代理、用一条命令包装常见编码 agent，以及作为 MCP 服务器供任意 MCP 客户端调用。

压缩过程在本机完成，仓库里写明不会把提示词或文件内容发出去做压缩。项目地址是 https://github.com/headroomlabs-ai/headroom，许可证为 Apache License 2.0，主要语言是 Python，仓库语言占比中 Rust 也占到 12.3%。抓取时 Star 74168、Fork 5731、开放 Issue 539。

它怎么做到的

Headroom 坐在 agent 与模型提供商之间。上游是 agent 或应用发来的消息，里面混着提示词、工具输出、日志、RAG 结果和文件内容；下游是 Anthropic、OpenAI、Bedrock 这类提供商的接口。ContentRouter 先判断每段内容的类型，再挑对应的压缩器：JSON 交给 SmartCrusher，源码交给 CodeCompressor，散文交给 Kompress-v2-base。压缩后的消息发往提供商，原始文本留在本地由 CCR 缓存，模型需要全文时可以调用 headroom_retrieve 取回。

 agent / app（Claude Code、Cursor、Codex、LangChain、自写代码…）
        │  提示词 · 工具输出 · 日志 · RAG 结果 · 文件
        ▼
   CacheAligner → ContentRouter → CCR
                    ├─ SmartCrusher      (JSON)
                    ├─ CodeCompressor    (AST)
                    └─ Kompress-v2-base  (文本)
        │  压缩后的提示词 + 检索工具
        ▼
 LLM 提供商（Anthropic · OpenAI · Bedrock · …）

内容类型的判断规则、三个压缩器各自的算法细节，仓库在架构文档之外没有展开说明。文本压缩器 Kompress-v2-base 在 Hugging Face 上有对应的模型卡，可离线使用，这一点从 README 的模型徽章与链接能确认，至于模型规模与训练数据，仓库里没有交代。

几个关键设计

按内容类型分流，而不是一套通用压缩

JSON、源码、自然语言的冗余结构差别很大。ContentRouter 负责识别类型并分发，三种压缩器各管一摊：SmartCrusher 针对 JSON 里重复的键和数组，CodeCompressor 基于 AST 处理源码，Kompress-v2-base 处理普通文本。这种分流解释了为什么官方给出的压缩率在不同场景里差别明显——重复度越高，能砍掉的越多。

CCR：压缩可逆，原文留在本地

压缩最大的风险是砍掉关键信息。CCR 把原始内容缓存到本地，压缩结果里保留一条检索路径，模型需要原文时通过 headroom_retrieve 取回。README 里的演示用一次 55,957 token 的 agent 提示压缩到 24,340 token，第 67 项那条 FATAL 日志行逐字节保留。这个设计让压缩从「一次性有损」变成了可回退的操作，代价是本地要多存一份原文。

CacheAligner 只做标记，不改写提示词

提供商的 KV-cache 按前缀复用，提示词里混进时间戳、随机 ID 这类易变内容，整个前缀缓存就会失效，成本会比不压缩还高。CacheAligner 标记出这类易变内容，README 明确写了它不会重写提示词。它解决的是缓存命中率问题，而不是压缩率问题。

多种接入形态与跨 agent 记忆

接入上有四条路：库（compress(messages)）、代理（headroom proxy --port 8787）、包装命令（headroom wrap claude 等）、MCP 服务器（暴露 headroom_compress、headroom_retrieve、headroom_stats）。此外还有一份跨 agent 共享的记忆存储，覆盖 Claude、Codex、Gemini 与 Grok，带自动去重；headroom learn 会挖出失败的会话，把纠正写进 CLAUDE.local.md（默认，已加进 gitignore）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md。

这样设计的代价

压缩率随载荷浮动，宣传数字容易被误读。官方基准里四个场景分别是 21%（代码搜索 17,199→13,597）、57%（SRE 排障 55,957→24,340）、42%（代码库探索 58,801→33,895）、30%（GitHub issue 分诊 46,067→32,429）；重复的 JSON 数组和日志行在 benchmarks/bench_latency.py 里能过 90%，散文和已经很密的内容几乎压不动。有用户在 Issue 里指出自己实测只有 7% 到 19%，并抱怨缓存被破坏、Windows 支持有问题，该条标记为已解决。

代理模式要改客户端配置，兼容问题会直接打断工作流。把 proxy url 填进 VSCode 之后 Copilot 插件不再工作，这条 Issue 攒了 102 条评论，已解决；Codex 走代理后向 OpenAI 认证失败，35 条评论，已解决；Claude Code v2.1.196 之后 Remote Control 在代理后面被静默禁用，这条仍待解决。代理越靠近客户端，客户端升级带来的摩擦就越多。

本地要有一套运行环境。安装走 uv tool install --python 3.13 "headroom-ai[all]" 或 pip install "headroom-ai[all]"，仓库里另有 8.6 KB 的 Dockerfile，语言占比里还带着 12.3% 的 Rust。代理与 dashboard 都需要常驻进程，dashboard 必须等代理跑起来才能看实时节省。

版本迭代快，行为会在相邻版本间变化。0.39.0 引入的 TPM limiter 会让大上下文请求一直被拒绝，0.39.1 才修掉，这类回归对长期挂着的代理用户不友好。CHANGELOG.md 有 521 KB，说明发版节奏相当密。

生态覆盖有边界。Google Antigravity IDE 的原生集成目前只是待解决的 feature request，Copilot 订阅模式（不带个人 API key）与 CLI 订阅模式的支持也是后来才补上的。已经出现在 headroom wrap 列表里的工具不代表体验已经打磨完。

和同类项目放在一起看

Headroom 的取舍点在于接入深度。它需要在客户端和模型之间插一层，换取对每一轮请求的持续压缩，这层插得越深，跟客户端版本、账号认证的耦合就越紧。只想把一份仓库一次性喂给模型看，Repomix 这类打包工具更直接，也不需要常驻进程和一个被改写的客户端配置。

对你的实际影响

省下来的 token 数量取决于你平时读回来的是什么。工具输出里大量重复 JSON、日志行的场景，压缩收益最明显，官方基准里从 21% 到 57% 不等；如果你的 agent 主要在处理长散文、大段自然语言文档，能压掉的部分会少很多，值得先用 headroom savings 对着自己的流量测一遍再决定是否长期挂上。压缩开销在官方基准里是 10K token JSON 结果上 0.21 ms（p50），这个数量级不太可能成为瓶颈。

接入成本主要落在环境与配置上。代理模式要起常驻进程、占端口，还要把客户端指向它；headroom wrap 会顺带装上 Serena 并把注册写到用户级配置（Claude Code 在 ~/.claude.json），不想要可以用 --code-memory none，事后要靠 headroom unwrap <tool> 清理。多人共用一台开发机、或者客户端版本被 IT 统一管控的团队，这层代理会带来额外的协调工作。

适合长期跑 Claude Code、Cursor、Codex 这类编码 agent，且上下文经常被工具输出、日志和仓库探索结果撑满的个人开发者与小团队；也适合想把压缩能力嵌进自己应用、直接用库或 MCP 服务器接入的工程团队。不适合只想把仓库打包给模型看一次的人，也不适合无法接受在客户端与模型之间多一层代理、或者所在环境锁死客户端版本与网络配置的团队。

代理会把请求经本机转发到 LLM 提供商，使用前需要确认自己有权使用所配置的 API key 或订阅账号，别把共享的、来源不明的密钥挂上去；跨 agent 记忆和 headroom learn 会把会话内容落到本地文件，写进 CLAUDE.md 这类入库文件时注意别把内部信息提交到公开仓库。

焚评：这个项目的量化评分

本项目的选题来自 焚.com（一个按公开公式给 GitHub 项目打分的站）。焚评当前总分 9.9 分（满分 10）。下表是各维度的得分：

评分口径、权重与计算方式见焚.com 的评分方法页；数据随 GitHub 指标刷新，具体数值以焚.com 当前页面为准。本文正文为诀.com 独立撰写，评分数据由焚.com 授权引用。