Headroom
Headroom 是面向 LLM 应用的上下文优化层，可在工具输出、数据库结果、文件读取、日志、RAG 检索结果和 API 响应到达模型前进行压缩，在保持回答质量的同时减少 token；可作为库、代理或 MCP 服务器使用，压缩在本地运行并支持可逆恢复。
访问 headroomlabs-ai/headroom项目简介
Headroom 是面向 LLM 应用的上下文优化层。它会在工具输出、数据库结果、文件读取、RAG 检索结果、API 响应、日志和对话历史到达模型前进行压缩，让模型看到的噪声更少。压缩在本地运行，压缩后的内容可通过本地 CCR 存储进行可逆恢复。
核心功能
- 可逆压缩（CCR）在本地保存原始内容，并向模型提供 headroom_retrieve 工具以按需获取完整细节。智能内容检测可将 JSON、源代码、日志、文本、差异和 HTML 路由到合适的压缩器，无需配置。SmartCrusher 通过统计分析保留 JSON 工具输出中的错误、异常以及首尾边界。Headroom 可作为透明代理、Python 或 TypeScript 库、智能体包装器或 MCP 服务器使用。缓存优化会稳定前缀以帮助命中提供方 KV 缓存，并跟踪冻结消息以保留缓存读取折扣。持久化记忆采用用户、会话、代理和轮次级层次化作用域，后端使用
适用场景
- 在将工具输出、日志、数据库读取、RAG 结果、文件读取和 API 响应发送给 LLM 前减少 token。在 SRE 事故排查中压缩大量以例行内容为主的工具输出，同时保留关键错误。在代码库探索和 GitHub 问题分诊中压缩上下文。通过 SharedContext 在不同智能体和框架之间共享压缩后的上下文。
快速开始
- 使用 uv tool install --python 3.13 "headroom-ai[all]" 或 pip install "headroom-ai[all]" 安装 Python 包；使用 npm install headroom-ai 安装 TypeScript SDK。可选择 headroom deploy 进行本地部署，使用 headroom wrap claude 包装编码智能体，使用 headroom proxy --port 8787 启动即插即用代理，或以内联 Python 库方式使用。运行 headroom doctor
部署与要求
- 压缩在你的机器上本地运行，不会将提示或文件内容发送到外部进行压缩。headroom CLI 仅随 PyPI 包提供；npm 的 headroom-ai 包是 TypeScript SDK，不提供 headroom 命令。文档提供 Docker 原生安装方式。本地代理可运行在 8787 端口。
采用前须知
- 许可证：Apache-2.0。在使用、修改或分发项目前，请确认其具体条款。
