블로그로 돌아가기
[TUTORIAL]

headroom으로 AI 에이전트 토큰 92% 줄이기 — 컨텍스트 압축 레이어

5분 읽기0 views
#RAG#컨텍스트 엔지니어링#headroom#토큰 절감#Claude Code#컨텍스트 압축#AI 에이전트#LLM#context rot

AI 코딩 에이전트를 쓰다 보면 한 가지가 계속 거슬립니다. 코드 검색 한 번, 로그 한 번 읽었을 뿐인데 토큰이 수만 개씩 빠져나가죠. 비용도 비용이지만, 컨텍스트가 길어질수록 답이 오히려 흐트러지는 경험, 다들 해보셨을 거예요.

오늘 소개할 headroom은 바로 그 지점을 노립니다. AI 에이전트가 LLM에 보내는 모든 걸 도달하기 전에 압축해서, 토큰은 60~95% 줄이면서 답은 그대로 유지한다는 오픈소스 도구예요. GitHub 스타 15,000개를 넘긴 화제의 프로젝트죠.

토큰을 92% 줄였는데 답이 똑같다고요?

headroom이 공개한 실제 에이전트 워크로드 절감 수치부터 볼게요.

  • 코드 검색(결과 100개): 17,765 → 1,408 토큰 (92% 절감)
  • SRE 장애 디버깅: 65,694 → 5,118 토큰 (92%)
  • GitHub 이슈 분류: 54,174 → 14,761 토큰 (73%)

여기서 당연히 의심이 듭니다. "이만큼 줄이면 답 품질도 떨어지는 거 아니야?" headroom은 표준 벤치마크로 답합니다. GSM8K(수학)는 압축 전후 정확도가 0.870으로 완전히 동일했고, TruthfulQA(사실성)는 오히려 0.530 → 0.560으로 소폭 올랐어요. 도구 호출 벤치마크(BFCL)도 32% 압축 상태에서 97% 정확도를 유지했고요.

다만 한 가지는 짚어둘게요. 이 수치들은 headroom이 자체적으로 발표한 벤치마크입니다. 제3자 독립 재현 결과는 아니니, 도입 전엔 본인 워크로드로 직접 python -m headroom.evals suite --tier 1을 돌려 확인하시는 걸 권합니다.

headroom이 정확히 뭔가요 — 붙이는 법 4가지

한 줄로 말하면 "AI 에이전트를 위한 컨텍스트 압축 레이어"예요. 도구 출력, 로그, RAG 검색 결과, 파일, 대화 기록까지 LLM에 보내기 전에 압축합니다. 표어가 딱 이거죠. "Same answers, fraction of the tokens."

도입 장벽이 낮은 게 매력입니다. 붙이는 방법이 4가지예요.

  1. 라이브러리 — 코드 안에서 compress(messages) 호출 (Python·TypeScript)
  2. 프록시 — headroom proxy --port 8787 한 줄. 코드 변경이 0이에요
  3. 에이전트 래핑 — headroom wrap claude 처럼 에이전트를 감싸기 (Codex·Cursor·Aider·Copilot CLI도 지원)
  4. MCP 서버 — headroom_compress / headroom_retrieve / headroom_stats

Claude Code 사용자라면 headroom wrap claude --memory --code-graph 한 줄이면 끝납니다.

왜 단순 비용 절감이 아닐까 — context rot

토큰을 줄이는 게 비용만 아끼는 일이 아니라는 게 핵심입니다.

긴 컨텍스트를 넣을수록 LLM이 오히려 멍청해지는 현상이 있어요. **context rot(컨텍스트 로트)**라고 부릅니다. 컨텍스트 창이 꽉 차지 않았는데도 생기죠. Chroma의 2025년 연구는 GPT-4.1·Claude Opus 4·Gemini 2.5를 포함한 18개 프론티어 모델을 테스트했는데, 측정한 모든 입력 길이 구간에서 전부 이 현상이 나타났습니다.

여기에 lost in the middle도 있어요. 중요한 정보가 맨 앞이나 맨 끝에 있으면 잘 찾지만, 중간에 묻히면 정확도가 30% 넘게 떨어진다는 연구(Liu et al.)죠.

그러니까 도구 출력이나 로그처럼 노이즈가 큰 입력을 줄이는 건, 비용 절감인 동시에 노이즈를 걷어내 품질을 끌어올리는 일이기도 합니다. headroom은 이 두 문제를 토큰 자체를 줄여 동시에 공략합니다.

어떻게 작동하나 — 타입별 압축 + 되돌리기

headroom이 영리한 건 콘텐츠 타입별로 다른 압축기를 쓴다는 점이에요.

  • SmartCrusher — 범용 JSON(딕셔너리 배열·중첩 객체)
  • CodeCompressor — AST를 인식하는 코드 압축 (Python·JS·Go·Rust·Java·C++)
  • Kompress-base — 일반 텍스트용 HuggingFace 모델 (agentic 트레이스로 훈련)
  • CacheAligner — prefix를 안정화해 Anthropic·OpenAI의 KV 캐시 적중률을 높임

그리고 압축이 되돌릴 수 있어요(CCR, Context Compression with Retrieval). 원본은 로컬에 그대로 두고 절대 삭제하지 않으며, LLM이 필요할 때 headroom_retrieve로 다시 불러옵니다. 데이터가 로컬에 머무는 local-first 설계라, 고객 데이터를 다루는 실무에도 부담이 적습니다.

실전 도입 — 그리고 언제 안 써도 되나

설치는 간단합니다.

pip install "headroom-ai[all]"   # Python
npm install headroom-ai          # Node / TypeScript

라이선스는 Apache 2.0, 최신 버전은 v0.23.0(2026-06-04 릴리스)이에요. Python 3.10 이상이면 됩니다.

물론 무조건 도입하라는 얘긴 아닙니다. 공식 문서도 솔직하게 적어놨어요. "단일 provider의 native 압축만 쓰고, 여러 에이전트 간 공유 메모리가 필요 없다면 굳이 안 써도 된다"고요. 또 로컬 프로세스를 띄울 수 없는 샌드박스 환경이라면 맞지 않습니다.

참고로 프롬프트 압축 자체는 새로운 연구 주제는 아니에요. Microsoft의 LLMLingua는 작은 언어 모델로 프롬프트 토큰을 제거해 최대 20배 압축을 달성했고, 한 SaaS 고객지원 사례에서는 월 LLM 비용을 $42,000에서 $2,100으로 줄이기도 했죠. headroom은 여기서 한 걸음 더 나가, 도구 출력·로그·코드를 타입별 알고리즘으로 압축하고, 되돌릴 수 있게 만들고, 라이브러리·프록시·에이전트 래핑·MCP의 4가지 통합 경로를 제공하는 "운영 도구"에 가깝습니다.

마무리

1인 개발자나 AI 자동화를 매일 돌리는 분에게 headroom은 두 가지를 동시에 줍니다. 토큰 비용·지연을 직접 줄여주고, context rot를 완화해 긴 세션에서도 답이 흐트러지지 않게 해주죠. 코드 변경 없이 프록시나 headroom wrap으로 붙일 수 있으니, 부담 없이 본인 워크로드로 한번 측정해 보시길 권합니다.

참고 자료

https://github.com/chopratejas/headroom https://headroom-docs.vercel.app/docs https://redis.io/blog/context-rot/ https://www.understandingai.org/p/context-rot https://www.microsoft.com/en-us/research/blog/llmlingua-innovating-llm-efficiency-with-prompt-compression/