AI 에이전트 (AI agents)를 구축하거나 프로덕션 환경에서 LLM 파이프라인 (LLM pipelines)을 운영하고 있다면, 이미 그 고충을 알고 계실 것입니다. 도구 출력값 (tool outputs), 로그 (logs), RAG 청크 (RAG chunks), 그리고 대화 기록 (conversation history)이 빠르게 쌓여갑니다. 어느샌가 여러분은 결제 대시보드를 보기조차 불편할 정도로 빠른 속도로 토큰을 소모하고 있을 것입니다.

Headroom은 이 문제를 직접적으로 해결하는 오픈 소스 (open-source) 프로젝트입니다. 이 프로젝트는 AI 에이전트가 읽는 모든 것을 — LLM에 도달하기 전에 — 압축하며, 정확도를 유지하면서 실제 워크로드 (workloads)에서 60~95%의 토큰 절감을 달성한다고 주장합니다.

핵심 아이디어 (The Core Idea)

Headroom은 애플리케이션과 LLM 제공자 (LLM provider) 사이의 계층 (layer)으로 자리 잡습니다. 에이전트가 보내려던 것 — 도구 호출 결과 (tool call results) 더미, 긴 로그 파일, RAG 검색 결과 (RAG retrieval dump) 등 — 을 가져와서 콘텐츠 유형에 따라 다음과 같은 여러 전략 중 하나를 사용하여 압축합니다.

• SmartCrusher: JSON (배열, 중첩된 객체, 혼합 타입)을 처리합니다.
• CodeCompressor: Python, JS, Go, Rust, Java, C++에 대해 AST 인식 압축 (AST-aware compression)을 사용합니다.
• Kompress-base: 산문 및 텍스트를 위해 에이전트 추적 데이터 (agentic traces)로 학습된 HuggingFace 모델입니다.
• CacheAligner: 프롬프트 접두사 (prompt prefixes)를 안정화하여 제공자의 KV 캐시 (KV caches)가 일관되게 적중(hit)하도록 합니다.
• CCR (Content-Compressed Retrieval): 원본을 로컬에 저장하고 LLM이 필요할 때 요청하여 가져올 수 있도록 합니다. 따라서 압축은 완전히 가역적 (reversible)입니다.

ContentRouter는 어떤 종류의 콘텐츠인지 파악하고 적절한 압축기를 자동으로 선택합니다. 여러분이 직접 고민할 필요가 없습니다.

핵심은 원본이 절대 삭제되지 않는다는 것입니다. LLM이 무언가의 전체 버전이 필요하다면 이를 검색할 수 있습니다. 그런 의미에서 압축은 무손실 (lossless)입니다.

실제 수치 (Real Numbers)

다음은 실제 에이전트 워크로드에 대한 프로젝트 벤치마크 (benchmarks)의 토큰 수입니다:

워크로드 (Workload)	적용 전	적용 후	절감률
코드 검색 (Code search, 100개 결과)	17,765	1,408	92%
...

정확도 벤치마크 (Accuracy benchmarks: GSM8K 수학, TruthfulQA, SQuAD v2, BFCL 도구 사용 (tool-use))에서 점수는 압축 후에도 안정적으로 유지되거나 약간 향상됩니다. 그 직관적인 이유는 노이즈 (noise)를 제거함으로써 모델이 신호 (signal)에 더 집중할 수 있도록 돕기 때문입니다.

다음 명령어를 통해 직접 재현해 볼 수 있습니다:

python -m headroom.evals suite --tier 1

설정 (Setup): 세 가지 사용 방법

Headroom은 세 가지 통합 모드를 제공합니다. 작업 방식에 가장 적합한 것을 선택하세요.

옵션 1: 기존 에이전트 래핑 (Wrap) (코드 변경 없음)

pip install "headroom-ai[all]"
headroom wrap claude

이것으로 끝입니다. Headroom은 Claude Code, Codex, Cursor, Aider 또는 Copilot CLI로부터 오는 트래픽을 자동으로 가로챕니다 (intercept). 기존 코드를 전혀 건드릴 필요가 없습니다.

옵션 2: 드롭인 프록시 (Drop-in proxy)

Headroom을 임의의 포트에서 로컬 프록시 (local proxy)로 실행하세요:

headroom proxy --port 8787

그 다음, 기존의 OpenAI/Anthropic SDK 호출 대상을 제공자 URL 대신 localhost:8787로 지정하세요. 어떤 언어, 어떤 프레임워크든 상관없으며, 베이스 URL (base URL)을 업데이트하는 것 외에는 코드 변경이 필요하지 않습니다.

옵션 3: 인라인 라이브러리 (Inline library)

더 세밀한 제어를 원한다면 Python 또는 TypeScript에서 직접 사용하세요:

Python:

from headroom import compress

messages = [{"role": "user", "content": your_giant_tool_output}]
...

TypeScript:

import { compress } from "headroom-ai";

const compressed = await compress(messages, { model: "claude-opus-4-6" });

Anthropic SDK 직접 사용 시:

from anthropic import Anthropic
from headroom import withHeadroom

...

LangChain 사용 시:

from headroom.integrations.langchain import HeadroomChatModel

llm = HeadroomChatModel(your_existing_llm)

Vercel AI SDK 사용 시:

import { wrapLanguageModel } from "ai";
import { headroomMiddleware } from "headroom-ai";

...

Python 3.10 이상이 필요합니다. Node/TypeScript의 경우: npm install headroom-ai를 사용하세요.

MCP 서버 모드 (MCP Server Mode)

MCP 클라이언트(Claude Desktop 등)를 사용하는 경우, Headroom을 MCP 서버로 설치할 수 있습니다:

headroom mcp install

이 명령어는 headroom_compress, headroom_retrieve, 그리고 headroom_stats 세 가지 MCP 도구를 노출합니다. 사용자의 AI 에이전트는 이를 자신의 툴 루프(tool loop)의 일부로 직접 호출할 수 있습니다.

크로스-에이전트 메모리 (Cross-Agent Memory)

과소평가된 기능 중 하나는 여러 에이전트 간의 공유 메모리입니다. Claude와 Codex를 나란히 실행하는 경우, Headroom은 자동 중복 제거(deduplication) 기능을 갖춘 공통 압축 컨텍스트 저장소를 제공할 수 있습니다.

from headroom.memory import SharedContext

ctx = SharedContext()
...

이는 그렇지 않으면 동일한 컨텍스트를 반복적으로 전달해야 하는 멀티-에이전트 파이프라인에서 유용합니다.

headroom learn

또한, 실패한 에이전트 세션을 분석하고 수정 사항을 CLAUDE.md, AGENTS.md, 또는 GEMINI.md 파일에 기록하는 headroom learn 명령어가 있습니다. 이 아이디어는 사용자의 에이전트가 무엇이 잘못되었는지에 대한 기록을 축적하여 같은 실수를 반복하지 않도록 하는 것입니다.

headroom learn

이는 세션 로그를 구문 분석하고, 실패 패턴을 추출하며, 프로젝트의 에이전트 설정 파일에 구조화된 학습 내용을 추가합니다.

절감량 확인 (Check Your Savings)

Headroom을 일정 기간 사용한 후에는 다음 명령어를 실행하여 확인할 수 있습니다:

headroom stats

이 명령어는 누적 압축 비율, 절약된 토큰 수, 그리고 콘텐츠 유형별 세부 내역을 보여줍니다.

사용해 볼 가치가 있을까요?

다음과 같은 경우: 예(Yes)

• AI 코딩 에이전트(Claude Code, Cursor, Codex, Aider)를 정기적으로 실행하고 토큰 비용을 지불하는 경우
• 툴 출력 및 RAG 청크가 크고 반복적인 파이프라인을 구축하는 경우
• 직접 구축하지 않고도 크로스-에이전트 공유 메모리를 원하는 경우
• 원본 데이터를 절대 폐기하지 않는 가역적 압축(reversible compression)이 필요한 경우 (Headroom은 원본을 절대로 버리지 않습니다)

다음과 같은 경우: 건너뛰거나 신중하게 접근하세요(Skip it, or approach carefully)

• 단일 제공업체의 내장 컨텍스트 관리 기능만 사용하고 더 많은 것이 필요하지 않은 경우
• 로컬 프로세스 실행이 문제가 되는 샌드박스 또는 제한된 환경에서 작업하는 경우
• 아직 컨텍스트 비대화(context bloat)가 실제 문제가 아닌 매우 단순한 단일 턴 설정인 경우

빠른 참고 자료 (Quick Reference)

설치

pip install "headroom-ai[all]"
npm install headroom-ai
...

GitHub: chopratejas/headroom