headroom

Headroom是为AI代理设计的上下文压缩层，可在内容抵达大语言模型（LLM）前，对工具输出、日志、RAG片段、文件及对话历史进行压缩，目标是在保留答案完整性的同时减少令牌使用量。所有压缩操作均在本地完成，提示词与文件内容不会被发送至外部服务。 功能特性包括： - 库支持：提供Python或TypeScript中的`compress(messages)`函数，可直接嵌入任意应用。 - 代理模式：通过`headroom proxy --port 8787`启动本地代理，无需修改代码，兼容任何OpenAI兼容客户端。 - 代理封装：`headroom wrap`支持Claude Code、Codex、Grok CLI、Cursor、Aider、Copilot CLI、VS Code Copilot、OpenClaw、OpenCode、Cline、Continue、Goose、OpenHands、Mistral Vibe、Oh My Pi、Kimi CLI、ZCode等工具；`headroom unwrap`可还原原始配置。 - MCP服务器：暴露`headroom_compress`、`headroom_retrieve`和`headroom_stats`工具，供任意MCP客户端调用。 - 跨代理内存：在Claude、Codex、Gemini和Grok间共享并去重的存储系统。 - `headroom learn`：自动挖掘失败会话，将修正内容写入`CLAUDE.local.md`（默认，被git忽略）或其他代理指令文件。 - 输出令牌优化：支持代理端的冗余控制与努力路由，减少模型返回的令牌，而不仅限于输入。 - 可逆压缩（CCR）：原始内容本地缓存，可通过`headroom_retrieve`按需恢复。 工作原理：ContentRouter识别内容类型并选择适配压缩器——JSON使用SmartCrusher，代码（支持Python、JS/TS、Go、Rust、Java、C/C++、Perl）使用AST感知的CodeCompressor，文本则使用基于代理轨迹训练的Hugging Face模型Kompress-v2-base。CacheAligner识别易变内容，避免破坏提供商KV缓存前缀，通过live-zone压缩保持前缀字节完全一致，确保缓存有效。提供针对Anthropic/OpenAI SDK、Vercel AI SDK、LiteLLM、LangChain、Agno、Strands、ASGI应用和多代理SharedContext的框架适配器。 README中报告的离线基准测试显示：代码搜索节省21%，SRE故障调试节省57%，代码库探索节省42%，GitHub问题分类节省30%，重复的JSON/日志负载压缩率可达90%。在10K令牌下，压缩延迟低于1毫秒。准确性评估显示，在GSM8K和TruthfulQA上无明显差异，在SQuAD v2和BFCL上以19–32%压缩率实现97%准确率。 安装方式：`uv tool install --python 3.13 "headroom-ai[all]"`、`pip install "headroom-ai[all]"`、`npm install headroom-ai`（仅TypeScript SDK，无CLI），或使用Docker镜像`ghcr.io/headroomlabs-ai/headroom`。要求Python 3.10+，采用Apache 2.0许可证。可选模块包括`[proxy]`、`[mcp]`、`[ml]`、`[code]`、`[memory]`、`[vector]`、`[image]`及各框架适配器。