headroom: 토큰 사용량을 60–95% 절감하는 AI 에이전트용 압축 라이브러리 및 프록시

██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗
██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║
███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║
...

60–95% 더 적은 토큰 (tokens) · 라이브러리 (library) · 프록시 (proxy) · MCP · 6가지 알고리즘 · 로컬 우선 (local-first) · 가역적 (reversible)

Docs · Install · Proof · Agents · Discord · llms.txt

AI 에이전트 (AI agents) / LLM: 여기에서 /llms.txt를 읽거나, 실시간 인덱스 / 전체 문서 블롭 (docs blob)을 가져오세요.

Headroom은 AI 에이전트가 읽는 모든 것—도구 출력 (tool outputs), 로그 (logs), RAG 청크 (RAG chunks), 파일 (files), 대화 기록 (conversation history)—이 LLM에 도달하기 전에 압축합니다. 답변은 동일하지만, 토큰은 아주 적은 부분만 사용합니다.

실시간: 10,144 → 1,260 토큰 — 동일한 FATAL 오류 발견.

라이브러리 (Library)—compress(messages)

Python 또는 TypeScript에서 모든 앱에 인라인으로 적용 가능
프록시 (Proxy)—headroom proxy --port 8787

코드 변경 없이 모든 언어에서 사용 가능
에이전트 래핑 (Agent wrap)—headroom wrap claude|codex|cursor|aider|copilot

단 한 번의 명령으로 실행
MCP 서버 (MCP server)—headroom_compress

, headroom_retrieve

, headroom_stats

모든 MCP 클라이언트용
교차 에이전트 메모리 (Cross-agent memory)— Claude, Codex, Gemini 간 공유 저장소, 자동 중복 제거(auto-dedup)—실패한 세션을 분석하여 headroom learn을 통해 CLAUDE.md / AGENTS.md에 수정 사항을 기록
가역적 (Reversible, CCR)— 원본은 절대 삭제되지 않으며, LLM이 필요할 때 요청하여 검색

Your agent / app
(Claude Code, Cursor, Codex, LangChain, Agno, Strands, your own code…)
│ prompts · tool outputs · logs · RAG results · files
...

콘텐츠 라우터 (ContentRouter)— 콘텐츠 유형을 감지하고 적절한 압축기를 선택
SmartCrusher / CodeCompressor / Kompress-base— JSON, AST 또는 산문 (prose) 압축
CacheAligner— 제공업체의 KV 캐시 (KV caches)가 실제로 작동하도록 접두사 (prefixes)를 안정화
CCR— 원본을 로컬에 저장; LLM이 필요할 경우 headroom_retrieve를 호출

→ Architecture · CCR reversible compression · Kompress-base model card

# 1 — Install
pip install "headroom-ai[all]" # Python
npm install headroom-ai # Node / TypeScript
...

세부 추가 기능: [proxy], [mcp], [ml], [agno], [langchain], [evals]

. **Python 3.10+**가 필요합니다.

실제 에이전트 워크로드(Workload)에서의 절감 효과:

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

표준 벤치마크(Benchmark)에서의 정확도 유지:

벤치마크	카테고리	N	베이스라인 (Baseline)	Headroom	차이 (Delta)
GSM8K	수학 (Math)	100	0.870	0.870	±0.000
...	19% 압축
BFCL	도구 (Tools)	100	—	97%	32% 압축

재현 방법: python -m headroom.evals suite --tier 1

· 전체 벤치마크 및 방법론

커뮤니티에서 60B+ 토큰 절약 중 — 실시간 리더보드 보기 →

에이전트	headroom wrap	비고
Claude Code	●	--memory · --code-graph
Codex	●	Claude와 메모리 공유
...

headroom proxy를 통해 모든 OpenAI 호환 클라이언트가 작동합니다.

· MCP 네이티브: headroom mcp install

·

이런 분들께 추천합니다…

• 매일 AI 코딩 에이전트를 사용하며, 코드를 변경하지 않고 비용을 절감하고 싶은 경우
• 여러 에이전트를 사용하며 공유 메모리(Shared memory)가 필요한 경우
• 가역적 압축(Reversible compression)이 필요한 경우 — CCR을 통해 원본을 언제든 검색 가능

이런 분들께는 권장하지 않습니다…

• 단일 제공업체의 네이티브 압축 기능만 사용하며, 에이전트 간 메모리 공유가 필요하지 않은 경우
• 로컬 프로세스를 실행할 수 없는 샌드박스(Sandboxed) 환경에서 작업하는 경우

통합(Integrations) — 어떤 스택에도 Headroom을 적용하세요

사용 중인 환경	연결 방법
모든 Python 앱	compress(messages, model=…)
...

내부 구성 요소

내부 구성 요소

SmartCrusher— 범용 JSON: 딕셔너리 배열(arrays of dicts), 중첩된 객체(nested objects), 혼합 타입(mixed types).
CodeCompressor— Python, JS, Go, Rust, Java, C++를 위한 AST 인식(AST-aware) 압축.
Kompress-base— 에이전트 추적 데이터(agentic traces)로 학습된 당사의 HuggingFace 모델.
Image compression— 학습된 ML 라우터(router)를 통해 40–90% 절감.
CacheAligner— Anthropic/OpenAI의 KV 캐시(KV caches)가 실제로 적중할 수 있도록 접두사(prefixes)를 안정화.
IntelligentContext— 학습된 중요도(importance)를 기반으로 점수화된 컨텍스트 피팅(context fitting).
CCR— 가역적 압축(reversible compression); LLM이 필요 시 원본을 검색.
Cross-agent memory— 공유 저장소, 에이전트 출처(provenance), 자동 중복 제거(auto-dedup).
SharedContext— 멀티 에이전트 워크플로우 전반에 걸친 압축된 컨텍스트 전달.
— Claude, Codex, Gemini를 위한 플러그인 기반 실패 마이닝(failure mining).
headroom learn

파이프라인 내부 구조 (Pipeline internals)

Headroom은 compress() 함수, SDK, 그리고 프록시(proxy) 전반에 걸쳐 하나의 안정적인 요청 라이프사이클(request lifecycle)을 노출합니다:

Setup

→ Pre-Start

→ Post-Start

→ Input Received

→ Input Cached

→ Input Routed

→ Input Compressed

→ Input Remembered

→ Pre-Send

→ Post-Send

→ Response Received

Transforms가 실제 작업을 수행합니다: CacheAligner, ContentRouter, SmartCrusher, CodeCompressor, Kompress-base, IntelligentContext / RollingWindow.

Pipeline extensions는 on_pipeline_event(...)를 통해 라이프사이클 단계를 관찰하거나 커스텀할 수 있습니다.

Compression hooks는 추가적인 확장 접합부(extension seam)로서 표준 라이프사이클과 나란히 위치합니다.

Proxy extensions는 ASGI 미들웨어, 라우트(routes), 시작 정책(startup policy)을 위한 서버/앱 통합 접합부(integration seam)로 유지됩니다.

제공자(Provider) 및 도구별 동작은 headroom/providers/ 아래에 위치하여, 핵심 오케스트레이션(orchestration)이 라이프사이클, 시퀀싱(sequencing), 정책에 집중할 수 있도록 합니다.

CLI/도구 슬라이스 (CLI/tool slices):
headroom/providers/claude
, copilot
, codex
, openclaw

제공자 런타임 슬라이스 (Provider runtime slices):
headroom/providers/claude
, gemini
, 그리고 headroom/providers/registry.py에 있는 공유 백엔드/런타임 디스패치(dispatch).

핵심 파일은 오케스트레이션 우선 원칙을 유지합니다:
wrap.py
, client.py
, cli/proxy.py
, 그리고 proxy/server.py

provider별 환경 구성 (env shaping), API 대상 정규화 (normalization), 백엔드 선택, 그리고 전송 디스패치 (transport dispatch)를 위임합니다.

pip install "headroom-ai[all]" # Python, 모든 기능 포함
npm install headroom-ai # TypeScript / Node
docker pull ghcr.io/chopratejas/headroom:latest

세부 extras: [proxy], [mcp], [ml] (Kompress-base), [agno], [langchain], [evals].
**Python 3.10+**가 필요합니다.

pipx를 사용하시나요?
지원되는 인터프리터를 명시적으로 선택하십시오:

pipx install --python python3.13 "headroom-ai[all]"

→ 설치 가이드 — Docker 태그, 영구 서비스 (persistent service), PowerShell, devcontainers.

headroom learn — 실패한 세션을 분석하여 CLAUDE.md / AGENTS.md / GEMINI.md에 수정 사항을 작성합니다.

시작하기	더 깊이 알아보기
Quickstart	Architecture
...

Headroom은 **로컬 (locally)**에서 실행되며, 모든 콘텐츠 유형을 다루고, 모든 주요 프레임워크와 작동하며, **가역적 (reversible)**입니다.

범위 (Scope)	배포 (Deploy)	로컬 (Local)	가역성 (Reversible)
Headroom	모든 컨텍스트 — 도구 (tools), RAG, 로그, 파일, 히스토리	Proxy · library · middleware · MCP	예
RTK	CLI 명령 출력	CLI wrapper	예
lean-ctx	CLI 명령, MCP 도구, 에디터 규칙	CLI wrapper · MCP	예
...

Attribution. Headroom은 셸 출력 재작성(shell-output rewriting)을 위한 뛰어난 RTK 바이너리 — git show --short, 범위가 지정된 ls, 요약된 설치 프로그램(summarized installers) — 를 함께 제공합니다. RTK 팀에 큰 감사를 표합니다. 그들의 도구는 우리 스택의 일급 구성 요소이며, Headroom은 그 하위의 모든 것을 압축합니다. Headroom은 선택된 CLI 컨텍스트 도구로 lean-ctx를 사용할 수도 있습니다; headroom wrap ...을 실행하기 전에 HEADROOM_CONTEXT_TOOL=lean-ctx를 설정하십시오.

git clone https://github.com/chopratejas/headroom.git && cd headroom
pip install -e ".[dev]" && pytest

.devcontainer/ 내의 Devcontainers (기본값 + Qdrant 및 Neo4j가 포함된 memory-stack). CONTRIBUTING.md를 참조하십시오.

실시간 리더보드 (Live leaderboard)— 6,00억 개 이상의 토큰을 절감했으며 계속 증가 중입니다. Discord— 질문, 피드백, 경험담 공유. HuggingFace의 Kompress-base— 당사의 텍스트 압축 (text compression) 기술의 기반이 되는 모델.

Apache 2.0 — LICENSE를 참조하십시오.