headroom

Headroom es una capa de compresión de contexto para agentes de IA. Comprime todo lo que un agente lee — salidas de herramientas, logs, fragmentos RAG, archivos e historial de conversaciones — antes de que lleguen al LLM, con el objetivo de mantener la integridad de las respuestas mientras se reduce el uso de tokens. La compresión se ejecuta localmente; los prompts y contenidos de archivos no se envían a ningún otro lugar para ser comprimidos. Funcionalidades: - Biblioteca: `compress(messages)` en Python o TypeScript, usable directamente en cualquier aplicación. - Proxy: `headroom proxy --port 8787` es un proxy local de reemplazo que no requiere cambios de código y funciona con cualquier cliente compatible con OpenAI. - Envoltorio de agente: `headroom wrap` soporta 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 y otros; `headroom unwrap` deshace la configuración. - Servidor MCP: expone las herramientas `headroom_compress`, `headroom_retrieve` y `headroom_stats` para cualquier cliente MCP. - Memoria cruzada entre agentes: un almacén compartido y deduplicado entre Claude, Codex, Gemini y Grok. - `headroom learn`: analiza sesiones fallidas y escribe correcciones en `CLAUDE.local.md` (por defecto, ignorado por git) u otros archivos de instrucciones del agente. - Reducción de tokens de salida: dirección opcional de verbosidad y enrutamiento de esfuerzo del proxy para recortar tokens que el modelo escribe de vuelta, no solo los enviados. - Compresión reversible (CCR): los originales se almacenan en caché localmente y se recuperan bajo demanda mediante `headroom_retrieve`. Funcionamiento: un ContentRouter detecta el tipo de contenido y selecciona un compresor — SmartCrusher para JSON, CodeCompressor (con conciencia de AST, compatible con Python, JS/TS, Go, Rust, Java, C/C++ y Perl) y Kompress-v2-base (un modelo de Hugging Face entrenado con trazas de agentes) para texto. CacheAligner marca contenido volátil que invalidaría el prefijo de caché KV del proveedor sin reescribir prompts; la compresión en zona activa mantiene el prefijo congelado idéntico en bytes para que las cachés del proveedor persistan. Se proporcionan adaptadores para SDKs de Anthropic/OpenAI, Vercel AI SDK, LiteLLM, LangChain, Agno, Strands, aplicaciones ASGI y SharedContext multi-agente. El README reporta benchmarks offline con datos sembrados: ahorro del 21% en búsqueda de código, 57% en depuración de incidentes de SRE, 42% en exploración de bases de código y 30% en clasificación de issues de GitHub, con cargas repetidas de JSON/logs que logran limpiezas del 90%. La latencia de compresión se informa en menos de un milisegundo a 10K tokens. Las evaluaciones de precisión en el README muestran ninguna diferencia detectable en GSM8K y TruthfulQA, y 97% en SQuAD v2 y BFCL con compresión del 19–32%. Instalación: `uv tool install --python 3.13 "headroom-ai[all]"`, `pip install "headroom-ai[all]"`, `npm install headroom-ai` (solo SDK de TypeScript, sin CLI), o imagen Docker `ghcr.io/headroomlabs-ai/headroom`. Requiere Python 3.10+. Licenciado bajo Apache 2.0. Extras granulares incluyen `[proxy]`, `[mcp]`, `[ml]`, `[code]`, `[memory]`, `[vector]`, `[image]` y adaptadores de framework.