headroom

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

1. Reducir coste de tokens en agentes que procesan grandes outputs de herramientas
2. Extender ventana de contexto — más información en el mismo espacio de tokens
3. Cross-agent memory — compartir contexto entre diferentes agentes IA
4. RAG optimization — comprimir chunks de recuperación antes de pasarlos al LLM
5. headroom learn — aprender de sesiones fallidas y mejorar automáticamente
6. 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)
# Misma respuesta útil, 60-95% menos tokens

Shell (proxy)

# Iniciar proxy en puerto 8787
headroom proxy --port 8787

# Wrap directo en un agente
headroom wrap claude
headroom wrap codex
headroom wrap cursor

MCP Server

# Herramientas MCP disponibles:
# headroom_compress - comprime contenido
# headroom_retrieve - recupera original comprimido
# headroom_stats - estadísticas de compresión

Cross-agent memory

# Almacén compartido entre agentes
# Los datos se deduplican automáticamente
# Útil para mantener contexto consistente
# entre Claude, Codex y Gemini

headroom learn

# Analiza sesiones fallidas y escribe
# correcciones en CLAUDE.md / AGENTS.md
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  # o codex, cursor, aider, copilot

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

• Documentación oficial
• Arquitectura
• CCR reversible compression
• Kompress-base model card
• Discord de la comunidad
• llms.txt — índice para LLMs

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