Memoria y contexto

Conjunto de mecanismos que determinan qué información recibe el modelo en cada turno y qué información se conserva entre sesiones. En la práctica, es el factor que más condiciona la coherencia de las respuestas en trabajos largos: una sesión que empieza bien puede perder precisión no porque el modelo haya cambiado, sino porque el estado relevante ha desaparecido del contexto o ha quedado desplazado por contenido acumulado.

Anatomía

El modelo no mantiene estado entre invocaciones. Cada llamada al endpoint de inferencia recibe un bloque de tokens y produce una respuesta; fuera de ese bloque, no hay continuidad. Lo que el usuario percibe como memoria de la conversación es el resultado de reenviar, en cada turno, el historial completo de mensajes junto con el resto del contexto. El tamaño de la ventana depende del modelo: Haiku 4.5 mantiene 200 000 tokens; Sonnet 4.6 y Opus 4.7 admiten hasta 1M en beta, aunque el límite efectivo de una sesión típica suele situarse muy por debajo.

Composición del contexto. El contexto no es una acumulación desordenada. Claude Code lo compone en un orden fijo antes de enviar cada turno al endpoint: primero el system prompt del binario y la información de entorno; después la auto-memoria del proyecto; a continuación las herramientas MCP disponibles y las definiciones de skills; luego el archivo CLAUDE.md del usuario y el de proyecto, inyectados como mensaje de usuario; finalmente el historial de mensajes de la sesión. Este orden determina qué se procesa primero y, en consecuencia, qué aprovecha mejor la caché de prompt.

El punto sobre CLAUDE.md merece una precisión. El archivo no se inyecta como parte del system prompt del binario, sino como mensaje de usuario. Esta distinción afecta a la dinámica de atención del modelo: el system prompt actúa como marco permanente, mientras que CLAUDE.md compite con el historial por la atención disponible en la mitad inferior del contexto.

Auto-memoria. La auto-memoria es la capa que Claude Code gestiona de forma autónoma para preservar observaciones entre sesiones. Sus archivos se almacenan en ~/.claude/projects/<project>/memory/, donde el identificador <project> se deriva del repositorio git. Todos los worktrees de un mismo repositorio comparten este directorio; el contenido es local a la máquina y no se sincroniza entre entornos.

El archivo principal es MEMORY.md. Al inicio de cada sesión, Claude Code carga hasta 200 líneas o 25 KB de su contenido e incluye la información en el contexto. Junto a este archivo pueden existir archivos temáticos cargados bajo demanda — notas sobre arquitectura, decisiones de diseño, convenciones detectadas — que solo se inyectan cuando el modelo los considera relevantes para la tarea en curso.

La diferencia conceptual entre auto-memoria y CLAUDE.md es operativa, no técnica: CLAUDE.md registra lo que el equipo exige al modelo; la auto-memoria registra lo que el modelo ha observado sobre el proyecto. Ambas capas conviven y se complementan. Una recoge las convenciones que el equipo ha decidido; la otra acumula el contexto que el modelo ha derivado de la experiencia de trabajo en ese repositorio.

Comandos de control del contexto. Claude Code expone cuatro comandos para gestionar el estado activo. El comando /compact reemplaza el historial de la sesión por un resumen estructurado generado por el modelo; acepta instrucciones opcionales que precisan qué conservar. El comando /clear cierra la conversación activa y abre una sesión nueva con contexto vacío; la conversación anterior queda accesible mediante /resume. El comando /context — con el modificador all para desglose completo — muestra el uso actual de la ventana desglosado por categoría. El comando /btw permite formular una pregunta lateral sin añadir el intercambio al historial; la respuesta aparece en un overlay descartable y no afecta a la conversación en curso.

Funcionamiento

En cada turno, Claude Code compone el contexto en el orden descrito, lo envía al endpoint y procesa la respuesta. Si la respuesta contiene llamadas a herramientas, sus resultados se incorporan al historial y el modelo vuelve a invocarse con el contexto actualizado. Este ciclo se repite hasta que la respuesta no contiene llamadas pendientes. El crecimiento del historial es acumulativo: cada turno reenvía todo lo anterior, y el coste de entrada crece con la longitud de la sesión.

El orden de composición tiene consecuencias directas sobre el coste por turno. Los primeros bloques que llegan al endpoint — el system prompt del binario, la información de entorno, las herramientas MCP y las definiciones de skills — son los que mejor aprovechan la caché de prompt de la API, porque su contenido cambia poco entre turnos y la capa de caché puede reutilizarlos sin recomputarlos. La auto-memoria se inyecta en posición temprana y, por las mismas razones, también resulta cacheable en la mayoría de los turnos. CLAUDE.md aparece después: cuando el archivo se edita entre sesiones, invalida la caché para todo lo que le sigue en la secuencia, incluido el historial. El orden de capas no es una convención de presentación; es una decisión con efecto económico directo sobre la latencia y el coste de cada turno.

Cuando el contexto se aproxima al límite de la ventana, Claude Code ejecuta la compactación automática. No existe un umbral fijo publicado; la variable de entorno CLAUDE_AUTOCOMPACT_PCT_OVERRIDE —documentada en el changelog del CLI, no en la referencia pública— permite ajustar el porcentaje de ocupación a partir del cual se activa, por ejemplo al 80 %. La compactación reemplaza el historial por un resumen estructurado que conserva: las solicitudes del usuario, los conceptos clave trabajados, los archivos modificados, los errores encontrados y su resolución, y el estado del trabajo en curso. Lo que se descarta son los contenidos literales de los tool results — salidas de comandos, fragmentos de archivos leídos — y el razonamiento intermedio producido durante el procesamiento.

La reinyección desde disco es el paso menos evidente del ciclo. Tras la compactación, Claude Code recupera automáticamente un conjunto de componentes desde sus archivos de origen: el system prompt y el output style no cambian; el CLAUDE.md raíz y las reglas sin restricción de paths se releen desde disco; la auto-memoria del proyecto se reincorpora desde ~/.claude/projects/<project>/memory/; los cuerpos de los skills invocados durante la sesión se restauran, con un límite de 5 000 tokens por skill y 25 000 tokens para el bloque de skills en conjunto. Este mecanismo garantiza que el contexto resultante no sea solo una síntesis narrativa, sino un contexto operativo completo.

No todo se conserva tras la compactación. Las reglas de CLAUDE.md con restricciones de paths y los archivos CLAUDE.md de subdirectorios anidados no se reinyectan de forma automática; vuelven al contexto cuando el modelo los activa al operar en esa parte del árbol. Las descripciones de skills no invocados durante la sesión no se restauran. Las instrucciones dadas únicamente en la conversación — sin respaldo en CLAUDE.md ni en la auto-memoria — se pierden con el historial.

El sesgo de posición afecta al procesamiento de forma constante. Los extremos del contexto — el inicio y el final — reciben más atención que el contenido situado en la parte central. Una instrucción relevante que quede enterrada en el medio de un historial largo reduce su influencia sobre el comportamiento del modelo, incluso si no ha sido descartada por la compactación.

Los hooks PreCompact y PostCompact permiten intervenir en el ciclo de compactación con acciones deterministas. PreCompact se ejecuta antes de que el historial se reemplace; puede utilizarse para registrar el estado en archivos del proyecto. PostCompact se ejecuta después de la reinyección; permite verificar que el contexto resultante es coherente o añadir información que la reinyección automática no recupera.

Construcción

Configurar la auto-memoria

La auto-memoria está activa por defecto. Para desactivarla, añade "autoMemoryEnabled": false en settings.json o establece la variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. El comando /memory alterna el estado desde la sesión activa sin modificar la configuración persistente.

Para controlar el alcance de la auto-memoria en subagentes, utiliza el campo memory: en el frontmatter del agente. Este campo acepta tres valores: user limita la memoria al ámbito del usuario y no lee ni escribe en el directorio del proyecto; project activa la memoria a nivel de repositorio, que es el comportamiento por defecto; local restringe la memoria a la sesión del subagente y no la persiste entre invocaciones.

Mantén MEMORY.md dentro del límite de 200 líneas. Cuando una observación requiere más detalle — el esquema de una base de datos, las convenciones de una API interna — coloca el contenido en un archivo temático bajo el directorio de memoria y añade una referencia desde MEMORY.md. El archivo principal actúa como índice; los archivos temáticos se cargan bajo demanda.

Higiene de sesión

La compactación manual con /compact da más control que la automática sobre qué se conserva. El uso recomendado es anticiparse al límite: cuando la sesión alcanza el 50-70 % de la ventana, ejecutar /compact con instrucciones específicas —por ejemplo, indicando qué archivos modificados y qué comandos de test deben preservarse— produce una síntesis más precisa que la compactación reactiva.

Utiliza /clear al cambiar de tarea sin relación con la anterior. El coste de reconstruir el contexto desde CLAUDE.md y la auto-memoria es habitualmente menor que el de mantener en el historial activo el contenido acumulado de una tarea distinta. La sesión anterior queda accesible con /resume si es necesario retomar.

Cuando una instrucción dada en la conversación debe persistir más allá de la compactación, registrala en CLAUDE.md o en la auto-memoria antes de que el historial se reemplace. Las instrucciones que solo existen en el cuerpo de la conversación no se conservan en la síntesis.

Instrumentar la compactación con PreCompact

El hook PreCompact se ejecuta justo antes de que el modelo reemplace el historial por la síntesis. En ese momento, el estado completo de la sesión — archivos leídos, comandos ejecutados, tool results acumulados — todavía está disponible. Una vez que la compactación termina, ese contenido desaparece y la síntesis automática no lo recupera de forma literal. PreCompact es el único punto fiable del ciclo donde se puede actuar sobre esa información antes de que se descarte.

Un uso habitual es volcar al proyecto la lista de archivos modificados durante la sesión. El hook puede escribir en un fichero de seguimiento del repositorio —por ejemplo CHANGES_SESSION.md— los nombres de los archivos que el modelo ha editado, los comandos que ha ejecutado y cualquier error encontrado junto con su resolución. Este registro permanece en disco independientemente de lo que ocurra con el historial y resulta útil al retomar el trabajo en una sesión posterior.

Otro uso frecuente es añadir una entrada a MEMORY.md con el resumen de la tarea cerrada. Cuando una tarea de varios turnos concluye, el hook puede escribir un bloque fechado con el objetivo alcanzado, las decisiones tomadas y los archivos afectados. De este modo la auto-memoria acumula historial de trabajo real sin depender de que el modelo recuerde hacerlo al final del turno.

El campo command del hook recibe el nombre del evento como argumento. Para PreCompact, el hook no necesita modificar el estado del contexto ni detener la compactación; su función es exclusivamente registrar en archivos del proyecto la información que la síntesis descartará. PostCompact, el hook complementario, se activa después de la reinyección y permite añadir contenido que la reinyección automática no recupera — por ejemplo, instrucciones específicas de la tarea actual que el modelo debe conocer al retomar el trabajo.

Patrón de resúmenes acumulativos

En proyectos con sesiones largas y recurrentes, conviene añadir a CLAUDE.md una instrucción que indique a /compact que añada al inicio del resumen un bloque con los resúmenes históricos de sesiones anteriores, de modo que el historial del proyecto se acumule en lugar de sobrescribirse en cada compactación.

Este patrón, conocido como Compaction Memory, garantiza que la síntesis de cada sesión incluya el estado de las sesiones previas. Con el tiempo, el bloque de resúmenes históricos crece; conviene revisarlo periódicamente y comprimirlo cuando supera el tamaño que justifica su utilidad.

Verificar el estado del contexto

Ejecuta /context all antes de una tarea compleja para conocer el desglose de uso por categoría. La categoría que más crece entre turnos suele ser el historial de mensajes; si los tool results ocupan una proporción alta, considera delegar las operaciones de lectura a subagentes o utilizar herramientas más específicas que devuelvan menos contenido.

El desglose que produce /context all organiza el consumo por categoría: el system prompt del binario y la información de entorno; las definiciones de herramientas, que incluyen las integradas y las expuestas por los MCP servers activos; los archivos CLAUDE.md cargados en la sesión, ordenados por nivel; la auto-memoria del proyecto; el historial de mensajes de la conversación; y los tool results acumulados desde el último turno de compactación. Cada categoría aparece con su volumen en tokens y su porcentaje sobre el total de la ventana.

Interpretar el desglose requiere identificar qué categoría domina. Si los tool results representan una fracción alta del total, la causa habitual son operaciones de lectura extensas — comandos que producen salidas largas o archivos grandes leídos íntegros — y la corrección es delegar esas operaciones a subagentes o usar herramientas que devuelvan solo los fragmentos necesarios. Si el historial de mensajes ocupa la mayor parte, la sesión se acerca al punto en que la compactación será inevitable; ejecutar /compact con instrucciones precisas en ese momento produce una síntesis mejor que la compactación reactiva. Si las definiciones de herramientas pesan más de lo esperado, conviene revisar cuántos MCP servers están activos: cada servidor añade sus herramientas al contexto en cada turno, y desactivar los servidores no utilizados en la sesión actual reduce ese volumen de forma inmediata.

Cuando la sesión entra en un ciclo de errores — el modelo repite el mismo error turno tras turno a pesar de correcciones explícitas — la causa habitual es que el historial acumulado pesa más que las instrucciones recientes. En ese caso, /compact o /clear interrumpen el ciclo y permiten retomar con un contexto limpio.

Límites

Pérdida de instrucciones de conversación. Toda instrucción dada solo en el cuerpo de la conversación — un ajuste de tono pedido en el turno 3, una restricción de alcance acordada en el turno 7 — desaparece cuando el historial se reemplaza por la síntesis. La compactación no distingue entre una instrucción operativa y un comentario informativo: ambos quedan fuera si no se registran en un archivo persistente. La única garantía de que una instrucción sobreviva a la compactación es que figure en CLAUDE.md o en la auto-memoria antes de que esta ocurra.

Contaminación de contexto en sesiones largas. En sesiones que acumulan muchos turnos, los errores cometidos y corregidos quedan en el historial. El modelo los procesa junto con el resto del contexto, y en ciertos casos reproduce el patrón erróneo aunque haya recibido corrección explícita. Este efecto aumenta con la longitud del historial y no se resuelve con más instrucciones: la solución es ejecutar /compact o /clear para partir de un estado limpio. Registrar la corrección en CLAUDE.md garantiza que se aplique en sesiones futuras.

Límite de tamaño de la auto-memoria. MEMORY.md se carga hasta 200 líneas o 25 KB. Cuando el archivo supera ese límite, el contenido más antiguo no se carga y el sistema opera sin notificación. Las observaciones registradas hace tiempo — decisiones de arquitectura, convenciones detectadas — pueden desaparecer sin que el modelo lo indique. Mantener el archivo dentro del límite y mover el contenido extenso a archivos temáticos referenciados desde él evita esta pérdida.

Reinyección incompleta tras compactación. La reinyección automática no recupera todos los componentes activos en el momento de la compactación. Las reglas con restricciones de paths, los archivos CLAUDE.md de subdirectorios y las descripciones de skills no invocados no se restauran hasta que el modelo los activa de nuevo. En sesiones donde el trabajo se distribuye entre varios subdirectorios o skills especializados, la compactación puede producir un cambio de comportamiento perceptible en el turno siguiente. Los hooks PreCompact y PostCompact son el mecanismo para instrumentar ese momento y garantizar que el estado relevante se preserve explícitamente.

Sesgo de posición y dilución de instrucciones. El modelo procesa los extremos del contexto con más atención que el contenido central. Una instrucción crítica que quede en la parte media del historial tras varios turnos de tool results puede dejar de aplicarse, no porque haya sido descartada, sino porque su posición reduce su peso efectivo. Cuando una restricción debe mantenerse con independencia de la longitud de la sesión, el mecanismo apropiado es un hook, que se ejecuta en cada turno al margen del estado del contexto.