Compresión de Contexto: 4 Niveles para No Perder Nada
Tu conversación con Claude Code puede durar horas, pero la ventana de contexto tiene un límite físico. Así es como un sistema de 4 niveles de compresión, un resumen de 9 secciones y una "sección sagrada" garantizan que nunca se pierda una instrucción tuya.
En el artículo anterior desmontamos las 18 secciones del system prompt de Claude Code. Pero hay un problema que el system prompt no resuelve: ¿qué pasa cuando tu conversación crece tanto que ya no cabe en la ventana de contexto?
La ventana por defecto es de 200K tokens. Con el beta flag context-1m, puede llegar a un millón. Pero incluso un millón de tokens tiene límite. Y en sesiones de programación intensas — debug de errores encadenados, refactoring de archivos grandes, consultas de documentación — es normal quemar contexto rápido.
La solución de Claude Code no es un solo mecanismo. Es un sistema de 4 niveles de compresión progresiva — cada nivel más agresivo que el anterior, activándose solo cuando el anterior ya no basta. Una defensa en profundidad donde el objetivo es claro: nunca perder una instrucción del usuario.
⚡ Tesis de este artículo
Claude Code usa un sistema de compresión de contexto de 4 niveles progresivos: desde limpiar resultados de herramientas antiguos hasta resumir toda la conversación en 9 secciones XML. El nivel 3 contiene una "sección sagrada" — las instrucciones del usuario — que nunca se omiten bajo ninguna circunstancia.
Tu conversación nunca termina, pero la ventana sí
Piénsalo como la memoria RAM de un ordenador. Tienes una cantidad finita, y cuantos más programas abres, más se llena. El sistema operativo no cierra tus programas — comprime datos, mueve cosas al disco y libera espacio manteniendo la ilusión de que tienes memoria infinita.
Claude Code hace exactamente lo mismo con tu conversación. La analogía es precisa:
🖥️ Sistema Operativo
- • CPU cache → datos calientes, acceso inmediato
- • L1/L2 cache → datos frecuentes, acceso rápido
- • RAM → datos activos, acceso normal
- • Disco → datos fríos, acceso lento
🤖 Claude Code
- • Tier 0 → todo en contexto, sin compresión
- • Tier 1 → limpia tool results viejos
- • Tier 2 → el servidor limpia bloques enteros
- • Tier 3 → resumen completo de 9 secciones
La constante que gobierna todo es simple: Claude Code mide el tamaño de la conversación en tokens usando una heurística rápida — BYTES_PER_TOKEN = 4. No cuenta tokens reales (eso requeriría un tokenizador), sino que divide los bytes por 4. Es impreciso pero predecible y barato.
// Constantes centrales del sistema de compresión const BYTES_PER_TOKEN = 4; const MAX_INPUT_TOKENS = 180_000; // Umbral para activar compresión const TARGET_COMPACT_TOKENS = 40_000; // Objetivo post-compresión const AUTOCOMPACT_BUFFER_TOKENS = 10_000; // Buffer de seguridad const POST_COMPACT_TOKEN_BUDGET = 50_000; // Presupuesto de re-inyección
Los 4 Tiers de un vistazo
| Tier | Nombre | Estrategia | Agresividad |
|---|---|---|---|
| 0 | Normal | Sin compresión. Todos los tool results intactos. | Ninguna |
| 1 | Microcompact | Limpieza quirúrgica de tool results antiguos inline. | Baja |
| 2 | API-Native | El servidor elimina thinking y tool_use completos. | Media |
| 3 | Full Compaction | Resumen de 9 secciones. Reescritura total de la conversación. | Máxima |
Operación Normal — Sin Compresión
En operación normal, Claude Code no toca el contexto. Cada resultado de herramienta, cada bloque de pensamiento, cada mensaje del usuario y del asistente — todo permanece en la ventana de contexto tal cual.
La ventana por defecto es de 200,000 tokens. Con el beta header context-1m, se expande a 1 millón. A 4 bytes por token, 200K tokens equivalen a ~800KB de texto — unas 130,000 palabras. Para sesiones cortas o medianas, esto es más que suficiente.
El sistema monitorea el uso de contexto en cada turn. Cuando se acerca a MAX_INPUT_TOKENS (180K), el sistema comienza la escalada hacia el Tier 1.
Microcompact — Limpieza Quirúrgica
El primer nivel de compresión es la forma más gentil de liberar espacio. Funciona reemplazando los resultados de herramientas antiguas in-place — el mensaje original queda en la conversación, pero su contenido se sustituye por un marcador.
// El texto de reemplazo es siempre el mismo: "[Old tool result content cleared]" // Herramientas compactables (tienen resultados reproducibles): const COMPACTABLE_TOOLS = [ 'FileRead', // Puedes re-leer el archivo 'Bash', // Puedes re-ejecutar el comando 'Grep', // Puedes re-buscar 'Glob', // Puedes re-listar 'WebSearch', // Puedes re-buscar en web 'WebFetch', // Puedes re-descargar 'FileEdit', // El diff ya se aplicó 'FileWrite', // El archivo ya se escribió ];
La lógica de selección es temporal: se limpian los resultados más antiguos primero, preservando los N más recientes. Esto se basa en una premisa razonable: si leíste un archivo hace 50 turnos, probablemente ya no necesitas ver su contenido literal. Si lo necesitas de nuevo, Claude puede volver a leerlo.
💡 ¿Por qué no limpiar todo? Solo se limpian herramientas cuyos resultados son reproducibles. Si puedes volver a leer un archivo o re-ejecutar un grep, perder el resultado antiguo tiene coste mínimo. Resultados de herramientas con efectos secundarios (como un git commit) nunca se limpian.
El microcompact es elegante porque no altera la estructura de la conversación. El modelo sigue viendo que usó una herramienta y en qué orden — solo pierde los detalles del resultado. Es como borrar la salida de un comando en tu terminal pero mantener el historial de qué comandos ejecutaste.
API-Native — El Servidor Decide
Cuando el Tier 1 no libera suficiente espacio, Claude Code activa la gestión de contexto del lado del servidor. Esto usa el beta header context-management-2025-06-27 de la API de Anthropic.
A diferencia del Tier 1, que opera en el lado del cliente manipulando mensajes, el Tier 2 le dice al servidor de Anthropic: "elimina estos bloques enteros de la conversación". Hay dos estrategias disponibles:
clear_tool_uses
Elimina completamente bloques de tool_use y tool_result antiguos de la conversación. No los marca como limpiados — los borra. El modelo ya no sabe que usó esas herramientas.
clear_thinking
Elimina los bloques de thinking (razonamiento extendido) de turns antiguos. El pensamiento del modelo tiende a ser verbose — limpiarlo puede liberar miles de tokens sin perder los resultados reales.
// Umbrales del Tier 2 if (inputTokens > MAX_INPUT_TOKENS) { // 180,000 // Activar gestión de contexto server-side headers['anthropic-beta'] = 'context-management-2025-06-27'; // Objetivo: reducir a TARGET_COMPACT_TOKENS targetTokens = TARGET_COMPACT_TOKENS; // 40,000 }
La diferencia clave con el Tier 1 es que el Tier 2 elimina bloques enteros, no solo contenidos. Es más agresivo, pero sigue siendo determinista — no hay interpretación ni resumen, solo borrado selectivo de secciones.
Compactación Total — El Resumen de 9 Secciones
Cuando ni el microcompact ni la gestión API-native son suficientes, Claude Code despliega su arma definitiva: un agente dedicado que resume toda la conversación en un formato XML estructurado de 9 secciones.
Esto no es un resumen libre. Es un template estricto que el agente de compactación debe seguir. La salida tiene dos partes: un bloque <analysis> (razonamiento interno) y un bloque <summary> (el resumen final). Solo el bloque <summary> se inyecta como nueva conversación.
Las 9 secciones obligatorias son:
El objetivo principal del usuario. Qué se intenta lograr en la conversación.
Tecnologías, frameworks, APIs y conceptos técnicos discutidos.
Lista de archivos tocados, qué cambios se hicieron, estado actual.
Errores encontrados y cómo se solucionaron. Crítico para no repetir intentos fallidos.
Estrategias intentadas, razonamiento de diseño, decisiones técnicas tomadas.
MUST NOT OMIT ANY user messages. Todas las instrucciones, preguntas y clarificaciones del usuario se preservan íntegramente. Esta sección es la que garantiza que ninguna instrucción del usuario se pierda jamás, sin importar cuánto se comprima la conversación.
Tareas que quedaron por hacer. Evita que la compactación genere amnesia sobre work-in-progress.
En qué se estaba trabajando exactamente cuando se activó la compactación.
Sugerencia del siguiente paso lógico para continuar el trabajo.
🛡️ La Sección 6 es "sagrada". El prompt del agente de compactación dice explícitamente: "MUST NOT OMIT ANY user messages". Se formatea todo como citas textuales. Es la garantía fundamental del sistema: no importa cuánto se comprima la conversación, tus instrucciones se preservan íntegramente.
// Formato XML del resumen de compactación <analysis> ... razonamiento interno del agente de compactación ... </analysis> <summary> <section title="Primary Request & Goal">...</section> <section title="Key Technical Concepts">...</section> <section title="Files & Code Modified">...</section> <section title="Errors & Fixes">...</section> <section title="Problem Solving Approach">...</section> <section title="All User Messages"> // Aquí van TODOS los mensajes del usuario, sin omitir ninguno User: "Refactoriza el módulo de auth para usar JWT" User: "Ah, y asegúrate de que el refresh token expire en 7 días" User: "Cambia el nombre del campo de 'token' a 'accessToken'" ... </section> <section title="Pending Tasks">...</section> <section title="Current Work">...</section> <section title="Optional Next Step">...</section> </summary>
Recuperación Post-Compactación
Después de ejecutar el Tier 3, la conversación se ha reducido dramáticamente — de potencialmente 200K+ tokens a un resumen estructurado. Pero un resumen solo no es suficiente para que el modelo retome el trabajo efectivamente. Claude Code ejecuta un proceso de recuperación que re-inyecta contexto crítico.
// Presupuesto de recuperación post-compactación const POST_COMPACT_TOKEN_BUDGET = 50_000; // 1. Restaurar los 5 archivos más recientemente usados const RECENT_FILES_COUNT = 5; const MAX_TOKENS_PER_FILE = 5_000; // Total: hasta 25,000 tokens en archivos // 2. Restaurar skills activos const SKILL_RESTORE_BUDGET = 25_000; // Skills que estaban en uso cuando se compactó
El proceso sigue dos pasos:
1. Restauración de archivos recientes
Los 5 archivos que el modelo estaba leyendo o editando más recientemente se re-inyectan en el contexto, cada uno con un máximo de 5,000 tokens. Esto le da al modelo un "vistazo" inmediato a los archivos en los que estaba trabajando, sin necesidad de volver a leerlos desde cero.
2. Restauración de skills activos
Si la conversación tenía skills cargados (documentación, instrucciones especiales, contexto de herramientas MCP), se re-inyectan hasta un presupuesto de 25,000 tokens. Esto asegura que el modelo no pierda conocimiento especializado adquirido durante la sesión.
La post-recuperación es lo que diferencia la compactación de Claude Code de un simple "truncar la conversación". No pierdes el contexto — lo comprimes y luego restauras lo más importante. Es como despertar de un sueño con un post-it de las 5 cosas más importantes en tu mesita de noche.
Circuit Breaker — Cuando Todo Falla
¿Qué pasa si la compactación falla? ¿Si el agente de resumen genera un resumen que sigue siendo demasiado grande? ¿Si hay un loop donde se compacta, crece, se compacta, crece?
Claude Code tiene un circuit breaker para exactamente este escenario:
// Máximo de compactaciones consecutivas sin progreso const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3; // Si se alcanzan 3 fallos consecutivos: // → Se detiene la auto-compactación // → Se notifica al usuario // → Se sugiere usar /clear para reset manual // Override para casos especiales: env.CLAUDE_AUTOCOMPACT_PCT_OVERRIDE = "80"; // Fuerza compactación cuando el contexto llega al 80%
El circuit breaker previene loops infinitos de compactación. Si el sistema intenta compactar 3 veces seguidas y sigue sin poder reducir el contexto lo suficiente, deja de intentarlo. Esto puede pasar en conversaciones con contenido extremadamente denso donde incluso el resumen es grande.
Para situaciones especiales, existe la variable de entorno CLAUDE_AUTOCOMPACT_PCT_OVERRIDE. Poniendo un valor como "80", puedes forzar que la compactación se active cuando el contexto alcance el 80% del máximo, en lugar de esperar al umbral por defecto.
Árbol de Decisión — Cuándo se Activa Cada Tier
La activación de cada tier no es aleatoria — es un árbol de decisión determinista basado en el conteo de tokens:
// Pseudocódigo del árbol de decisión function decideCompressionTier(inputTokens, maxTokens) { const utilizationPct = inputTokens / maxTokens; // ¿Estamos dentro del presupuesto? if (inputTokens < MAX_INPUT_TOKENS - AUTOCOMPACT_BUFFER_TOKENS) { return TIER_0; // Sin compresión } // ¿Hay tool results que limpiar? if (hasCompactableToolResults(conversation)) { clearOldToolResults(); // Tier 1 if (estimateTokens() < MAX_INPUT_TOKENS) { return TIER_1; // Microcompact bastó } } // ¿El servidor puede limpiar bloques? if (betaHeaderSupported('context-management')) { activateServerSideClearing(); // Tier 2 if (estimateTokens() < MAX_INPUT_TOKENS) { return TIER_2; // API-native bastó } } // Último recurso: compactación total if (consecutiveFailures < MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES) { return TIER_3; // Resumen de 9 secciones } // Circuit breaker activado notifyUser("Context too dense. Use /clear to reset."); return CIRCUIT_BREAKER; }
Patrones que Puedes Aplicar Hoy
El sistema de compresión de Claude Code no es solo un ejercicio de ingeniería interna. Hay patrones concretos que puedes aplicar a tus propios agentes o flujos de trabajo con LLMs:
1. Defensa multi-capa (no una sola estrategia)
No construyas un solo mecanismo de compresión. Usa niveles progresivos — primero lo más suave (limpiar resultados reproducibles), luego lo medio (borrar bloques enteros), y solo al final lo más agresivo (resumir todo). Cada nivel tiene un coste diferente y una pérdida de información diferente.
2. Nunca perder las instrucciones del usuario
Si resumes una conversación para ahorrar contexto, trata los mensajes del usuario como datos sagrados. El contexto técnico se puede reconstruir (re-leer archivos, re-ejecutar comandos), pero las instrucciones del usuario son únicas e irrecuperables. La sección 6 del resumen de Claude Code existe por esta razón.
3. Post-recuperación activa
Después de comprimir, no esperes a que el modelo pida lo que necesita. Re-inyecta proactivamente los archivos más recientes y el contexto de skills. Es la diferencia entre despertar sin memoria y despertar con un resumen y tus 5 archivos más importantes ya abiertos.
4. Circuit breakers en todo sistema de auto-compresión
Si tu agente comprime automáticamente, pon un máximo de intentos consecutivos. Sin circuit breaker, puedes acabar en un loop donde el agente gasta tokens comprimiendo, el resumen es casi igual de grande, y vuelve a comprimir. Con 3 fallos consecutivos, para y pide intervención humana.
La Ilusión de Memoria Infinita
El sistema de compresión de contexto de Claude Code es un sistema de memoria virtual para LLMs. Igual que tu sistema operativo te da la ilusión de RAM infinita combinando cache, RAM y swap — Claude Code te da la ilusión de una conversación infinita combinando 4 niveles de compresión progresiva.
La clave del diseño es la progresividad: cada nivel es más agresivo pero solo se activa cuando el anterior falla. Y la invariante que atraviesa todo el sistema es que las instrucciones del usuario nunca se pierden — la sección 6 del resumen es sagrada.
En el próximo artículo de esta serie, exploraremos los sistemas de memoria persistente — cómo Claude Code recuerda cosas entre sesiones. Auto-extract, session memory, magic docs y auto-dream: cuatro mecanismos que trabajan mientras duermes para que tu próxima sesión empiece donde dejaste la anterior.
📚 Serie Anatomía de Claude Code: Este es el artículo 2 de 6. El anterior cubre el system prompt de 18 capas. Los siguientes cubren sistemas de memoria, features ocultas, sistema de herramientas y permisos, y el build dual (interno vs público).
¿Construyes agentes con LLMs?
En Cadences diseñamos agentes con los mismos patrones industriales que hemos descubierto en Claude Code. Si quieres aplicar estos principios a tu negocio, hablemos.
Gonzalo Monzón
Fundador de CadencesLab. Ingeniero de software, arquitecto de sistemas multi-agente y eterno estudiante de cómo piensan las máquinas. Esta serie nace de meses de reverse engineering sobre las herramientas que usamos a diario.