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 perf

额外组件：[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 · 完整基准测试与方法论

智能体兼容性矩阵

| 智能体 | 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。

流水线扩展通过 on_pipeline_event(...) 观察或自定义生命周期阶段。

chopratejas headroom