Python本月中等

chopratejas/headroom

压缩LLM输入内容，降token成本不影响效果

这是一款专为AI代理打造的上下文压缩工具，可对工具输出、日志、RAG片段等LLM输入内容进行压缩，实现60%-95%的Token缩减且不影响回答准确性，支持库、代理、MCP服务器等多种部署方式。

Stars

20.4k

Forks

1,306

增长

+16.2k（this month）

在 GitHub 打开

Overview

项目介绍

chopratejas/headroom 解决的是压缩LLM输入内容，降token成本不影响效果这类实际需求。作为上下文工具，它的核心是把代码库、文档或运行输出整理成 AI 可以持续引用的上下文，核心价值在于把原本分散的操作沉淀成更稳定的项目能力。

拆开看，压缩率达60-95%，大幅降成本、不改变AI最终回答质量和支持库、代理、服务器多种部署形式构成了这个项目的主要竞争力。它不是追求大而全，而是先把一个具体环节做顺，再让开发者按自己的环境继续改造。

Technical Route

技术路线

headroom 采用本地优先的上下文压缩架构，以 CacheAligner 为前置缓存优化层，通过 ContentRouter 智能匹配对应压缩算法，再经 CCR（可逆压缩机制）存储原始内容，同时提供跨代理共享内存、`headroom learn` 自优化能力，最终以库、代理、MCP 服务器多形态适配不同 AI 代理场景。用户理解此路线可根据自身部署模式选择最优压缩流程，兼顾 Token 成本控制与回答准确性。

1内容路由层：ContentRouter 自动检测输入内容类型，如 JSON、代码、文本，分别匹配 SmartCrusher、CodeCompressor（AST 感知压缩）、Kompress-base（HuggingFace 开源模型）三种算法，实现针对性高效压缩，确保不同场景下的 Token 缩减效果。
2缓存优化层：CacheAligner 对输入前缀进行标准化处理，解决 AI 提供商 KV 缓存命中率低的问题，在压缩基础上进一步降低重复内容的处理成本，同时保证缓存一致性。
3可逆压缩层：CCR（上下文可逆压缩）机制将原始内容本地存储，LLM 可通过 `headroom_retrieve` 命令按需调取，既实现 60%-95% 的 Token 缩减，又避免因压缩丢失关键信息影响回答准确性。
4跨代理内存层：构建跨 Claude、Codex、Gemini 等 AI 代理的共享存储，实现上下文自动去重与复用，支持多代理协作场景下的一致压缩效果，降低整体 Token 消耗。
5自优化学习层：`headroom learn` 命令挖掘失败会话数据，自动生成修正规则写入 `CLAUDE.md` 等文件，持续优化压缩策略，适配不同代理的业务特性与场景需求。
6多形态部署层：支持三种核心部署模式，包括 Python/TypeScript 库的 `compress()` 调用、`headroom proxy` 零侵入代理、MCP 服务器的 `headroom_compress` 等命令，适配从单个应用到多代理集群的不同架构。

Why Trending

为什么它会上榜

结合增长、最近更新与社区关注，给出一个更接近“决策参考”的上榜解读。

社区关注度上升：近期新增 +16237 Stars（this month），讨论热度明显提高。
定位清晰：一款可压缩工具输出、日志、文件等内容的工具，能减少60-95%的token消耗，且不影响AI回答质量，支持多种部署形式

Audience

适合谁

日常使用AI编码代理的独立开发者
需要处理大量日志、文档喂给LLM的运维团队
基于多AI代理搭建工作流的开发团队
关注Token成本控制的LLM应用开发者

Use Cases

能拿来做什么

开发者用AI分析大量日志时降成本
企业部署AI应用时优化输入成本

Quick Start

怎么开始

请看仓库README的安装章节

Watchouts

使用前注意事项

Windows系统下GitHub Copilot CLI的凭证管理器功能尚未经过充分验证，建议手动传入`GITHUB_COPILOT_TOKEN`
仅支持Python 3.10及以上版本，低版本环境需先升级Python才能安装使用
作为本地运行工具，若在沙盒化环境中部署可能会因权限限制无法正常运行