headroom

Headroom은 AI 에이전트가 읽는 모든 내용—도구 출력, 로그, RAG 청크, 파일, 대화 기록—을 LLM에 도달하기 전 압축하는 컨텍스트 압축 레이어입니다. 목표는 응답의 정확성을 유지한 채 토큰 사용량을 줄이는 것입니다. 압축은 로컬에서 실행되며 프롬프트나 파일 내용은 외부로 전송되지 않습니다. 기능: - 라이브러리: Python 또는 TypeScript에서 `compress(messages)`를 사용하여 어떤 애플리케이션에도 직접 통합 가능. - 프록시: `headroom proxy --port 8787`은 코드 변경 없이 어떤 OpenAI 호환 클라이언트라도 즉시 사용 가능. - 에이전트 래퍼: `headroom wrap`은 Claude Code, Codex, Grok CLI, Cursor, Aider, Copilot CLI, VS Code Copilot, OpenClaw, OpenCode, Cline, Continue, Goose, OpenHands, Mistral Vibe, Oh My Pi, Kimi CLI, ZCode 등과 호환하며, `headroom unwrap`으로 원래 상태로 복원 가능. - MCP 서버: `headroom_compress`, `headroom_retrieve`, `headroom_stats` 도구를 모든 MCP 클라이언트에 노출. - 크로스 에이전트 메모리: Claude, Codex, Gemini, Grok 간 공유되고 중복 제거된 저장소. - `headroom learn`: 실패한 세션을 분석하여 수정 사항을 `CLAUDE.local.md`(기본값, gitignored) 또는 다른 에이전트 지시 파일에 기록. - 출력 토큰 감소: 모델이 반환하는 토큰(전송된 토큰만이 아님)을 줄이기 위한 프록시 측의 자세한 수준 조절 및 작업 라우팅. - 가역 압축(CCR): 원본은 로컬에 캐시되며 `headroom_retrieve`로 필요 시 즉시 복원 가능. 동작 방식: ContentRouter는 콘텐츠 유형을 감지하고 적절한 압축기를 선택합니다—JSON에는 SmartCrusher, 코드에는 AST 인식 CodeCompressor(Python, JS/TS, Go, Rust, Java, C/C++, Perl 지원), 문장에는 Hugging Face에서 에이전트 추적 데이터로 학습된 Kompress-v2-base를 사용합니다. CacheAligner는 프로바이더 KV 캐시 접두사에 영향을 주는 변동성 있는 콘텐츠를 식별하며, live-zone 압축은 고정된 접두사를 바이트 단위로 동일하게 유지하여 프로바이더 캐시를 유지합니다. Anthropic/OpenAI SDK, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands, ASGI 앱, 멀티에이전트 SharedContext 등에 프레임워크 어댑터 제공. README에는 오프라인 벤치마크 결과가 포함되어 있습니다: 코드 검색에서 21% 절감, SRE 사고 디버깅에서 57%, 코드베이스 탐색에서 42%, GitHub 이슈 분류에서 30% 절감, 반복되는 JSON/로그 페이로드는 90% 이상 압축. 10K 토큰 기준 압축 지연은 1ms 미만입니다. 정확도 평가에서는 GSM8K와 TruthfulQA에서 감지 가능한 차이 없음, SQuAD v2와 BFCL에서는 19–32% 압축 시 97% 정확도 유지. 설치: `uv tool install --python 3.13 "headroom-ai[all]"`, `pip install "headroom-ai[all]"`, `npm install headroom-ai`(TypeScript SDK만, CLI 미포함), 또는 Docker 이미지 `ghcr.io/headroomlabs-ai/headroom`. Python 3.10+ 필요. Apache 2.0 라이선스. 세부적인 extras로는 `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]`, `[image]`, 프레임워크 어댑터가 제공됩니다.