Cómo recuerda Claude Code tu proyecto

Cada sesión de Claude Code empieza con una ventana de contexto nueva. Dos cosas llevan el conocimiento de una sesión a la siguiente: un archivo CLAUDE.md que escribes tú y las notas que Claude escribe para sí mismo, la memoria automática. Hacen trabajos distintos, y saber cuál es cuál ahorra muchas confusiones.

Las dos, una al lado de la otra

• CLAUDE.mdLo escribes tú. Instrucciones y reglas: normas de código, flujos de trabajo, cómo está organizado el proyecto. Puede estar a nivel de proyecto, de usuario o de organización. Se carga al empezar cada sesión.
• Memoria automáticaLa escribe Claude. Aprendizajes y patrones: tus preferencias, las correcciones que le diste, contexto del proyecto que no puede deducir del código. Se guarda por repositorio. De su índice solo se carga el principio en cada sesión.

Usa CLAUDE.md cuando quieras guiar el comportamiento de Claude. La memoria automática sirve para que Claude aprenda de tus correcciones sin que tengas que apuntar nada.

Qué guarda la memoria automática

Claude archiva sus notas en cuatro tipos: user (tu rol y cómo te gusta trabajar), feedback (correcciones y enfoques que confirmaste), project (trabajo en curso y decisiones que no puede sacar del código ni del historial de git) y reference (dónde encontrar cosas fuera del proyecto, como un gestor de tareas o un panel). Se salta lo que puede leer en el código y lo que ya dice tu CLAUDE.md. No guarda algo en todas las sesiones.

Dónde vive

Cada proyecto tiene una carpeta en ~/.claude/projects/<proyecto>/memory/. Todos los worktrees y subdirectorios del mismo repositorio de git la comparten. Contiene un índice MEMORY.md, una línea por recuerdo, y un archivo por tema. Al empezar la sesión Claude carga las primeras 200 líneas o 25 KB del índice, lo que llegue antes. Los archivos de cada tema se leen cuando hacen falta. Son archivos markdown normales en tu equipo: no se comparten entre máquinas, y puedes leerlos, editarlos o borrarlos.

Mirar, editar, apagar

• /memory lista los archivos de memoria, abre uno en tu editor y tiene el interruptor de la memoria automática y un acceso a su carpeta.
• Pídele a Claude «recuerda que los tests de la API necesitan un Redis local» y lo guarda en la memoria automática. Para que vaya a CLAUDE.md, dilo: «añade esto a CLAUDE.md».
• Para apagarla en un proyecto, pon autoMemoryEnabled a false en los ajustes de ese proyecto. La variable de entorno CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 hace lo mismo.

Cuando Claude ignora tu CLAUDE.md

La documentación es clara: CLAUDE.md es contexto, no configuración que se imponga. Claude lo lee e intenta seguirlo, pero no hay garantía, sobre todo con instrucciones vagas o que se contradicen. Revisa, por este orden:

1. ¿Está cargado? Ejecuta /context y mira en Memory files. Si tu archivo no sale ahí, Claude no puede verlo. (Un CLAUDE.md de un subdirectorio se carga cuando hace falta, así que al arrancar no aparecerá.)
2. ¿Está en el sitio correcto? Los archivos de proyecto, de usuario y de organización se cargan desde ubicaciones distintas. Mira la carpeta .claude explicada.
3. ¿Es concreto? «Usa sangría de 2 espacios» funciona mejor que «da buen formato al código».
4. ¿Se contradicen dos archivos? Si dos archivos dan indicaciones distintas sobre lo mismo, Claude puede elegir una al azar.
5. ¿Es demasiado largo? La documentación dice que los archivos de más de 200 líneas gastan más contexto y pueden reducir el seguimiento. Quita lo que Claude puede encontrar en el código, como listados de directorios y de dependencias. Dividir en importaciones @ruta ordena el archivo pero no ahorra contexto, porque lo importado se carga con el archivo que lo importa. Nuestra lista de comprobación de CLAUDE.md lo repasa.
6. ¿Tiene que pasar siempre? Entonces no es trabajo para CLAUDE.md. Un hook se ejecuta como comando en un punto fijo decida lo que decida Claude. Mira CLAUDE.md, skill, hook o subagente para elegir.

Cuando parece que olvida tras /compact

Según la documentación, el CLAUDE.md de la raíz del proyecto sobrevive a la compactación: Claude lo vuelve a leer del disco después. Los CLAUDE.md anidados y las reglas por ruta se cargan otra vez cuando hacen falta. Si una instrucción desapareció, lo más probable es que solo se hubiera dado en la conversación. Lo que deba durar, ponlo en CLAUDE.md. Para llevar trabajo de una sesión a otra también ayuda una nota de relevo.

¿Ya tienes un AGENTS.md?

Las versiones recientes de Claude Code pueden leer el AGENTS.md de un repositorio como instrucciones del proyecto, pero por defecto solo si no hay un CLAUDE.md en tu directorio de trabajo ni por encima. Si hay los dos, lee CLAUDE.md. La forma sencilla de compartir un solo archivo es un CLAUDE.md que lo importe con una línea @AGENTS.md. Depende de tu versión y de tus ajustes, así que mira la página de memoria de la documentación para la tuya.

Pruébalo con algo inofensivo

1. Ejecuta /memory y abre la carpeta de la memoria automática. Lee lo que hay.
2. Ejecuta /context y comprueba que salen los CLAUDE.md que esperas.
3. Busca una línea vaga de tu CLAUDE.md y reescríbela para que un extraño pueda comprobar si se cumplió.

Esta página sigue la documentación de memoria de Anthropic tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los casos. Donde esta página y la documentación no coincidan, manda la documentación.

Mira también: Claude Code en un código grande · Claude Code en GitHub Actions.

La skill gratis loop-stop da a las tareas largas un límite y una regla de parada. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).