headroomlabs-ai/headroom

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

해결하는 문제

Headroom은 LLM으로 전송되거나 LLM으로부터 수신되는 토큰 수를 줄이기 위해 설계된 컨텍스트 압축 레이어입니다. 도구 출력, 로그, RAG 청크, 파일 및 대화 기록을 압축하여 AI 에이전트의 높은 비용과 토큰 제한 문제를 해결하며, 정확도를 유지하면서도 JSON의 경우 60-95%, 코딩 에이전트의 경우 15-20%의 토큰 절감 효과를 제공합니다.

작동 방식

Headroom은 AI 에이전트와 LLM 제공자 사이에 위치하는 로컬 우선 프록시, 라이브러리 또는 MCP 서버로 작동합니다. ContentRouter를 사용하여 콘텐츠 유형을 감지하고 특정 압축기를 적용합니다:

SmartCrusher: JSON 데이터용.
CodeCompressor: 다양한 프로그래밍 언어에 대한 AST 인식 압축.
Kompress-v2-base: 산문/텍스트를 위한 특화된 HuggingFace 모델.
CacheAligner: 제공자의 KV 캐시 히트율을 최대화하기 위해 접두사(prefix)가 안정적으로 유지되도록 합니다.
CCR (Reversible Compression): 원본 콘텐츠를 로컬에 캐시하여, 필요한 경우 LLM이 도구 호출을 통해 전체 버전을 검색할 수 있도록 합니다.

또한 모델이 간결하게 답변하도록 유도하고 일상적인 단계의 추론 노력을 조정하여 출력 토큰을 줄입니다.

대상 사용자

비용과 지연 시간을 낮추고자 하는 AI 코딩 에이전트(Claude Code, Cursor, Aider 등) 사용자.
서로 다른 LLM 간에 공유되고 중복이 제거된 메모리가 필요한 멀티 에이전트 워크플로우를 구축하는 팀.
Python 또는 TypeScript SDK를 통해 LLM 애플리케이션을 통합하는 개발자.

주요 특징

다양한 배포 모드: 드롭인 프록시, 인라인 라이브러리 또는 MCP 서버로 사용 가능.
에이전트 래핑: 다양한 에이전트(예: Claude Code, Copilot CLI, Grok)를 한 번의 명령으로 래핑.
출력 감소: 모델의 서문을 다듬고 추론 노력을 조정하여 값비싼 출력 토큰을 절약.
교차 에이전트 메모리: Gemini, Grok, Claude와 같은 다양한 제공자 간에 작동하는 공유 컨텍스트 저장소.
실패 마이닝: headroom learn 명령이 실패한 세션을 분석하여 에이전트 설정 파일에 수정 사항을 기록합니다.