Compactación de Contexto en Agentes AI: Cómo Hermes, Codex, Claude Code y OpenCode gestionan la ventana de memoria

Cuando usas un agente AI para una sesión larga de programación, algo inevitable sucede: la conversación crece, los tool results se acumulan, y el contexto se acerca al límite del modelo. El agente empieza a “olvidar” cosas — el system prompt, instrucciones tempranas, decisiones clave. Y en el peor caso, la API devuelve un error de context_length_exceeded y la sesión muere.

La solución se llama compactación de contexto (context compaction). No se trata de expandir la memoria del modelo, sino de aprender a olvidar con precisión: conservar lo esencial, descartar el ruido, y hacerlo gastando el mínimo de tokens posible en el proceso.

Este artículo analiza cómo cuatro sistemas de agentes AI implementan esta funcionalidad crítica. Hermes Agent, Codex CLI, Claude Code y OpenCode tienen enfoques radicalmente distintos — desde la doble capa de seguridad de Hermes hasta las tres fases progresivas de Claude Code — pero todos convergen en un patrón común.

¿Qué es la compactación de contexto y por qué importa?

Cada turno en una conversación con un agente AI añade tokens al historial. El system prompt (con definiciones de herramientas, instrucciones, memoria persistente), los mensajes del usuario, las respuestas del asistente, las tool calls y los tool results — todo se acumula.

En una sesión típica de depuración, los tool results representan ~80% de los tokens totales. Una búsqueda con grep puede devolver 2,000 tokens; leer un archivo de 300 líneas suma 3,500; una ejecución de tests con stack traces añade otros 3,000. Estos datos fueron críticos durante la depuración, pero una vez que el bug está resuelto, son lastre.

Sin compactación, el agente tiene tres opciones, todas malas:

1. Fallar con un error de contexto excedido, perdiendo todo el progreso
2. Ignorar instrucciones tempranas porque el contexto se desbordó por tool results
3. Costar una fortuna porque cada turno cuesta tokens de input proporcionales al historial acumulado

La compactación resuelve esto reemplazando el historial medio (old tool results, conversación resuelta, debugging completado) con un resumen estructurado, preservando la cabeza (system prompt + primer intercambio) y la cola (turns recientes). Es una inversión: gastas unos centavos en un LLM barato para generar el resumen, y ahorras ese costo en cada turno futuro.

Hermes Agent: el sistema de doble capa

Hermes Agent, desarrollado por Nous Research, tiene el sistema de compactación mejor documentado y más configurable de los cuatro. Su arquitectura usa dos capas independientes que operan en distintos puntos del flujo.

Capa 1: Gateway Session Hygiene (85% del contexto)

Esta capa vive en gateway/run.py y se ejecuta antes de que el agente procese un mensaje entrante. Es un safety net para sesiones que crecen sin control entre turnos — por ejemplo, una sesión de Telegram que acumula mensajes mientras el agente no está activo.

• Umbral: fijo al 85% del contexto del modelo
• Fuente de tokens: usa tokens reales reportados por la API si están disponibles; fallback a estimación por caracteres
• Disparo: solo cuando len(history) >= 4 y la compresión está habilitada
• Propósito: atrapar sesiones que escaparon al compressor del agente

El umbral de gateway está intencionalmente más alto que el del agente. Ponerlo al 50% (igual que el agente) causaba compresiones prematuras en cada turno de sesiones gateway largas.

Capa 2: Agent ContextCompressor (50% del contexto, configurable)

Esta es la capa principal, en agent/context_compressor.py. Corre dentro del tool loop del agente con acceso a contajes de tokens precisos del API.

Configuración típica:

compression:
  threshold: 0.50          # Fracción del contexto que dispara compresión
  target_ratio: 0.20       # Qué fracción del threshold preservar como cola
  protect_last_n: 20       # Mínimo de mensajes recientes protegidos

Para un modelo con 200K de contexto, la compresión se dispara al alcanzar ~100K tokens. La cola protegida recibe ~20K tokens, y el resumen tiene un presupuesto de hasta 10K tokens.

Algoritmo de 4 fases

La magia está en cómo ContextCompressor.compress() transforma 45 mensajes y ~95K tokens en 25 mensajes y ~45K tokens.

Fase 1: Podar tool results viejos (sin LLM, costo ~cero)

Los tool results >200 caracteres que están fuera de la cola protegida se reemplazan con un placeholder: [Old tool output cleared to save context space]. Esto libera una enorme cantidad de tokens sin necesidad de llamar a ningún modelo.

El agente recuerda que ejecutó un comando, pero no el output exacto. Si necesita el detalle, puede re-ejecutarlo.

Fase 2: Determinar límites

[0..2]   ← protege primeros 3 mensajes (system + primer intercambio)
[3..N]   ← turns del medio → serán resumidos
[N..end] ← cola protegida (por budget de tokens O protect_last_n)

La protección de cola camina hacia atrás desde el final acumulando tokens hasta agotar el budget. Si el budget protegería menos mensajes que protect_last_n, se usa el mínimo fijo.

Los límites se alinean para no partir grupos tool_call/tool_result. El método _align_boundary_backward() camina hacia atrás a través de tool results consecutivos para encontrar el mensaje assistant padre.

Fase 3: Resumen estructurado vía LLM auxiliar

La sección media se envía a un modelo auxiliar (configurable, típicamente más barato que el principal) con una plantilla de 8 secciones:

## Goal
[Qué intenta lograr el usuario]

## Constraints & Preferences
[Preferencias, estilo de código, decisiones importantes]

## Progress
### Done
[Trabajo completado — paths específicos, comandos, resultados]
### In Progress
[Trabajo en curso]
### Blocked
[Bloqueos o issues encontrados]

## Key Decisions
[Decisiones técnicas importantes y por qué]

## Relevant Files
[Archivos leídos, modificados o creados]

## Next Steps
[Qué debe pasar después]

## Critical Context
[Valores específicos, mensajes de error, detalles de configuración]

El presupuesto del resumen escala con el contenido a comprimir: content_tokens × 0.20, con mínimo de 2,000 y máximo de min(context_length × 0.05, 12,000).

Fase 4: Ensamblar mensajes comprimidos

Se construye una nueva lista de mensajes:

• Mensajes de cabeza (con una nota añadida al system prompt en la primera compresión: “Algunos turns anteriores fueron compactados…”)
• Mensaje de resumen (con rol elegido para evitar violaciones de roles consecutivos)
• Cola (mensajes recientes sin modificar)

_sanitize_tool_pairs() limpia pairs huérfanos: tool results que referencian calls eliminados se remueven, tool calls cuyo resultado se eliminó reciben un stub.

Re-compresión iterativa

En compresiones subsecuentes, el resumen anterior se pasa al LLM con instrucciones de actualizarlo, no resumir desde cero. Items pasan de “In Progress” a “Done”, se añade nuevo progreso, y se elimina información obsoleta.

Prompt Caching (Anthropic)

Hermes también integra Prompt Caching para modelos Anthropic, en agent/prompt_caching.py. La estrategia system_and_3 coloca 4 breakpoints de cache:

• Breakpoint 1: System prompt (estable siempre)
• Breakpoints 2-4: Últimos 3 mensajes no-system (rolling window)

Esto reduce costos de input ~75% en conversaciones multi-turno sin sacrificar información.

Codex CLI: el handoff summary

OpenAI Codex CLI adopta un enfoque más simple pero igualmente efectivo: una sola capa de compresión que lo reemplaza todo con un resumen “handoff”.

Diseño de doble ruta

Codex ofrece dos caminos de compresión:

• Ruta local (compact.rs): el cliente llama a un LLM para generar el resumen. Funciona con cualquier proveedor de modelos.
• Ruta remota (compact_remote.rs): llama al endpoint interno de OpenAI responses/compact. El servidor de OpenAI maneja la compresión, probablemente con modelos especializados y caché interna.

En ambos casos la compresión requiere una llamada LLM. La diferencia es dónde se ejecuta: la ruta local orquesta todo desde el cliente; la remota subcontrata el paso de “generar resumen” a OpenAI.

El prompt de compresión

You are performing a CONTEXT CHECKPOINT COMPRESSION. Create a handoff
summary for another LLM that will resume the task.

Include:
- Current progress and key decisions made
- Important context, constraints, or user preferences
- What remains to be done (clear next steps)
- Any critical data, examples, or references needed to continue

Be concise, structured, and focused on helping the next LLM seamlessly
continue the work.

La palabra clave es handoff — no son minutas de reunión, sino un briefing para que el próximo modelo pueda retomar el trabajo sin perder el paso.

Preservación de mensajes del usuario

Una característica distintiva de Codex: preserva los mensajes del usuario verbatim. Solo comprime respuestas del asistente y resultados de herramientas. Esto significa que el agente siempre puede ver lo que el usuario dijo originalmente, aunque reduce la eficiencia de compresión cuando los mensajes del usuario son largos.

Fallback: head trimming

Si después de la compresión aún falta espacio, Codex recurre a head trimming — corta desde los mensajes más antiguos. Esto es destructivo y se considera último recurso.

Claude Code: tres capas de precisión

Anthropic’s Claude Code tiene el sistema más sofisticado de los cuatro, con tres capas progresivas que van de lo más barato a lo más costoso.

Claude Code no es open source. Este análisis se basa en ingeniería inversa de la comunidad y materiales públicos.

Capa 1: Tool Result Trimming (costo LLM = cero)

Esta capa corre automáticamente antes de cada request. Sin llamadas al LLM — es puramente un motor de reglas local.

La lógica:

• Protege los resultados de las tool calls más recientes
• Tool results viejos → reemplazados con [Old tool result content cleared]

El agente recuerda que ejecutó una búsqueda, pero no el resultado. Si necesita el detalle, puede re-ejecutar el comando. Es amnesia selectiva, no olvido total.

Capa 2: Cache-Friendly Strategy

Esta es la ventaja única de Claude Code. Anthropic soporta Prompt Cache: si el prefijo de tu mensaje al API coincide con el request anterior, el servidor reusa cómputos previos, reduciendo drásticamente costo y latencia.

Cuando limpia mensajes, Claude Code deliberadamente evita modificar la primera mitad de la secuencia. Prefiere cortar del final, manteniendo el principio idéntico para maximizar cache hits.

El trade-off: menor eficiencia de limpieza, pero máxima tasa de cache. Para tareas largas (refactorizar un módulo completo), esto se traduce en ahorros significativos — pagas solo por el contenido nuevo al final.

Capa 3: Structured LLM Summary (último recurso, 9 secciones)

Cuando las dos primeras capas no son suficientes, se dispara el resumen completo. El umbral de auto-compactación es: ventana efectiva - 13,000 tokens.

Antes de llamar al LLM, el sistema intenta Session Memory Compact — usar información estructurada ya en memoria de sesión. Solo cuando esto no es posible cae al resumen LLM tradicional, que genera 9 secciones fijas:

1. Intención original del usuario
2. Conceptos técnicos centrales
3. Archivos y código relevantes
4. Errores encontrados y cómo se corrigieron
5. Cadena lógica de resolución de problemas
6. Resumen de todos los mensajes del usuario
7. Tareas pendientes
8. Qué se está trabajando ahora
9. Próximos pasos sugeridos

El prompt exige citas textuales de frases clave del original, no paráfrasis. Esto previene el “context drift” — que el modelo sutilmente se desvíe del significado original al recontar.

Post-compresión

Después de comprimir, Claude Code ejecuta una serie de pasos de reconstrucción de estado:

• Inyecta un lead-in: “This session continues from a previous conversation…”
• Re-lectura automática de hasta 5 archivos editados recientemente (budget de 50K tokens, 5K por archivo)
• Redeclara tool definitions y skill definitions
• Las especificaciones en CLAUDE.md (system prompt) permanecen intactas

También hay un fallback pasivo: si el API devuelve prompt_too_long, inicia compresión reactiva y reintenta. Se pausa tras 3 fallos consecutivos para evitar loops infinitos.

OpenCode: stepped governance con ocultación no destructiva

OpenCode (archivado, anteriormente sst/opencode) ofrece la estrategia más equilibrada, implementada en session/compaction.ts con Effect-TS.

Paso 1: Prune (ocultar, no borrar)

La primera acción no es borrar — es marcar. OpenCode añade un timestamp compacted = Date.now() a los mensajes viejos, haciéndolos invisibles en requests subsecuentes. Los datos siguen en la base de datos.

Reglas:

• Solo se ejecuta si puede liberar >20K tokens
• Siempre preserva los últimos 40K tokens como colchón de seguridad
• Tool outputs de tipo skill nunca se podan
• Protege el contenido completo de los últimos 2 turns del usuario

Esta es una decisión de diseño visionaria: los datos no se pierden realmente. Deja espacio para futuras auditorías, rollbacks, o funcionalidades de historial.

Paso 2: LLM Summary de 5 secciones

Si después del prune aún hay problemas, OpenCode usa un agente oculto dedicado (sin interrumpir al usuario) que genera un resumen con 5 secciones fijas:

1. Qué se hizo
2. Qué se está trabajando ahora
3. Archivos modificados
4. Próximos pasos
5. Decisiones técnicas importantes

Auto-replay del último mensaje

La característica más inteligente de OpenCode: después de la compactación, el sistema reenvía automáticamente el último mensaje del usuario. El usuario ni siquiera nota que ocurrió la compresión — su último mensaje se reprocesa, el agente responde, como si nada hubiera pasado.

OpenCode también sigue el idioma del usuario: si la conversación es en español, el resumen se genera en español.

Tabla comparativa

El patrón común

A pesar de las diferencias, los cuatro sistemas convergen en un patrón compartido:

1. Poda barata primero: antes de llamar al LLM, todos tienen una fase de limpieza mecánica (tool results → placeholder/ocultación). Esto libera 50-80% del espacio sin gastar un token.
2. Cabeza y cola siempre protegidas: el system prompt y los mensajes recientes nunca se tocan. Lo que se resume es la sección media, donde está el trabajo ya completado.
3. Resumen estructurado: el formato libre no funciona. Todos usan plantillas con secciones fijas (entre 4 y 9) que guían al modelo sumarizador.
4. Modelo auxiliar más barato: nadie usa el modelo principal para resumir. La compactación se delega a un modelo secundario (a menudo 10-100× más barato).
5. Post-procesamiento: después de comprimir, todos hacen algo para evitar que el agente se “desoriente” — reenviar el último mensaje, re-leer archivos, inyectar prefijos.

¿Vale la pena? La matemática de la inversión

La compactación de contexto gasta tokens ahora para ahorrar después. ¿Tiene sentido?

Para un modelo como DeepSeek V4 Flash a $0.28/1M tokens de output:

• Costo de una compactación: generar un resumen de ~2,000 tokens → ~$0.0006
• Ahorro por turno posterior: un historial compactado de 45K tokens vs 95K tokens → ahorro de $0.014 por turno solo en input
• Punto de equilibrio: después de ~1 turno, la compactación ya se pagó sola
• Retorno a 20 turnos: 20× más barato que sin compactación

Para un modelo premium como Claude Opus 4.8 a $25/1M tokens de output:

• Costo de compactación: ~$0.05 (modelo auxiliar más barato)
• Ahorro por turno: ~$1.25
• Retorno a 20 turnos: 25× más barato

La compactación no es un lujo — es un requisito económico para que los agentes AI puedan trabajar en sesiones largas sin arruinarte en costos de API.

Implicaciones para el desarrollo de agentes

Si estás construyendo tu propio agente o eligiendo uno existente, estas son las preguntas correctas:

• ¿Cuántas capas de compresión necesitas? Una capa (como Codex) es suficiente para sesiones cortas. Dos capas (como Hermes) dan seguridad contra escapes. Tres capas (como Claude Code) optimizan costos en sesiones muy largas.
• ¿Es importante la irreversibilidad? OpenCode es el único que no destruye datos. Si haces auditorías o necesitas rollbacks, su enfoque de timestamp es superior.
• ¿Usas Anthropic? La integración Prompt Cache de Claude Code o Hermes puede reducir tus costos ~75% en sesiones multi-turno.
• ¿El modelo auxiliar importa? Mucho. Si tu modelo auxiliar tiene una ventana de contexto menor que el principal, las compactaciones fallarán silenciosamente (Hermes documenta esto como “la causa más común de degradación”).

Al final, los cuatro sistemas demuestran que la mejor gestión de contexto no es expandir la memoria del modelo, sino aprender a olvidar con precisión.

Fuente principal: Hermes Agent Documentation — Context Compression and Caching | Código fuente: Hermes Agent, Codex CLI, OpenCode (archivado)