토큰 60~95% 줄이는 컨텍스트 압축 레이어, Headroom

2026년 6월 6일 하루에만 별 2,503개. chopratejas/headroom이 GitHub 트렌딩 정상에 올랐다. 별 누적 14,431개짜리 이 레포가 오늘 갑자기 터진 건 아이디어가 새롭기 때문이 아니다 — 타이밍이 맞아떨어졌기 때문이다. AI 에이전트가 파일시스템을 뒤지고 MCP 도구 호출이 컨텍스트를 삼키는 지금, 토큰 비용은 "프로덕션 AI"에서 가장 아픈 청구서가 됐다.

이게 뭔가

LLM에 텍스트를 보내기 전에 압축기를 한 겹 끼워 넣는다고 생각하면 된다. 서버 로그, 코드 파일, RAG 검색 결과, 도구 출력물 — 이 텍스트 덩어리들이 headroom을 통과하며 핵심 의미만 남기고 줄어든다. 공식 README에 따르면 60~95% 적은 토큰으로 같은 답을 얻는다고 주장한다.

통합 방식이 세 가지라는 점이 실용적이다. Python/TypeScript 라이브러리, OpenAI 호환 HTTP 프록시, 그리고 MCP 서버. 기존 스택을 거의 손대지 않고 붙일 수 있다.

왜 지금 뜨는가

세 가지 흐름이 동시에 수렴했다.

① 에이전트의 컨텍스트 폭발. Claude Code, Cursor 같은 코딩 에이전트는 레포를 탐색하며 수십만 토큰을 쌓는다. 컨텍스트 창이 넓어질수록 비용도 선형으로 오른다.

② MCP 생태계 확산. Model Context Protocol이 에이전트 통합의 사실상 표준이 되면서, 도구 호출 응답이 대화 컨텍스트를 잠식하는 문제가 가시화됐다. Headroom의 MCP 서버 지원은 이 흐름에 정면으로 올라탄 선택이다.

③ 비용 압박. GPT-4o 입력 기준 $2.50/1M 토큰. RAG 파이프라인이 하루 수백만 토큰을 소비하는 팀에게 60% 절감은 인프라 비용을 바꾸는 수준이다.

핵심 기능

압축 알고리즘은 6가지다. 신경망 기반 모델(Kompress-base)을 포함하며 전부 로컬에서 돌아간다. 가역(reversible) 압축을 지원해 필요하면 원문을 복원할 수 있고, 중간 처리에 원본이 필요한 파이프라인에서 유용하다. 텍스트가 외부 서버로 유출되지 않는 로컬 퍼스트 구조라 보안 민감 환경에도 적합하다. LangChain, Claude Code, Cursor, FastAPI 기반 스택 등을 명시적으로 지원한다.

누구에게 쓸모 있나

RAG 파이프라인을 운영하는 팀이라면 검색 결과 청크가 곧바로 압축 대상이다. MCP 서버 개발자는 도구 응답 크기를 줄여 에이전트 대화 수명을 늘린다. Claude Code·Cursor를 주로 쓰는 경우, 대형 레포 작업 시 컨텍스트 소모를 크게 줄인다. API 비용을 낮추려는 스타트업은 프록시 한 줄 교체만으로 기존 코드를 그대로 쓸 수 있다.

시작하기

# Python
pip install headroom-ai

# Node.js / TypeScript
npm install headroom-ai

전체 설정 옵션은 공식 문서를 참고한다.

사용 예시

① RAG 청크를 LLM에 넘기기 전에 압축 — 검색 결과 뭉치를 그대로 쏘는 대신 먼저 줄인다.

from headroom import compress
from openai import OpenAI

chunks = retriever.get_relevant_documents(query)
raw = "\n\n".join([c.page_content for c in chunks])
compressed = compress(raw)  # 핵심 의미만 남기고 압축

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": compressed.text + f"\n\n질문: {query}"}
    ]
)

② 프록시 모드 — 기존 OpenAI 클라이언트 한 줄만 수정 — base_url만 바꾸면 나머지 코드는 그대로다.

from openai import OpenAI

# 기존: OpenAI()
# 변경: base_url만 headroom 프록시로 교체
client = OpenAI(base_url="http://localhost:8080/v1", api_key="sk-...")

# 이후 코드 동일 — 압축은 프록시가 자동으로 처리
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": long_tool_output}]
)

③ MCP 서버 — Claude Code 연동 — claude_desktop_config.json에 추가해 에이전트 도구 응답을 자동 압축한다.

# MCP 서버 실행
headroom mcp serve

// claude_desktop_config.json
{
  "mcpServers": {
    "headroom": {
      "command": "headroom",
      "args": ["mcp", "serve"]
    }
  }
}

한계·주의

과장 없이 짚어야 할 지점들이 있다.

손실 압축 가능성부터다. "같은 답"이 보장되는 건 아니다 — 수치 데이터, 고유명사, 코드 세부 문법이 중요한 작업이라면 직접 벤치마크를 돌려봐야 한다. 텍스트 유형에 따라 효과 차이도 크다. 서사형 텍스트는 잘 압축되지만, 이미 요약된 텍스트나 촘촘한 JSON 구조체는 기대치를 밑돌 수 있다. 프록시 레이턴시도 고려할 요소다. 압축 처리 오버헤드가 더해지기 때문에 짧은 프롬프트에는 오히려 역효과다. 아직 초기 레포인 만큼 프로덕션 도입 전 엣지 케이스를 충분히 검증하는 편이 좋다. 라이선스는 Apache 2.0으로 상업적 사용 제약은 없다.

컨텍스트 창이 넓어진다고 비용 문제가 해결되는 건 아니다. 에이전트가 더 많은 것을 끌어오면 창도 그만큼 빨리 찬다. 압축 레이어는 그 레이스에서 벗어나는 한 가지 현실적인 출구다.