Durante meses, los asistentes de programación han tenido un problema bastante humano: olvidaban. La sesión terminaba y, con ella, se iba el contexto: comandos de build, convenciones del proyecto, patrones de arquitectura o ese “aquí usamos pnpm, no npm” que te tocaba repetir una y otra vez. Claude Code intenta resolverlo con un sistema de memoria persistente que combina dos ideas sencillas: memoria automática (la escribe el propio Claude) y archivos CLAUDE.md (los escribe el equipo).
La clave es que no se trata de “guardar todo”. Se trata de guardar lo justo, en el sitio adecuado y con prioridad clara, para que el asistente se comporte como un compañero que llega ya con el briefing leído.
Dos tipos de memoria que persisten entre sesiones
Claude Code usa dos mecanismos complementarios:
- Auto memory: notas que Claude va guardando sobre el proyecto (patrones, comandos, soluciones de debugging, preferencias).
- CLAUDE.md: instrucciones explícitas que el usuario o el equipo mantiene (reglas, estándares, decisiones de arquitectura, forma de testear, etc.).
Un matiz importante: la memoria automática solo carga de inicio las primeras 200 líneas del archivo principal (MEMORY.md). El resto se organiza en ficheros temáticos que Claude abre “bajo demanda” cuando los necesita.
La jerarquía: no hay un solo CLAUDE.md (y eso es buena noticia)
Claude Code no funciona con un único archivo mágico, sino con una estructura jerárquica de ubicaciones. Lo más específico manda sobre lo general, y la memoria se “descubre” desde el directorio de trabajo hacia arriba.
Tabla rápida de tipos de memoria y dónde viven
| Tipo de memoria | Ubicación | Para qué sirve | Se comparte con |
|---|---|---|---|
| Managed policy (empresa) | macOS: /Library/Application Support/ClaudeCode/CLAUDE.md · Linux: /etc/claude-code/CLAUDE.md · Windows: C:\Program Files\ClaudeCode\CLAUDE.md | Reglas corporativas (seguridad, compliance, estándares) | Organización |
| Project memory | ./CLAUDE.md o ./.claude/CLAUDE.md | Instrucciones del proyecto | Equipo (vía repo) |
| Project rules | ./.claude/rules/*.md | Reglas modulares por tema | Equipo (vía repo) |
| User memory | ~/.claude/CLAUDE.md | Preferencias personales globales | Solo tú |
| Project memory (local) | ./CLAUDE.local.md | Preferencias personales del proyecto (sin commitear) | Solo tú |
| Auto memory | ~/.claude/projects/<project>/memory/ | Notas automáticas por proyecto | Solo tú |
Auto memory: lo que Claude apunta “para la próxima vez”
La memoria automática está pensada para registrar cosas útiles que aparecen trabajando:
- comandos de build/test,
- soluciones a errores recurrentes,
- notas de arquitectura (ficheros clave, relaciones),
- preferencias de flujo (herramientas, estilo).
Cada repositorio tiene su carpeta en ~/.claude/projects/<project>/memory/, con un MEMORY.md como índice y otros archivos temáticos (por ejemplo, debugging.md). Solo se precargan las primeras 200 líneas de MEMORY.md, así que la recomendación implícita es clara: índice corto, detalles en ficheros separados.
Cómo desactivar auto memory (si lo necesitas)
En equipos, CI o entornos regulados, puede interesar apagarlo:
// ~/.claude/settings.json (global)
{ "autoMemoryEnabled": false }
// .claude/settings.json (solo para un proyecto)
{ "autoMemoryEnabled": false }
O forzarlo por variable de entorno (ideal para CI):
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # fuerza OFF
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 # fuerza ON
CLAUDE.md: tu “briefing” de proyecto, con imports para no crear un monstruo
Los archivos CLAUDE.md permiten documentar reglas, decisiones y preferencias. Pero el truco para que no se conviertan en una biblia inmanejable es que soportan imports con sintaxis @ruta/al/archivo, con un límite de profundidad (hasta 5 saltos). Esto permite mantener un CLAUDE.md corto y derivar reglas extensas a documentos específicos (seguridad, testing, API, frontend, etc.).
Ejemplo práctico:
# Contexto del proyecto
- Stack: Node + TypeScript + Postgres
- Comandos: ver @package.json
- Arquitectura: ver @docs/arquitectura.md# Reglas
- Testing: @docs/testing.md
- API: @docs/api.md
- Seguridad: @docs/security.md
Reglas modulares: .claude/rules y “solo aplica si tocas estos ficheros”
Para equipos grandes, lo más útil suele ser organizar reglas en ./.claude/rules/ con ficheros por tema. Y, además, se pueden limitar por rutas usando frontmatter YAML (por ejemplo, que ciertas reglas solo apliquen cuando Claude trabaja en src/api/**).
---
paths:
- "src/api/**/*.ts"
---# Reglas API
- Validación de entrada obligatoria
- Formato estándar de errores
También admite globs habituales y brace expansion (por ejemplo {src,lib}/**/*.ts).
Recomendaciones “de sysadmin” para no meterte en líos
- No metas secretos en CLAUDE.md ni en memorias (tokens, URLs internas sensibles, credenciales). Trata estos archivos como documentación.
- Mantén el CLAUDE.md del proyecto corto: comandos, convenciones, “gotchas” y enlaces a docs.
- Versiona reglas del equipo (
.claude/CLAUDE.mdy.claude/rules/) y deja lo personal enCLAUDE.local.md. - En CI, considera forzar
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1para evitar escritura de contexto en runners efímeros. - Revisa periódicamente la memoria automática: si el asistente “aprende” mal, lo arrastrará.
vía: Claude Memory
