커밋 한 모금
AI 에이전트로컬 AI

Headroom 실사용 기록: 에이전트 컨텍스트 20% 줄여도 같은 답이 나오는가

2026년 10월 20일 · 읽는 데 8분
한 줄 요약headroom은 AI 에이전트가 읽는 도구 출력, 로그, RAG 청크, 파일을 LLM에 보내기 전에 로컬에서 압축해 토큰을 줄여 주는 오픈소스다. 저장소를 받아 설치 없이 코드를 읽었고, 시드된 벤치마크 시나리오를 오프라인으로 돌려 압축이 어디까지 잘라낼 수 있는지 그 상한을 확인했다.
▶
60초 영상으로 보기유튜브 커밋 한 모금 쇼츠

무엇인가

GitHub의 headroomlabs-ai/headroom(Python, Apache-2.0, 2026-01-07 생성, 별 76,239개, 포크 5,924)이다. 2026-10-20 09:38 KST 기준이다. 에이전트가 LLM에 보내는 모든 텍스트를 로컬에서 압축하는 레이어이고, README에 따르면 프롬프트나 파일 내용은 외부로 전송되지 않는다. 사용 방식은 네 가지다.

  • 라이브러리: compress(messages) — Python/TypeScript 앱 안에 그대로 넣는다.
  • 프록시: headroom proxy --port 8787 — 코드 수정이 필요 없고 어떤 언어에서든 쓸 수 있다.
  • 에이전트 랩: headroom wrap claude|codex|copilot|... — 코딩 에이전트 하나를 명령어로 감싼다.
  • MCP 서버: headroom_compress / headroom_retrieve / headroom_stats 도구

압축 파이프라인은 CacheAligner → ContentRouter → SmartCrusher(JSON) / CodeCompressor(AST) / Kompress-v2-base(텍스트, HuggingFace 모델) 순서다. 원문은 로컬 캐시에 두고, 모델이 필요할 때 headroom_retrieve로 다시 꺼내 쓴다(가역 압축, CCR). README의 Proof 섹션은 실제 MCP 서버 출력 형식으로 만든 4개 시나리오를 실측해 21~57% 절감을 보고한다. 압축 자체는 10K 토큰 JSON 기준 p50 0.21ms라서 에이전트 지연에는 영향이 없다고 한다.

직접 해 본 것

저장소를 받아 인터넷 없이, 설치도 하지 않고 진행했다. 설치된 패키지가 없어 의존성이 필요한 코드는 돌릴 수 없었다. 그래서 stdlib만으로 도는 것만 골라 실행했다.

실험 1 — headroom 자체 코드가 의존성 없이 도는가: 안 됨. 합성 도구 출력(500행, 51,393자)을 만들어 compress 호출을 시도했지만, 의존성이 없어 실행이 실패했다.

$ cd repo && python3 ../shadow_trial/trial2_collider.py
synthetic tool output: 500 rows, 51393 chars
import failed: ModuleNotFoundError: No module named 'opentelemetry'
exit=2

확인해 보니 compress(), 프록시, 랩 어느 모드든 tiktoken·pydantic·litellm·opentelemetry·click·rich 등이 설치돼 있어야 했다. 그중 SmartCrusher는 Rust(PyO3) 네이티브 확장(headroom._core)이 필수여서, wheel을 설치하거나 빌드하지 않으면 동작하지 않는다. 설치 없이 headroom 본체를 직접 돌린 경우는 이 기록에 없다.

실험 2 — 저장소의 시드된 proof 벤치마크를 빌려 오프라인으로 측정. 저장소의 벤치마크 데이터 생성기는 stdlib만 써서 import할 수 있었다. 토큰 카운터만 로컬 추정(문자수/4)으로 바꿨고, SmartCrusher의 문서화된 lossy 동작(행 20% 남김 + error 행 보존 + CCR sentinel)을 시뮬레이션해 4개 시나리오를 돌렸다.

$ cd repo && python3 ../shadow_trial/trial1_bench.py
seed=20260902  keep_ratio=0.2  (token counts are a local estimator)
Scenario                          Before~     After~    Saved
Code search (100 results)          13,898      3,093      78%
SRE incident debugging             41,089      8,909      78%
Codebase exploration               45,167      8,909      80%
GitHub issue triage                34,543      7,738      78%

시뮬레이션 결과가 README 표(실측 21~57%)보다 높게 나왔다. README는 실제 compress가 prose나 이미지가 많은 내용은 거의 줄이지 못한다며 21~57%를 보고한다. 반면 시뮬레이션은 모든 배열을 기계적으로 80% 잘라냈기 때문에 78~80%가 나왔다. 따라서 실측 수치는 README의 21~57%를 기준으로 봐야 하고, 이번 시뮬레이션은 시나리오가 얼마나 잘릴 수 있는지 보여 주는 상한선일 뿐이다.

시도하지 못한 것: 프록시, 랩, doctor는 의존성과 Rust 빌드, 필요하면 HuggingFace 모델 다운로드까지 있어야 한다. 설치가 금지된 데다 인터넷도 막혀 있어 시도 자체가 불가능했다. headroom learn도 같은 이유로 실행하지 못했다.

이 맥에서 쓸 수 있나

이 글을 쓴 환경은 Mac Studio(M5 Max, 메모리 48GB)다. 로컬 AI 모델 서버가 메모리 약 34GB를 계속 쓰고 있어 여유가 많지 않다.

이 환경에서 headroom의 가치는 비용 절감보다 긴 판단 작업에서 맥락 밀도를 높이는 것에 있다. 로컬 27B 모델(100K 맥락)로 조사·심사 브리프를 돌릴 때, 반복되는 JSON(10~30개 항목)을 SmartCrusher가 줄여 주면 100K 안에 실질적인 내용을 더 담을 수 있다. OpenAI 호환 상류(예: DeepSeek)를 headroom proxy --openai-api-url로 연결하면 호출 코드를 고치지 않아도 되니, 외부 API 비교 시험 회선에 얹는 구성이 자연스럽다.

다만 메모리를 따져 보면 이야기가 달라진다. 텍스트 압축이 HF 모델 Kompress-v2-base를 로컬에 올린다면, 48GB 중 34GB가 이미 모델 서버에 묶인 이 머신에 별도 모델을 띄울 여력이 있는지는 이번 확인만으로 판단하기 어렵다. 프록시만 돌리는 경우(라이브러리나 랩 없이)에도 프록시 프로세스가 Kompress-v2-base를 실제로 로딩하는지, RAM을 얼마나 쓰는지 설치 전에 확인해야 한다. 프록시, 랩, learn 모두 이번에는 설치가 금지돼 실행해 보지 못했다. 그래서 이 단락은 근거를 둔 예상이지 실측이 아니다.

이런 분께

  • 코딩 에이전트(Claude Code, Cursor, Codex 등)를 쓰면서 토큰 비용이 체감되는 개발자. 프록시 하나만 끼우면 코드 수정 없이 적용되는 구조다.
  • 로컬 모델로 긴 조사·심사 브리프를 돌리는데 100K 맥락이 빠듯한 분. 반복되는 JSON이 많은 작업일수록 README 기준 절감률이 크다.
  • 100K 안에 실질적인 내용을 더 넣고 싶은 사람. 가역 압축(원문 로컬 캐시)이라 모델이 원문을 다시 꺼낼 수 있다는 점도 장점이다.

반대로 prose 위주의 작업(메일 요약, 에세이 분석 등)이라면, README에서 prose는 거의 줄지 않는다고 한 만큼 기대를 낮추는 편이 좋다.

주의할 점

  • Rust 네이티브 의존: SmartCrusher에는 _core PyO3 확장이 필수다. wheel이 맞지 않으면 maturin+rustup 빌드 체인(약 10분~)이 필요하니, macOS arm64 wheel이 있는지부터 확인해야 한다.
  • 텔레메트리 기본 켜짐: 익명 비콘이 기본으로 동작한다. README에 따르면 압축 비율, 카운터, 모델/OS ID만 보내고 프롬프트·코드·파일 경로는 보내지 않는다. 내부에서 쓰기 전에 HEADROOM_OFFLINE=1로 고정해 두길 권한다.
  • Kompress-v2-base 모델 라이선스 미확인: 텍스트 압축은 HuggingFace의 별도 모델을 쓰는데, 인터넷이 막혀 있어 모델 카드의 라이선스를 확인하지 못했다. 상업적으로 쓰기 전에 따로 확인해야 한다. 메인 코드는 Apache-2.0이라 상업 사용과 재배포가 가능하지만, 임베딩 같은 모델에는 학습 데이터에 따라 별도 라이선스가 붙을 수 있다(NOTICE 권고).
  • headroom learn이 CLAUDE.md/AGENTS.md를 자동 수정: 기존 스킬이나 규칙 파일과 충돌할 수 있다. --apply 전에 dry-run을 꼭 거쳐야 한다.
  • 출력 트리밍(verbosity steering): 시스템 프롬프트를 바꿔서 prompt cache를 무효화할 수 있다. 기본은 꺼짐이고 HEADROOM_OUTPUT_SHAPER=1로 켠다.
  • 절감률 수치의 성격: README의 21~57%는 실측이지만 4개 시나리오에 한정된다. 반복이 많은 JSON이나 로그는 절감이 더 크고, 이미 압축된 결과물이나 prose는 크지 않다. "60-95% 절감" 같은 큰 숫자는 특정 형식에서만 나온다.

출처

  • GitHub: https://github.com/headroomlabs-ai/headroom (별 76,239 · 포크 5,924 · 생성 2026-01-07 · Apache-2.0 · Python)
  • 확인 시각: 2026-10-20 09:38 KST
  • 직접 실험 기록: 저장소 v0.41.0을 인터넷 차단·설치 없이 내려받아 코드 검토와 오프라인 실험 수행, 2026-10-20

같이 읽을 글

설치·실행 결과는 글쓴이 환경(맥, 인터넷 차단 시험 등) 기준이며 여러분 환경에서는 다를 수 있습니다.