Headroom GitHub 저장소

Headroom은 AI 에이전트가 읽는 tool outputs, logs, RAG chunks, files, 대화 이력을 LLM에 보내기 전에 압축하는 local-first 컨텍스트 압축 레이어다. 라이브러리, proxy, MCP, headroom wrap으로 제공되며, 6개 압축 알고리즘과 reversible 구조를 묶어 같은 답을 유지한 채 토큰을 60~95% 줄이는 것을 목표로 한다.

핵심 파이프라인은 CacheAligner → ContentRouter → CCR이다. ContentRouter가 JSON, 코드, 일반 텍스트를 판별해 SmartCrusher, CodeCompressor, Kompress-base를 선택하고, CacheAligner는 provider KV cache가 더 잘 맞도록 접두어를 안정화한다. CCR는 원본을 로컬에 보관한 뒤 LLM이 필요할 때 headroom_retrieve로 다시 불러오게 한다. cross-agent memory와 headroom learn도 제공해 Claude, Codex, Gemini 사이의 상태 공유와 실패 세션 보정까지 다룬다.

실측 결과도 제시한다.

• Code search(100 results): 17,765 → 1,408 토큰, 92% 절감
• SRE incident debugging: 65,694 → 5,118 토큰, 92% 절감
• GitHub issue triage: 54,174 → 14,761 토큰, 73% 절감
• Codebase exploration: 78,502 → 41,254 토큰, 47% 절감

벤치마크에서는 GSM8K가 0.870을 유지했고 TruthfulQA는 0.530에서 0.560으로 소폭 상승했다. SQuAD v2와 BFCL도 각각 97% 성능을 보였다고 적시하며, python -m headroom.evals suite --tier 1로 재현할 수 있다고 안내한다.

Claude Code, Codex, Cursor, Aider, Copilot CLI, OpenClaw와의 호환 매트릭스도 담았다. OpenAI-compatible client는 headroom proxy로, MCP-native client는 headroom mcp install로 연결되며, Python 3.10+와 [proxy], [mcp], [ml], [agno], [langchain], [evals] 선택 설치를 지원한다.