headroomlabs-ai/headroom

해결하는 문제

AI 에이전트는 도구 출력, 로그, RAG 청크, 파일, 대화 기록 등 많은 컨텍스트를 읽습니다. 그리고 모든 토큰은 비용과 지연 시간을 발생시킵니다. 도구 출력이 많은 긴 에이전트 세션은 모델이 실제로 필요로 하는 것보다 훨씬 많은 토큰을 보내면서도 전체 프롬프트에 대해 비용을 지불하는 경우가 많습니다. Headroom은 컨텍스트가 LLM에 도달하기 전에 축소하여 중요한 부분(예: 오류 줄)을 보존하면서 토큰 사용량을 크게 줄입니다. 압축은 로컬에서 실행되므로 프롬프트나 파일 내용이 머신을 벗어나지 않습니다.

작동 방식

Headroom은 에이전트/앱과 LLM 공급자 사이에 위치합니다. 각 콘텐츠 청크를 검사하고 유형(JSON, 소스 코드, 산문, 이미지)을 감지하여 최상의 압축기를 적용합니다:

• ContentRouter가 압축기를 선택합니다.
• SmartCrusher는 JSON 배열과 중첩 객체를 처리하며 필드 분산에 따라 이상치, 오류 항목, 경계를 유지합니다.
• CodeCompressor는 많은 프로그래밍 언어에 대해 AST를 인식합니다.
• Kompress-v2-base는 산문을 위해 에이전트 추적으로 훈련된 HuggingFace 모델입니다.
• CacheAligner는 프롬프트를 다시 쓰지 않고 공급자의 KV 캐시 접두사를 깨뜨릴 수 있는 휘발성 콘텐츠를 표시합니다.
• CCR(Cache-and-Compress-Reversible)은 원본을 로컬에 저장하여 모델이 headroom_retrieve를 통해 필요할 때 전체 텍스트를 검색할 수 있게 합니다.

압축 후 더 작은 프롬프트와 검색 도구가 LLM으로 전송됩니다. Headroom을 라이브러리(Python/TypeScript의 compress()), 포트의 프록시(코드 변경 없음), 에이전트 래퍼(headroom wrap으로 20개 이상의 에이전트), 또는 MCP 서버로 통합할 수 있습니다. 또한 과거 세션을 읽어 장황함을 조정하는 headroom learn과 시스템 프롬프트에 간결성 메모를 추가하여 모델이 작성하는 내용을 줄이는 출력 토큰 감소 기능도 있습니다.

대상 사용자

매일 코딩 에이전트를 실행하고 코드를 변경하지 않고 토큰 비용을 줄이려는 개발자와 팀. 여러 에이전트(Claude Code, Codex, Cursor 등)를 사용하고 하나의 공유 메모리 저장소를 원하거나 TTL 동안 원본을 검색 가능하게 유지하기 위해 가역 압축이 필요한 경우에 적합합니다. 짧은 대화 교환, 산문 중심 작업 또는 로컬 프로세스를 실행할 수 없는 환경에서는 덜 유용합니다.

주요 특징

• 로컬 압축: 압축을 위해 데이터가 어디로도 전송되지 않습니다.
• 여러 통합 모드: 라이브러리, 프록시, 에이전트 래퍼, MCP, 교차 에이전트 메모리.
• 입증된 절감: 실제 시나리오에서 30~57%(예: 인시던트 디버깅 사례에서 55,957 → 24,340 토큰), 반복적인 JSON/로그에서는 훨씬 더 높은 절감.
• 서브 밀리초 지연 시간(10K 토큰 JSON에서 p50 0.21ms, 100K에서 1.4ms)으로 에이전트 응답성에 영향을 주지 않습니다.
• 정확성 유지: 벤치마크에서 유의미한 저하 없음(예: GSM8K, TruthfulQA, SQuAD v2, BFCL).
• CCR을 통한 가역 압축: 모델이 필요할 때 전체 컨텍스트를 검색할 수 있습니다.
• 출력 토큰 감소: 모델이 작성한 텍스트를 다듬고 측정 가능하거나 추정된 절감을 보고합니다.