headroom: 콘텐츠 인식 압축기와 로컬 프록시를 통해 AI 에이전트의 LLM 토큰 사용량을 줄이는 컨텍스트 압축 레이어

해결하는 문제

Headroom은 LLM에 전송되고 LLM으로부터 수신되는 토큰 수를 줄여 AI 에이전트의 비용과 지연 시간을 크게 낮춥니다. 반복적인 도구 출력, 장황한 로그, RAG 청크, 중복된 모델 프리앰블 등 에이전트 작업에서 발생하는 "낭비"를 목표로 하면서 모델 답변의 정확성은 유지합니다.

작동 방식

Headroom은 AI 에이전트와 LLM 제공자 사이에 위치하는 로컬 압축 레이어로 동작합니다. ContentRouter를 사용해 데이터 유형을 감지하고 가장 효율적인 압축기를 적용합니다:

• SmartCrusher: JSON 데이터용.
• CodeCompressor: 여러 프로그래밍 언어에 대한 AST 인식 압축.
• Kompress-v2-base: 산문/텍스트 전용 HuggingFace 모델.

Headroom은 **CCR (Reversible Compression)**을 제공하여 원본 콘텐츠를 로컬에 캐시하고, 필요 시 LLM이 도구 호출을 통해 전체 버전을 가져올 수 있게 합니다. 또한 CacheAligner를 포함해 프롬프트 접두사가 제공자 KV 캐시와 안정적으로 유지되도록 합니다. 출력 비용을 줄이기 위해 과잉 표현 제어와 노력 라우팅을 사용해 불필요한 모델 응답을 다듬습니다.

대상 사용자

• 매일 AI 코딩 에이전트(예: Claude Code, Cursor, Aider, Cline)를 운영하는 개발자.
• 여러 종류의 AI 에이전트를 사용하고 공유 메모리 저장소를 원하는 팀.
• 라이브러리나 프록시를 통해 Python 또는 TypeScript 애플리케이션에 토큰 압축을 통합하고자 하는 애플리케이션 개발자.

주요 특징

• 다중 통합 모드: Python/TypeScript 라이브러리, 즉시 사용 가능한 프록시, MCP 서버 중 선택 가능.
• 에이전트 래핑: 인기 에이전트를 위한 원-커맨드 래핑(e.g., headroom wrap claude).
• 출력 감소: 모델 프리앰블을 정리하고 일상적인 단계에서 "생각" 노력을 줄여 출력 토큰을 절감.
• 크로스-에이전트 메모리: 서로 다른 LLM 제공자 간에 공유되고 자동 중복 제거되는 메모리.
• 실패 마이닝: headroom learn 명령으로 실패한 세션을 분석해 에이전트 설정 파일에 교정 내용을 작성.

요약

콘텐츠 인식 압축과 출력 형태 조정을 통해 토큰 사용량을 60-95% 감소시키면서 정확성을 유지하는 AI 에이전트를 위한 컨텍스트 압축 레이어.

제목

headroom: 콘텐츠 인식 압축기와 로컬 프록시를 통해 AI 에이전트의 LLM 토큰 사용량을 줄이는 컨텍스트 압축 레이어