Headroom, LLM 도달 전 도구 출력·로그를 로컬에서 압축하는 오픈소스 계층
Apache 2.0 라이선스의 Headroom은 도구 출력·로그·파일·RAG 청크를 LLM 전송 전에 로컬에서 압축하는 라이브러리·프록시·MCP 서버이며, 절감률은 페이로드의 반복도에 따라 달라진다.
이미지 출처: https://github.com/headroomlabs-ai/headroom
구성: 라이브러리·프록시·MCP
Headroom은 AI 에이전트가 읽는 도구 출력, 로그, RAG 청크, 파일, 대화 기록을 LLM에 도달하기 전에 압축한다고 README는 밝힌다. 압축은 사용자 기기에서 실행되며, 압축을 위해 프롬프트나 파일 내용을 외부로 보내지 않는다고 설명한다. 사용 방식은 Python·TypeScript 라이브러리(compress), 프록시(headroom proxy), 에이전트 wrap, MCP 서버 네 가지다. ContentRouter가 콘텐츠 유형을 판별해 JSON은 SmartCrusher, 소스 코드는 CodeCompressor, 산문은 Kompress-v2-base로 보낸다. CacheAligner는 프롬프트를 다시 쓰지 않고 프로바이더 KV 캐시 접두사를 깨뜨릴 수 있는 변동 콘텐츠만 표시한다.
공개된 절감 수치와 측정 조건
README의 표는 실제 MCP 서버 출력 형식으로 만든 네 시나리오를 프로바이더 토크나이저와 배포된 compress()로 측정한 결과이며, 시드가 고정된 오프라인 실행이라 같은 수치가 재현된다고 밝힌다. 코드 검색 100건은 17,199에서 13,597토큰으로 21%, SRE 장애 디버깅은 55,957에서 24,340토큰으로 57%, 코드베이스 탐색은 58,801에서 33,895토큰으로 42%, GitHub 이슈 분류는 46,067에서 32,429토큰으로 30% 줄었다. README는 절감 폭이 페이로드의 반복 정도에 비례한다고 덧붙인다. 반복되는 JSON 배열과 로그 줄은 별도 벤치마크에서 90%를 넘겼고, 산문과 이미 밀도가 높은 출력은 거의 압축되지 않는다. 실제 적용 수치는 headroom savings로 자체 트래픽에서 확인하라고 안내한다.
정확도와 복원
정확도는 python -m headroom.evals suite --tier 1 결과로 제시된다. GSM8K는 100문항 기준 0.870에서 0.870으로 변동이 없었고(±0.000), SQuAD v2는 19% 압축에서 97%, BFCL은 32% 압축에서 97%를 기록했다. TruthfulQA는 0.530에서 0.560으로 +0.030이었지만, README는 N=100에서 ±0.03이 신뢰구간 안에 들어가므로 개선이 아니라 검출 가능한 차이가 없는 것으로 본다고 적는다. 압축 비용은 10K 토큰 JSON 검색 결과에서 p50 0.21ms, 100K 토큰에서 1.4ms로 제시된다. 원문은 로컬 캐시에 보관되어 필요할 때 headroom_retrieve로 되돌릴 수 있으며, 프로젝트는 Apache License 2.0으로 배포된다.