headroom

center"><pre> ██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝ 面向 AI 智能体的上下文压缩层 </pre></div> <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://github.com/chopratejas/headroom/actions/workflows/ci.yml/badge.svg" alt="CI"></a> href="https://app.codecov.io/gh/chopratejas/headroom"><imghttps://codecov/chopratejas/headroom/graph/badge.svg" alt="codecov"></a> <a href="https.org/project/headroom-ai/"><img src="https://img.shields.io/pypi/v/headroom-ai.svg" alt="PyPI"></a> <a href="https://www.npmjs.com/package/headroom-ai"><img src="https://img.shields.io/npm/v/headroom-ai.svg" alt="npm"></a> <a href="https://huggingface.co/chopratejas/kompress-v2-base"><img src="https://img.shields.io/badge/model-Kompress--v2--base-yellow.svg" alt="模型：Kompress-v2-base"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="许可证：Apache 2.a> <="https://headroom-docs.vercel.app/docs"><img src="https://img/badge/docs-online-blue.svg="文档"></ap> <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">智能体</a> · <a href="https://discord.gg/yRmaUNpsPJ">Discord</a> · <a href="llms.txt">llms.txt</a> · <a href="ENTERPRISE.md">企业</a> </p> <p align="center">_{<b>AI 智能体 / 大型语言模型：</b> 在此处阅读 <a href="llms.txt"><code>/llms.txt</code></a>，或获取 <a href="https://headroom-docs.vercel.app/llms实时索引</a <a href="https://headroom-docs.vercel.app/llms-full.txt">完整文档 blob</a>。}</p> --- <p align="center"><a href="https://trendshift.io/repositories/20881" target="_blank"><img src="https://trendshift.io/api/badge/repositories/20881" alt="chopratejas%2Fheadroom | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a></p> Headroom 压缩 AI 智能体读取的所有内容 — 工具输出、日志、RAG 分片、文件和对话历史 — 然后才将其发送到大型语言模型（LLM）。相同的答案，但 token 数量减少了几分之一。 <p align="center"> <img src="HeadroomDemo-Fast.gif" alt="Headroom in action" width="820"> <br/><sub>实时：10,1441,260 tokens — 找到相同的 Fsub> </p> ## 它能做什么 - **库** — 或 TypeScript 中compress(messages)`，在任何应用程序中 **代理** — 使用 `headroom proxy --8787`，代码，适用于任何- **智能体包装** — 使用 `headroom wrap claude|codex|cursor|aider|copilot|opencode`，只需一条命令 -CP 服务器** — MCP 客户端提供 `headroom_compress`、`_retrieve`room_stats` - **跨智能体内存**跨 Claude、Codex、Gemini 共享去重 - **`headroom learn`** — 分析失败的会话，并将更正写入 `CLAUDE.md` / `AGENTS.md` - **输出 token 减少** — 修剪模型 *写回* 的内容（不仅是您发送的内容）：删除仪式/重复的代码，并跳过例行步骤的深入“思考”。请参阅 [输出 token 减少](#output-token-reduction-cut-what-the-model-writes-back)。 - **可逆（CCR）** — 原始内容缓存在本地；LLM 调用 `headroom_retrieve` 如果需要它们 ## 它是如何工作的（30 秒） ``` 您的智能体/应用程序 （Claude Code、Cursor、Codex、LangChain、Agno、Strands、您的自定义代码...） │ 提示 · 工具输出 · 日志 · RAG 结果 · 文件 ┌────┐ │ Headroom本地运行 — 您的保留在此） │ │ ──────────────────────────────────────────────── │ │ CacheAligner → ContentRouter → CCR │ │ ├─ SmartCrusher （JSON） │ │ ├─ CodeCompressor （AST） │ │ └─ Kompress-base （文本，HF） │ │ │ │ 跨智能体内存 · 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-v2-base 模型卡](https://huggingface.co/chopratejas/kompress-v2-base) ## 快速开始（60 秒） ```bash # 1 — 安装 pip install "headroom-ai[all]" # Python npm install headroom-ai # Node / TypeScript # 2 — headroomaude # 智能体 headroom proxy --port 8787 # 替换代理，无需更改代码 # 或：from headroom import compress # 内联库 # 3 — 查看节省 headroom perf headroom dashboard 实时节省仪表盘（代理必须运行） ``` 精细化额外功能： `[proxy]`、 `[]`、 `[ml]`、 `[code]`、 `[memory]`、 `[relevance]`、 `[image]`、 `[agno]`、 `[langchain]`、 `[evals]`、 `[pytorch-mps]` （Apple-GPU 内存嵌入卸载 — 设置 `HEADROOM_EMBEDDER_RUNTIME=pytorch_mps`）。**需要 Python 3.10+**。 ## 证明 **真实智能体工作负载上的节省：** | 工作负载 | 之前 | 之后 | 节省 | |-------------------------------|-------:|-------:|--------:| | 代码搜索（100 个结果） | 17,765 | 1,408 | **92%** | | SRE 事件调试 | 65,694 | 5,118 | **92%** | | GitHub 问题分类 | 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` · [完整基准测试和方法https://headroom.app/docs/## 输出 token（减少模型写） 上述所有内容都减少了您 **发送** 的提示。但是，您也需要为模型 **写回** 的每个付费 — 而在 Opus 类模型输出成本是输入5 倍。 输出都是浪费：，让我…” 前重新打印您刚刚显示的代码，以及在例行读取文件深入“思考”。 Headroom 还可以修剪这些内容，从代理中您更改任何代码- **控制** — 在的末尾附加短的“保持，不要重复上下文”注释（因此您的仍然有效）。 -路由** — 当只是模型在工具结果后恢复（读取文件，测试通过），它会降低模型的思考努力。新的问题和错误仍会全力以赴。 启用： ```bash export HEADROOM_OUTPUT_SHAPER=1 # 默认关闭 headroom proxy --port 8787 ``` > **代理已经运行？** 这些开关在每次请求时实时读取，因此 `headroom wrap` **重用** 的代理（而不是启动）不会看到您之后导出的值 — 其环境在启动时快照。`headroom wrap` 现在通过循环回路 `POST /admin/runtime-env` 将您的当前设置热同步到正在运行的代理，因此它们立即生效，无需 **重启** （无需冷启动，无需请求丢失，无需缓存丢失）。在共享代理上，这些覆盖全局 — 最后一个显式设置生效。 **为你学习合适的简洁度。** 人们不 *说* 他们希望答案有多简洁 — 他们 * （他们打断，或在能够之前继续）。` learn --verbosity` 读取您的过去会话并级别： headroom learn # 预览的内容（试headroom learn --apply #代理从现在它 ``` 您节省了多少。** 输出节省反事实* 我们看不到会* 写出什么 — 因此 Headroom 报告一个诚实的 **，带有置** ，而不是编造的数字： ```bash headroom output-savings # 减少：31.7% （95% CI 27.7% … 35.7%） [估计] ``` 想要一个 *衡量* 的数字而不是估计值？ 将 10% 的对话留作对照组：`export HEADROOM_OUTPUT_HOLDOUT=0.1`。 仪表盘显示一个 **已节省的输出 token** 卡位于输入压缩旁边为`已 或 `已估计带有置信区间。 → 完整的测量方法： [`docs/proposals/output-token.md`](docs-token-reduction<a href="www.star-historyrepos=choprate2Fhead&legend=top <picture> img alt="Star History Chart" src="api.star-history.comrepos=choprate&type=date&legend=top-left" /> </picture> </a> ## 智能体兼容性矩阵 | 智能体 | `headroom wrap` | 备注 | |--------------|:---------------:|----------------------------------| | Claude Code | ✅ memory` · `--code-graph`| Codex ✅ | 与 Claude 共享内存 Cursor | ✅ | 打印配置粘贴一次| Aider | ✅ | 启动代理 + 启动 | | Copilot CLI | | 启动代理 | | Open | ✅ 安装为 ContextEngine | | | ✅ | 注入配置 · 启动代理 + 启动 | | Cortex Code | | 60% 节省模式 | 任何 兼容的客户端都可以通过 `headroom 工作。M生：` mcp install`. Copilot订阅模式 Head通过本地代理 Copilot订阅流量： headroom cop login head copilot -- --model go ``` Headroom OpenAI 兼容ilot CLI 请求到 GitHub 的托管 API 代理压缩包装器会 的可重Hub OAuth 获取 Copilot API 令打印上游端点为 `COPIL_API_URL=启动期间。 room copilot 存储了一个有的 Copilot OAuth 令牌。这样了依赖通用 或 Copilot CLI，这些令 Copilot元数据，但仍 Copilot 的交换端点拒绝。 对于 GitHub Enterprise自定义域 Cop，请在设置部署域： exportOPILISE_DOMAIN=g.com ``` .com/enterprises/your` 形式的 GitHub.com 企业云网址，请勿设置企业域覆盖。Headroom 使用 GitHub 的标准令牌交换端点和为登录帐户提供的 Copilot API 端点。 平台支持注意：macOS 身份验证重用通过 Copilot CLI 钥匙串存储进行烟雾测试。Windows 凭证管理器、Linux 机密服务 / `secret-tool` 和 Docker/CI 令牌注入路径正在实施或计划作为身份验证发现路径，但仍需要 验证，然后才能被视为完全验证。对于 Docker 和 CI喜欢传递显式 `_COPILOT_TOKEN` 或 `GITHUB_COPILOT_GITHUB，而不是依赖主机钥匙串## 何时使用 · 何时 **非常适合如果您- 每天运行 AI 编码，希望在不更改代码的情况下获得- 跨多个智能体工作内存 - 需要可逆压缩配置的 TTL，原始内容 **跳过如果您... 仅使用单一提供商的，不需要跨智能体内存 沙盒环境中工作，无法运行 <details> <summary>集成 — 将 Headroom 放入任何堆栈中</b></summary 您的设置 | | |------------------------|------------------------------------------------------------------| 任何 Python 应用程序 | `, model=…)` 任何 TypeScript 应用程序 | compress(messages, { model }) | | Anthropic / Open | `withHeadroom(new Anth · `withHeadroom(new())` | | V AI SDK | `wrapLanguage model, middleware: headroomMiddleware() })` | | LiteLLM | `litellm.callbacks =roomCallback()]` | Chain | `HeadroomChatour_llm)` | no | `HeadroomAg(your_model)` | | | [Strands https://headroom-docs.vercel.app/docs/strands) | | AS应用程序 | `app.add_mCompressionMiddleware)` | |体 | `SharedContext(). .get` | |客户端 | `headroom m | </details> <detailssummary><b>内部有什么></summary> - **SmartCrusher** — 通用 JSON：数组、混合类型。 - **CodeCompressor** — 针对 Python、Go、Rust、Java、C++ 的 AST 感知。 - **Kompress — 我们的 HuggingFace，针对代理轨迹进行- **图像压缩** — 通过 ML 路由器减少 90%。 - **CacheAligner 稳定前缀，以便 AnthAI KV 缓存实际命中。 IntelligentContext** — 基于上下文拟合，学习重要性 **CCR** — 可逆LLM 按需检索原始内容 **跨智能体内存**共享存储、智能体来源、重。 - **SharedContext** — 跨多智能体工作压缩上下文传递。 - **`head`** — 用于 Claude、Codex、Gemini 的基于插件的故障挖掘。 </details> <details> <summary><b>管道内部</b></summary> Headroom 通过 `compress()`、SDK 和代理公开一个稳定的请求生命周期： `设置` → `预启动` → `启动后` → `输入接收` → `输入缓存` → `输入路由` → `输入压缩` → `记住输入` → `预发送` → `发送后` → `接收响应` - **转换** 执行工作：CacheAlignContentRouter、Smart、CodeCompressor、Kompress-base、Intelligent RollingWindow。 - **管道 通过 `on_pipeline_event(...)观察或自定义生命周期阶段。 -钩子** 与规范生命周期附加扩展缝。 - **** 保持服务器/应用程序集成 ASGI 中间件、启动策略。 提供者和工具特定的行为位于 `headroom/providers/` 下编排专注于生命周期、策略。 - **CLI/**：`headroom/providers/cl、 `copilot`、 `codex`、 `openclaw **提供商运行时切片**：room/providers/claude`、ini`，以及 `head/registry.py` 中的共享运行时调度 - **核心文件排优先**：`wrap、 `client.py`、 `.py` 和 `proxy` 委托提供商特定的形、API 目标规范、和传输调度。 </## 安装 ```bash "headroom-ai[all]" Python，一切皆有可能 headroom-ai # Type Node docker pull ghcr.io/chopratejas/headroom:latest精细化额外功能： `[、 `[mcp]`、 `[ml]` （Kompress-base）、]`、 `[memory]`、 `[relevance]`、 `[image]`agno]`、 `[langchain]`evals]`、 `[pps]` （Apple-GPU嵌入卸载 — 设置 `HEADBEDDER_RUNTIME=pytorch`）。**需要 Python 10+**。 使用 ``？请显式选择受解释器： ```bash pipx install --python python3.13 "headroom-ai[all→ [安装指南](https://headroom-docs.vercel.app/docs/install — Docker 标签、持久服务Shell、开发容器。 ###```bash headroom update 检测 pip / pipx 工具并就地升级room update --check # 版本而无需升级 headroom update --pre # 发布版本 ``` `headroom 会确定 Headroom 的安装pip/venv、`pip --、 pipx、uv 并运行相应的跨 macOS 和 Windows 的升级。对于 git、editable 安装、Docker 外部管理的系统 Python（668），它会打印正确的而不是猜测。 代理还时显示一行“可用更新。它每隔一天最多检查一次 PyPI，在后台运行，绝。可以通过设置 `HEADROOM_UPDATE_CHECK=off` 来选择退出（在 `--stateless` 模式和 CI 中也会跳过）。 ### 企业 / SSL 审查环境 如果 `pip install "headroom-ai[all]"` 失败并出现 `CERTIFICATE_VERIFY_FAILED` 错误（`unable to get local issuer certificate`），则您的网络可能使用了 **SSL 审查** — 一种中间人攻击代理，呈现由公司颁发的 CA。构建后端（`maturin`）通过 TLS 堆栈不信任的连接下载 `rustup`。**请先安装 Rust**，以便构建不获取它： ```bash # macOS / Linux curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh && rustup default stable # Windows winget install Rustlang.Rustup && rustup default stable ``` 重启您的 shell，然后运行 `pip install "headroom-ai[all]"`。预编译的 wheel 在可用时可完全避免 Rust 构建：`pip install --only-binary headroom-ai headroom-ai`。 有两个运行时资产通过 TLS 获取；如果它们被阻止，请通过 `REQUESTS_CA_BUNDLE` / `SSL_CERT_FILE` / `CURL_CA_BUNDLE` 信任您的企业 CA： - **`cdn.pyke.io`** — 用于 Rust 核心的 ONNX 运行时。或者，使用 `ORT_STRATEGY=system` 和 `ORT_LIB_LOCATION=/path/to/onnxruntime` 预先提供它。 - **`huggingface.co`** — `kompress-base` 压缩模型。预先下载它并在 `HF_HUB_OFFLINE=1` 下运行，或将 `HF_ENDPOINT` 设置为受信任的镜像。 在禁用压缩的情况下运行（纯网关）不需要任何资产。 ## headroom learn <p align="center"> <img src="headroom_learn.gif" alt="headroom learn in action" width="720"> </p> `headroom learn` — 分析失败的会话，将更正写入 `CLAUDE.md` / `AGENTS.md` / `GEMINI.md`。 ## 文档 | 开始这里 | 更深入 | |-------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | [快速开始](https://headroom-docs.vercel.app/docs/quickstart) | [架构](https://headroom-docs.vercel.app/docs/architecture) | | [代理](https://headroom-docs.vercel.app/docs/proxy) | [压缩工作原理](https://headroom-docs.vercel.app/docs/how-compression-works) | | [MCP 工具](https://headroom-docs.vercel.app/docs/mcp) | [CCR — 可逆压缩](https://headroom-docs.vercel.app/docs/ccr) | | [内存](https://headroom-docs.vercel.app/docs/memory) | [缓存优化](https://headroom-docs.vercel.app/docs/cache-optimization) | | [故障学习](https://headroom-docs.vercel.app/docs/failure-learning) | [基准测试](https://headroom-docs.vercel.app/docs/benchmarks) | | [配置](https://headroom-docs.vercel.app/docs/configuration) | [限制](https://headroom-docs.vercel.app/docs/limitations) | ## 相比之下 Headroom **本地运行**，涵盖 **所有** 内容类型，与所有主要框架配合使用，并且是 **可逆的**。 | | 范围 | 部署 | 本地 | 可逆 | |------------------------------------------------------------------------------|------------------------------------------------|------------------------------------|:-----:|:----------:| | **Headroom** | 所有上下文 — 工具、RAG、日志、文件、历史 | 代理 · 库 · 中间件 · MCP | 是 | 是 | | [RTK](https://github.com/rtk-ai/rtk) | CLI 命令输出 | CLI 包装器 | 是 | 否 | | [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI 命令、MCP 工具、编辑器规则 | CLI 包装器 · MCP | 是 | 否 | | [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | 发送到其 API 的文本 | 主机 API 调用 | 否 | 否 | | OpenAI 压缩 | 会话历史 | 提供者原生 | 否 | 否 | > **致谢。** Headroom 配备了优秀的 [RTK](https://github.com/rtk-ai/rtk) 二进制文件，用于 shell 输出重写 — `git show --short`、作用域 `ls`、摘要安装程序。非常感谢 RTK 团队；他们的工具是我们堆栈中一流的部分，Headroom 在其下游压缩所有内容。Headroom 还可以使用 [lean-ctx](https://github.com/yvgude/lean-ctx) 作为选定的 CLI 上下文工具；在运行 `headroom wrap ...` 之前设置 `HEADROOM_CONTEXT_TOOL=lean-ctx`。 ## 贡献 ```bash git clone https://github.com/chopratejas/headroom.git && cd headroom uv sync --extra dev && uv run pytest ``` `.devcontainer/` 中的开发容器（默认 + 带有 Qdrant 和 Neo4j 的 `memory-stack`）。参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 社区 - **[Discord](https://discord.gg/yRmaUNpsPJ)** — 问题、反馈、战斗故事。 - **[Kompress-v2-base on HuggingFace](https://huggingface.co/chopratejas/kompress-v2-base)** — 我们文本压缩背后的模型。 ## 许可证 Apache 2.0 — 参见 [LICENSE](LICENSE)。