ntizar Headroom — Capa de Compresión de Contexto para Agentes IA
Repo: https://github.com/headroomlabs-ai/headroom (69K⭐, Python+Rust, Apache-2.0, verificado 2026-09-06 contra README real)
Qué es
Comprime salidas de herramientas, logs, ficheros y chunks RAG antes de que lleguen al LLM: ~20% menos tokens en salidas de coding agents, 60-95% en JSON repetitivo, con las mismas respuestas. Corre local (los datos no salen de la máquina) y es librería + proxy + servidor MCP a la vez. Encaja con token-tracking de Mastermind: reduce coste real de sesiones Hermes/NaN.
Diferenciadores (README, sección "Compared to"): scope total de contexto (no solo historia), proxy local reversible — los originales se guardan en CCR y el modelo los recupera con headroom_retrieve.
Arquitectura (pipeline por request)
CacheAligner → ContentRouter → {SmartCrusher (JSON), CodeCompressor (AST), Kompress-v2-base (prosa, HF)}
- ContentRouter detecta el tipo de contenido y elige el compresor.
- SmartCrusher: JSON universal — conserva items de error, valores fuera de rango estadístico y bordes primero/último (por varianza de campos, no por keywords).
- CodeCompressor: AST-aware Python/JS/TS/Go/Rust/Java/C/C++/Perl.
- CacheAligner: marca contenido volátil que rompería el prefijo KV-cache del proveedor; NUNCA reescribe prompts.
- Live-zone: solo se comprimen bytes nuevos; el prefijo congelado queda byte-idéntico → la cache del proveedor sobrevive.
- Compresión <1 ms (0.21 ms p50 en 10K tokens JSON) — no añade latencia.
Instalación y modos de uso (verificados del README)
pip install "headroom-ai[all]" # Python — incluye la CLI `headroom`
uv tool install --python 3.13 "headroom-ai[all]" # CLI aislada
npm install headroom-ai # SOLO SDK TypeScript, sin CLI
headroom proxy --port 8787 # proxy drop-in, cero cambios de código
headroom wrap claude # envuelve un agente (arranca proxy + Serena + config)
headroom deploy # despliegue local llave en mano
headroom doctor # health check del routing
headroom dashboard # ahorros en vivo
headroom savings # nº de ahorro sobre TU tráfico
Librería Python:
from headroom import compress
result = compress(messages, model="gpt-4o") # result.messages, result.tokens_saved, result.compression_ratio
Integraciones: Anthropic/OpenAI SDK (withHeadroom(new OpenAI())), LangChain (HeadroomChatModel), LiteLLM (HeadroomCallback), ASGI (CompressionMiddleware), multi-agente (SharedContext), MCP (headroom mcp install).
Reducción de tokens de SALIDA (proxy, opcional)
export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787
- Verbosity steering: añade nota "sé breve" al final del system prompt (la cache sigue impactando).
- Effort routing: baja
reasoning_effort(OpenAI) /thinking.budget_tokens(Anthropic) en turnos rutinarios post-tool-result. headroom learn --verbosityinfiere la concisión deseada de sesiones pasadas.
Pitfalls
- Python 3.13 para el dólar: el dashboard "Proxy $ Saved" usa LiteLLM, que no se instala en 3.14+. Con 3.14 los tokens se ahorran pero la cifra $ queda en 0.
- npm
headroom-aies solo librería — no provee el comandoheadroom. - Clientes MCP sin PATH heredado (Codex): poner la ruta absoluta de
command -v headroomen la config TOML. - Prosa ya densa y payloads cortos apenas se comprimen (bloque bajo
min_input_wordsvuelve byte-idéntico) — el ahorro escala con la repetitividad. - ONNX (detección Magika + relevancia embebida) requiere AVX2 en x86; sin él cae a BM25/heurísticas (no rompe).
- Beacon de telemetría ON por defecto:
HEADROOM_BEACON=offoDO_NOT_TRACK=1. - En redes con inspección SSL corporativa puede fallar el build maturin/rustup: instalar Rust antes o usar wheel:
pip install --only-binary headroom-ai headroom-ai.
Cuándo usarlo en Mastermind
- Sesiones Hermes largas con outputs de tool masivos (scraping, dumps API ESIOS/GTFS) →
headroom proxy+--1m-style savings. - Dashboards/pipelines JSON pesados: el caso SRE del README pasa 55.957 → 24.340 tokens (57%).
- Comparativa:
memory-context-engine/supermemory= memoria y retrieval;dspy= optimización de prompts; headroom = compresión del contexto ya assembled — son complementarios, no sustitutos.
Verificación
headroom doctor → routing OK; correr un compress() sobre un JSON de 10K tokens propio y comprobar compression_ratio y que las líneas de error sobreviven byte a byte.