Headroom: AI 에이전트가 절실히 필요로 하는 컨텍스트 압축 계층

토큰 문제는 실재하며—점점 심해지고 있다

프로덕션에서 AI 에이전트를 구축·운영해 본 적이 있다면 그 느낌을 안다. 에이전트가 검색 도구를 호출하면 500개 결과. 로그 파일을 읽으면 10,000줄. DB를 쿼리하면 소설 한 권 분량의 JSON blob. 이 모든 것이 LLM 컨텍스트 윈도우에 들어가고—토큰 수가 폭발하고, 지연이 부풀고, API 청구서가 조용히 통제 불능이 되는 것을 본다.

이는 틈새 edge case가 아니다. 2025–2026년 agentic AI의 기본 현실이다. 도구 출력은 장황하고, 로그는 노이즈가 많으며, RAG retrieval은 부정확하다. LLM은 뛰어나지만 무관한 정보를 무시하는 데 놀랍도록 서투르다—중요 여부와 관계없이 주어진 모든 것을 읽는다.

GitHub chopratejas/headroom의 Tejas Chopra가 만든 오픈소스 프로젝트 Headroom은 바로 이를 고치기 위해 만들어졌다. 기술적으로 우아하면서도 놀랍도록 실용적인 방식으로.

---

Headroom이란?

Headroom은 스스로를 「AI 에이전트를 위한 컨텍스트 압축 계층」이라고 부른다. 쉽게 말해: 애플리케이션과 LLM provider 사이에 위치해 모델 컨텍스트 윈도우로 흘러 들어가는 모든 콘텐츠를 가로채, 지능적으로 압축한 뒤 더 가볍고 깨끗한 prompt를 전달한다. LLM은 같은 의미를 얻는다—훨씬 적은 token으로.

핵심 숫자는 인상적이다:

그리고 중요한 것은—정확도가 유지된다는 점. GSM8K 같은 표준 벤치마크에서 Headroom으로 압축한 prompt는 비압축과 같은 정답을 낸다.

---

실제 작동 방식

Headroom이 진짜 흥미로운 부분. 단순히 「공백 제거·중복 삭제」가 아니다. 압축 파이프라인은 다단계이며 콘텐츠를 인식한다.

Stage 1: CacheAligner

압축 전에 Headroom은 system prompt를 안정화한다. timestamp, session token, UUID 같은 동적 콘텐츠를 감지해 prompt 중간이 아니라 끝으로 옮긴다. 왜? Anthropic, OpenAI 같은 provider는 prefix caching을 쓰기 때문—호출마다 prompt 시작이 같으면 캐시된 KV computation을 재사용해 비용을 크게 줄일 수 있다. system prompt 중간에 묻힌 하루마다 바뀌는 timestamp 하나가 매 호출마다 cache hit rate를 조용히 망가뜨리고 있었다. CacheAligner는 sub-millisecond overhead로 이를 고친다.

Stage 2: SmartCrusher

핵심 엔진. 에이전트가 1,000개 log entry JSON array를 반환할 때 SmartCrusher는 무작위 20개를 뽑지 않는다. 모든 field에 대해 분산, uniqueness, change point를 측정하는 field-level 통계 분석을 실행한다. bigram coverage에 Kneedle 알고리즘으로 대표 subset을 선택한다. 그리고 중요하게 error, anomaly, distribution boundary—LLM이 문제를 진단하는 데 필요한 항목—를 무조건 보존한다.

item retention 전략도 신중하다: array 시작 30%(schema 이해), 끝 15%(최신성), 계산된 importance score 55%. error item은 budget과 관계없이 항상 살아남는다.

코드에는 AST-aware 압축—signature 보존, body collapse. HTML에는 article extraction. log에는 pattern clustering. 콘텐츠 유형마다 맞는 도구.

Stage 3: Context Manager

컨텍스트 윈도우를 넘을 위험이 있는 긴 multi-turn 대화에 Headroom은 두 모드를 제공한다. 기본 Rolling Window는 가장 오래된 message부터 drop(system prompt와 최근 turn 유지). 고급 Intelligent Context 모드는 recency, semantic similarity, error indicator, forward reference, token density, TOIN이라는 learned importance signal 등 6차원으로 각 message를 점수화해 가장 낮은 것부터 drop한다.

---

킬러 기능: CCR(Compress-Cache-Retrieve)

Headroom에서 철학적으로 가장 흥미로운 부분은 명백한 반론에 대한 답이다: 「압축해 버린 데이터가 LLM에 필요하면?」

답은 CCR—Compress-Cache-Retrieve. Headroom이 무언가를 압축할 때마다 원본을 로컬 SQLite cache에 저장하고 압축 출력에 retrieval marker를 주입한다:

[1000 items compressed to 20. Retrieve more: hash=abc123]

또한 LLM 사용 가능 tool에 headroom_retrieve tool을 주입한다. 모델이 전체 데이터가 필요하다고 판단하면 hash로 이 tool을 호출—약 1ms에 원본을 되돌린다. client application은 이를 전혀 모른다; 투명하게 처리된다.

더 똑똑한 점: LLM이 전부 retrieve할 필요는 없다. optional query parameter를 넘기면 Headroom이 cached item에 BM25 search를 실행해 관련 subset만 반환한다. 압축은 공격적일 뿐 아니라 진정으로 reversible하고 queryable하다.

이는 고전적 압축 tradeoff를 우아하게 없앤다. 「token 절약」과 「정보 보존」 중 하나를 고르지 않아도 된다. 둘 다 가능하다.

---

네 가지 사용 방법

Headroom은 어디에 있든 맞춰 설계되었다:

• Library mode — Python/TypeScript에서 compress(messages) inline. 두 줄.
• Proxy mode — headroom proxy --port 8787. 코드 변경 zero. 기존 LLM client base URL만 바꾸면 됨.
• Agent wrap — headroom wrap claude 또는 headroom wrap cursor. 한 명령으로 코딩 agent 전체 wrap.
• MCP server — headroom_compress, headroom_retrieve, headroom_stats를 MCP 호환 client용 tool로 노출.

LangChain, Agno, Strands, LiteLLM, Vercel AI SDK와도 native 통합.

---

왜 중요한가

Headroom의 의미는 API 비용 절감(73–92% token reduction, 절감은 매우 실재)을 넘어선다. 이 프로젝트가 중요한 더 깊은 이유 세 가지:

agent를 더 신뢰할 수 있게

노이즈 많고 bloated한 context는 LLM reasoning error의 주요 원인 중 하나. 65,000 token log 중 500 token만 중요할 때 haystack에서 needle을 찾으라고 하는 셈. Headroom은 needle을 직접 건넨다.

유효 context ceiling을 높인다

128K context window는 agent가 실제 일을 하기 전까지는 거대해 보인다. 90% 압축이면 같은 window가 실질적으로 1.28M token window처럼 동작한다. 더 긴 task, 더 깊은 codebase, 더 풍부한 history 처리 가능.

local-first, privacy 존중

모든 압축·cache는 내 machine에서. 데이터는 LLM으로 가는 길에 infrastructure 밖으로 나가지 않는다—압축된 출력만 나간다. data sensitivity가 중요한 enterprise use case에서 의미 있다.

---

마무리

Headroom은 너무 근본적인 문제를 해결해 「왜 이제야」라고 wonder하게 만드는 프로젝트 중 하나다. context window는 공짜가 아니다—token마다 time, money, attention 비용. Headroom은 이를 regex heuristic 몇 개가 아니라 통계, AST parsing, learned pattern, reversible caching으로 엄밀히 풀 engineering problem으로 다룬다.

GitHub 23,400+ star와 성장 중—커뮤니티가 분명히 주목했다. 2026년 AI agent로 무언가를 만들고 있다면 Headroom은 진지히 볼 가치가 있다.