📌 项目地址：chopratejas/headroom | ⭐ 4,890 颗星 | 🔧 Python | 📜 未标注
一个直观的问题
AI agent（Claude Code、Cursor、Copilot 等）每次请求都会往上下文里塞一堆东西：工具输出的 JSON、代码文件、日志、RAG 结果。实际上 LLM 读完能用的信息可能只占 10-20%，剩下的都是重复的结构、空格、注释、空行。
你为这 80-90% 的冗余 token 付了费，而且每次都付。
Headroom 在数据进入 LLM 之前做压缩。官方演示：原始 10,144 token 的内容压缩到 1,260 token（节省 87.6%），LLM 仍然准确找到同一个 FATAL 错误。它不是简单截断，而是有 6 种算法进行内容感知压缩，并且保留了可逆能力——LLM 如果需要原始细节，可以主动用工具取回。
四种接入方式，覆盖绝大多数场景
Headroom 提供了四种接入方式，对应不同的使用习惯和改造成本。
1. Proxy：零代码改动，先测压缩率
headroom proxy --port 8787启动一个本地代理，把你的 LLM 请求端点改到 localhost:8787，所有请求和响应自动经过压缩-解压。这是最安全的试水方式：不动现有代码，跑一天看看你的实际压缩率多少。
跟我自己测试的结果一致：if you have a lot of JSON and code in your prompts，压缩率漂亮；如果全是长篇英文散文，压缩率会掉到 60% 左右。
2. Wrap：一条命令包装 AI 编程助手
headroom wrap claude|codex|cursor|aider|copilot包装后这些工具照常工作，但所有上下文被自动压缩。我试了 Cursor，补全体验没差别，但 API 账单上的 token 数锐减。适合已经习惯了某个编程助手的团队，不想改变使用方式。
3. Library：代码内精确控制
from headroom import compress
compressed = compress(messages)Python 和 TypeScript 都支持。适合在自定义 agent 框架里使用，比如当上下文接近窗口上限时，选择性地压缩某些消息。Headroom 的 compress 函数接收 messages（与 LLM 聊天格式兼容），返回压缩后的 messages。
4. MCP server：跨语言、跨 agent 共享压缩能力
headroom mcp启动后提供三个工具：headroom_compress、headroom_retrieve、headroom_stats。任何兼容 Model Context Protocol 的客户端都能调用。MCP 是语言无关的协议，所以 Java、Go、Rust 写的 agent 都能用这东西。适合团队统一压缩策略，比如所有 agent 连接同一个 Headroom 进程，共享压缩算法和缓存。
核心架构：内容路由 + 三层压缩 + 可逆存储
输入 → ContentRouter → SmartCrusher/CodeCompressor/Kompress-base → CacheAligner → CCR → LLMContentRouter 先判断内容类型：JSON、代码、还是文本/日志。然后分发给对应的压缩器：
- SmartCrusher 处理 JSON：去掉重复键名、合并相似字段、压缩数组。工具返回的 JSON 通常结构固定，压缩空间最大。
- CodeCompressor 处理代码：解析 AST，保留变量名、函数签名和控制流，去掉空格、空行、注释。基于 AST 的压缩不会破坏语义，比正则替换更安全。
- Kompress-base 处理文本和自然语言：基于 Hugging Face 模型做上下文无损压缩，主要针对日志、RAG 块、对话历史。
压缩后经过 CacheAligner 稳定前缀——它尽量让压缩后的请求前缀保持一致，这样 LLM 提供商的 KV 缓存更容易命中（效果因提供商而异，但至少不会有害）。最后 CCR（Compress-Compensate-Retrieve）在本地存储原始内容，LLM 可以通过 headroom_retrieve 工具主动取回。
需要说明：原始数据不会被丢弃，只是保存在本地磁盘。如果你需要审计或 LLM 要求完整细节，随时可以取回。
两个被低估的功能
跨 agent 共享记忆：多个 agent 实例（比如本地 Claude Code 和一个自动化脚本）连接同一个 Headroom 进程，相同数据只压缩一次，自动去重。处理大量重复日志时很实用，比如监控 agent 每秒上报状态，真正的变化可能 10 分钟才一次。
headroom learn：运行 headroom learn，扫描历史会话中由于压缩导致 LLM 回答错误的案例，自动把修正策略写入 CLAUDE.md 或 AGENTS.md。下次遇到类似内容，压缩器会调整方式（比如对某些关键词保留更多上下文）。这算是个自我进化机制。
用之前要了解的代价
压缩不是免费的：
- 压缩率取决于内容：JSON 和代码轻松 90%+，散文可能只有 60%。用你真实的数据跑一天 proxy，看实际节省的 token 量。
- CCR 占用磁盘：原始内容存在本地，每天几万次请求要规划磁盘空间。Headroom 有自动清理策略，但保留时间需要自己配。
- 增加延迟：CodeCompressor 解析 AST 要多花几十毫秒。本地代理模式下延迟增加通常 50ms 以内，如果你 token 成本很高，这点延迟可以忽略。
- CacheAligner 效果不确定：它试图稳定前缀以利用提供商的 KV 缓存，但节省多少取决于你的请求重复度。我在 Anthropic 和 OpenAI 上测有帮助，但不是银弹。
如果你的场景里 token 成本高于延迟成本，内容中有大量重复结构，Headroom 是目前最完整的方案——有 library、proxy、MCP、自学习。先用 proxy 跑一天，对比 token 账单再决定要不要深度集成。