chopratejas / headroom

The context compression layer for AI agents. 60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible. AI 智能体的上下文压缩层。减少 60%–95% 的 Token 使用量 · 提供库 · 代理 · MCP · 6 种算法 · 本地优先 · 可逆。

Docs · Install · Proof · Agents · Discord · llms.txt

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

AI agents / LLMs: read /llms.txt here, or fetch the live index / full docs blob. AI 智能体 / 大语言模型：在此处阅读 /llms.txt，或获取实时索引 / 完整文档包。

Headroom compresses everything your AI agent reads — tool outputs, logs, RAG chunks, files, and conversation history — before it reaches the LLM. Same answers, fraction of the tokens. Live: 10,144 → 1,260 tokens — same FATAL found. Headroom 会在数据到达大语言模型（LLM）之前，压缩 AI 智能体读取的所有内容——包括工具输出、日志、RAG 数据块、文件和对话历史。在保持回答质量不变的前提下，大幅减少 Token 消耗。实测：10,144 → 1,260 Token，且同样能定位到 FATAL 错误。

What it does

功能特性

• Library — compress(messages) in Python or TypeScript, inline in any app
• 库 — 在 Python 或 TypeScript 中使用 compress(messages)，可内嵌于任何应用。
• Proxy — headroom proxy —port 8787, zero code changes, any language
• 代理 — headroom proxy --port 8787，无需修改代码，支持任何编程语言。
• Agent wrap — headroom wrap claude|codex|cursor|aider|copilot in one command
• 智能体封装 — 通过一条命令 headroom wrap 即可封装 Claude、Codex、Cursor、Aider 或 Copilot。
• MCP server — headroom_compress, headroom_retrieve, headroom_stats for any MCP client
• MCP 服务器 — 为任何 MCP 客户端提供 headroom_compress、headroom_retrieve 和 headroom_stats 功能。
• Cross-agent memory — shared store across Claude, Codex, Gemini, auto-dedup
• 跨智能体记忆 — 在 Claude、Codex、Gemini 之间共享存储，并自动去重。
• headroom learn — mines failed sessions, writes corrections to CLAUDE.md / AGENTS.md
• headroom learn — 挖掘失败的会话，并将修正建议写入 CLAUDE.md 或 AGENTS.md。
• Reversible (CCR) — originals never deleted; LLM retrieves on demand
• 可逆 (CCR) — 原始数据永不删除；LLM 可按需检索。

How it works (30 seconds)

工作原理（30 秒速览）

Your agent / app (Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…) 你的智能体 / 应用（Claude Code, Cursor, Codex, LangChain, Agno, Strands，或你自己的代码……） │ prompts · tool outputs · logs · RAG results · files │ 提示词 · 工具输出 · 日志 · RAG 结果 · 文件 ▼ ┌────────────────────────────────────────────────────┐ │ Headroom (runs locally — your data stays here) │ │ ──────────────────────────────────────────────── │ │ CacheAligner → ContentRouter → CCR │ │ ├─ SmartCrusher (JSON) │ │ ├─ CodeCompressor (AST) │ │ └─ Kompress-base (text, HF) │ │ │ │ Cross-agent memory · headroom learn · MCP │ └────────────────────────────────────────────────────┘ │ compressed prompt + retrieval tool ▼ LLM provider (Anthropic · OpenAI · Bedrock · …) LLM 提供商（Anthropic · OpenAI · Bedrock · …）

• ContentRouter — detects content type, selects the right compressor
• ContentRouter — 检测内容类型，选择合适的压缩器。
• SmartCrusher / CodeCompressor / Kompress-base — compress JSON, AST, or prose
• SmartCrusher / CodeCompressor / Kompress-base — 压缩 JSON、AST 或普通文本。
• CacheAligner — stabilizes prefixes so provider KV caches actually hit
• CacheAligner — 稳定前缀，确保提供商的 KV 缓存能够有效命中。
• CCR — stores originals locally; LLM calls headroom_retrieve if it needs them
• CCR — 在本地存储原始数据；LLM 在需要时调用 headroom_retrieve 进行检索。

Get started (60 seconds)

快速上手（60 秒）

1 — Install

1 — 安装

pip install "headroom-ai[all]" # Python npm install headroom-ai # Node / TypeScript

2 — Pick your mode

2 — 选择模式

headroom wrap claude # wrap a coding agent (封装编程智能体) headroom proxy --port 8787 # drop-in proxy, zero code changes (即插即用代理，无需改代码)

or: from headroom import compress # inline library (或：内联库)

3 — See the savings

3 — 查看节省情况

headroom stats

Granular extras: [proxy], [mcp], [ml], [agno], [langchain], [evals]. Requires Python 3.10+. 细分扩展包：[proxy], [mcp], [ml], [agno], [langchain], [evals]。需要 Python 3.10+。

Proof

验证数据

Savings on real agent workloads: 在真实智能体工作负载下的节省情况：

Workload	Before	After	Savings
Code search (100 results)	17,765	1,408	92%
SRE incident debugging	65,694	5,118	92%
GitHub issue triage	54,174	14,761	73%
Codebase exploration	78,502	41,254	47%

Accuracy preserved on standard benchmarks: 在标准基准测试中保持准确性：

Benchmark	Category	N	Baseline	Headroom	Delta
GSM8K	Math	100	0.870	0.870	±0.000
TruthfulQA	Factual	100	0.530	0.560	+0.030
SQuAD v2	QA	100	—	97%	19% compression
BFCL	Tools	100	—	97%	32% compression

Reproduce: python -m headroom.evals suite --tier 1 · Full benchmarks & methodology 复现命令：python -m headroom.evals suite --tier 1 · 查看完整基准测试与方法论。

Agent compatibility matrix

智能体兼容性矩阵

• Claude Code: ● —memory · —code-graph
• Codex: ● shares memory with Claude (与 Claude 共享记忆)
• Cursor: ● prints config — paste once (打印配置 — 粘贴一次即可)
• Aider: ● starts proxy + launches (启动代理并运行)
• Copilot CLI: ● starts proxy + launches (启动代理并运行)
• OpenClaw: ● installs as ContextEngine plugin (作为 ContextEngine 插件安装)

Any OpenAI-compatible client works via headroom proxy. MCP-native: headroom mcp install. 任何兼容 OpenAI 的客户端均可通过 headroom proxy 使用。MCP 原生支持：headroom mcp install。

When to use · When to skip

适用场景 · 不适用场景

Great fit if you… 非常适合：

• run AI coding agents daily and want savings without changing your code
• 每天运行 AI 编程智能体，且希望在不修改代码的情况下节省成本。
• work across multiple agents and want shared memory
• 在多个智能体之间工作，并需要共享记忆。
• need reversible compression — originals always retrievable via CCR
• 需要可逆压缩——原始数据始终可通过 CCR 检索。

Skip it if you… 不适用：

• only use a single provider’s native compaction and don’t need cross-agent memory
• 仅使用单一提供商的原生压缩功能，且不需要跨智能体记忆。
• work in a sandboxed environment where local processes can’t run
• 在无法运行本地进程的沙盒环境中工作。

Integrations — drop Headroom into any stack

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

• Any Python app: compress(messages, model=…)
• Any TypeScript app: 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 guide
• ASGI apps: app.add_middleware(CompressionMiddleware)
• Multi-agent: SharedContext().put / .get
• MCP clients: headroom mcp install