요즘 AI 코딩 에이전트(Claude Code, Cursor, Codex 같은 것들)는 일을 하면서 엄청난 양의 텍스트를 LLM에게 먹입니다. 파일을 통째로 읽고, 터미널 명령 결과를 그대로 붙이고, 검색 결과 100개를 쏟아붓죠. 문제는 이 텍스트의 상당 부분이 반복·여백·중복 구조로 채워진 군더더기라는 점입니다. LLM은 그걸 다 "읽고" 그만큼 돈을 받습니다.
옷(정보)은 그대로인데 부피(토큰)만 확 줄어듭니다. Headroom은 에이전트가 LLM에게 짐을 부치기 직전, 그 사이에 끼어들어 압축팩처럼 눌러줍니다. 도착하면 LLM은 같은 옷을 받고, 당신은 더 적은 수하물 요금(API 비용)을 냅니다. 그리고 누른 짐의 원본은 창고에 그대로 보관돼 있어서, LLM이 "그 디테일 다시 보여줘"라고 하면 즉시 꺼내줍니다.
구체적인 숫자로 보면 감이 옵니다. 코드 검색 결과 100건이 원래 17,765 토큰이었는데 압축 후 1,408 토큰(92% 절감)이 됩니다. 장애 대응 로그는 65,694 → 5,118 토큰. 같은 질문, 같은 답, 비용만 1/10. Headroom 측은 커뮤니티 누적으로 600억 토큰 이상을 절약했다고 집계합니다.
2026년 AI 에이전트가 폭발하면서 가장 아픈 곳이 토큰 비용과 문맥 한계가 됐습니다. 에이전트를 하루 종일 돌리면 같은 코드베이스를 수십 번 다시 읽고, 그때마다 비용이 붙죠. 그래서 "문맥 최적화(context engineering)"가 뜨거운 주제가 됐고, Headroom은 그 흐름 한복판에 있습니다. 단순히 텍스트를 자르는 게 아니라, JSON·코드·로그·산문을 각각 다른 방식으로 똑똑하게 압축한다는 게 차별점입니다.
경쟁 도구들과 비교하면 Headroom의 포지션이 분명해집니다.
| 도구 | 압축 범위 | 로컬 실행 / 가역 |
|---|---|---|
| Headroom | 도구결과·RAG·로그·파일·대화 등 전부 | 예 / 예 |
| RTK | CLI 명령 출력만 | 예 / 아니오 |
| lean-ctx | CLI·MCP 도구·에디터 규칙 | 예 / 아니오 |
| Compresr 등 (호스팅 API) | 그들 API로 보낸 텍스트 | 아니오 / 아니오 |
| OpenAI Compaction | 대화 기록만 | 아니오(프로바이더 내장) / 아니오 |
무지성으로 뒷부분을 잘라내면(truncation) 정작 중요한 에러 메시지가 통째로 날아가거나, JSON이 깨져서 LLM이 파싱을 못 합니다. 단순 자르기는 비용은 줄여도 정답률을 떨어뜨립니다.
JSON 배열은 반복 구조를 접고, 코드는 문법 트리(AST)를 살려 핵심만 남기고, 로그는 중복 줄을 묶습니다. 벤치마크에서 GSM8K(수학) 정답률은 압축 전후 변화 0.000, TruthfulQA는 오히려 +0.030. "답은 그대로, 토큰만 절감"이 마케팅 구호가 아니라 측정값이라는 게 신뢰를 얻은 이유입니다.
마지막 한 방은 도입 장벽이 0에 가깝다는 점입니다. headroom proxy --port 8787 한 줄이면 코드를 한 글자도 안 고치고, 어떤 언어의 앱이든 그 앞에 압축 레이어가 생깁니다. Python/TypeScript 라이브러리로 인라인 호출도 되고, MCP 서버로 붙이면 Claude·Codex 같은 도구가 압축 기능을 "도구"로 직접 부를 수도 있습니다.
Headroom의 가장 흥미로운 점은 한 패키지(headroom-ai) 안에 Python·Rust·TypeScript가 공존한다는 것입니다. 사용자에게 보이는 얼굴(CLI·설정·통합)은 Python, 토큰을 실제로 깎는 뜨거운 루프(JSON 압축기 SmartCrusher 등)는 Rust, 그리고 JS/TS 생태계용으로 별도 SDK까지 — 셋이 역할을 나눠 가집니다.
| 레이어 | 기술 / 버전 | 역할 |
|---|---|---|
| 토크나이저 | tiktoken ≥0.5 | 모든 압축기가 토큰 수를 세는 기준자 |
| 설정·데이터모델 | pydantic ≥2.0 | 설정값·결과 객체의 형식 검증 |
| 모델 레지스트리 | litellm 1.82.3 | 수십 개 LLM 프로바이더의 가격·문맥크기 정보 |
| CLI | click ≥8.1 + rich ≥13 | headroom 명령어와 컬러 터미널 출력 |
| 코드 슬라이싱 | ast-grep-cli ≥0.30 | 코드를 문법 단위로 잘라 핵심만 남김 |
저장소는 Cargo 워크스페이스로 4개의 Rust 크레이트를 품고 있습니다. 빌드는 일반 setuptools가 아니라 maturin(Rust→Python 확장 빌더)으로 합니다.
| 크레이트 | 역할 |
|---|---|
| headroom-core | 핵심 타입 + 압축 트랜스폼 트레이트. SmartCrusher 본체(388개 단위 테스트) |
| headroom-py | PyO3 바인딩 — core를 Python에서 headroom._core로 import 가능하게 |
| headroom-proxy | axum 기반 고속 리버스 프록시 |
| headroom-parity | Rust↔Python 결과가 바이트 단위로 같은지 검증하는 하네스 |
pip install 한 번으로 "겉은 파이썬, 속은 Rust"인 패키지가 깔립니다.| extra / 패키지 | 들어가는 것 |
|---|---|
| [proxy] | fastapi·uvicorn·httpx·mcp·magika(내용 감지)·onnxruntime |
| [ml] | torch·transformers — Kompress-base(자체 텍스트 압축 모델) |
| [memory] / [memory-stack] | 벡터검색(sqlite-vec·hnswlib) / Qdrant·Neo4j 백엔드 |
| [relevance] | fastembed(BAAI/bge-small) — 중요도 점수 임베딩 |
| sdk/typescript | npm headroom-ai — Vercel AI·OpenAI·Anthropic 어댑터 포함 |
멀티스테이지 Dockerfile(빌드 단계에서 Rust 툴체인으로 확장 컴파일 → distroless 런타임 이미지)과 docker-compose(프록시 + Qdrant 1.17 + Neo4j 5.15 메모리 스택)를 제공합니다. 이미지는 ghcr.io/chopratejas/headroom로 배포됩니다.
당신의 에이전트가 보내는 프롬프트·도구결과·로그·RAG 결과가 Headroom을 통과해 LLM 프로바이더로 갑니다. 핵심은 전부 로컬에서 처리된다는 것 — 당신의 데이터가 외부로 새지 않습니다.
가장 대표적인 동작을 골라 손으로 따라가 봅니다. 에이전트가 코드 검색을 돌려 거대한 JSON 결과를 받은 상황입니다.
headroom_retrieve 불러" 표시를 남깁니다. LLM이 디테일이 필요하다고 판단하면 그때만 원본을 꺼내옵니다. 압축의 부작용(정보 손실)을 되돌릴 수 있게 한 안전장치.코드를 열어보면 프로바이더별 특수 처리(Anthropic·Gemini·Codex 등)는 모두 headroom/providers/ 아래로 격리돼 있고, 핵심 파일(wrap.py·client.py·proxy/server.py)은 "흐름·순서·정책"만 담당하도록 설계돼 있습니다. 또 하나의 관례는 "조용한 실패(silent fallback)를 거부"한다는 것 — 예컨대 사용자가 준 점수 매기기 함수를 아직 Rust가 못 받으면, 몰래 무시하지 않고 NotImplementedError로 시끄럽게 터뜨립니다. "압축이 됐다고 했는데 사실 안 됐다" 같은 사고를 원천 차단하려는 태도입니다.
| 위치 | 역할 |
|---|---|
| headroom/transforms/ | 이 프로젝트의 심장. 각 파일이 하나의 압축 전략(Transform) |
| headroom/pipeline.py | 여러 Transform을 정해진 순서로 줄세우는 파이프라인 |
| crates/ | 성능이 중요한 압축을 Rust로 다시 구현한 곳 |
| headroom/providers/ | 프로바이더별 차이(인증·API 형식)를 여기 가둬 핵심을 깨끗하게 |
| headroom/evals/ | "압축해도 정답률 유지"를 증명하는 자동 벤치마크 |
"파이썬은 느리다"는 말의 진짜 의미는 "뜨거운 루프(같은 일을 수백만 번 반복하는 부분)가 느리다"입니다. Headroom은 JSON 압축처럼 반복이 많은 부분만 Rust(headroom-core)로 옮기고, PyO3로 다리를 놓아 파이썬에서 그대로 부릅니다. 게다가 두 구현이 바이트 단위로 같은 결과를 내는지 parity 하네스로 검증합니다.
📖 한 줄 풀이: compress(messages)를 부르면 겉은 파이썬이지만, JSON 배열은 내부적으로 headroom._core.SmartCrusher(Rust)가 처리합니다.
가장 단순한 사용법입니다. 메시지 리스트를 넣으면 압축된 메시지가 나옵니다.
# 💡 하는 일: 메시지를 LLM에 보내기 전에 한 번 압축한다 from headroom import compress result = compress( messages, # OpenAI/Anthropic 형식 그대로 model="gpt-4o", # 토큰 계산·문맥크기 기준 ) print(result.messages) # 압축된 메시지 → 이걸 LLM에 보낸다
안심하세요 — 위 코드는 복사만 하면 동작합니다. optimize=False로 주면 압축을 끄고 원본을 그대로 돌려주므로, 압축 전후를 A/B로 비교하기도 쉽습니다.
이미 돌아가는 앱이 있고 코드를 못 건드릴 때, 프록시가 답입니다. LLM API 요청이 프록시를 거쳐 가도록 주소만 바꾸면 됩니다.
# 💡 하는 일: 8787 포트에 압축 프록시를 띄운다 (어떤 언어 앱이든 OK) headroom proxy --port 8787 # 또는 코딩 에이전트를 통째로 감싸기 (메모리·코드그래프까지) headroom wrap claude --memory --code-graph
📖 한 줄 풀이: 앱은 "평소처럼 OpenAI에 보낸다"고 믿지만, 실제로는 그 사이에서 Headroom이 압축을 합니다. OpenAI 호환 클라이언트면 무엇이든 동작합니다.
여러 에이전트를 쓰면 같은 실수를 각자 반복합니다. Headroom의 cross-agent memory는 공유 저장소에 누가 무엇을 했는지 기록하고 중복을 자동 제거합니다. headroom learn은 한발 더 나아가 실패한 세션을 채굴해 교정 사항을 CLAUDE.md·AGENTS.md·GEMINI.md에 적어줍니다 — 다음엔 같은 실수를 안 하도록.
압축 도구의 가장 큰 의심은 "그래서 답 질이 떨어지는 거 아냐?"입니다. Headroom은 이 의심을 코드로 반박합니다.
# 💡 하는 일: 표준 벤치마크로 압축 전후 정답률을 직접 잰다 python -m headroom.evals suite --tier 1 # GSM8K(수학) ±0.000 · TruthfulQA +0.030 · SQuAD 97% · BFCL 97%
오픈소스 프로젝트에서 "주장"을 "재현 가능한 측정"으로 바꾸는 좋은 본보기입니다. 직접 돌려서 숫자를 확인할 수 있다는 게 신뢰의 핵심입니다.
| 항목 | 요구사항 |
|---|---|
| Python | 3.10 이상 (pipx 사용 시 인터프리터 명시 권장) |
| 기본 설치 | pip install headroom-ai — tiktoken·pydantic 등 경량 의존성만 |
| 프록시 / MCP | [proxy] extra — fastapi·uvicorn·onnxruntime (torch 불필요) |
| ML 압축(Kompress) | [ml] extra — torch·transformers (수백 MB, GPU 있으면 유리) |
| 메모리 스택(풀) | Docker로 Qdrant + Neo4j 컨테이너 (벡터·그래프 메모리) |
| 빌드(소스에서) | Rust 툴체인 1.80+ & maturin (휠 설치 시엔 불필요) |
| 실행 환경 | 로컬 프로세스 실행이 막힌 샌드박스에서는 부적합 |
설치를 "차 옵션 고르기"로 보면 됩니다. 기본형(headroom-ai)은 출퇴근용 경차 — 가볍고 즉시 굴러갑니다. [proxy]는 내비·하이패스 추가, [ml]는 큰 엔진 업그레이드(torch), 메모리 스택은 트레일러(Qdrant·Neo4j)까지 다는 풀옵션. 필요한 만큼만 골라 다는 구조라 처음부터 무겁게 시작할 필요가 없습니다.
pip install "headroom-ai[all]" 후, 큰 JSON 도구 결과(예: git log --json이나 검색 결과)를 메시지로 만들어 compress()에 넣어보세요. result의 압축 전후 토큰 수를 출력해 "원래 몇 토큰 → 몇 토큰"을 표로 남겨보면 감이 확 옵니다.
headroom wrap claude 또는 headroom proxy --port 8787로 평소 쓰는 에이전트 앞에 압축 레이어를 끼우고 하루 작업해보세요. 끝나고 headroom perf로 누적 절감 토큰을 확인하면, 실제 워크플로에서 얼마나 굳는지 체감할 수 있습니다.
python -m headroom.evals suite --tier 1을 돌려 GSM8K·TruthfulQA 정답률이 압축 전후로 정말 같은지 스스로 확인하세요. 압축률을 설정으로 더 공격적으로 올렸을 때 어디서부터 정답률이 흔들리는지 찾아보면, 압축의 한계선을 몸으로 배웁니다.
headroom/transforms/base.py의 Transform 인터페이스를 보고, 특정 형식(예: 너무 긴 마크다운 표)을 줄이는 간단한 압축기를 파이썬으로 하나 만들어 파이프라인에 끼워보세요. ContentRouter가 어떻게 내용을 판정하는지도 함께 읽으면 구조가 잡힙니다.
scripts/build_rust_extension.sh(maturin develop 래퍼)로 headroom._core를 로컬 빌드하고, parity 하네스로 Rust와 (옛) 파이썬 구현 결과가 바이트 단위로 같은지 검증해보세요. PyO3로 언어 경계를 넘는 코드가 실제로 어떻게 묶이는지 들여다볼 수 있는 좋은 기회입니다.
| 주차 | 주제 | 학습 자료 / 키워드 |
|---|---|---|
| 1주 | 토큰·문맥창·LLM 비용 구조 이해 | tiktoken, 프롬프트 캐싱(KV 캐시), Anthropic/OpenAI 가격표 읽기 |
| 2주 | 문맥 엔지니어링 & 압축 전략 | truncation vs 구조적 압축, RAG 청크 압축, Headroom evals 재현 |
| 3주 | Rust + Python 확장 | PyO3, maturin, ast-grep, "뜨거운 루프만 Rust로" 패턴 |
| 4주 | 에이전트 인프라 | MCP 서버, 프록시 패턴(axum/FastAPI), cross-agent memory, Qdrant/Neo4j |
| 용어 | 의미 |
|---|---|
| SmartCrusher | JSON 배열·중첩 객체를 반복 구조를 접어 압축하는 Rust 압축기. 이 프로젝트의 주력 |
| CodeCompressor | Python·JS·Go·Rust·Java·C++ 등의 코드를 문법 트리(AST)를 보존하며 핵심만 남김 |
| Kompress-base | 에이전트 트레이스로 학습한 자체 텍스트 압축 모델(HuggingFace 공개). 산문 압축 담당 |
| ContentRouter | 내용 종류를 판정해 알맞은 압축기로 보내는 교통경찰 |
| CacheAligner | 압축 후에도 프롬프트 앞부분을 안정화해 프로바이더 KV 캐시가 적중하게 함 |
| CCR | 가역 압축 — 원본을 로컬에 보관하고 LLM이 headroom_retrieve로 꺼내쓰게 함 |
| MCP | Model Context Protocol. 에이전트가 외부 기능을 "도구"로 부르는 표준. headroom_compress 등 제공 |
| PyO3 / maturin | Rust를 파이썬에서 import 가능한 모듈로 만들고(PyO3), 휠로 빌드(maturin)하는 도구쌍 |
| headroom learn | 실패 세션을 채굴해 CLAUDE.md·AGENTS.md·GEMINI.md에 교정 사항을 적어주는 기능 |
| extras ([proxy] 등) | pip 설치 시 선택적으로 끼우는 의존성 묶음. 필요한 기능만 골라 무게를 조절 |