headroomlabs-ai/headroom

解决的问题

Headroom 通过减少发送给和从大型语言模型（LLM）接收的令牌数量，降低 AI 代理的成本并减少延迟。它特别针对工具输出、日志、RAG 块和对话历史中常见的“仪式性”和重复性数据，这些数据常常导致代理提示膨胀。

工作原理

Headroom 作为一个位于 AI 代理和 LLM 提供商之间的本地压缩层。它使用 ContentRouter 检测数据类型并应用适当的压缩方法：

• SmartCrusher：利用统计方差处理 JSON 数据，保留关键信息的同时去除冗余。
• CodeCompressor：利用抽象语法树（AST）感知能力，压缩多种语言的源代码。
• CodeCompressor：使用在代理轨迹上训练的专用 HuggingFace 模型（Kompress-v2-base）压缩文本。
• CCR（可逆压缩）：将原始内容本地存储，必要时可通过工具调用检索完整文本。
• CacheAligner：确保易变内容不会破坏提供方的 KV 缓存前缀，保持缓存命中率。

它可以作为库（Python/TypeScript）、无需代码更改的即插即用代理，或用于流行代理（如 Claude Code、Cursor、Aider）的包装器部署。

适用人群

每天使用代码代理的开发者和高级用户，跨多个不同 AI 代理工作并希望拥有共享内存存储的用户，以及希望在不牺牲准确性的前提下降低 LLM API 成本的任何人。

主要亮点

• 多模态压缩：针对 JSON、代码和文本的专用压缩器。
• 代理包装：通过单命令 headroom wrap 快速配置大量 AI 代理和 IDE 扩展。
• 输出令牌减少：通过引导模型减少冗余表达并调整常规任务的推理努力，缩短模型响应。
• 跨代理记忆：在不同 LLM 提供方之间共享、去重的上下文存储。
• headroom learn：分析失败会话，自动将修正写入代理配置文件。
• 本地执行：所有压缩均在用户设备上完成；压缩过程中不会将数据发送到外部服务器。