| name | headroom |
| description | Compresión de contexto para agentes IA — reduce 60-95% los tokens de salidas de herramientas, logs, RAG y archivos antes de que lleguen al LLM. Library, proxy, MCP server, cross-agent memory, reversible compression. 19k⭐ |
| url | https://github.com/chopratejas/headroom |
| category | ia |
| fecha | 2026-06-08T00:00:00.000Z |
Headroom — Compresión de contexto para agentes IA
60–95% fewer tokens · library · proxy · MCP · 6 algorithms · local-first · reversible · cross-agent memory
¿Qué hace?
Headroom es una capa de compresión de contexto para agentes de IA. Comprime todo lo que el agente lee — salidas de herramientas, logs, chunks de RAG, archivos e historial de conversación — antes de que llegue al LLM. Mismas respuestas, fracción de tokens.
Arquitectura interna
ContentRouter → detecta tipo de contenido y selecciona compresor:
├─ SmartCrusher → comprime JSON
├─ CodeCompressor → compila AST para código
└─ Kompress-base → modelo HF para texto general
CacheAligner → estabiliza prefijos para KV cache hits
CCR (Compression-Compression-Retrieval) → almacena originales localmente;
el LLM llama a headroom_retrieve
si necesita los datos completos
Características principales (actualizado 2026-06-08)
- 6 algoritmos de compresión — heurístico, JSON, AST, modelo (Kompress-base en HF)
- 4 modos de uso:
- Library —
compress(messages) en Python o TypeScript
- Proxy —
headroom proxy --port 8787, cero cambios de código
- Agent wrap —
headroom wrap claude|codex|cursor|aider|copilot en un comando
- MCP Server —
headroom_compress, headroom_retrieve, headroom_stats
- Cross-agent memory — almacén compartido entre Claude, Codex, Gemini con auto-deduplicación
headroom learn — analiza sesiones fallidas y escribe correcciones a CLAUDE.md / AGENTS.md- Reversible (CCR) — los originales nunca se borran; el LLM los recupera bajo demanda
- Compatible con: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, LangChain, OpenAI, Anthropic, Agno, Strands
- 10,144 → 1,260 tokens en demo real (mismo FATAL encontrado)
Casos de uso
- Reducir coste de tokens en agentes que procesan grandes outputs de herramientas
- Extender ventana de contexto — más información en el mismo espacio de tokens
- Cross-agent memory — compartir contexto entre diferentes agentes IA
- RAG optimization — comprimir chunks de recuperación antes de pasarlos al LLM
headroom learn — aprender de sesiones fallidas y mejorar automáticamente- MCP integration — usar como servidor MCP para cualquier agente compatible
Snippets útiles
Python (library)
from headroom import compress
messages = [
{"role": "user", "content": "Revisa este log y dime qué salió mal"},
{"role": "assistant", "content": "Claro, déjame ver..."},
{"role": "user", "content": "log_output_very_large..."},
]
compressed = compress(messages)
Shell (proxy)
headroom proxy --port 8787
headroom wrap claude
headroom wrap codex
headroom wrap cursor
MCP Server
Cross-agent memory
headroom learn
headroom learn
Cómo integrarlo en Mastermind
Opción 1: Library en Python
pip install headroom-ai
Opción 2: Proxy transparente
pip install headroom-ai
headroom proxy --port 8787
Configurar el cliente HTTP de Mastermind para que use http://localhost:8787 como endpoint del LLM.
Opción 3: MCP Server
pip install headroom-ai
headroom mcp
Integrar como servidor MCP en la configuración de Hermes Agent.
Opción 4: Agent wrap (más fácil)
pip install headroom-ai
headroom wrap claude
Pitfalls
- Los algoritmos basados en modelo requieren descargar Kompress-base de HuggingFace (~200MB)
- El proxy puede añadir latencia adicional (compresión en tiempo real)
- No comprime imágenes ni binarios — solo texto
- Algunos algoritmos pueden perder información sutil en logs muy técnicos
- Cross-agent memory requiere configuración explícita del almacén compartido
Referencias
Fecha de descubrimiento
2026-06-08: 12.9k⭐ → 17.2k⭐ (+4.3k), trending diario+semanal, mayor crecimiento del período
2026-06-09: 17.2k⭐ → 19.1k⭐ (+1.9k), sigue subiendo rápido, 6 algoritmos de compresión, cross-agent memory, headroom learn
