CubeLabs

1. El problema: la inflación de tokens en los agentes

Cada turno de un agente de IA reenvía al modelo un contexto que crece sin control: salidas de herramientas (búsquedas de código, respuestas de APIs, logs), chunks de RAG, ficheros leídos, diffs, y todo el historial de la conversación. Ese contexto se paga por token, y además choca con la ventana de contexto del modelo.

Con cargas de trabajo reales de agentes, el desperdicio es enorme. Headroom publica mediciones sobre workloads reales:

Y la precisión se conserva: en GSM8K se mantiene exactamente (0.870 → 0.870), y en TruthfulQA incluso sube (+0.030). El ahorro no es "apretar texto a ciegas": es quitar lo que no aporta y comprimir lo que sí aporta de forma estructurada.

2. Qué es Headroom y cómo funciona

Headroom es una capa que se coloca entre tu agente/app y el proveedor de LLM. Comprime todo lo que el agente lee — prompts, salidas de herramientas, logs, resultados RAG, ficheros e historial — antes de que llegue al modelo. Corre en tu máquina: tus datos no salen de tu equipo (local-first).

El pipeline interno es:

Se integra de cuatro maneras, según tu caso:

3. Instalación y verificación

Headroom requiere Python 3.10+ y se instala con tu gestor favorito. El paquete de PyPI es headroom-ai e incluye el CLI headroom.

uv tool install --python 3.13 "headroom-ai[all]"

pip install "headroom-ai[all]"

npm install headroom-ai

headroom --version
headroom doctor

Los extras se instalan por separado cuando los necesitas: [proxy], [mcp], [ml] (modelo Kompress-v2-base), [code], [memory], [langchain], [agno], [evals]…

4. Modo Proxy: compresión sin cambiar código

El modo proxy levanta un endpoint local compatible con OpenAI. Cualquier cliente que apunte su base_url al proxy recibe compresión automática — cero cambios de código.

headroom proxy --port 8787

Luego apunta tu cliente al proxy:

# Python (OpenAI SDK)
from openai import OpenAI
client = OpenAI(base_url="http://localhost:8787/v1", api_key="tu-key")

# CLI
export OPENAI_BASE_URL="http://localhost:8787/v1"

El proxy también puede recortar lo que el modelo escribe de vuelta (los tokens de salida cuestan hasta 5× más):

export HEADROOM_OUTPUT_SHAPER=1     # off por defecto
headroom proxy --port 8787

• Verbosity steering — añade una nota "sé conciso, no repitas contexto" al final del system prompt (el caché de prompt sigue pegando).
• Effort routing — cuando el turno es solo reanudar tras un tool result, baja el esfuerzo de razonamiento; preguntas nuevas y errores mantienen el esfuerzo completo.

5. Modo Wrap: envuelve tu agente de código

El modo wrap es la vía más rápida para agentes de código: lanza el proxy local, instala Serena (navegación semántica de código) y arranca tu agente ya configurado para pasar por Headroom.

headroom wrap claude      # Claude Code
headroom wrap codex       # Codex (comparte memoria con Claude)
headroom wrap cursor      # imprime las base URLs para configurar Cursor
headroom wrap aider
headroom wrap opencode
headroom wrap grok

Para deshacer el wrapping de forma duradera:

headroom unwrap claude    # también: copilot, codex, grok, kimi, opencode, openclaw…

Matriz de compatibilidad (extraída del README oficial):

6. Modo Librería: compress() en Python

Si tu app construye los mensajes ella misma, la llamada compress() es lo más simple que existe:

from headroom import compress

messages = [
    {"role": "system", "content": "Eres un asistente de operaciones."},
    {"role": "user", "content": "Resume este incidente: " + tool_output},
]
compressed = compress(messages, model="gpt-4o")
# compressed.messages -> mensajes comprimidos
# compressed.tokens_saved -> 12345

También puedes medir antes de enviar con simulación (sin hacer llamada al LLM):

from headroom import simulate

result = simulate(messages)
print(result.summary)
# {'total_requests': 1, 'total_tokens_saved': 245, 'average_savings_percent': 12.3}

Para apps ASGI (FastAPI, etc.) hay middleware directo:

from headroom.asgi import CompressionMiddleware
app.add_middleware(CompressionMiddleware)

7. SDK TypeScript e integraciones con frameworks

En TypeScript/Node la API es equivalente:

import { compress } from 'headroom-ai';

const result = await compress(messages, { model: 'gpt-4o' });
// result.messages, result.tokensSaved

Y con los SDKs oficiales basta un wrapper:

import { withHeadroom } from 'headroom-ai';
import Anthropic from '@anthropic-ai/sdk';

const client = withHeadroom(new Anthropic());   // Anthropic SDK
const client2 = withHeadroom(new OpenAI());     // OpenAI SDK

Headroom se conecta a casi cualquier stack de agentes:

8. Compresores especializados: JSON, código, texto e imágenes

No todo se comprime igual. Headroom enruta cada tipo de contenido al compresor que mejor lo preserva:

La clave está en la live-zone compression: solo se comprimen los bytes nuevos (salida fresca de herramienta, último turno). El prefijo congelado permanece byte-idéntico para que el caché KV del proveedor siga pegando. El historial nunca se descarta.

9. CCR: compresión reversible con recuperación

La arquitectura CCR (Compress-Cache-Retrieve) hace la compresión prácticamente lossless: los originales se guardan en caché local y el LLM puede pedirlos cuando los necesita.

1. Compress — el contenido se comprime antes de enviarse al modelo.
2. Cache — el original se almacena localmente con un TTL.
3. Retrieve — si el modelo necesita el dato exacto, llama a la herramienta de recuperación y obtiene el original.

# Configura el TTL de la caché CCR (7200 s = 2 h)
HEADROOM_CCR_TTL_SECONDS=7200 headroom proxy

# Estado de la caché de recuperación
curl http://localhost:8787/v1/retrieve/stats

Este diseño es lo que permite afirmar "mismas respuestas, fracción de los tokens": el modelo nunca pierde acceso a la información completa — solo decide cuándo merece la pena recuperarla.

10. MCP, memoria cross-agent y monitoreo del ahorro

Servidor MCP

Headroom expone compresión, recuperación y estadísticas como herramientas MCP para cualquier host compatible:

headroom mcp install          # para hosts MCP (Claude Code, Cursor…)

# Config manual en el cliente MCP:
# [mcp_servers.headroom]
# command = "/ruta/absoluta/headroom"
# args = ["mcp", "serve"]

Herramientas disponibles: headroom_compress, headroom_retrieve y headroom_stats.

Memoria cross-agent y aprendizaje de fallos

La memoria es compartida entre agentes (Claude, Codex, Gemini, Grok) con procedencia por agente y auto-dedup. Y headroom learn mina tus sesiones fallidas y escribe correcciones en CLAUDE.local.md (gitignored), AGENTS.md o GEMINI.md:

headroom learn                      # analiza y muestra qué corregir (dry run)
headroom learn --apply              # escribe las correcciones en CLAUDE.local.md
headroom learn --target AGENTS.md   # o en el fichero de otro agente
headroom learn --verbosity --apply  # aprende el nivel de concisión que prefieres

Monitoreo del ahorro

headroom doctor        # health check — confirma que el routing funciona
headroom perf          # benchmark rápido
headroom savings       # ahorro acumulado: hoy / últimos 7 días / total, por modelo y cliente
headroom output-savings
# Reduction: 31.7%  (95% CI 27.7% … 35.7%)   [estimated]
headroom dashboard     # dashboard en vivo (requiere proxy en marcha)

Los ahorros de salida son contrafactuales (nunca vemos lo que el modelo habría escrito), así que Headroom reporta una estimación honesta con rango de confianza. Para una cifra medida, deja un 10% de conversaciones sin moldear como grupo de control: export HEADROOM_OUTPUT_HOLDOUT=0.1.