Headroom：让 AI Agent「吃得少、营养好」的开源上下文压缩神器

Claude Code 跑一次日志分析1.7 万 Token 没了调试线上故障翻个堆栈6.5 万 Token 打不住——这不是你的用法有问题是 AI Agent 的上下文管理本身就缺了一环。一、问题的根源LLM 不挑食但你喂不起了我们先来算一笔账。假设你重度使用 Claude Code每天的 Token 消耗结构大概是消耗来源占比问题代码库搜索结果~25%大量重复行、注释、空格日志文件~30%时间戳/进程ID占 60% 篇幅RAG 检索结果~25%相关性低的片段占据 context对话历史累积~20%早期对话已经无关紧要这其中真正对回答有帮助的信息密度可能不到 40%。剩下 60% 全是冗余——重复行、时间戳、UUID、空格、格式标签……Claude Code 原生有没有上下文管理有但它的策略就三个字截、截、截。Context 满了就截后面的早期关键信息被截掉了你甚至不知道。这就是 Headroom 要解决的问题。二、Headroom 是什么HeadroomGitHub:chopratejas/headroom是一个开源的 LLM 上下文压缩中间件定位是「AI Agent 的智能消化层」。它的核心原理很简单在 AI Agent 读取的所有内容到达 LLM 之前进行四层智能处理——归一化、去重、结构压缩、语义剪枝——减少 60-95% 的 Token 消耗同时保持 97% 的信息精度。[Headroom 工作原理] 原始数据 ↓ [归一化] Unicode 统一、换行符统一、时间戳占位符 ↓ [去重] MinHash LSH 近似去重5万行→5000次对比 ↓ [结构压缩] JSON/代码/日志/自然语言 分类型压缩 ↓ [语义剪枝] 句子编码按信息密度筛选保留 top-K% ↓ 压缩后数据 → 送入 LLM Context三、核心技术原理四层压缩管线Stage 1Normalizer——格式归一化解决「看起来不同、实则相同」的问题Unicode NFKC 归一化全角→半角换行符统一\r\n/\r→\n日志时间戳正则替换为[TIMESTAMP]占位符连续空白符合并# 示例 # 压缩前 2026-06-10T10:35:11.12345608:00 ERROR: connection timeout 2026-06-10T10:35:11.98765408:00 ERROR: connection timeout ​ # 压缩后 [TIMESTAMP] ERROR: connection timeout (x2)Stage 2Deduplicator——冗余消除使用MinHash LSH局部敏感哈希做近似去重将每行文本转为 MinHash 签名LSH局部敏感哈希将相似行放入同一个「桶」查询复杂度从 O(n²) 降到 O(n)5万行日志暴力对比需 25亿次 → MinHash LSH 只需约 5000次Stage 3Structure-Aware Compressor——结构感知压缩根据内容类型分发到专用压缩器内容类型压缩策略JSON深层嵌套扁平化 重复 key 去重代码文件AST 感知保留骨架压缩实现细节日志错误行摘要化重复堆栈合并自然语言HuggingFace 专用压缩模型Stage 4Semantic Pruner——语义剪枝可选使用sentence-transformers对句子编码按信息密度评分保留 top-K%。这是唯一一个调用 ML 模型的阶段也是「有损压缩」的主要发生地——但实测精度保留率依然高达 97%。四、五大亮点功能1. CCR——可逆压缩传统压缩是不可逆的——压缩完就丢了。CCRContext Compression with Retrieval是 Headroom 的核心创新1. 原始数据存入本地 CCR 仓库数据不离开你的机器 2. 压缩后的数据发送给 LLM 3. LLM 随时可通过 headroom_retrieve 工具按需检索原始内容这相当于给 LLM 一个「放大镜」——平时看摘要需要时查原文。数据主权完全在用户手里。2. CacheAligner——KV Cache 命中率优化将动态值时间戳、UUID、进程 ID替换为固定占位符让相同结构的请求产生相同的前缀。不仅省 Token还降低推理延迟。3. CodeCompressor——AST 感知代码压缩支持 Python、JavaScript、Go、Rust、Java、C 六种语言基于抽象语法树压缩保留函数签名、类定义、导入关系等「骨架」对实现细节压缩。LLM 仍能理解代码整体架构不需要逐行阅读。4. headroom learn——从失败中学习分析 Agent 失败会话提取失败原因和修正方案自动写入CLAUDE.md/AGENTS.md等文档。相当于给 Agent 积累「错题本」。5. RAG 管道优化对检索到的文档和片段进行智能压缩在送入 LLM 前降低 Token 压力。相当于给 RAG 系统加了一个「最后一道过滤器」确保只有高价值信息才能占满宝贵的 context 空间。五、四种接入方式方式一Wrap 模式⭐ 推荐零改动一行命令包装现有的 Claude Code / Cursor / Copilotpip install headroom-ai[wrap] headroom wrap claude ​ # 查看 Token 节省统计 headroom stats之后正常用claude命令Headroom 在后台自动压缩所有上下文完全不用改用法。方式二Proxy 模式零侵入适合团队共享headroom proxy --upstream https://api.openai.com/v1 --port 8080 --mode balanced应用侧只需改一行 base_url# 之前 client OpenAI(api_keysk-xxx, base_urlhttps://api.openai.com/v1) # 之后 client OpenAI(api_keysk-xxx, base_urlhttp://localhost:8080/v1)方式三Library 模式程序化接入from headroom import compress ​ raw_logs open(app.log).read() compressed compress(raw_logs, modebalanced) 方式四MCP Server 模式标准 MCP 协议 任何 MCP 客户端都能用配置到 Claude Code 只需修改 mcp_servers.json { mcpServers: { headroom: { command: npx, args: [headroom/mcp-server, --mode, balanced] } } }六、压缩效果实测数据类型原始 Token压缩后 Token节省率服务器日志重复行多50,0002,50095%Stack Trace8,0001,20085%网页抓取正文30,0006,00080%代码文件含注释15,0006,00060%纯自然语言文本10,0007,00030%精度方面基准测试显示基准压缩后精度说明GSM8K数学推理87.0%与基线持平精度完全不降TruthfulQA事实准确性56.0%3pp压缩甚至提升了准确性SQuAD v2阅读理解97% 精度保留压缩率 81%BFCL工具调用97% 精度保留压缩率 68%七、和同类项目对比特性HeadroomRTKlean-ctxOpenAI Compaction压缩范围全部上下文仅 CLI 输出CLI MCP 工具仅对话历史部署方式Proxy/Library/MCPCLICLI/MCPProvider 原生本地运行✅✅✅❌CCR 可逆压缩✅❌❌❌跨 Agent 记忆✅❌❌❌AST 感知压缩✅6语言❌❌❌八、适用与不适用的场景✅ 非常适合重度使用 Claude Code / Cursor / Copilot 等编程助手同时使用多个 AI AgentToken 费用是痛点对数据安全有要求CCR 本地存储原始数据不外传日志分析、代码审查、文档处理等高 Token 消耗场景❌ 可以跳过只做简单对话Token 消耗本身就不大在沙箱环境无法运行本地进程对 Token 成本完全不敏感法律/医疗等不允许任何信息损失的场景九、总结Headroom 解决的是一个根本性问题AI Agent 的上下文管理不能只靠「截断」要靠「筛选」。Claude Code 负责「对话」Headroom 负责「省着点喂」。给 Claude Code 加上 Headroom 后所有内容会先经过四层智能处理再进入 contextToken 消耗减少 60-95%同样的上下文窗口能聊更多轮、响应更快、账单更省——本质就是给 AI 对话加了一个「智能消化系统」让它吃得少但营养不丢。相关资源GitHub: https://github.com/chopratejas/headroom官方文档: https://headroom-docs.vercel.app/docs压缩模型: https://huggingface.co/chopratejas/kompress-base