Cómo Claude recuerda su proyecto
Proporcione a Claude instrucciones persistentes con archivos CLAUDE.md, y permita que Claude acumule aprendizajes automáticamente con auto memory.
Cada sesión de Claude Code comienza con una ventana de contexto nueva. Dos mecanismos llevan el conocimiento entre sesiones:
- Archivos CLAUDE.md: instrucciones que usted escribe para dar a Claude contexto persistente
- Auto memory: notas que Claude escribe por sí mismo basadas en sus correcciones y preferencias
Esta página cubre cómo:
- Escribir y organizar archivos CLAUDE.md
- Limitar reglas a tipos de archivo específicos con
.claude/rules/ - Configurar auto memory para que Claude tome notas automáticamente
- Solucionar problemas cuando las instrucciones no se siguen
CLAUDE.md vs auto memory
Claude Code tiene dos sistemas de memoria complementarios. Ambos se cargan al inicio de cada conversación. Claude los trata como contexto, no como configuración forzada. Para bloquear una acción independientemente de lo que Claude decida, use un hook PreToolUse en su lugar. Cuanto más específicas y concisas sean sus instrucciones, más consistentemente Claude las seguirá.
| Archivos CLAUDE.md | Auto memory | |
|---|---|---|
| Quién lo escribe | Usted | Claude |
| Qué contiene | Instrucciones y reglas | Aprendizajes y patrones |
| Alcance | Proyecto, usuario u organización | Por repositorio, compartido entre worktrees |
| Se carga en | Cada sesión | Cada sesión (primeras 200 líneas o 25KB) |
| Usar para | Estándares de codificación, flujos de trabajo, arquitectura del proyecto | Sus preferencias, correcciones que le da a Claude, contexto del proyecto que Claude no puede derivar del código |
Use archivos CLAUDE.md cuando quiera guiar el comportamiento de Claude. Auto memory permite que Claude aprenda de sus correcciones sin esfuerzo manual.
Los subagents también pueden mantener su propia auto memory. Consulte configuración de subagent para obtener detalles.
Archivos CLAUDE.md
Los archivos CLAUDE.md son archivos markdown que dan a Claude instrucciones persistentes para un proyecto, su flujo de trabajo personal o toda su organización. Usted escribe estos archivos en texto plano; Claude los lee al inicio de cada sesión.
Cuándo agregar a CLAUDE.md
Trate CLAUDE.md como el lugar donde escribe lo que de otro modo tendría que re-explicar. Agregue a él cuando:
- Claude comete el mismo error una segunda vez
- Una revisión de código detecta lo que sí llega al PR que Claude debería haber sabido sobre esta base de código
- Usted escribe la misma corrección o aclaración en el chat que escribió la sesión anterior
- Un nuevo compañero de equipo necesitaría el mismo contexto para ser productivo
Manténgalo en hechos que Claude debe retener en cada sesión: comandos de compilación, convenciones, diseño del proyecto, reglas "siempre haz X". Si una entrada es un procedimiento de múltiples pasos o solo importa para una parte de la base de código, muévala a un skill o una regla con alcance de ruta en su lugar. La descripción general de extensiones cubre cuándo usar cada mecanismo.
Elija dónde colocar los archivos CLAUDE.md
Los archivos CLAUDE.md pueden vivir en varios lugares, cada uno con un alcance diferente. La tabla a continuación los enumera en orden de carga, desde el alcance más amplio hasta el más específico, por lo que una instrucción de proyecto aparece en contexto después de una instrucción de usuario.
| Alcance | Ubicación | Propósito | Ejemplos de casos de uso | Compartido con |
|---|---|---|---|---|
| Política gestionada | • macOS: /Library/Application Support/ClaudeCode/CLAUDE.md• Linux y WSL: /etc/claude-code/CLAUDE.md• Windows: C:\Program Files\ClaudeCode\CLAUDE.md |
Instrucciones de toda la organización gestionadas por TI/DevOps | Estándares de codificación de la empresa, políticas de seguridad, requisitos de cumplimiento | Todos los usuarios de la organización |
| Instrucciones del usuario | ~/.claude/CLAUDE.md |
Preferencias personales para todos los proyectos | Preferencias de estilo de código, atajos de herramientas personales | Solo usted (todos los proyectos) |
| Instrucciones del proyecto | ./CLAUDE.md o ./.claude/CLAUDE.md |
Instrucciones compartidas por el equipo para el proyecto | Arquitectura del proyecto, estándares de codificación, flujos de trabajo comunes | Miembros del equipo a través del control de versiones |
| Instrucciones locales | ./CLAUDE.local.md |
Preferencias personales específicas del proyecto; agregue a .gitignore |
Sus URLs de sandbox, datos de prueba preferidos | Solo usted (proyecto actual) |
Los archivos CLAUDE.md y CLAUDE.local.md en la jerarquía de directorios por encima del directorio de trabajo se cargan al iniciar. Los archivos en subdirectorios se cargan bajo demanda cuando Claude lee archivos en esos directorios. Consulte Cómo se cargan los archivos CLAUDE.md para el orden de resolución completo.
Para proyectos grandes, puede dividir las instrucciones en archivos específicos de temas usando reglas de proyecto. Las reglas le permiten limitar las instrucciones a tipos de archivo específicos o subdirectorios.
Configure un CLAUDE.md de proyecto
Un CLAUDE.md de proyecto puede almacenarse en ./CLAUDE.md o ./.claude/CLAUDE.md. Cree este archivo y agregue instrucciones que se apliquen a cualquiera que trabaje en el proyecto: comandos de compilación y prueba, estándares de codificación, decisiones arquitectónicas, convenciones de nomenclatura y flujos de trabajo comunes. Estas instrucciones se comparten con su equipo a través del control de versiones, así que enfóquese en estándares a nivel de proyecto en lugar de preferencias personales. Para confirmar que el archivo se cargó, ejecute /context en una sesión y verifique la lista bajo Memory files.
Escriba instrucciones efectivas
Los archivos CLAUDE.md se cargan en la ventana de contexto al inicio de cada sesión, consumiendo tokens junto con su conversación. La visualización de la ventana de contexto muestra dónde se carga CLAUDE.md en relación con el resto del contexto de inicio. Debido a que son contexto en lugar de configuración forzada, cómo escribe las instrucciones afecta qué tan confiablemente Claude las sigue. Las instrucciones específicas, concisas y bien estructuradas funcionan mejor.
Tamaño: apunte a menos de 200 líneas por archivo CLAUDE.md. Los archivos más largos consumen más contexto y reducen la adherencia. Si sus instrucciones están creciendo mucho, use reglas con alcance de ruta para que las instrucciones se carguen solo cuando Claude trabaje con archivos coincidentes. También puede dividir contenido en importaciones para organización, aunque los archivos importados aún se cargan e ingresan a la ventana de contexto al iniciar.
Estructura: use encabezados y viñetas de markdown para agrupar instrucciones relacionadas. Claude escanea la estructura de la misma manera que los lectores: las secciones organizadas son más fáciles de seguir que los párrafos densos.
Especificidad: escriba instrucciones que sean lo suficientemente concretas para verificar. Por ejemplo:
- "Usar indentación de 2 espacios" en lugar de "Formatear código correctamente"
- "Ejecutar
npm testantes de hacer commit" en lugar de "Probar sus cambios" - "Los controladores de API viven en
src/api/handlers/" en lugar de "Mantener los archivos organizados"
Consistencia: si dos reglas se contradicen entre sí, Claude puede elegir una arbitrariamente. Revise sus archivos CLAUDE.md, archivos CLAUDE.md anidados en subdirectorios y archivos .claude/rules/ periódicamente para eliminar instrucciones desactualizadas o conflictivas. En monorepos, use claudeMdExcludes para omitir archivos CLAUDE.md de otros equipos que no sean relevantes para su trabajo.
Importar archivos adicionales
Los archivos CLAUDE.md pueden importar archivos adicionales usando la sintaxis @path/to/import. Los archivos importados se expanden y se cargan en contexto al iniciar junto con el CLAUDE.md que los referencia.
Se permiten rutas relativas y absolutas. Las rutas relativas se resuelven en relación con el archivo que contiene la importación, no con el directorio de trabajo. Los archivos importados pueden importar recursivamente otros archivos, con una profundidad máxima de cuatro saltos.
El análisis de importación omite espacios de código Markdown y bloques de código delimitados. Para mencionar una ruta en su CLAUDE.md sin importarla, envuélvala en backticks: escribir `@README` mantiene el texto literal, mientras que @README fuera de backticks importa el archivo.
Para incluir un README, package.json y una guía de flujo de trabajo, haga referencia a ellos con la sintaxis @ en cualquier lugar de su CLAUDE.md:
Consulte @README para obtener una descripción general del proyecto y @package.json para los comandos npm disponibles para este proyecto.
# Instrucciones adicionales
- flujo de trabajo git @docs/git-instructions.md
Para preferencias personales privadas por proyecto que no desea registrar en el control de versiones, cree un CLAUDE.local.md en la raíz del proyecto. Se carga junto con CLAUDE.md y se trata de la misma manera. Agregue CLAUDE.local.md a su .gitignore para que no se confirme. Con CLAUDE_CODE_NEW_INIT=1 establecido, ejecutar /init y elegir la opción personal hace esto por usted.
Si trabaja en múltiples git worktrees del mismo repositorio, un CLAUDE.local.md ignorado por git solo existe en el worktree donde lo creó. Para compartir instrucciones personales entre worktrees, importe un archivo desde su directorio de inicio en su lugar:
# Preferencias individuales
- @~/.claude/my-project-instructions.md
AGENTS.md
Claude Code lee CLAUDE.md, no AGENTS.md. Si su repositorio ya usa AGENTS.md para otros agentes de codificación, cree un CLAUDE.md que lo importe para que ambas herramientas lean las mismas instrucciones sin duplicarlas. También puede agregar instrucciones específicas de Claude Code debajo de la importación. Claude carga el archivo importado al inicio de la sesión, luego agrega el resto:
@AGENTS.md
## Claude Code
Use plan mode para cambios bajo `src/billing/`.
Un enlace simbólico también funciona si no necesita agregar contenido específico de Claude Code:
ln -s AGENTS.md CLAUDE.md
El comando no imprime salida en caso de éxito. En su próxima sesión, ejecute /context y confirme que CLAUDE.md aparece bajo Memory files.
En Windows, crear un enlace simbólico requiere privilegios de administrador o modo de desarrollador, así que use la importación @AGENTS.md en su lugar.
Ejecutar /init lee reglas de Cursor, en .cursor/rules/ o .cursorrules, y reglas de Copilot, en .github/copilot-instructions.md, e incorpora las partes relevantes en el CLAUDE.md generado. Con CLAUDE_CODE_NEW_INIT=1 establecido, /init también lee AGENTS.md, .devin/rules/, .windsurf/rules/ o .windsurfrules, y .clinerules.
También puede ejecutar /import para traer la configuración de un agente de codificación compatible a Claude Code, que agrega una copia única de archivos de instrucciones como AGENTS.md al CLAUDE.md coincidente y lleva consigo servidores MCP, comandos, subagentes y skills. Requiere Claude Code v2.1.213 o posterior.
Cómo se cargan los archivos CLAUDE.md
Claude Code carga CLAUDE.md y CLAUDE.local.md desde su directorio de trabajo actual y cada directorio por encima de él. Ejecute Claude Code en foo/bar/ y carga instrucciones desde foo/bar/CLAUDE.md, foo/CLAUDE.md y cualquier archivo CLAUDE.local.md junto a ellos.
Todos los archivos descubiertos se concatenan en contexto en lugar de anularse entre sí. Dentro de la jerarquía de directorios, el contenido se ordena desde la raíz del sistema de archivos hasta su directorio de trabajo. Para el ejemplo foo/bar/, foo/CLAUDE.md aparece en contexto antes de foo/bar/CLAUDE.md, por lo que las instrucciones más cercanas a donde lanzó Claude se leen al final. Dentro de cada directorio, CLAUDE.local.md se agrega después de CLAUDE.md, por lo que sus notas personales son lo último que Claude lee en ese nivel.
Claude también descubre archivos CLAUDE.md y CLAUDE.local.md en subdirectorios bajo su directorio de trabajo actual. En lugar de cargarlos al iniciar, se incluyen cuando Claude lee archivos en esos subdirectorios.
Si trabaja en un monorepo grande donde se recogen archivos CLAUDE.md de otros equipos, use claudeMdExcludes para omitirlos. Para el diseño completo de archivos CLAUDE.md de raíz y por directorio y reglas, consulte Monorepos y repositorios grandes.
Los comentarios HTML a nivel de bloque (<!-- notas de mantenimiento -->) en archivos CLAUDE.md se eliminan antes de que el contenido se inyecte en el contexto de Claude. Úselos para dejar notas para los mantenedores humanos sin gastar tokens de contexto en ellas. Los comentarios dentro de bloques de código se conservan. Cuando abre un archivo CLAUDE.md directamente con la herramienta Read, los comentarios permanecen visibles.
Cargar desde directorios adicionales
La bandera --add-dir da a Claude acceso a directorios adicionales fuera de su directorio de trabajo principal. De forma predeterminada, los archivos CLAUDE.md de estos directorios no se cargan.
Para cargar también archivos de memoria desde directorios adicionales, establezca la variable de entorno CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
Esto carga CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md y CLAUDE.local.md desde el directorio adicional. CLAUDE.local.md se omite si excluye local de --setting-sources.
Organizar reglas con `.claude/rules/`
Para proyectos más grandes, puede organizar instrucciones en múltiples archivos usando el directorio .claude/rules/. Esto mantiene las instrucciones modulares y más fáciles de mantener para los equipos. Las reglas también pueden ser limitadas a rutas de archivo específicas, por lo que solo se cargan en contexto cuando Claude trabaja con archivos coincidentes, reduciendo ruido y ahorrando espacio de contexto.
Configurar reglas
Coloque archivos markdown en el directorio .claude/rules/ de su proyecto. Cada archivo debe cubrir un tema, con un nombre de archivo descriptivo como testing.md o api-design.md. Todos los archivos .md se descubren recursivamente, por lo que puede organizar reglas en subdirectorios como frontend/ o backend/:
your-project/
├── .claude/
│ ├── CLAUDE.md # Instrucciones principales del proyecto
│ └── rules/
│ ├── code-style.md # Directrices de estilo de código
│ ├── testing.md # Convenciones de prueba
│ └── security.md # Requisitos de seguridad
Las reglas sin frontmatter paths se cargan al iniciar con la misma prioridad que .claude/CLAUDE.md.
Las reglas del proyecto se omiten si excluye project de --setting-sources. Antes de v2.1.211, las reglas que se cargan bajo demanda, incluidas las reglas con alcance de ruta y las reglas en directorios .claude/rules/ anidados, se cargaban incluso cuando project estaba excluido.
Reglas específicas de ruta
Las reglas pueden limitarse a archivos específicos usando frontmatter YAML con el campo paths. Estas reglas condicionales solo se aplican cuando Claude trabaja con archivos que coinciden con los patrones especificados.
---
paths:
- "src/api/**/*.ts"
---
# Reglas de desarrollo de API
- Todos los puntos finales de API deben incluir validación de entrada
- Usar el formato de respuesta de error estándar
- Incluir comentarios de documentación OpenAPI
Las reglas sin un campo paths se cargan incondicionalmente y se aplican a todos los archivos. Las reglas con alcance de ruta se activan cuando Claude lee archivos que coinciden con el patrón, no en cada uso de herramienta. A partir de v2.1.198, la coincidencia también funciona cuando Claude alcanza un archivo a través de una ruta de proyecto vinculada simbólicamente, por ejemplo en un checkout vinculado simbólicamente.
Use patrones glob en el campo paths para hacer coincidir archivos por extensión, directorio o cualquier combinación:
| Patrón | Coincide con |
|---|---|
**/*.ts |
Todos los archivos TypeScript en cualquier directorio |
src/**/* |
Todos los archivos bajo el directorio src/ |
*.md |
Archivos Markdown en la raíz del proyecto |
src/components/*.tsx |
Componentes React en un directorio específico |
Puede especificar múltiples patrones y usar expansión de llaves para hacer coincidir múltiples extensiones en un patrón:
---
paths:
- "src/**/*.{ts,tsx}"
- "lib/**/*.ts"
- "tests/**/*.test.ts"
---
Cada grupo de llaves multiplica el número de patrones expandidos: src/*.{ts,tsx} se expande a dos patrones, y {a,b}/{c,d}/*.{ts,tsx} a ocho. Para mantener la expansión acotada, la lista paths completa de una regla comparte un presupuesto de 1.000 patrones expandidos y 4 MiB, y los patrones sin llaves no cuentan en su contra.
Claude Code usa cualquier patrón que excedería el presupuesto sin expandir, y sus llaves literales no coinciden con ningún archivo. Antes de v2.1.217, un valor paths con muchos grupos de llaves detenía o bloqueaba la CLI al iniciar.
La sintaxis glob trata [ como el inicio de una expresión de corchetes como [abc]. Un patrón con un [ que no se puede leer como una expresión de corchetes, como photos [2024/**, es inválido: no coincide con nada, y los otros patrones de la regla siguen funcionando. Para hacer coincidir un [ literal en un nombre de archivo, escápelo como photos \[2024/**. Antes de v2.1.207, un patrón inválido hacía que la herramienta Read fallara para cada archivo contra el cual se evaluaba la regla, en lugar de no coincidir con nada.
Compartir reglas entre proyectos con enlaces simbólicos
El directorio .claude/rules/ admite enlaces simbólicos, por lo que puede mantener un conjunto compartido de reglas y vincularlas en múltiples proyectos. Los enlaces simbólicos se resuelven y se cargan normalmente, y los enlaces simbólicos circulares se detectan y se manejan correctamente.
Este ejemplo vincula tanto un directorio compartido como un archivo individual:
ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md
Reglas a nivel de usuario
Las reglas personales en ~/.claude/rules/ se aplican a cada proyecto en su máquina. Úselas para preferencias que no son específicas del proyecto:
~/.claude/rules/
├── preferences.md # Sus preferencias personales de codificación
└── workflows.md # Sus flujos de trabajo preferidos
Las reglas a nivel de usuario se cargan antes que las reglas del proyecto, dando a las reglas del proyecto mayor prioridad.
Gestionar CLAUDE.md para equipos grandes
Para organizaciones que implementan Claude Code en equipos, puede centralizar instrucciones y controlar qué archivos CLAUDE.md se cargan.
Implementar CLAUDE.md en toda la organización
Las organizaciones pueden implementar un CLAUDE.md gestionado centralmente que se aplique a todos los usuarios en una máquina. Este archivo no puede ser excluido por configuraciones individuales.
Crear el archivo en la ubicación de política gestionada
- macOS:
/Library/Application Support/ClaudeCode/CLAUDE.md - Linux y WSL:
/etc/claude-code/CLAUDE.md - Windows:
C:\Program Files\ClaudeCode\CLAUDE.md
Implementar con su sistema de gestión de configuración
Use MDM, Group Policy, Ansible o herramientas similares para distribuir el archivo en máquinas de desarrolladores. Consulte configuración gestionada para otras opciones de configuración de toda la organización.
La clave claudeMd le permite poner contenido CLAUDE.md gestionado directamente dentro de managed-settings.json en lugar de implementar un archivo separado.
Alcance: cada sesión de Claude Code en la máquina, en cada repositorio. Para orientación específica del repositorio, confirme un CLAUDE.md de proyecto en su lugar.
Precedencia: igual que un archivo CLAUDE.md gestionado. Se carga antes que CLAUDE.md de usuario y proyecto.
Dónde se respeta: solo configuración gestionada y de política. Establecer claudeMd en configuración de usuario, proyecto o local no tiene efecto.
El ejemplo a continuación agrega instrucciones conductuales directamente en un archivo de configuración gestionada:
{
"claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}
Un CLAUDE.md gestionado y configuración gestionada sirven para propósitos diferentes. Use configuración para aplicación técnica y CLAUDE.md para orientación conductual:
| Preocupación | Configurar en |
|---|---|
| Bloquear herramientas, comandos o rutas de archivo específicas | Configuración gestionada: permissions.deny |
| Aplicar aislamiento de sandbox | Configuración gestionada: sandbox.enabled |
| Variables de entorno y enrutamiento de proveedor de API | Configuración gestionada: env |
| Método de autenticación y bloqueo de organización | Configuración gestionada: forceLoginMethod, forceLoginOrgUUID |
| Directrices de estilo de código y calidad | CLAUDE.md gestionado |
| Recordatorios de manejo de datos y cumplimiento | CLAUDE.md gestionado |
| Instrucciones conductuales para Claude | CLAUDE.md gestionado |
Las reglas de configuración se aplican por el cliente independientemente de lo que Claude decida hacer. Las instrucciones de CLAUDE.md moldean el comportamiento de Claude pero no son una capa de aplicación forzada.
Excluir archivos CLAUDE.md específicos
En monorepos grandes, los archivos CLAUDE.md ancestros pueden contener instrucciones que no son relevantes para su trabajo. La configuración claudeMdExcludes le permite omitir archivos específicos por ruta o patrón glob.
Este ejemplo excluye un CLAUDE.md de nivel superior y un directorio de reglas de una carpeta principal. Agréguelo a .claude/settings.local.json para que la exclusión permanezca local en su máquina:
{
"claudeMdExcludes": [
"**/monorepo/CLAUDE.md",
"/home/user/monorepo/other-team/.claude/rules/**"
]
}
Los patrones se comparan contra rutas de archivo absolutas usando sintaxis glob. Puede configurar claudeMdExcludes en cualquier capa de configuración: usuario, proyecto, local o política gestionada. Los arrays se fusionan entre capas.
Para excluir un archivo de reglas que alcanza a través de un enlace simbólico, ya sea que el archivo o su directorio sea el enlace, escriba el patrón contra cualquiera de las rutas: la ruta del archivo bajo .claude/rules/ o su destino de enlace. Un patrón que coincida con cualquiera de las rutas excluye el archivo. Antes de v2.1.239, solo un patrón que coincidiera con el destino del enlace excluía el archivo.
Los archivos CLAUDE.md de política gestionada no pueden ser excluidos. Esto asegura que las instrucciones de toda la organización siempre se apliquen independientemente de la configuración individual.
Auto memory
Auto memory permite que Claude acumule conocimiento entre sesiones sin que usted escriba nada. Mientras trabaja, Claude guarda cuatro tipos de notas para sí mismo. Claude registra el tipo como un campo type en el frontmatter del archivo de memoria:
user: su rol, experiencia y preferencias de trabajofeedback: correcciones que usted le da a Claude y enfoques que usted confirmaproject: trabajo en curso, plazos y decisiones que Claude no puede derivar del código o del historial de gitreference: dónde encontrar información fuera del proyecto, como un rastreador de problemas o un panel de control
Claude omite cualquier cosa que pueda derivar del código base, como arquitectura, rutas de archivo o correcciones de depuración. También omite cualquier cosa que sus archivos CLAUDE.md ya digan.
Claude no guarda algo cada sesión. Decide qué vale la pena recordar basándose en si la información sería útil en una conversación futura.
Habilitar o deshabilitar auto memory
Auto memory está habilitado de forma predeterminada. Para alternarlo, abra /memory en una sesión y use el botón de alternancia de auto memory, que guarda autoMemoryEnabled en la configuración de usuario en ~/.claude/settings.json. Para desactivarlo en un único proyecto, establezca autoMemoryEnabled en la configuración de ese proyecto:
{
"autoMemoryEnabled": false
}
Para deshabilitar auto memory a través de variable de entorno, establezca CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
Ubicación de almacenamiento
Cada proyecto obtiene su propio directorio de memoria en ~/.claude/projects/<project>/memory/. La ruta <project> se deriva del repositorio git, por lo que todos los worktrees y subdirectorios dentro del mismo repositorio comparten un directorio de auto memory. Fuera de un repositorio git, se usa la raíz del proyecto en su lugar.
Si establece CLAUDE_CODE_PROJECT_DIR_NAME junto a CLAUDE_CONFIG_DIR, Claude Code usa ese nombre como el directorio <project> bajo <config dir>/projects/ en lugar de cualquier repositorio que inicie, por lo que los proyectos iniciados con ese directorio de configuración comparten un directorio de auto memory. Requiere Claude Code v2.1.234 o posterior.
Para almacenar auto memory en una ubicación diferente, establezca autoMemoryDirectory en su settings.json. Se lee desde cualquier ámbito de configuración: usuario, proyecto, local, política, o --settings.
{
"autoMemoryDirectory": "~/my-custom-memory-dir"
}
El valor debe ser una ruta absoluta o comenzar con ~/. Cuando se establece en .claude/settings.json o .claude/settings.local.json de un proyecto, Claude Code lo respeta bajo la misma regla de confianza del espacio de trabajo que los hooks en archivos de configuración.
El directorio contiene un índice MEMORY.md y un archivo de tema por memoria:
~/.claude/projects/<project>/memory/
├── MEMORY.md # Índice, una línea por memoria, cargado en cada sesión
├── user_role.md # Una memoria
├── feedback_testing.md # Una memoria
└── ... # Cualquier otro archivo de tema que Claude cree
MEMORY.md actúa como un índice del directorio de memoria. Claude lee y escribe archivos en este directorio durante su sesión, usando MEMORY.md para mantener un registro de lo que se almacena dónde.
Auto memory es local de la máquina. Todos los worktrees y subdirectorios dentro del mismo repositorio git comparten un directorio de auto memory. Los archivos no se comparten entre máquinas o entornos en la nube.
Claude Code elimina transcripciones de sesiones antiguas después del período de retención cleanupPeriodDays, pero excluye los archivos de memoria en el directorio de memoria de ese barrido de retención. MEMORY.md y los archivos de tema permanecen hasta que usted o Claude los edite o elimine.
Cómo funciona
Las primeras 200 líneas de MEMORY.md, o los primeros 25KB, lo que sea menor, se cargan al inicio de cada conversación. El contenido más allá de ese umbral no se carga al inicio de la sesión. Claude mantiene MEMORY.md conciso moviendo notas detalladas a archivos de tema separados.
Después de que Claude escribe en MEMORY.md, Claude Code mide el archivo contra los límites de lectura de 200 líneas y 25KB. Si el archivo está cerca de un límite, Claude Code le recuerda a Claude que lo acorte: mantenga una línea por entrada, mueva detalles a archivos de tema y combine o elimine entradas obsoletas. Si el archivo supera un límite, la escritura aún tiene éxito, pero Claude Code devuelve un error indicándole a Claude que reescriba el índice, porque todo lo que está más allá del límite se descarta en la siguiente carga.
Este límite se aplica solo a MEMORY.md. Claude Code carga un archivo CLAUDE.md de hasta 4 MiB en su totalidad y omite un archivo más grande. Los archivos más cortos producen mejor adherencia.
Claude Code no carga archivos de tema como user_role.md o feedback_testing.md al iniciar. Claude los lee bajo demanda usando sus herramientas de archivo estándar cuando necesita la información.
La auto memory de la conversación principal no se carga en subagentes; la excepción es un fork, que hereda la conversación principal y el prompt del sistema. La auto memory propia de un subagente, habilitada con el campo memory del subagente, es un directorio separado.
Claude lee y escribe archivos de memoria durante su sesión. Cuando ve mensajes como "Saved 2 memories" o "Recalled 2 memories" en la interfaz de Claude Code, Claude está actualizando o leyendo activamente desde ~/.claude/projects/<project>/memory/.
Cuando Claude escribe un archivo de memoria que comienza con frontmatter YAML, Claude Code registra la hora de escritura en un campo modified del frontmatter como una marca de tiempo ISO 8601. La marca de tiempo muestra cuán actual es el hecho, tanto para usted como para Claude cuando lo vuelve a leer. Cualquier archivo que tenga frontmatter obtiene el campo la próxima vez que Claude lo escribe, incluidos los archivos creados en versiones anteriores; Claude Code nunca agrega frontmatter a un archivo que no lo tenga. El campo modified requiere Claude Code v2.1.214 o posterior.
Auditar y editar su memoria
Los archivos de auto memory son markdown plano que puede editar o eliminar en cualquier momento. Ejecute /memory para examinar y abrir archivos de memoria desde dentro de una sesión.
Ver y editar con `/memory`
El comando /memory enumera sus archivos CLAUDE.md, CLAUDE.local.md y otros archivos de memoria en los ámbitos de usuario y proyecto, incluidas las entradas CLAUDE.md de usuario y proyecto para archivos que aún no existen. También le permite alternar auto memory activado o desactivado y proporciona una opción para abrir la carpeta de auto memory. Seleccione cualquier archivo para abrirlo en su editor; seleccionar uno que aún no existe lo crea primero. Para verificar qué archivos se cargaron realmente en la sesión actual, ejecute /context.
Los editores GUI como VS Code abren el archivo en una ventana separada, y puede seguir usando la sesión mientras está abierto. Antes de v2.1.216, /memory esperaba a que cerrara el archivo antes de responder. Los editores de terminal como Vim toman el control del terminal hasta que salga.
Cuando le pide a Claude que recuerde algo, como "siempre usar pnpm, no npm" o "recuerde que las pruebas de API requieren una instancia local de Redis", Claude lo guarda en auto memory. Para agregar instrucciones a CLAUDE.md en su lugar, pídale a Claude directamente, como "agregue esto a CLAUDE.md", o edite el archivo usted mismo a través de /memory.
Solucionar problemas de memoria
Estos son los problemas más comunes con CLAUDE.md y auto memory, junto con pasos para depurarlos.
Claude no está siguiendo mi CLAUDE.md
El contenido de CLAUDE.md se entrega como un mensaje de usuario después del prompt del sistema, no como parte del prompt del sistema en sí. Claude lo lee e intenta seguirlo, pero no hay garantía de cumplimiento estricto, especialmente para instrucciones vagas o conflictivas.
Para depurar:
- Ejecute
/contexty verifique la lista bajo Memory files para verificar que sus archivos CLAUDE.md y CLAUDE.local.md se cargaron. Si un archivo no aparece allí, Claude no puede verlo. Use/memorypara abrir y editar los archivos. - Verifique que el CLAUDE.md relevante esté en una ubicación que se cargue para su sesión (consulte Elija dónde colocar los archivos CLAUDE.md).
- Haga instrucciones más específicas. "Usar indentación de 2 espacios" funciona mejor que "formatear código bien".
- Busque instrucciones conflictivas en archivos CLAUDE.md. Si dos archivos dan orientación diferente para el mismo comportamiento, Claude puede elegir uno arbitrariamente.
Si la instrucción es algo que debe ejecutarse en un punto específico, como antes de cada commit o después de cada edición de archivo, escríbala como un hook en su lugar. Los hooks se ejecutan como comandos de shell en eventos de ciclo de vida fijos y se aplican independientemente de lo que Claude decida hacer.
Para instrucciones que desea a nivel de prompt del sistema, use --append-system-prompt. Esto debe pasarse en cada invocación, por lo que es más adecuado para scripts y automatización que para uso interactivo.
No sé qué guardó auto memory
Ejecute /memory y seleccione la carpeta de auto memory para examinar lo que Claude ha guardado. Todo es markdown plano que puede leer, editar o eliminar.
Mi CLAUDE.md es demasiado grande
Los archivos de más de 200 líneas consumen más contexto y pueden reducir la adherencia. Claude Code omite un archivo de más de 4 MiB. Use reglas con alcance de ruta para cargar instrucciones solo cuando Claude trabaja con archivos coincidentes, o recorte contenido que no sea necesario en cada sesión. Dividir en importaciones @path ayuda a la organización pero no reduce el contexto, ya que los archivos importados se cargan al iniciar.
La revisión /doctor propone recortes para un CLAUDE.md registrado: elimina contenido que Claude puede derivar de la base de código, como diseños de directorios, listas de dependencias y descripción general de la arquitectura, y mantiene trampas, justificación y convenciones que difieren de los valores predeterminados de las herramientas. La verificación de recorte requiere Claude Code v2.1.206 o posterior.
Las instrucciones parecen perdidas después de `/compact`
CLAUDE.md de raíz de proyecto sobrevive a la compactación: después de /compact, Claude vuelve a leer desde el disco e lo reinyecta en la sesión. Los archivos CLAUDE.md anidados en subdirectorios y reglas con frontmatter paths: se recargan cuando Claude lee archivos a los que se aplican.
Si una instrucción desapareció después de la compactación, se dio solo en la conversación, vive en un CLAUDE.md anidado que aún no se ha recargado, o es una regla con alcance de ruta que no ha coincidido con un archivo desde entonces. Agregue instrucciones solo de conversación a CLAUDE.md para que persistan. Consulte Qué sobrevive a la compactación para el desglose completo.
Consulte Escriba instrucciones efectivas para obtener orientación sobre tamaño, estructura y especificidad.
Recursos relacionados
- Depurar su configuración: diagnosticar por qué CLAUDE.md o configuración no están surtiendo efecto
- Skills: empaquetar flujos de trabajo repetibles que se cargan bajo demanda
- Settings: configurar el comportamiento de Claude Code con archivos de configuración
- Subagent memory: permitir que los subagents mantengan su propia auto memory