Headroom

项目简介

Headroom 是一个专为 AI 智能体打造的上下文压缩层，已收获 16000+ Star，采用 Apache-2.0 协议。它坐在你的应用和大模型之间，把智能体读到的一切——工具输出、日志、RAG 检索片段、文件内容、对话历史——在进入大模型之前压掉 60% 到 95% 的 token，答案几乎不变。它的杀手锏是压缩可逆：原文都存在本地，模型需要时可以随时调用工具把完整内容取回来，压缩不等于丢弃。这样既省钱、又降延迟，模型还因为噪声更少而回答更准。

核心特性

• 大幅省 Token — 工具输出、日志、RAG 片段等压缩 60% 到 95%，直接降低成本和延迟
• 可逆压缩 CCR — 原文本地索引永不删除，模型可按需调用工具取回完整内容
• 代理模式零改代码 — 起一个本地 proxy，把客户端地址指过去即可，任何语言通用
• 库模式 — Python / TypeScript 里直接调用 compress 函数，内嵌进任意应用
• 一键包裹智能体 — headroom wrap claude / codex / cursor / aider，自动注入压缩
• MCP 服务器 — 向任意 MCP 客户端提供压缩、取回、统计能力
• 跨智能体记忆 — Claude、Codex、Gemini 之间共享存储，自动去重
• 框架集成丰富 — 支持 LangChain、LiteLLM 等，背后可接 100+ 模型提供商

安装方法

推荐一次装全功能：

pip install "headroom-ai[all]"

最省事的代理模式，零改代码：

headroom proxy --port 8787
# 然后把你的客户端 base URL 指向 http://localhost:8787 即可

也提供 TypeScript / Node.js 版：npm install headroom-ai。

使用场景

• 给 AI 智能体省 token，降低 API 调用成本
• 压缩 RAG 检索结果与长工具输出，提升回答质量
• 用代理模式给 Claude Code、Cursor 等工具透明加压
• LangChain / LiteLLM 应用里内嵌压缩
• 跨多个智能体共享记忆与上下文
• 处理超长日志、文件时避免爆上下文窗口