오늘의 오픈 소스 프로젝트 (#86): headroom - AI 에이전트를 위한 컨텍스트 압축 레이어, 최대 95% 토큰 절감

서론

"컨텍스트가 부족해지는 것은 항상 창(window)이 작아서 발생하는 문제가 아닙니다. 대개는 노이즈로 가득 찬 창 때문입니다."

이 글은 Open Source Project of the Day 시리즈의 #86번째 기사입니다. 오늘의 프로젝트는 AI 에이전트를 위해 특수 제작된 컨텍스트 압축 레이어인 headroom입니다.

에이전트의 능력이 향상됨에 따라 컨텍스트 창(context window)은 더 빠르게 채워집니다. 도구(tool)의 응답은 수천 줄의 JSON을 반환하고, RAG(Retrieval-Augmented Generation) 검색은 중복이 심한 문서를 생성하며, 검색 결과에는 무관한 내용이 포함되고, 로그는 노이즈로 가득 차게 됩니다. 그 결과: 토큰 소비량이 급증하고, 비용이 치솟으며, 에이전트가 작업 도중 컨텍스트 한계에 도달하는 일이 종종 발생합니다.

headroom의 해답은 간단합니다. LLM(Large Language Model)에 도달하기 전에 콘텐츠를 압축하는 것입니다. 이는 절단(truncation, 영구적 손실)도 아니고, 요약(summarization, 왜곡 가능성)도 아닙니다. 신호(signal)는 유지하고 노이즈(noise)는 버리는 의미론적 인지 압축(semantically-aware compression)이며, 원본은 언제든 필요할 때 다시 불러올 수 있습니다.

학습 내용

• 에이전트 컨텍스트가 왜 "팽창"하는지와 그 비용
• headroom의 네 가지 통합 모드: Library, Proxy, Agent Wrap, MCP Server
• 세 가지 압축 엔진의 작동 방식: SmartCrusher, CodeCompressor, Kompress-base
• CCR (Compressed Context Retrieval): 원본 접근성을 유지하는 가역적 압축
• 실제 벤치마크 데이터: 워크로드 유형별 압축률 및 정확도 유지력

사전 요구 사항

• 기본적인 Python 경험
• LLM API 사용에 대한 익숙함 (토큰이 과금 단위라는 것을 아는 정도면 충분합니다)
• 최소 하나 이상의 AI 에이전트 프레임워크 경험 (선택 사항)

프로젝트 배경

headroom이란 무엇인가?

headroom은 애플리케이션과 LLM 사이에 위치하는 "AI 에이전트를 위한 컨텍스트 압축 레이어"를 표방합니다. 이 프로젝트의 핵심 통찰은 도구 출력, 로그, 코드 스니펫, RAG 검색 결과가 현재 질문과 무관한 콘텐츠로 가득 차 있다는 점입니다. 이러한 무관한 콘텐츠를 제거하는 것은 LLM에 해를 끼치지 않습니다. 오히려 모델이 더 이상 주의를 분산시키지 않게 되므로 종종 도움이 됩니다.

단순한 절단 (truncation) 방식이나 LLM 기반의 요약 (summarization) 방식과 달리, headroom의 압축은 **가역적 (reversible)**입니다. 원본 데이터는 로컬에 저장되며, LLM은 headroom_retrieve 도구를 통해 필요할 때마다 이를 호출하여 가져올 수 있습니다. 그 어떤 것도 실제로 버려지지 않습니다.

저자 / 팀

• 저자: Tejas Chopra (chopratejas)
• 언어 구성: Python 76.9% + Rust 18.3% + TypeScript 2.7%
• 라이선스: Apache 2.0

프로젝트 통계

• ⭐ GitHub Stars: 12,800+
• 🍴 Forks: 823
• 📦 최신 버전: v0.23.0
• 📄 라이선스: Apache 2.0
• 🌐 요구 사항: Python 3.10+, Node.js, 또는 Docker

핵심 기능

주요 기능

headroom은 에이전트 도구의 출력이 LLM 컨텍스트 (context)에 입력되기 전에 이를 가로채어 노이즈를 제거하고, 토큰 수를 60~95%까지 줄입니다. 이는 **투명한 압축 미들웨어 (transparent compression middleware)**로 작동합니다. 즉, 에이전트의 로직을 변경하지 않고 흐르는 콘텐츠의 밀도만을 조절합니다.

활용 사례

1. 코드 검색 및 분석

   • 17,765 토큰 분량의 검색 결과 100개가 1,408 토큰으로 압축됩니다 (92% 감소). 에이전트는 현재 쿼리와 관련된 코드 스니펫 (code snippets)만을 보게 됩니다.

2. SRE 장애 디버깅 (incident debugging)

   • 시스템 로그, 스택 트레이스 (stack traces), 메트릭 (metrics)이 하나의 컨텍스트에 섞여 있는 경우: 65,694 토큰 → 5,118 토큰 (92% 감소). 중요한 이상 징후가 가려지지 않고 오히려 더 명확하게 드러납니다.

3. GitHub 이슈 분류 (triage)

   • 이슈를 대량으로 처리할 때: 54,174 → 14,761 토큰 (73% 감소), 분류 정확도는 저하되지 않습니다.

4. RAG 증강 생성 (RAG-augmented generation)

   • 검색된 청크 (chunks)들이 LLM에 도달하기 전에 중복이 제거되고 필터링됩니다. 모델은 노이즈를 헤매는 대신 관련 있는 콘텐츠를 바탕으로 답변합니다.

5. 멀티 에이전트 협업 (Multi-agent coordination)

   • 압축되고 중복이 제거된 메모리가 에이전트 간에 공유됩니다. 동일한 정보가 파이프라인 내의 모든 에이전트에 의해 반복적으로 소비되지 않습니다.

빠른 시작

# 전체 설치 (모든 확장 기능 포함)
pip install "headroom-ai[all]"

...

모드 1: 라이브러리 (코드 내 직접 사용)

from headroom import Headroom

hr = Headroom()
...

모드 2: 프록시 (Proxy, 코드 변경 없음)

headroom proxy --port 8787

import anthropic

# 단 한 가지 변경 사항: base_url을 headroom 프록시로 지정합니다
...

모드 3: 에이전트 래핑 (Agent Wrap, 단일 명령으로 기존 에이전트 적용)

headroom wrap claude    # Claude Code 래핑
headroom wrap aider     # Aider 래핑
headroom wrap cursor    # Cursor 래핑
...

압축 통계 확인

headroom perf
# 오늘의 절감량: 48,392 토큰 | 누적 절감액: $12.40

주요 특징 (Key Properties)

1. 네 가지 통합 모드
   • 라이브러리 (Library) / 프록시 (Proxy) / 에이전트 래핑 (Agent Wrap) / MCP 서버 (MCP Server) — 기존 구조를 건드리지 않고 아키텍처에 맞는 방식을 선택할 수 있습니다.
2. CCR — 압축 컨텍스트 검색 (Compressed Context Retrieval)
   • 원본 데이터는 로컬에 인덱싱됩니다. LLM은 headroom_retrieve를 호출하여 필요할 때마다 압축된 콘텐츠를 다시 가져올 수 있습니다. 압축은 삭제가 아닙니다.
3. 에이전트 간 공유 메모리 (Cross-agent shared memory)
   • 여러 에이전트가 동일한 메모리 저장소에 읽고 쓰며, 자동 중복 제거 (deduplication) 기능이 제공됩니다.
4. headroom learn — 실패로부터의 자동 학습
   • 실패한 에이전트 세션을 분석하여 도출된 규칙을 CLAUDE.md / AGENTS.md에 직접 작성합니다.
5. 모든 콘텐츠 유형 지원
   • JSON (SmartCrusher), 코드 (AST 레벨의 CodeCompressor), 산문 (Kompress-base), 이미지
6. 로컬 우선, 프라이버시 보호 (Local-first, privacy-safe)
   • 모든 압축은 로컬에서 실행됩니다. 데이터가 사용자의 기기를 벗어나지 않습니다.

대안과의 비교

차원	headroom	단순 절단 (Simple truncation)	LLM 요약 (LLM summarization)	수동 필터링 (Manual filtering)
정보 보존	✅ 가역적, 원본 유지	❌ 영구적 손실	⚠️ 왜곡 가능성 있음	⚠️ 규칙에 의존적
...

심층 분석 (Deep Dive)

압축 파이프라인 아키텍처 (Compression Pipeline Architecture)

headroom의 내부 처리 과정은 세 단계로 구성됩니다:

사용자 입력 / 도구 출력 (User input / Tool output)
         ↓
    CacheAligner        ← 이미 압축된 콘텐츠의 재처리 건너뛰기
...

CacheAligner: 이번 세션에서 이미 처리된 콘텐츠를 감지하여 건너뜀으로써 불필요한 연산을 방지합니다.

ContentRouter: 유입되는 콘텐츠를 JSON 구조, 코드 구문(syntax), 또는 일반 텍스트로 분류하고 가장 효과적인 엔진으로 라우팅합니다. 콘텐츠 유형을 인식하는 압축 방식은 단일 범용 방식보다 훨씬 뛰어난 성능을 발휘합니다.

세 가지 압축 엔진

① SmartCrusher (JSON / 구조화된 데이터)

도구 호출(Tool call) 응답은 흔히 수십 개의 필드를 가진 JSON 형태이며, 그중 대부분은 현재 작업과 무관합니다. SmartCrusher는 이전의 LLM 쿼리를 분석하여 중요한 필드만을 추출합니다:

# 원본 도구 응답: ~1,200 토큰
{
  "results": [
...

② CodeCompressor (소스 코드, AST 레벨)

코드는 단순 절단(truncation) 방식으로 압축할 수 없습니다. 함수 중간을 잘라버리면 구문(syntax)이 깨지고 LLM을 혼란스럽게 만들기 때문입니다. CodeCompressor는 AST(Abstract Syntax Tree)를 파싱하여 함수 시그니처, 클래스 정의, 주요 독스트링(docstrings)은 유지하고 구현 본문(implementation bodies)을 압축하여 제거합니다:

# 원본 코드: ~800 토큰
def process_payment(
    user_id: int,
...

③ Kompress-base (산문 텍스트)

문서, 로그, 자유 형식의 텍스트의 경우, headroom은 Kompress-base 모델(HuggingFace)을 사용하여 의미론적 압축(semantic compression)을 수행합니다. 현재 쿼리와 가장 관련이 높은 문장은 유지하고, 중복되거나 주제에서 벗어난 문장은 삭제합니다.

CCR: 가역적 압축이 중요한 이유

표준적인 절단 방식은 단방향입니다. headroom의 CCR (Compressed Context Retrieval, 압축된 컨텍스트 검색)은 압축을 가역적(reversible)으로 만듭니다:

원본 ────── 압축 ──────→ LLM
   │                                │
   └── 로컬 CCR 인덱스에 저장        │
...

MCP 서버 모드에서는 LLM이 직접 검색을 주도합니다:

# LLM이 전체 구현 내용이 필요하다고 판단할 때:
headroom_retrieve(
    trace_id="abc123",
...

MCP 서버 모드

MCP 모드에서 headroom은 LLM에 세 가지 도구를 노출합니다:

headroom_compress(content, content_type="auto")
# → 콘텐츠 압축; 압축된 텍스트 + trace_id 반환

...

설정 (claude_desktop_config.json):

{
  "mcpServers": {
    "headroom": {
...

headroom learn: 실패로부터의 자동 학습

에이전트 세션이 실패할 때 — 즉, 작업이 완료되지 않았거나, LLM (Large Language Model)이 여러 번 재시도했거나, 혹은 컨텍스트 (Context)가 넘쳤을 때 — headroom learn은 세션 로그를 분석하여 도출된 규칙을 CLAUDE.md 또는 AGENTS.md에 기록합니다:

headroom learn --session-log ./logs/session_2026-06-05.jsonl

# 출력 예시:
...

벤치마크 결과

실제 워크로드 (Workload) 벤치마크 (합성 데이터 아님):

워크로드	이전	이후	절감액
코드 검색 (100개 결과)	17,765	1,408	92%
...

정확도 유지 (핵심 질문: 압축이 답변 품질을 저하시키는가?):

벤치마크	압축률	정확도 변화
GSM8K (수학적 추론)	—	delta = ±0.000 (변화 없음)
SQuAD v2 (독해)	19%	97% 유지

핵심 발견 사항: 에이전트 워크로드의 경우, 관련 없는 콘텐츠를 제거하는 것이 답변 품질을 저하시키지 않으며, 오히려 향상시키는 경우가 많습니다. LLM이 더 이상 노이즈 (Noise)에 의해 방해받지 않기 때문입니다.

링크 및 리소스

공식 리소스

• 🌟 GitHub: chopratejas/headroom
• 📦 PyPI: pip install headroom-ai
• 🐛 Issue Tracker: github.com/chopratejas/headroom/issues

관련 리소스

• LangChain 통합 (Integration)
• MCP 프로토콜 사양 (Protocol Specification)
• Kompress-base 모델 (HuggingFace)

결론

headroom은 만성적으로 과소평가되어 온 문제인 컨텍스트 윈도우 (Context Window) 내의 노이즈 문제를 해결합니다. 우리는 프롬프트 (Prompt) 문구를 조정하는 데 수 시간을 소비하지만, 도구 (Tool) 응답에서 발생하는 비대함에 대해서는 거의 생각하지 않습니다. 코드 검색 한 번에 17,765개의 토큰이 반환되고 그 중 16,357개가 노이즈인 상황 — 복잡한 에이전트에서는 이러한 일이 분당 수십 번씩 발생하고 있습니다.

네 가지 통합 모드(Library / Proxy / Wrap / MCP)를 통해 headroom는 대대적인 수술 없이도 거의 모든 기존 에이전트 아키텍처(Architecture)에 맞게 적용될 수 있습니다. CCR 가역적 압축(Reversible compression)은 압축이 곧 삭제를 의미하지 않음을 뜻합니다. 그리고 headroom learn 기능은 에이전트가 자신의 실패로부터 자동으로 더 똑똑해질 수 있음을 의미합니다.

만약 귀하의 에이전트가 비용 초과나 컨텍스트 오버플로(Context overflow) 문제에 직면해 있다면, headroom는 가장 먼저 시도해 볼 가치가 있는 솔루션입니다.

실제 기업급 워크플로에서 검증된 AI 에이전트와 기술의 큐레이션 마켓플레이스인 PrimeSkills를 확인해 보세요. 군더더기 없이 실제로 작동하는 것들만 모았습니다.

저의 홈페이지에서 더 유용한 지식과 흥미로운 제품들을 찾아보세요.