Auto memory en Claude Code: qué carga cada sesión y qué se pierde

Auto memory escribe por su cuenta un MEMORY.md por proyecto, del que Claude Code carga solo las primeras 200 líneas en cada sesión. Esa era básicamente toda la historia el primer día que la función llegó a producción, en Claude Code 2.1.59. Seis meses después el sistema tiene más piezas: un límite doble que entonces nadie documentaba bien, memoria propia para subagentes que no comparte nada con la del hilo principal, un directorio de almacenamiento que ya se puede mover, y una restricción de plataforma que la documentación actual ya no menciona.

La documentación en sí también cambió de casa: lo que hasta hace poco vivía en docs.claude.com ahora resuelve en code.claude.com, con una redirección 301 de por medio. Si tienes la URL vieja guardada, sigue funcionando, pero vale la pena actualizar el enlace.

Dos sistemas de memoria, no uno

Auto memory es un directorio de archivos Markdown que Claude escribe por su cuenta durante la sesión, sin que tú redactes nada: guarda comandos de build, hallazgos de depuración, notas de arquitectura y preferencias de estilo que descubre mientras trabaja, decidiendo qué merece guardarse según si le será útil en una conversación futura. CLAUDE.md es lo contrario: instrucciones que tú escribes y versionas en Git. La documentación oficial actual resume la diferencia de alcance con más precisión que la versión de febrero: CLAUDE.md se puede definir a nivel de proyecto, usuario u organización (con una capa de política gestionada por encima), mientras que auto memory vive por repositorio y se comparte entre worktrees de ese mismo repositorio, nunca a nivel de organización.

El límite real: 200 líneas o 25 KB, lo que llegue primero

Esto es lo que la versión anterior de este artículo dejaba incompleto: el límite que se carga al inicio de cada conversación no son solo 200 líneas, son "las primeras 200 líneas de MEMORY.md, o los primeros 25 KB, lo que ocurra antes", según la documentación vigente. Un archivo con líneas largas puede tocar el límite de 25 KB mucho antes de llegar a la línea 200, así que contar líneas ya no basta para saber si el índice va a cargar completo.

El comportamiento al superar el límite también quedó mejor definido. Claude Code mide MEMORY.md después de cada escritura; si el archivo se acerca al límite, avisa a Claude para que lo recorte (una línea por entrada, detalle movido a archivos temáticos); si ya lo supera, la escritura se completa igual, pero Claude Code devuelve un error explícito pidiendo reescribir el índice, porque todo lo que queda por encima del límite se descarta en la siguiente carga. La medición solo cuenta el contenido que realmente se carga: el frontmatter YAML y los comentarios HTML de bloque se eliminan antes de medir. Antes de la versión 2.1.211, Claude Code medía el archivo en crudo, así que un frontmatter largo podía disparar el error aunque el contenido que realmente cargaba cupiera de sobra.

La memoria de los subagentes es un directorio distinto

Esto no existía cuando se escribió el artículo original: un subagente personalizado puede declarar su propio campo memory, con tres alcances posibles, y ese directorio no comparte nada con el MEMORY.md de la conversación principal.

La documentación de subagentes señala una trampa concreta: la memoria propia del subagente forma parte de auto memory en su conjunto, así que si desactivas auto memory con autoMemoryEnabled: false o con la variable CLAUDE_CODE_DISABLE_AUTO_MEMORY, el campo memory del subagente deja de tener efecto sin ningún aviso adicional: el subagente arranca sin las instrucciones de memoria ni el acceso a las herramientas de lectura/escritura que normalmente se habilitan para gestionarla.

En sentido inverso, la memoria de la conversación principal tampoco se carga en los subagentes ordinarios. La única excepción es un fork de la conversación actual, que hereda tanto la conversación como el system prompt del padre, memoria incluida.

Un subagente con memoria propia, listo para copiar

Este es exactamente el formato que documenta Anthropic para declarar memoria persistente en un subagente. Guárdalo como .claude/agents/code-reviewer.md en cualquier proyecto:

---
name: code-reviewer
description: Revisa código en busca de calidad, convenciones y problemas recurrentes
memory: project
---

Eres un revisor de código. A medida que revises código, actualiza tu memoria
de agente con patrones, convenciones y problemas recurrentes que descubras.
Antes de empezar una revisión nueva, consulta tu memoria para no repetir
observaciones ya hechas en sesiones anteriores.

Con memory: project, el directorio queda en .claude/agent-memory/code-reviewer/, versionable en Git y compartido con el equipo. Cambia a memory: user si quieres que ese subagente acumule conocimiento propio a través de todos tus proyectos, o a memory: local si el conocimiento es específico del proyecto pero no quieres commitearlo.

Dónde vive, y cómo moverla si lo necesitas

La ubicación por defecto sigue siendo ~/.claude/projects/<proyecto>/memory/, derivada de la raíz del repositorio Git y compartida entre todos los worktrees y subdirectorios de ese repo. Lo nuevo es autoMemoryDirectory: un ajuste que se puede definir en cualquier nivel de settings (usuario, proyecto, local, política gestionada o --settings) para redirigir el directorio a una ruta absoluta o a algo que empiece por ~/. Si lo configuras dentro de .claude/settings.json o .claude/settings.local.json de un proyecto, solo se aplica después de aceptar el diálogo de confianza de esa carpeta, la misma puerta que gobierna los hooks.

Lo que no cambió: sigue siendo local a la máquina. Ningún archivo se sincroniza entre equipos ni entre entornos cloud, y cada worktree del mismo repositorio comparte un único directorio, no uno por rama.

Qué se corrigió desde febrero, y qué dejó de estar restringido

El changelog público de Claude Code documenta varios cambios puntuales sobre esta función desde su introducción en la versión 2.1.59:

• La versión 2.1.211 corrigió la medición de frontmatter y comentarios explicada arriba.
• Desde la 2.1.214, cuando Claude escribe un archivo de memoria que empieza con frontmatter YAML, Claude Code añade un campo modified con la marca de tiempo ISO 8601 de esa escritura, útil para que Claude sepa qué tan vigente es un hecho guardado cuando lo relee más adelante. Los archivos creados en versiones anteriores reciben el campo la próxima vez que Claude los reescribe.
• Antes de la versión 2.1.216, el comando /memory bloqueaba la sesión hasta que cerrabas el editor del archivo abierto; ahora un editor gráfico como VS Code lo abre en una ventana aparte y puedes seguir trabajando mientras está abierto.

La restricción de plataforma que documentaba la versión anterior de este artículo (auto memory disponible solo con API directa o suscripciones Pro/Max, no con Amazon Bedrock, Google Vertex AI o Microsoft Foundry) ya no aparece en ningún punto de la página de memoria vigente. Eso no es prueba absoluta de disponibilidad universal en todas las plataformas para todas las cuentas, pero si estás evaluando esto para un equipo en una nube gestionada, el punto de partida correcto ahora es comprobarlo directamente en tu propio entorno, no asumir la restricción de hace seis meses.

Cómo desactivarlo, con lo mínimo copiable

El toggle interactivo de /memory no es un interruptor aparte: escribe directamente el mismo campo autoMemoryEnabled que verías si editases settings.json a mano. Si prefieres fijarlo una vez y no tocarlo sesión a sesión, ponlo ahí directamente:

// ~/.claude/settings.json (nivel usuario, afecta a todos los proyectos)
{ "autoMemoryEnabled": false }

// .claude/settings.json (nivel proyecto, solo afecta a este repo)
{ "autoMemoryEnabled": false }

Para una sesión puntual, o para pipelines de CI/CD donde no quieres dejar rastro en ningún archivo del repositorio, la variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY logra lo mismo sin tocar settings.json:

# Una sola sesión, sin cambiar configuración
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

# Pipelines CI/CD (GitHub Actions, GitLab CI y similares)
env:
  CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"

De los dos mecanismos, solo la variable de entorno es realmente independiente de autoMemoryEnabled: tiene prioridad sobre ese campo sea cual sea su valor, esté puesto a mano en settings.json o mediante el toggle de /memory. Es también la opción recomendable en un runner de CI/CD, donde no interesa que Claude Code escriba memoria persistente al sistema de archivos de una máquina efímera que se destruye al terminar el job.

Casos borde que rompen la intuición

• Windows sin modo desarrollador: crear un symlink de AGENTS.md a CLAUDE.md requiere permisos de administrador o modo desarrollador; sin eso, usa el import @AGENTS.md en su lugar, que no necesita privilegios elevados.
• Solo hay dos controles reales, no tres: el toggle de /memory y el campo autoMemoryEnabled de settings.json son la misma palanca vista desde dos sitios distintos; lo único genuinamente independiente es la variable de entorno, que gana siempre sobre lo que diga settings.json (ver la sección de arriba para los snippets exactos).
• Los archivos temáticos no se autocargan nunca: debugging.md, api-conventions.md o cualquier otro archivo que Claude cree dentro del directorio de memoria solo se leen bajo demanda, con las herramientas normales de lectura de archivos, cuando Claude decide que los necesita para la tarea en curso. Si algo importante quedó enterrado en uno de esos archivos y Claude no lo menciona, puede que simplemente no haya tenido motivo para abrirlo esa sesión.
• Revisar no es opcional: auto memory sigue siendo texto plano editable con /memory. Una hipótesis de depuración equivocada que Claude guardó a mitad de una sesión larga no se autocorrige sola; sigue ahí hasta que alguien la borre o la corrija a mano.

Ninguno de estos casos es motivo para desactivarlo por defecto: la ganancia de que Claude recuerde comandos de build y hallazgos de depuración de una sesión a la siguiente sigue superando el coste de un MEMORY.md que de vez en cuando queda desactualizado, siempre que alguien lo repase con /memory de tanto en tanto en vez de darlo por sentado.