Headroom은 AI 에이전트가 LLM에 보내기 전 도구 출력, 로그, 파일, RAG 청크, 대화 이력을 압축하는 로컬 우선 컨텍스트 레이어다. 라이브러리, 프록시, 에이전트 래퍼, MCP 서버 형태로 제공되며 원문은 로컬 캐시에 남겨 필요할 때 되찾을 수 있다.
핵심 기능
| 기능 | 설명 |
|---|---|
| library | Python/TypeScript에서 compress(messages)로 직접 사용 |
| proxy | 기존 앱 앞에 프록시로 붙여 코드 변경 없이 압축 |
| agent wrap | Claude, Codex, Cursor, OpenCode 등 CLI 에이전트 래핑 |
| MCP | headroom_compress, headroom_retrieve, headroom_stats 제공 |
| cross-agent memory | 여러 에이전트 간 공유 저장소와 중복 제거 |
| reversible compression | 원문을 캐시하고 필요 시 검색·복원 |
압축 방식
Headroom은 콘텐츠 유형을 판별해 JSON, 코드 AST, 일반 텍스트에 다른 압축기를 적용한다. 또한 provider KV cache가 잘 맞도록 prefix를 안정화하는 CacheAligner를 포함한다. 원문 기준 실제 에이전트 workload에서 47~92% 수준의 입력 토큰 절감 사례를 제시한다.
언제 쓰면 좋은가
코딩 에이전트가 rg, 테스트 로그, 대형 JSON, RAG 검색 결과를 반복해서 읽는 환경에 적합하다. 반대로 짧고 정확성이 중요한 법률·재무 원문처럼 압축 손실이 위험한 데이터는 원문 검색과 출처 보존 정책을 함께 둬야 한다.
관련 문서
- context-engineering — 컨텍스트 창을 유한 자원으로 설계하는 방법론
- prompt-compression-tips-agentic-loop-cost — 에이전틱 루프의 토큰 비용 줄이기
- caveman — 출력 토큰을 줄이는 Claude Code 스킬
참고 자료
- headroomlabs-ai/headroom — GitHub 공식 저장소