chopratejas headroom

██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝

面向 AI 智能体的上下文压缩层 —— 减少 60–95% 的 Token · 库 · 代理 · MCP · 6 种算法 · 本地优先 · 可逆

文档 · 安装 · 验证 · 智能体 · Discord · llms.txt

AI 智能体 / LLM：在此处阅读 /llms.txt，或获取实时索引 / 完整文档 blob。

Headroom 在你 AI 智能体读取的所有内容（工具输出、日志、RAG 块、文件和对话历史）到达 LLM 之前对其进行压缩。答案不变，Token 量大幅减少。实时效果：10,144 → 1,260 个 Token —— 相同的 FATAL 错误依然被找到。

它能做什么

库 —— 在 Python 或 TypeScript 中调用 compress(messages)，内联集成到任何应用
代理 —— headroom proxy --port 8787，零代码改动，支持任何语言
智能体封装 —— 一条命令 headroom wrap claude|codex|cursor|aider|copilot
MCP 服务器 —— 为任何 MCP 客户端提供 headroom_compress、headroom_retrieve、headroom_stats
跨智能体记忆 —— 在 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） │ │ │ │ 跨智能体记忆 · headroom learn · MCP │ └────────────────────────────────────────────────────┘ │ 压缩后的提示词 + 检索工具 ▼ LLM 提供商（Anthropic · OpenAI · Bedrock · …）

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

→ 架构 · CCR 可逆压缩 · Kompress-base 模型卡

快速开始（60 秒）

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

# 2 — 选择模式
headroom wrap claude             # 封装一个编码智能体
headroom proxy --port 8787       # 即时代理，零代码改动
# 或：from headroom import compress  # 内联库

# 3 — 查看节省效果
headroom stats

可选扩展：[proxy]、[mcp]、[ml]、[agno]、[langchain]、[evals]。需要 Python 3.10+。

验证

在真实智能体工作负载上的节省效果：

| 工作负载 | 压缩前 | 压缩后 | 节省比例 | |---------|--------|--------|---------| | 代码搜索（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 · 完整基准测试与方法论

社区已节省超过 600 亿 Token —— 实时排行榜 →

智能体兼容性矩阵

| 智能体 | headroom wrap | 备注 | |-------|---------------|------| | Claude Code | ● | --memory · --code-graph | | Codex | ● | 与 Claude 共享记忆 | | Cursor | ● | 打印配置 —— 粘贴一次即可 | | Aider | ● | 启动代理 + 启动 | | Copilot CLI | ● | 启动代理 + 启动 | | OpenClaw | ● | 作为 ContextEngine 插件安装 |

任何兼容 OpenAI 的客户端均可通过 headroom proxy 使用。MCP 原生支持：headroom mcp install。

何时使用 · 何时跳过

非常适合你如果……

每天使用 AI 编码智能体，希望在不改动代码的情况下节省 Token
跨多个智能体工作，需要共享记忆
需要可逆压缩 —— 原始数据始终可通过 CCR 检索

跳过它如果……

只使用单一提供商的原生压缩功能，不需要跨智能体记忆
在沙盒环境中工作，无法运行本地进程

集成 —— 将 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) | | 多智能体 | SharedContext().put / .get | | MCP 客户端 | headroom mcp install |

内部组件

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

管道内部机制

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

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

转换器完成实际工作：CacheAligner、ContentRouter、SmartCrusher、CodeCompressor、Kompress-base、IntelligentContext / RollingWindow。

管道扩展可以观察或自定义生命周期。