你的 AI 编程助手,每次对话都在烧钱?这个开源项目帮你砍掉 95% 的 Token

每天跟 AI 编程助手打交道，Token 消耗是个很容易被忽视的成本。

代码搜索返回几百条结果，日志动辄上万行，这些东西一股脑塞给大模型，账单蹭蹭往上涨。上下文窗口塞满之后，模型还容易"失忆"，回答质量跟着下降。

有个叫 Headroom 的项目，干的事情很直接：在内容发给大模型之前先压一遍，砍掉 60% 到 95% 的 Token，模型回答基本不受影响。

1. 项目长什么样

Headroom 是一个本地运行的上下文压缩工具，支持压缩工具输出、日志、文件内容、RAG 检索结果。今天在 GitHub Trending 排第一，12,639 Stars。

2. 压缩效果怎么样

工作负载压缩对比：

工作负载	压缩前 Token	压缩后 Token	节省比例
代码搜索（100 条结果）	17,765	1,408	92%
SRE 事故排查日志	65,694	5,118	92%
GitHub Issue 分类	54,174	14,761	73%
代码库探索	78,502	41,254	47%

数据来自真实的工作负载测试。

3. 内部机制

Headroom 内置了六种压缩算法，由一个 ContentRouter 自动判断内容类型，分配对应的压缩器：

SmartCrusher：处理 JSON，支持数组、嵌套对象、混合类型

CodeCompressor：基于 AST 的代码压缩，覆盖 Python、JavaScript、Go、Rust、Java、C++

Kompress-base：团队自己训练的文本压缩模型，放在 HuggingFace 上

Image Compression：通过 ML 路由器压缩图片，压缩率 40% 到 90%

CacheAligner：稳定前缀缓存，让 Anthropic 和 OpenAI 的 KV Cache 真正命中

IntelligentContext：基于评分的上下文拟合，学习内容重要性

流程是：内容进来 → ContentRouter 识别类型 → 分配压缩器 → 压缩后发给模型。

4. 可逆压缩：不丢数据

大多数压缩工具压缩完就完事了，被砍掉的信息找不回来。Headroom 不一样。

它的 CCR（Compress-Compress-Retrieve）机制会在本地保存原始内容。模型先看压缩后的摘要，需要展开某个细节时，通过 headroom_retrieve 工具调取原文。

Token 省了，关键信息不会丢。

5. 怎么用

包裹 Agent

headroom wrap claudeheadroom wrap codexheadroom wrap cursor

一行命令，零代码改动。

代理模式

headroom proxy --port 8787

启动本地代理，所有请求自动压缩，不挑语言和框架。

库模式

from headroom import compressresult = compress(messages, model="claude-sonnet-4-6")

import { compress } from"headroom-ai";const result = awaitcompress(messages, { model: "claude-sonnet-4-6" });

直接嵌到代码里调用。

MCP Server

headroom mcp install

给任何支持 MCP 协议的客户端提供 headroom_compress、headroom_retrieve、headroom_stats 三个工具。

6. headroom learn

这个功能值得单独拎出来说。headroom learn 会挖掘 Agent 执行失败的会话记录，分析失败原因，把修正信息写入 CLAUDE.md、AGENTS.md 或 GEMINI.md。

Agent 犯过的错不会犯第二次。比起单纯的 Token 压缩，这个功能更让人感兴趣。

7. 跨 Agent 共享记忆

同时用 Claude Code、Codex、Cursor 的开发者大概都有体会：每个 Agent 各学各的，经验不互通。Headroom 提供了一个跨 Agent 的共享记忆存储，自动去重。

8. 安装

pip install "headroom-ai[all]"# Python，安装全部功能npm install headroom-ai           # Node / TypeScriptdocker pull ghcr.io/chopratejas/headroom:latest  # Docker

需要 Python 3.10 以上。

9. 基准测试

装好后可以跑个性能测试：

headroom perf

完整的评估套件：

python -m headroom.evals suite --tier 1

GSM8K（数学）、TruthfulQA（事实）、SQuAD v2（问答）这几个基准测试的结果显示，压缩后的准确率和未压缩基本持平。

10. 项目信息

GitHub：chopratejas/headroom

Stars：12k+

协议：Apache 2.0

语言：Python / TypeScript

支持平台：macOS、Linux、Windows