Headroom

压缩你的 AI 助手所读取的所有内容。答案不变，但使用的 token 数量大幅减少。

你的助手进行的每一次工具调用、数据库查询、文件读取以及 RAG 检索中，有 70% 到 95% 都是重复性的样板内容。
Headroom 可以在这些内容进入模型之前将其压缩掉。

支持任何助手——编程助手（Claude Code、Codex、Cursor、Aider）、自定义助手
（LangChain、LangGraph、Agno、Strands、OpenClaw），或者你自己的 Python 和 TypeScript 代码。

---

Headroom 的适用场景

你的助手 / 应用
  (编程助手、客服机器人、RAG 流水线、数据分析助手、研究助手、任何 LLM 应用)
      │
      │  工具调用、日志、数据库读取、RAG 结果、文件读取、API 响应
      ▼
   Headroom  ← 代理、Python/TypeScript SDK 或框架集成
      │
      ▼
 LLM 提供商  (OpenAI、Anthropic、Google、Bedrock、通过 LiteLLM 支持 100 多家)

Headroom 位于你的应用和 LLM 提供商之间。它会拦截请求，压缩上下文，并转发优化后的提示词。你可以将其作为透明代理使用（无需修改代码）、作为一个 Python 函数 (compress())，或者通过框架集成（LangChain、LiteLLM、Agno）来使用。

哪些内容会被压缩

Headroom 会优化你的助手注入到提示词中的任何数据：

• 工具输出 — shell 命令、API 调用、搜索结果
• 数据库查询 — SQL 查询结果、键值查找
• RAG 检索 — 文档片段、嵌入结果
• 文件读取 — 代码、日志、配置文件、CSV 文件
• API 响应 — JSON、XML、HTML
• 对话历史 — 长时间的助手会话中包含的重复性上下文

---

快速开始

Python:

pip install "headroom-ai[all]"

TypeScript / Node.js:

npm install headroom-ai

适用于任何助手——只需一个函数调用

Python:

from headroom import compress

result = compress(messages, model="claude-sonnet-4-5-20250929")
response = client.messages.create(model="claude-sonnet-4-5-20250929", messages=result.messages)
print(f"节省了 {result.tokens_saved} 个 token ({result.compression_ratio:.0%})")

TypeScript:

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'gpt-4o' });
const response = await openai.chat.completions.create({ model: 'gpt-4o', messages: result.messages });
console.log(`节省了 ${result.tokensSaved} 个 token`);

支持任何 LLM 客户端——Anthropic、OpenAI、LiteLLM、Bedrock、Vercel AI SDK，或你自己的代码。

适用于任何助手——代理模式（无需修改代码）

headroom proxy --port 8787

# 将任何 LLM 客户端指向代理
ANTHROPIC_BASE_URL=http://localhost:8787 your-app
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

支持任何语言、任何工具、任何框架。代理文档

编程助手——一条命令搞定

headroom wrap claude       # 启动代理并运行 Claude Code
headroom wrap codex        # 启动代理并运行 OpenAI Codex CLI
headroom wrap aider        # 启动代理并运行 Aider
headroom wrap cursor       # 启动代理并打印 Cursor 配置
headroom wrap openclaw     # 安装并配置 OpenClaw 插件

Headroom 会启动一个代理，将你的工具指向该代理，并自动压缩所有内容。

多智能体——SharedContext

from headroom import SharedContext

ctx = SharedContext()
ctx.put("research", big_agent_output)      # 智能体 A 存储（已压缩）
summary = ctx.get("research")               # 智能体 B 读取（体积缩小约 80%）
full = ctx.get("research", full=True)       # 智能体 B 在需要时获取原始数据

压缩在智能体之间传递的数据——适用于任何框架。SharedContext 使用指南

MCP 工具（Claude Code、Cursor）

headroom mcp install && claude

为你的 AI 工具提供三个 MCP 工具：headroom_compress、headroom_retrieve、headroom_stats。MCP 使用指南

轻松融入现有技术栈

你的设置	添加 Headroom	一行命令
任何 Python 应用	compress()	result = compress(messages, model="gpt-4o")
任何 TypeScript 应用	compress()	const result = await compress(messages, { model: 'gpt-4o' })
Vercel AI SDK	中间件	wrapLanguageModel({ model, middleware: headroomMiddleware() })
OpenAI Node SDK	包装客户端	const client = withHeadroom(new OpenAI())
Anthropic TS SDK	包装客户端	const client = withHeadroom(new Anthropic())
多智能体	SharedContext	ctx = SharedContext(); ctx.put("key", data)
LiteLLM	回调	litellm.callbacks = [HeadroomCallback()]
任何 Python 代理	ASGI 中间件	app.add_middleware(CompressionMiddleware)
Agno 助手	包装模型	HeadroomAgnoModel(your_model)
LangChain	包装模型	HeadroomChatModel(your_llm)
OpenClaw	一键封装	headroom wrap openclaw
Claude Code	封装	headroom wrap claude
Codex / Aider	封装	headroom wrap codex 或 headroom wrap aider

完整集成指南 | TypeScript SDK

---

演示

---

它真的有效吗？

100 条生产日志条目。第 67 位埋藏着一个严重错误。

	基线	Headroom
输入 token 数量	10,144	1,260
正确答案	4/4	4/4

两种响应均为：“支付网关，错误 PG-5523，修复方案：将 max_connections 增加到 500，受影响的交易数为 1,847。”

token 数量减少了 87.6%。答案相同。 运行命令：python examples/needle_in_haystack_test.py

Headroom 保留的内容

从 100 条日志中，SmartCrusher 保留了 6 条：前 3 条（边界）、第 67 条的 FATAL 错误（异常检测）以及最后 2 条（最近性）。该错误被自动保留——并非通过关键词匹配，而是通过对字段方差的统计分析实现。

真实工作负载

场景	前	后	节省
代码搜索（100 条结果）	17,765	1,408	92%
SRE 事件调试	65,694	5,118	92%
代码库探索	78,502	41,254	47%
GitHub 问题分类	54,174	14,761	73%

准确性基准测试

压缩不会降低准确性——已在真实的开源基准上进行了测试。

标准基准测试——基线（直接调用 API）与 Headroom（通过代理）：

基准	类别	N	基线	Headroom	差值
GSM8K	数学	100	0.870	0.870	0.000
TruthfulQA	事实性	100	0.530	0.560	+0.030

压缩基准测试——完整压缩流程后的准确性：

基准	类别	N	准确性	压缩率	方法
SQuAD v2	问答	100	97%	19%	压缩前后对比
BFCL	工具/函数	100	97%	32%	使用 LLM 作为评判者
内置工具输出	代理	8	100%	20%	压缩前后对比
CCR 针尖保留	无损	50	100%	77%	完全匹配

您可以自行运行：

# 快速烟雾测试（8 个案例，约 10 秒）
python -m headroom.evals quick -n 8 --provider openai --model gpt-4o-mini

# 完整 Tier 1 测试套件（约 $3，15 分钟）
python -m headroom.evals suite --tier 1 -o eval_results/

# CI 模式（回归时退出码为 1）
python -m headroom.evals suite --tier 1 --ci

完整方法论：基准测试 | 评估框架

---

核心功能

无损压缩

Headroom 绝不会丢弃任何数据。它会进行激进的压缩，同时保存原始数据，并为 LLM 提供在需要时检索完整细节的工具。当它将 500 个项目压缩至 20 个时，它会告诉模型 哪些内容被省略了（“87 个通过，2 个失败，1 个错误”），以便模型知道何时需要进一步查询。

智能内容检测

自动检测上下文中的内容类型——JSON 数组、代码、日志、纯文本——并将每种内容路由到最佳压缩器。JSON 数据交由 SmartCrusher 处理，代码则通过 AST 感知型压缩（Python、JS、Go、Rust、Java、C++），而文本则交给 Kompress（基于 ModernBERT 的压缩技术，额外包含 [ml] 标记）。

缓存优化

稳定消息前缀，使您的提供商的 KV 缓存真正发挥作用。Claude 对缓存前缀提供 90% 的读取折扣——但几乎没有框架能够利用这一点。Headroom 可以。

失败学习

headroom learn                   # 分析过去的 Claude Code 会话，展示建议
headroom learn --apply           # 将学习成果写入 CLAUDE.md 和 MEMORY.md
headroom learn --all --apply     # 在所有项目中学习

它会读取您的对话历史，找出每一次失败的工具调用，并将其与最终成功的操作相关联，然后将具体的修正建议写入您的项目文件中。下一次会话将更加智能。学习文档

图像压缩

通过训练好的 ML 路由器实现 40-90% 的 token 减少。自动为每张图像选择合适的缩放和质量权衡。

所有功能

功能	作用
内容路由器	自动检测内容类型，路由到最优压缩器
SmartCrusher	通用 JSON 压缩——字典数组、字符串、数字、混合类型、嵌套对象
CodeCompressor	基于 AST 的 Python、JS、Go、Rust、Java、C++ 代码压缩
Kompress	基于 ModernBERT 的 token 压缩（替代 LLMLingua-2）
CCR	可逆压缩——LLM 在需要时可检索原始数据
压缩摘要	告诉 LLM 哪些内容被省略了（“3 个错误，12 个失败”）
CacheAligner	稳定前缀，提高提供商 KV 缓存命中率
IntelligentContext	基于评分的上下文管理，结合学习到的重要性
图像压缩	通过训练好的 ML 路由器实现 40-90% 的 token 减少
Memory	跨对话的持久化记忆
Compression Hooks	使用预/后处理钩子自定义压缩过程
Read Lifecycle	检测过时/已替换的 Read 输出，用 CCR 标记代替
headroom learn	分析过去的失败，将项目特定的学习成果写入 CLAUDE.md/MEMORY.md
headroom wrap	一键设置 Claude Code、Codex、Aider、Cursor
SharedContext	压缩后的多智能体上下文共享，适用于多智能体工作流
MCP 工具	headroom_compress、headroom_retrieve、headroom_stats，专用于 Claude Code/Cursor

---

Headroom 与替代方案

上下文压缩是一个新兴领域。以下是各方法的主要区别：

	方法	范围	部署方式	框架集成	数据是否本地存储？	是否可逆
Headroom	多算法压缩	所有上下文（工具输出、数据库读取、RAG、文件、日志、历史记录）	代理、Python 库、ASGI 中间件或回调	LangChain、LangGraph、Agno、Strands、LiteLLM、MCP	是（开源）	是（CCR）
RTK	CLI 命令重写器	Shell 命令输出	CLI 包装器	无	是（开源）	否
Compresr	云端压缩 API	将文本发送至其 API	API 调用	无	否	否
Token Company	云端压缩 API	将文本发送至其 API	API 调用	无	否	否

随心所欲地使用。 Headroom 可以作为独立代理（headroom proxy）、单函数 Python 库（compress()）、ASGI 中间件，或 LiteLLM 回调来使用。已经在使用 LiteLLM、LangChain 或 Agno？无需替换任何东西，直接接入 Headroom 即可。

Headroom 与 RTK 搭配效果极佳。 RTK 会重写 CLI 命令（git show → git show --short），而 Headroom 则负责压缩其他内容（JSON 数组、代码、日志、RAG 结果、对话历史）。两者结合使用效果更佳。

Headroom 与云端 API 的对比。 Compresr 和 Token Company 是托管服务——您将上下文发送到他们的服务器，他们会进行压缩后再返回给您。而 Headroom 则在本地运行。您的数据永远不会离开您的设备。此外，您还能获得无损压缩（CCR）：当 LLM 需要更多细节时，可以恢复原始完整内容。

---

内部工作原理

  您的提示
      │
      ▼
  1. CacheAligner            稳定 KV 缓存前缀
      │
      ▼
  2. ContentRouter           路由每种内容类型：
      │                         → SmartCrusher    (JSON)
      │                         → CodeCompressor  (代码)
      │                         → Kompress        (文本，含 [ml])
      ▼
  3. IntelligentContext      基于评分的令牌优化
      │
      ▼
  LLM 提供者

  需要完整细节？LLM 会调用 headroom_retrieve。
  原始数据保存在压缩存储中——不会有任何丢失。

开销：15–200 毫秒的压缩延迟（对 Sonnet/Opus 来说是净收益）。完整数据：延迟基准测试

---

集成

集成	状态	文档
headroom wrap claude/codex/aider/cursor	稳定	代理文档
compress() — 单函数	稳定	集成指南
SharedContext — 多智能体	稳定	SharedContext 指南
LiteLLM 回调	稳定	集成指南
ASGI 中间件	稳定	集成指南
代理服务器	稳定	代理文档
Agno	稳定	Agno 指南
MCP（Claude Code、Cursor 等）	稳定	MCP 指南
Strands	稳定	Strands 指南
LangChain	稳定	LangChain 指南
OpenClaw	稳定	OpenClaw 插件

---

OpenClaw 插件

插件 @headroom-ai/openclaw 将 Headroom 集成为 OpenClaw 的 ContextEngine。它可以在原地压缩工具输出、代码、日志和结构化数据——节省 70%–90% 的令牌，且无需额外的 LLM 调用。该插件可以连接到本地或远程的 Headroom 代理，如果本地没有运行的代理，它还会自动启动一个。

安装

pip install "headroom-ai[proxy]"
openclaw plugins install --dangerously-force-unsafe-install headroom-ai/openclaw

为什么需要 --dangerously-force-unsafe-install？ 当检测不到正在运行的代理时，插件会自动以子进程的方式启动 headroom proxy。默认情况下，OpenClaw 会阻止启动进程的插件，因此必须使用此标志才能允许该行为。

安装完成后，在 OpenClaw 配置中将 Headroom 设置为上下文引擎：

{
  "plugins": {
    "entries": { "headroom": { "enabled": true } },
    "slots": { "contextEngine": "headroom" }
  }
}

插件会自动检测并启动代理——无需手动管理代理。完整的配置选项、本地开发设置和启动器详情，请参阅插件的 README。

---

云提供商

headroom proxy --backend bedrock --region us-east-1     # AWS Bedrock
headroom proxy --backend vertex_ai --region us-central1 # Google Vertex
headroom proxy --backend azure                          # Azure OpenAI
headroom proxy --backend openrouter                     # OpenRouter（400+ 模型）

---

安装

pip install headroom-ai                # 核心库
pip install "headroom-ai[all]"         # 包括评估在内的所有功能（推荐）
pip install "headroom-ai[proxy]"       # 代理服务器 + MCP 工具
pip install "headroom-ai[mcp]"         # 仅 MCP 工具（不含代理）
pip install "headroom-ai[ml]"          # ML 压缩（Kompress，需 torch）
pip install "headroom-ai[agno]"        # Agno 集成
pip install "headroom-ai[langchain]"   # LangChain（实验性）
pip install "headroom-ai[evals]"       # 仅评估框架

容器镜像（GHCR 标签）

• 支持的平台：linux/amd64、linux/arm64
• 标签 :code - 包含代码感知压缩（基于 AST）的镜像，即运行 pip install "headroom-ai[proxy,code]"
• 标签 :slim - 使用无损基础镜像

标签		额外组件	Docker Bake 目标
<version>	ghcr.io/chopratejas/headroom:<version>	proxy	runtime
latest	ghcr.io/chopratejas/headroom:latest	proxy	runtime
nonroot	ghcr.io/chopratejas/headroom:nonroot	proxy	runtime-nonroot
code	ghcr.io/chopratejas/headroom:code	proxy,code	runtime-code
code-nonroot	ghcr.io/chopratejas/headroom:code-nonroot	proxy,code	runtime-code-nonroot
slim	ghcr.io/chopratejas/headroom:slim	proxy	runtime-slim
slim-nonroot	ghcr.io/chopratejas/headroom:slim-nonroot	proxy	runtime-slim-nonroot
code-slim	ghcr.io/chopratejas/headroom:code-slim	proxy,code	runtime-code-slim
code-slim-nonroot	ghcr.io/chopratejas/headroom:code-slim-nonroot	proxy,code	runtime-code-slim-nonroot

Docker Bake

# 列出所有可用的构建目标
docker buildx bake --list targets

# 在本地构建默认镜像（包含代理且以非 root 用户运行）
docker buildx bake runtime-default

# 构建特定变体并加载到本地 Docker 镜像仓库
docker buildx bake runtime-code-slim-nonroot \
  --set runtime-code-slim-nonroot.platform=linux/amd64 \
  --set runtime-code-slim-nonroot.tags=headroom:local \
  --load

Python 3.10+

---

文档

集成指南	LiteLLM、ASGI、compress()、代理
代理文档	代理服务器配置
架构	管道的工作原理
CCR 指南	可逆压缩
基准测试	准确性验证
延迟基准测试	压缩开销及成本效益分析
局限性	压缩何时有效，何时无效
评估框架	证明压缩不会降低准确性
内存	持久化内存
Agno	Agno 代理框架
MCP	上下文工程工具包（压缩、检索、统计）
共享上下文	压缩后的多代理间上下文共享
学习	编码代理的离线故障学习
配置	所有可配置选项

---

社区

有问题、反馈，或只是想关注我们的进展？加入我们的 Discord

---

贡献

git clone https://github.com/chopratejas/headroom.git && cd headroom
pip install -e ".[dev]" && pytest

---

许可证

Apache License 2.0 — 详见 LICENSE。

Headroom 快速上手指南

Headroom 是一款专为 AI Agent 设计的上下文压缩工具。它能将 Agent 读取的工具调用、数据库查询、文件内容及 RAG 检索结果压缩 70-95%，在保持回答质量不变的前提下，大幅减少 Token 消耗。适用于 Claude Code、Cursor、LangChain 及自定义 Python/TS 应用。

环境准备

• 操作系统：Linux, macOS, Windows
• 运行环境：
  • Python: 版本 3.9 或更高
  • Node.js: 版本 18 或更高（如需使用 TypeScript/Node 集成）
• 前置依赖：无特殊系统级依赖，需确保已安装对应语言的包管理器（pip 或 npm）。

提示：国内开发者若遇到 PyPI 或 npm 下载缓慢，可配置国内镜像源加速：

• PyPI: pip install -i https://pypi.tuna.tsinghua.edu.cn/simple ...
• npm: npm config set registry https://registry.npmmirror.com

安装步骤

根据你的开发语言选择以下任一方式安装：

Python 环境

pip install "headroom-ai[all]"
# 或使用清华源加速
# pip install "headroom-ai[all]" -i https://pypi.tuna.tsinghua.edu.cn/simple

TypeScript / Node.js 环境

npm install headroom-ai
# 或使用淘宝镜像加速
# npm install headroom-ai --registry=https://registry.npmmirror.com

基本使用

Headroom 提供多种集成方式，以下是三种最常用的场景：

1. 代码集成（最灵活）

直接在代码中调用 compress 函数，适用于任何 LLM 客户端（OpenAI, Anthropic, LiteLLM 等）。

Python 示例：

from headroom import compress

# 压缩消息列表
result = compress(messages, model="claude-sonnet-4-5-20250929")

# 将压缩后的消息发送给 LLM
response = client.messages.create(model="claude-sonnet-4-5-20250929", messages=result.messages)

print(f"节省 {result.tokens_saved} tokens (压缩率 {result.compression_ratio:.0%})")

TypeScript 示例：

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'gpt-4o' });
const response = await openai.chat.completions.create({ model: 'gpt-4o', messages: result.messages });

console.log(`Saved ${result.tokensSaved} tokens`);

2. 透明代理模式（零代码修改）

启动一个本地代理服务器，拦截所有请求并自动压缩上下文。适用于无法修改源码的现有应用或 CLI 工具。

启动代理：

headroom proxy --port 8787

配置应用指向代理：

# Anthropic 系列工具
ANTHROPIC_BASE_URL=http://localhost:8787 your-app

# OpenAI 系列工具
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

3. 编程助手一键封装

针对主流编程 Agent（如 Claude Code, Cursor, Aider），使用 wrap 命令自动完成代理启动与配置。

# 封装 Claude Code
headroom wrap claude

# 封装 Cursor (打印配置信息)
headroom wrap cursor

# 封装 Aider
headroom wrap aider

# 封装 OpenAI Codex CLI
headroom wrap codex

执行后，Headroom 会自动启动后台代理并将对应的编程工具指向该代理，实现全自动压缩。