headroom

为LLM agent设计的上下文压缩层，能在工具输出、日志、代码等到达模型前将其压缩至原先的5%-40%而保持答案一致。支持库函数调用、透明代理、MCP Server等多种接入方式，无需修改现有代码。内置智能路由和多种压缩算法（JSON/代码/AST/通用文本），并提供可逆压缩机制以便LLM按需还原原文。适合高频使用AI编码工具（Claude Code、Cursor等）的团队大幅降低token开销和延迟。

README

██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ AI 智能体的上下文压缩层


<p align="center"><strong>减少 60–95% token · 库 · 代理 · MCP · 6 种算法 · 本地优先 · 可逆</strong></p>

<p align="center">
  <a href="https://github.com/chopratejas/headroom/actions/workflows/ci.yml"><img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/39faa54be350a1dab8afd3b2fb8c1c83e4d9cff84abfef2374d19a18053687c4.svg" alt="CI"></a>
  <a href="https://app.codecov.io/gh/chopratejas/headroom"><img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/d1366835268f1a7effea2441a0e1f5adb29f4b5df1bc9a9edeefffe123b6fbce.svg" alt="codecov"></a>
  <a href="https://pypi.org/project/headroom-ai/"><img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/f3dde1ff8e7528fe1063e8591ceeaf8945f120cb022d219cc061b8938d6afbbb.svg" alt="PyPI"></a>
  <a href="https://www.npmjs.com/package/headroom-ai"><img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/9d701db7dc4887e306b2f98d9ecace6f01b602bdc7960a0d59bf7ea84f7eca23.svg" alt="npm"></a>
  <a href="https://huggingface.co/chopratejas/kompress-base"><img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/9d2e9f4c1d2e16095844592a413c215479572cafa04b6a4b86f8368eff5a24a3.svg" alt="Model: Kompress-base"></a>
  <a href="LICENSE"><img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/cf8712a6e72b0befc0b6b3b71ef0b932a5c732eb6c6bfb1813384aec95abec78.svg" alt="License: Apache 2.0"></a>
  <a href="https://headroom-docs.vercel.app/docs"><img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/fdd193b41e1d60cba82f2cc61cd66b15dc31bb5aff4a78f9a4be1a07f8d9b8d1.svg" alt="文档"></a>
</p>

<p align="center">
  <a href="https://headroom-docs.vercel.app/docs">文档</a> ·
  <a href="#get-started-60-seconds">安装</a> ·
  <a href="#proof">效果验证</a> ·
  <a href="#agent-compatibility-matrix">支持的 Agent</a> ·
  <a href="https://discord.gg/yRmaUNpsPJ">Discord</a> ·
  <a href="llms.txt">llms.txt</a>
</p>

<p align="center"><sub>
  <b>AI 智能体 / LLM：</b> 在此处阅读 <a href="llms.txt"><code>/llms.txt</code></a>，或获取 <a href="https://headroom-docs.vercel.app/llms.txt">实时索引</a> / <a href="https://headroom-docs.vercel.app/llms-full.txt">完整文档块</a>。
</sub></p>

---

> Headroom 在 AI 智能体读取的所有内容——工具输出、日志、RAG 块、文件和对话历史——到达 LLM 之前对其进行压缩。答案相同，token 减少到零头。

<p align="center">
  <img src="https://api.ai-feeds.com/r/gh/chopratejas/headroom/c9012fc101f9592f157d443920a155c77ad6b5e642604cfadfc56bb3bf78819d.gif" alt="Headroom 运作演示" width="820">
  <br/><sub>实时：10,144 → 1,260 token —— 仍能找出相同的 FATAL 错误。</sub>
</p>

## 它能做什么

- **作为库** —— 在 Python 或 TypeScript 中直接调用 `compress(messages)`，嵌入任何应用
- **作为代理** —— `headroom proxy --port 8787`，零代码改动，支持任何语言
- **包装 Agent** —— 一条命令 `headroom wrap claude|codex|cursor|aider|copilot`
- **作为 MCP 服务器** —— 为任何 MCP 客户端提供 `headroom_compress`、`headroom_retrieve`、`headroom_stats`
- **跨 Agent 记忆** —— 在 Claude、Codex、Gemini 之间共享存储，自动去重
- **`headroom learn`** —— 挖掘失败会话，将修正写入 `CLAUDE.md` / `AGENTS.md`
- **可逆压缩 (CCR)** —— 原内容永不删除；LLM 可按需检索

## 工作原理（30 秒理解）

你的智能体 / 应用 (Claude Code, Cursor, Codex, LangChain, Agno, Strands, 你自己的代码……) │ 提示 · 工具输出 · 日志 · RAG 结果 · 文件 ▼ ┌────────────────────────────────────────────────────┐ │ Headroom (本地运行 —— 你的数据留在此处) │ │ ──────────────────────────────────────────────── │ │ CacheAligner → ContentRouter → CCR │ │ ├─ SmartCrusher (JSON) │ │ ├─ CodeCompressor (AST) │ │ └─ Kompress-base (文本, HF) │ │ │ │ 跨 Agent 记忆 · headroom learn · MCP │ └────────────────────────────────────────────────────┘ │ 压缩后的提示 + 检索工具 ▼ LLM 提供商 (Anthropic · OpenAI · Bedrock · …)


- **ContentRouter** —— 检测内容类型，选择正确的压缩器
- **SmartCrusher / CodeCompressor / Kompress-base** —— 压缩 JSON、AST 或散文
- **CacheAligner** —— 稳定前缀，使提供商 KV 缓存真正命中
- **CCR** —— 本地存储原内容；LLM 需要时调用 `headroom_retrieve`

→ [架构](https://headroom-docs.vercel.app/docs/architecture) · [CCR 可逆压缩](https://headroom-docs.vercel.app/docs/ccr) · [Kompress-base 模型卡片](https://huggingface.co/chopratejas/kompress-base)

## 快速上手（60 秒）

```bash
# 1 — 安装
pip install "headroom-ai[all]"          # Python
npm install headroom-ai                 # Node / TypeScript

# 2 — 选择你的模式
headroom wrap claude                    # 包装一个编程 Agent
headroom proxy --port 8787              # 即插即用代理，零代码改动
# 或： from headroom import compress      # 内联库

# 3 — 查看节省量
headroom stats

细粒度可选组件：[proxy]、[mcp]、[ml]、[agno]、[langchain]、[evals]。需要 Python 3.10+。

效果验证

真实 Agent 工作负载的节省量：

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

在标准基准测试上保持准确率：

基准测试	类别	N	基准	Headroom	差异
GSM8K	数学	100	0.870	0.870	±0.000
TruthfulQA	事实性	100	0.530	0.560	+0.030
SQuAD v2	问答	100	—	97%	压缩率 19%
BFCL	工具	100	—	97%	压缩率 32%

复现：python -m headroom.evals suite --tier 1 · 完整基准测试与方法论

Agent 兼容性矩阵

Agent	`headroom wrap`	说明
Claude Code	●	`--memory` · `--code-graph`
Codex	●	与 Claude 共享记忆
Cursor	●	打印配置 —— 粘贴一次即可
Aider	●	启动代理 + 启动应用
Copilot CLI	●	启动代理 + 启动应用
OpenClaw	●	作为 ContextEngine 插件安装

任何兼容 OpenAI 的客户端均可通过 headroom proxy 工作。MCP 原生：headroom mcp install。

何时使用 · 何时跳过

非常适合你，如果……

每天使用 AI 编程 Agent，希望在不改动代码的情况下节省 token
在多个 Agent 之间工作，需要共享记忆
需要可逆压缩 —— 原内容始终可通过 CCR 检索

可以跳过，如果……

仅使用单个提供商的本地压缩功能，且不需要跨 Agent 记忆
在沙盒环境中工作，无法运行本地进程

集成 —— 将 Headroom 插入任何技术栈

你的技术栈	集成方式
任何 Python 应用	`compress(messages, model=…)`
任何 TypeScript 应用	`await compress(messages, { model })`
Anthropic / OpenAI SDK	`withHeadroom(new Anthropic())` · `withHeadroom(new OpenAI())`
Vercel AI SDK	`wrapLanguageModel({ model, middleware: headroomMiddleware() })`
LiteLLM	`litellm.callbacks = [HeadroomCallback()]`
LangChain	`HeadroomChatModel(your_llm)`
Agno	`HeadroomAgnoModel(your_model)`
Strands	Strands 指南
ASGI 应用	`app.add_middleware(CompressionMiddleware)`
多 Agent	`SharedContext().put / .get`
MCP 客户端	`headroom mcp install`

内部组件

SmartCrusher —— 通用 JSON：字典数组、嵌套对象、混合类型。
CodeCompressor —— 基于 AST，支持 Python、JS、Go、Rust、Java、C++。
Kompress-base —— 我们的 HuggingFace 模型，在 Agent 追踪数据上训练。
图像压缩 —— 通过训练的 ML 路由实现 40–90% 缩减。
CacheAligner —— 稳定前缀，使 Anthropic/OpenAI 的 KV 缓存真正命中。
IntelligentContext —— 基于分数的上下文适配，带学习的重要性。
CCR —— 可逆压缩；LLM 按需检索原内容。
跨 Agent 记忆 —— 共享存储，Agent 来源追溯，自动去重。
SharedContext —— 跨多 Agent 工作流传递压缩上下文。
headroom learn —— 基于插件的失败挖掘，支持 Claude、Codex、Gemini。

管线内部机制

Headroom 在 compress()、SDK 和代理中暴露了一个稳定的请求生命周期：

设置 → 预启动 → 后启动 → 收到输入 → 输入缓存 → 输入路由 → 输入压缩 → 输入记忆 → 预发送 → 后发送 → 收到响应

变换（Transforms） 完成实际工作：CacheAligner、ContentRouter、SmartCrusher、CodeCompressor、Kompress-base、IntelligentContext / RollingWindow。
管线扩展 通过 on_pipeline_event(...) 观察或自定义生命周期阶段。
压缩钩子 作为额外的扩展接口，与规范生命周期并列。
代理扩展 作为服务器/应用集成的接口，用于 ASGI 中间件、路由和启动策略。

提供商和工具特定行为位于 headroom/providers/ 下，使核心编排专注于生命周期、顺序和策略。

CLI/工具切片：headroom/providers/claude、copilot、codex、openclaw
提供商运行时切片：headroom/providers/claude、gemini，以及 headroom/providers/registry.py 中的共享后端/运行时调度
核心文件保持编排优先：wrap.py、client.py、cli/proxy.py 和 proxy/server.py 将提供商特定的环境塑造、API 目标归一化、后端选择和传输调度委托出去。

安装

pip install "headroom-ai[all]"          # Python，全部组件
npm install headroom-ai                 # TypeScript / Node
docker pull ghcr.io/chopratejas/headroom:latest

细粒度可选组件：[proxy]、[mcp]、[ml]（Kompress-base）、[agno]、[langchain]、[evals]。需要 Python 3.10+。

使用 pipx？请显式指定一个支持的 Python 解释器：

pipx install --python python3.13 "headroom-ai[all]"

→ 安装指南 —— Docker 标签、持久化服务、PowerShell、devcontainers。

headroom learn

headroom learn 运作演示

headroom learn —— 挖掘失败会话，将修正写入 CLAUDE.md / AGENTS.md / GEMINI.md。

文档

从这里开始	深入探索
快速入门	架构
代理模式	压缩原理
MCP 工具	CCR —— 可逆压缩
记忆	缓存优化
失败学习	基准测试
配置	局限性

对比

Headroom 本地运行，覆盖所有内容类型，适用于每个主流框架，并且可逆。

	范围	部署方式	本地	可逆
Headroom	所有上下文——工具、RAG、日志、文件、历史	代理 · 库 · 中间件 · MCP	是	是
RTK	CLI 命令输出	CLI 包装器	是	否
lean-ctx	CLI 命令、MCP 工具、编辑器规则	CLI 包装器 · MCP	是	否
Compresr, Token Co.	发送到其 API 的文本	托管的 API 调用	否	否
OpenAI 压实	对话历史	提供商原生	否	否

致谢。 Headroom 随附出色的 RTK 二进制文件，用于 shell 输出重写 —— git show --short、作用域 ls、摘要安装程序。衷心感谢 RTK 团队；他们的工具是我们技术栈中的一等公民，Headroom 压缩其下游的所有内容。Headroom 也可以使用 lean-ctx 作为选定的 CLI 上下文工具；在运行 headroom wrap ... 前设置 HEADROOM_CONTEXT_TOOL=lean-ctx。

贡献

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

Devcontainer 位于 .devcontainer/（默认 + 带 Qdrant 和 Neo4j 的 memory-stack）。参见 CONTRIBUTING.md。

社区

实时排行榜 —— 已节省超过 600 亿 token，持续增长中。
Discord —— 提问、反馈、实战故事。
HuggingFace 上的 Kompress-base —— 我们文本压缩背后的模型。

许可证

Apache 2.0 —— 参见 LICENSE。

开源项目chopratejas2026-06-02原文

打开互动版

headroom

README

效果验证

Agent 兼容性矩阵

何时使用 · 何时跳过

安装

headroom learn

文档

对比

贡献

社区

许可证

相关内容

warp

sim

superpowers

skills

skills