Claude Code Auto-Memory: el contexto que persiste solo

TL;DR: Claude Code 2.1.59, lanzado el 26 de febrero de 2026, introduce auto-memory: un sistema en el que el agente escribe sus propias notas sobre el proyecto y las carga automáticamente al iniciar la siguiente sesión. La distinción clave es que CLAUDE.md contiene instrucciones que tú escribes para Claude, mientras que MEMORY.md contiene lo que Claude aprende por observación. El resultado práctico: menos repetición de contexto al arrancar, más continuidad en el trabajo diario.

El problema: cada sesión empieza desde cero

Si llevas tiempo usando Claude Code, conoces el ritual. Abres la terminal, inicias el agente y, antes de empezar a trabajar, le explicas el contexto: qué stack usa el proyecto, qué convenciones sigue el equipo, ese bug extraño que resolviste la semana pasada, por qué los tests de integración necesitan Redis corriendo en local en el puerto 6379. La misma información, sesión tras sesión.

No es un problema exclusivo de Claude Code. Es una limitación estructural de cualquier agente sin memoria persistente: cada sesión arranca con contexto frío. CLAUDE.md resuelve parte del problema, pero captura instrucciones estáticas que tú mantienes manualmente. Lo que el agente descubre durante el trabajo, las correcciones específicas, los patrones que emergen del proyecto concreto, se perdía al cerrar la terminal.

Auto-memory resuelve exactamente eso. Durante la sesión, Claude identifica qué vale la pena guardar y escribe esas notas en un archivo local. Al iniciar la siguiente sesión, las carga automáticamente en su contexto.

¿Qué es auto-memory en Claude Code?

Auto-memory es un directorio persistente donde Claude registra aprendizajes, patrones e insights mientras trabaja. Es distinto de CLAUDE.md: esos archivos los escribes y mantienes tú; auto-memory lo escribe Claude a partir de lo que descubre durante las sesiones.

El archivo principal es MEMORY.md, ubicado en:

~/.claude/projects/<ruta-del-repo-git>/memory/MEMORY.md

La ruta deriva de la raíz del repositorio git. Todos los subdirectorios dentro del mismo repo comparten el mismo directorio de memoria. Los git worktrees tienen directorios separados. Si trabajas fuera de un repositorio git, se usa el directorio de trabajo actual como base para el path.

El directorio puede contener varios archivos:

~/.claude/projects/<proyecto>/memory/
├── MEMORY.md           # Índice conciso, cargado al inicio de cada sesión
├── debugging.md        # Notas de depuración acumuladas
├── api-conventions.md  # Decisiones de diseño de API
└── patterns.md         # Patrones del proyecto

Las primeras 200 líneas de MEMORY.md se inyectan en el system prompt al iniciar cada sesión. El contenido que supera ese límite no se carga de forma automática. Por eso Claude mantiene MEMORY.md como un índice conciso y delega los detalles a archivos temáticos. Esos archivos no se cargan al inicio: Claude los lee bajo demanda durante la sesión cuando los necesita.

MEMORY.md vs CLAUDE.md: la distinción que cambia todo

Esta es la diferencia más importante del artículo, y vale la pena verla con claridad:

Característica	CLAUDE.md	MEMORY.md (auto-memory)
Quién escribe	Tú (el desarrollador o el equipo)	Claude (automáticamente)
Contenido	Reglas, convenciones, instrucciones explícitas	Aprendizajes, patrones descubiertos, correcciones
Control de versiones	Se commitea al repositorio	Permanece local, no va al repo
Actualización	Manual: editas cuando cambian las reglas	Automática durante cada sesión
Ámbito	Compartido con el equipo (si está en el repo)	Personal, por máquina y usuario
Carga al inicio	Completo	Solo primeras 200 líneas

Un ejemplo concreto: si durante una sesión le dices a Claude "usa pnpm, no npm en este proyecto", puede guardar esa preferencia en MEMORY.md. Si es una convención de todo el equipo, debería estar en CLAUDE.md y commitearse. Si es solo tu preferencia local, basta con que Claude lo aprenda a través de auto-memory. Son capas diferentes, complementarias, y las dos son útiles.

Configuración paso a paso

Auto-memory está activo por defecto desde Claude Code 2.1.59. No requiere configuración inicial para funcionar. Hay tres formas de controlarlo:

1. El comando /memory

Desde cualquier sesión de Claude Code, /memory abre un selector interactivo que muestra todos los archivos de memoria activos: los CLAUDE.md globales, de proyecto y de directorio, y el entrypoint de auto-memory del proyecto actual. El selector incluye un toggle para activar o desactivar auto-memory sin salir de la sesión. Al seleccionar cualquier archivo, se abre en tu editor de sistema. MEMORY.md es Markdown plano: puedes leerlo, editarlo, borrar entradas o reorganizarlo libremente.

2. settings.json

Para desactivarlo sin tocar el toggle en cada sesión:

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

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

El settings.json de proyecto permite desactivar auto-memory para un repositorio concreto sin tocar el resto de tu configuración.

3. Variable de entorno

# Desactivar para una sesión concreta
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude

# Desactivar globalmente en .bashrc o .zshrc
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

# En pipelines CI/CD (GitHub Actions, GitLab CI)
env:
  CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1"

La variable de entorno tiene prioridad sobre settings.json y sobre el toggle de /memory. Es la opción más fiable en entornos automatizados donde no quieres que Claude escriba al sistema de archivos del runner.

4. Indicar manualmente qué recordar

Claude también responde a instrucciones directas durante la sesión:

# Ejemplos de instrucciones directas en el chat de Claude Code
"Recuerda que los tests de integración necesitan Redis en localhost:6379"
"Guarda en memoria que en este proyecto el linter es ruff, no flake8"
"Añade a tu memoria que el endpoint /health no requiere autenticación"

Esto da control explícito sobre qué quieres que persista, sin depender de lo que Claude decida guardar de forma autónoma.

Dónde aporta valor real en proyectos

En proyectos nuevos o triviales, auto-memory pasa casi desapercibida. El valor aparece con proyectos que llevan tiempo activos y tienen complejidad acumulada.

El primer escenario es el de la configuración implícita. Si tu proyecto tiene decisiones de arquitectura que no están documentadas en ningún sitio, deuda técnica, convenciones que surgieron de forma orgánica, Claude puede capturarlas a medida que las descubre trabajando contigo. "La paginación usa cursor, no offset, porque se migró hace seis meses" es exactamente el tipo de contexto que Claude aprende al ver el código y puede guardar para el día siguiente.

El segundo es el debugging recurrente. Si resuelves un error con mucho contexto específico, como una condición de carrera en los tests que solo ocurre con más de cuatro workers en paralelo, puedes pedirle a Claude que guarde la causa y la solución. La próxima vez que aparezca el síntoma, Claude ya tiene el contexto sin que tengas que reconstruirlo desde cero.

El tercero es la capa de preferencias personales. Tu equipo comparte un CLAUDE.md con las reglas comunes. Pero tú individualmente puedes tener preferencias sobre cómo quieres que Claude estructure sus respuestas, qué nivel de detalle prefieres en las explicaciones, o cómo organizas tus peticiones. Auto-memory captura esa capa personal sin contaminar las instrucciones compartidas del equipo.

En producción

Hay varias consideraciones antes de confiar en auto-memory para trabajo diario en proyectos reales.

El límite de 200 líneas es real y tiene consecuencias. Si MEMORY.md crece sin control, las notas más recientes quedan fuera del contexto automático. Claude intenta mantenerse dentro del límite moviendo detalles a archivos temáticos, pero en proyectos con mucha actividad conviene revisar el archivo periódicamente. Si supera las 200 líneas, pide explícitamente: "Consolida MEMORY.md, mueve los detalles a archivos temáticos y mantén el entrypoint bajo las 200 líneas."

Las memorias incorrectas existen. Si en una sesión de debugging llegas a una hipótesis equivocada antes de encontrar la causa real, Claude podría haber guardado esa hipótesis. Si algo no cuadra en una sesión posterior, revisa MEMORY.md con /memory y corrige o elimina la entrada incorrecta. No es un sistema infalible: es un borrador que necesita revisión ocasional.

El coste de contexto por sesión es bajo pero existe. Las primeras 200 líneas de MEMORY.md se inyectan siempre, aunque la tarea actual no tenga relación con lo guardado. Si usas Claude Code con API key propia (no suscripción Pro/Max), esas 200 líneas consumen aproximadamente 1.500-2.000 tokens adicionales por sesión. A precios actuales de Claude Sonnet, el impacto es de fracciones de céntimo por sesión, prácticamente irrelevante en uso normal, pero a tener en cuenta si ejecutas muchas sesiones cortas automatizadas.

La memoria es por máquina y usuario, no sincronizada. Si trabajas desde dos equipos, cada uno tiene su propio MEMORY.md. No hay sincronización entre ellos. Si cambias de máquina, Claude Code empieza con memoria vacía para ese proyecto en ese entorno.

En CI/CD, desactívalo siempre. En pipelines donde Claude Code ejecuta tareas automatizadas, auto-memory puede generar escrituras al sistema de archivos del runner que no son deseadas. La variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 es el mecanismo más fiable para garantizarlo.

A fecha de febrero de 2026, auto-memory solo está disponible con la API directa de Anthropic y suscripciones Claude Pro/Max. Los usuarios que acceden a través de AWS Bedrock, Google Vertex AI o Azure no tienen acceso a esta funcionalidad.

Errores comunes y cómo resolverlos

Error: Claude no recuerda nada entre sesiones aunque auto-memory está activo.
Causa: El directorio de memoria se calcula desde la raíz del repositorio git. Si inicias Claude Code fuera de un repo git, el path de memoria puede ser diferente al esperado.
Solución: Verifica que estás dentro de un repositorio git con git rev-parse --show-toplevel y comprueba que el archivo existe en la ruta correcta (~/.claude/projects/<proyecto>/memory/MEMORY.md).

Error: Claude guarda información irrelevante o incorrecta.
Causa: Claude infiere qué es relevante basándose en la conversación. En sesiones largas o con mucho ruido, puede capturar conclusiones preliminares que luego resultaron incorrectas.
Solución: Abre MEMORY.md con /memory y edita o elimina las entradas incorrectas. También puedes pedirle: "Revisa MEMORY.md y elimina las entradas que ya no son relevantes."

Error: MEMORY.md supera las 200 líneas y parte del contexto no se carga.
Causa: Claude no consolida el archivo de forma proactiva en sesiones largas y puede crecer más allá del límite.
Solución: Pide explícitamente la reorganización: "Consolida MEMORY.md, mueve los detalles a archivos temáticos y mantén el entrypoint bajo las 200 líneas." Claude restructurará la jerarquía de archivos para que todo cargue correctamente.

¿Auto-memory reemplaza a CLAUDE.md?

No, son complementarios. CLAUDE.md contiene las reglas que tú impones al agente: convenciones de equipo, restricciones, instrucciones de workflow. Auto-memory contiene lo que Claude aprende por observación. El primero es el contrato que el equipo firma con el agente, versionado en Git. El segundo es el cuaderno de notas personal de Claude, local y actualizado automáticamente. Ambos se cargan al inicio de cada sesión y se usan de forma complementaria.

¿Se puede compartir MEMORY.md con el equipo vía Git?

Técnicamente sí, pero no está diseñado para eso. MEMORY.md vive en ~/.claude/, fuera del repositorio, y captura aprendizajes personales específicos de tu máquina y tus sesiones. Para instrucciones compartidas, usa CLAUDE.md dentro del repositorio. Si descubres algo que el equipo debería saber, migra esa información manualmente al CLAUDE.md del proyecto y commitéala.

¿Qué ocurre con los worktrees de git?

Cada worktree tiene su propio directorio de auto-memory independiente. Si tienes dos ramas activas en paralelo con contextos de trabajo distintos, las memorias de una no contaminan a la otra. Es el comportamiento esperado para flujos de trabajo con múltiples worktrees activos simultáneamente.

La lección de fondo

Auto-memory es una de esas funcionalidades que parece menor hasta que llevas dos semanas sin tener que repetir el mismo contexto al arrancar cada día. La clave está en entender qué resuelve y qué no: no sustituye a la documentación del proyecto ni a CLAUDE.md, no sincroniza entre máquinas, y necesita revisión periódica para evitar que acumule ruido o memorias incorrectas.

El modelo mental correcto: CLAUDE.md es el contrato explícito entre el equipo y el agente, versionado en Git y mantenido por humanos. MEMORY.md es el cuaderno de notas que Claude lleva al trabajo cada día, actualizado automáticamente, que solo tú ves en tu máquina. Los dos juntos hacen que el trabajo con Claude Code sea significativamente más fluido a medida que el proyecto madura y la relación de trabajo con el agente se asienta.

¿Tienes ya configurado un workflow de memoria en Claude Code, o lo gestionas todo desde CLAUDE.md? Cuenta cómo lo usas en los comentarios o en Twitter @sergiomarquezp_. En el siguiente artículo exploraré cómo combinar auto-memory con hooks precompact para maximizar qué información persiste antes de cada compresión de contexto.