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에 보내기 전 에이전트 입력을 압축하는 라이브러리·프록시·MCP 서버
Headroom은 코딩 에이전트의 도구 출력, 로그, 파일, RAG 결과를 로컬에서 압축해 LLM에 전달하는 오픈소스 도구입니다. 프로젝트가 공개한 오프라인 벤치마크에서는 시나리오별 토큰을 21~57% 줄였으며, 라이브러리·프록시·MCP 서버 방식으로 통합합니다.
- 주제
에디터 노트
공개된 결과는 압축이 유리한 입력과 그렇지 않은 입력을 구분해 제시합니다. 네 가지 오프라인 시나리오에서 21~57%를 절감했지만 프로젝트도 반복되는 JSON과 로그에서 효과가 크고 일반 문장에서는 작다고 설명합니다. 따라서 20% 이상 절감이라는 제목의 수치는 모든 입력에 적용되는 보장이 아니라 특정 에이전트 작업에서 나온 결과로 읽어야 합니다. 정확도 표도 제한을 드러냅니다. TruthfulQA의 0.03 차이는 표본 100개에서 유의한 개선으로 볼 수 없다고 프로젝트가 밝혔고, 나머지 두 평가 수치에는 비교 기준선이 제시되지 않았습니다. 원문 저장과 로컬 압축은 데이터 처리 경로를 설명하지만 익명 텔레메트리는 기본 활성화입니다. 텔레메트리에서 전송하는 항목과 비활성화 방법을 함께 밝힌 점은 투명하지만, 도입 시에는 로컬 처리 여부와 별도로 텔레메트리 설정도 확인해야 합니다.
AI 요약
Headroom은 에이전트가 읽는 도구 출력, 로그, 파일, RAG 청크와 대화 기록을 압축해 모델에 전달합니다. 처리는 로컬에서 이뤄지고, 원본은 로컬 캐시에 보관해 필요할 때 CCR(Compression, Cache, Retrieval)로 다시 가져옵니다. Python·TypeScript 라이브러리로 앱에 넣거나, 로컬 프록시로 기존 클라이언트의 요청을 라우팅하거나, MCP 서버로 연결할 수 있습니다. 에이전트 래퍼는 프록시와 설정을 구성한 뒤 Claude Code, Codex 등 도구를 실행합니다.
콘텐츠별 압축과 캐시 처리
ContentRouter가 입력 종류를 감지해 JSON에는 SmartCrusher, 소스 코드에는 AST 기반 CodeCompressor, 일반 텍스트에는 Hugging Face 모델 Kompress-v2-base를 선택합니다. SmartCrusher는 필드 통계에 따라 JSON의 대표 항목을 남기며 오류 항목과 통계적으로 드문 값, 배열의 처음과 끝을 보존한다고 설명합니다. CodeCompressor는 Python, JavaScript·TypeScript, Go, Rust 등 여러 언어를 지원합니다.
CacheAligner는 제공자 KV 캐시의 접두부를 깨뜨릴 수 있는 변동 콘텐츠를 표시하지만 프롬프트를 다시 쓰지는 않습니다. Live-zone 압축은 새 도구 출력과 최신 턴만 처리하고 고정된 이전 접두부는 바이트 단위로 유지합니다. 압축 전 원문은 CCR이 보관하며 모델이 headroom_retrieve 도구를 호출해 원문을 요청합니다.
공개된 절감량과 정확도
프로젝트는 실제 MCP 서버 출력 형식을 본뜬 네 가지 시나리오를 오프라인에서 측정했습니다. 코드 검색은 17,199토큰에서 13,597토큰으로 21%, SRE 장애 분석은 55,957에서 24,340으로 57%, 코드베이스 탐색은 58,801에서 33,895로 42%, GitHub 이슈 분류는 46,067에서 32,429로 30% 줄었습니다. 프로젝트는 반복되는 JSON 배열과 로그에서 절감 폭이 커지고, 일반 문장이나 이미 압축된 입력에서는 작다고 안내합니다. 10K 토큰 JSON 검색 결과의 압축 시간은 p50 0.21밀리초, 100K 토큰에서는 1.4밀리초라고 공개했습니다.
정확도 평가에서 GSM8K는 기준선과 Headroom 모두 0.870이었고, TruthfulQA는 0.530과 0.560이었습니다. 표본은 각각 100개이며 프로젝트는 TruthfulQA의 0.03 차이가 신뢰구간 안에 있어 개선으로 볼 수 없다고 명시합니다. SQuAD v2는 19% 압축에서 97%, BFCL은 32% 압축에서 97%를 기록했습니다.
모델 출력 제어와 운영 범위
Headroom은 입력뿐 아니라 모델 출력도 줄이는 기능을 제공합니다. 시스템 프롬프트 끝에 간결한 답변을 유도하는 문구를 덧붙이고, 도구 결과 뒤에 이어지는 턴에서만 추론 강도를 낮춥니다. 이 기능은 기본적으로 꺼져 있습니다. 출력 절감량은 실제 답변과 반사실적 답변을 비교할 수 없어 추정치와 신뢰구간으로 표시합니다. 대화의 10%를 미적용 대조군으로 두면 측정값을 얻는 방식도 안내합니다.
짧은 대화, 일반 문장, 정보 밀도가 높은 입력에서는 절감량이 작거나 없을 수 있습니다. 설정한 최소 단어 수보다 짧은 블록은 그대로 반환합니다. 익명 텔레메트리는 기본 활성화이며 압축 비율, 제공자·모델 ID, 운영체제와 아키텍처를 전송한다고 밝힙니다. 프롬프트, 완성된 답변, 코드, 파일 경로는 보내지 않으며 환경 변수로 끌 수 있습니다. 저장소 코드는 Apache 2.0 라이선스입니다.
원문: GitHub / 번역·요약: Trawling