AI 에이전트를 실제로 써본 사람이라면 한 번쯤 이런 경험을 했을 거다. Claude Code나 Codex로 코드베이스 분석을 시키는데, 툴 출력 결과 하나에만 토큰이 수천 개 쏟아지고 — 조금 지나면 컨텍스트가 꽉 차서 에이전트가 이상한 소리를 하기 시작한다. 결국 세션을 다시 시작하거나, 직접 프롬프트를 잘라내거나. 왜 이렇게 됐냐고 물어보면 대부분 "컨텍스트 윈도우가 작아서"라고 하는데, 진짜 문제는 따로 있다. LLM한테 필요도 없는 정보를 너무 많이 먹이고 있다는 거다.
headroom은 이 문제에 정면으로 달려드는 프로젝트다. GitHub 스타 6,300개, 포크 445개. 몇 주 전에 알게 됐는데 생각보다 훨씬 잘 만들어져 있어서 정리해봤다.
headroom이 하는 일
한 줄 요약하면 — 에이전트가 LLM한테 보내는 걸 압축해주는 미들웨어다. 툴 출력, 로그, RAG 청크, 파일 내용, 대화 히스토리 전부.
실제 벤치마크 수치를 보면 이게 마케팅이 아니라는 걸 알 수 있다:
코드 검색 결과 100개: 17,765 → 1,408 토큰 (92% 절감)
SRE 인시던트 디버깅: 65,694 → 5,118 토큰 (92% 절감)
GitHub 이슈 트리아지: 54,174 → 14,761 토큰 (73% 절감)
정확도도 같이 확인했다. GSM8K(수학) 기준 압축 전후 정확도 차이가 ±0.000이고, BFCL(툴 콜링) 기준 32% 압축에서 97% 정확도. 이게 가능한 이유가 있다. 단순히 토큰을 자르는 게 아니라, 실제로 LLM이 필요한 정보를 식별해서 나머지를 버리는 방식이기 때문이다.
내부 구조가 꽤 흥미롭다
headroom이 단순 텍스트 트리밍 도구가 아닌 이유는 컨텐츠 타입을 구분해서 각각 다른 압축기를 쓴다는 데 있다.
ContentRouter — 들어오는 내용이 JSON인지, 코드인지, 일반 텍스트인지 판단하고 적절한 압축기로 라우팅한다.
SmartCrusher — JSON과 구조화된 데이터 전용. 중첩 객체, 배열, 혼합 타입을 다 처리한다.
CodeCompressor — AST(추상 구문 트리) 기반. Python, JS, Go, Rust, Java, C++ 지원. 코드의 의미 구조를 이해하고 압축하기 때문에 단순 텍스트 압축보다 훨씬 안전하다.
Kompress-base — 일반 텍스트용 커스텀 HuggingFace 모델. 에이전트 트레이스 데이터로 학습됐다. LLMLingua처럼 별도의 로컬 LLM이 필요하지 않다.
CacheAligner — 프롬프트 프리픽스를 안정화해서 LLM 프로바이더의 KV 캐시 히트율을 높인다. 같은 컨텍스트를 반복 사용하는 에이전트 루프에서 실질적인 비용 절감이 된다.
CCR (Compressed-Context Retrieval) — 원본을 로컬에 저장해두고, LLM이 필요하면 headroom_retrieve 툴로 다시 가져올 수 있다. 압축이 되돌릴 수 없는 정보 손실이 아니라는 게 핵심이다.
설치와 사용 — 진입 장벽이 낮다
여러 배포 방식을 지원하는데, 가장 빠른 건 에이전트 래핑이다:
pip install "headroom-ai[all]"
headroom wrap claude # Claude Code 바로 연결
headroom wrap codex # Codex도 동일
기존 코드를 건드리기 싫으면 프록시 모드가 있다:
headroom proxy --port 8787 # OpenAI 호환 프록시, 코드 변경 없음
Python 코드에 직접 붙이는 것도 간단하다:
from headroom import compress
compress(messages, model=...)
LangChain, LiteLLM, Vercel AI SDK, Agno 등 주요 프레임워크 통합도 다 있다. Python 3.10+, 라이선스는 Apache 2.0.
MCP 서버로도 쓸 수 있다
headroom은 MCP 서버 모드를 지원한다. headroom_compress, headroom_retrieve, headroom_stats 세 가지 툴을 제공해서, Claude나 Cursor 같은 MCP 클라이언트가 직접 호출할 수 있다.
headroom mcp install # 끝
MCP 생태계에서 메모리/컨텍스트 관련 서버들을 비교해보면:
공식 MCP Memory Server (Anthropic) — 엔티티-릴레이션 기반 지식 그래프 메모리. 정보를 '저장하고 검색'하는 구조라서 headroom의 '압축'과는 다른 문제를 푼다. modelcontextprotocol/servers 레포(⭐86.6k)에 포함.
mem0 MCP Server — 대화에서 사실을 추출해 벡터/그래프 DB에 저장, 세션 간 메모리 유지. headroom과 상호 보완적으로 같이 쓸 수 있다.
압축을 해주는 MCP 서버는 현재 headroom이 유일하다고 봐도 된다.
비슷한 도구들이랑 뭐가 다른가
가장 자주 비교되는 건 Microsoft의 LLMLingua다. 둘 다 토큰 압축을 목표로 하지만 접근이 다르다. LLMLingua는 소형 LLM(Llama-2-7B)을 써서 토큰 퍼플렉시티를 계산하고 중요도 낮은 토큰을 제거한다. 학술 논문 기반(EMNLP 2023, ACL 2024)으로 잘 연구된 방식인데, 압축기 자체가 로컬 LLM을 필요로 한다는 게 실용적인 허들이다. 에이전트 래핑이나 프록시 모드, MCP 서버도 없다.
Letta(구 MemGPT)나 LangChain Memory 같은 메모리 프레임워크들은 사실 다른 문제를 푼다. 이쪽은 '세션 간 기억을 어떻게 유지할 것인가'가 핵심인데, headroom은 '지금 이 턴에 LLM한테 보내는 내용을 어떻게 줄일 것인가'에 집중한다. 상충하는 게 아니라 보완적이다.
headroom의 실질적인 차별점은 세 가지다. 첫째, 컨텐츠 타입별 압축기 — JSON을 텍스트처럼, 코드를 텍스트처럼 압축하지 않는다. 둘째, CCR 가역 압축 — 원본이 로컬에 살아있어서 필요하면 되찾을 수 있다. 셋째, 크로스 에이전트 공유 메모리 — Claude, Codex, Gemini가 같은 메모리 스토어를 쓸 수 있다.
headroom learn — 실패에서 배우는 기능
개인적으로 재밌다고 생각한 기능이 headroom learn이다. 에이전트 세션에서 실패한 케이스들을 자동으로 마이닝해서 CLAUDE.md, AGENTS.md, GEMINI.md 같은 지침 파일에 수정사항을 기록해준다. 다음 세션에서 같은 실수를 반복하지 않도록 에이전트 자체를 점진적으로 개선하는 구조다. 아직 실험적인 기능이겠지만 방향성이 맞다.
써볼 만한가
현재 버전 0.22.3, 커밋 1,389개, 브랜치 163개. 리포 상태를 보면 상당히 활발하게 개발되고 있다. 오픈 이슈 75개, PR 55개는 사용자가 많다는 신호이기도 하다.
Claude Code나 Codex로 큰 코드베이스 작업을 자주 하는 사람이라면 headroom wrap으로 감싸는 것만으로 토큰 비용이 꽤 줄어들 수 있다. 라이브 데모에서 10,144 → 1,260 토큰으로 줄어든 채로 동일한 버그를 찾아냈다는 수치가 허황된 느낌이 아니다.
단, Kompress-base ML 모델 없이 쓰려면 headroom-ai[proxy] 같은 세부 패키지를 쓰면 된다. 모든 기능이 다 필요한 게 아니라면 [all] 대신 필요한 것만 설치하는 게 낫다.
📎 참고 링크: headroom GitHub | headroom 문서 | LLMLingua (Microsoft) | Letta (MemGPT) | 공식 MCP Memory Server | mem0
