Claude Code memory: cómo funciona la memoria

Los 3 tipos de memoria en Claude Code

Claude Code tiene tres niveles de memoria, cada uno con diferente durabilidad y propósito:

1. Contexto de sesión (efímero): Todo lo que hablas en una sesión activa. Se pierde al cerrar. Tiene límite (ventana de contexto del modelo, actualmente hasta 200K tokens). Es la memoria de trabajo inmediata.
2. MEMORY.md (persistente, automática): Archivo que Claude Code actualiza automáticamente entre sesiones. Persiste hasta que lo borres o modifiques. Es la memoria a largo plazo dinámica.
3. CLAUDE.md (persistente, manual): Instrucciones estáticas que se cargan al inicio de cada sesión. Es tu control manual sobre lo que Claude Code "sabe". Es la memoria a largo plazo estática.

La combinación de estos tres niveles permite que Claude Code sea útil desde la primera interacción y mejore con el tiempo. Cada nivel resuelve un problema distinto: el contexto de sesión da inmediatez, MEMORY.md da continuidad, y CLAUDE.md da consistencia.

Jerarquía de memoria: cómo se cargan

Al iniciar una sesión de Claude Code, la memoria se carga en un orden específico. Entender este orden te ayuda a decidir dónde poner cada tipo de información:

1. CLAUDE.md global (~/.claude/CLAUDE.md): se carga primero. Aplica a todos los proyectos. Aquí van tus preferencias personales universales: idioma, estilo de respuesta, reglas que siempre quieres.

2. CLAUDE.md del proyecto (./CLAUDE.md en la raíz del repo): se carga segundo. Específico del proyecto. Stack, convenciones de código, restricciones técnicas, naming. Se commitea en git y lo comparte todo el equipo.

3. CLAUDE.md de subdirectorio (./src/CLAUDE.md, ./tests/CLAUDE.md): se cargan según el contexto de trabajo. Permiten reglas específicas por módulo o capa del proyecto.

4. MEMORY.md global (~/.claude/memory/MEMORY.md): memoria automática que aplica a todos los proyectos.

5. MEMORY.md del proyecto (.claude/memory/MEMORY.md): memoria automática específica del proyecto actual.

Todo esto se inyecta en el system prompt antes de tu primer mensaje. Consume tokens de la ventana de contexto, por lo que la brevedad importa. Un CLAUDE.md de 500 líneas consume espacio que podrías necesitar para la conversación.

# Orden de carga (simplificado)
~/.claude/CLAUDE.md          → Reglas globales personales
./CLAUDE.md                  → Reglas del proyecto (git)
./src/CLAUDE.md              → Reglas del subdirectorio (si existe)
~/.claude/memory/MEMORY.md   → Memoria global auto
.claude/memory/MEMORY.md     → Memoria proyecto auto
─────────────────────────────
[Tu primer mensaje]          → Empieza la sesión

MEMORY.md: memoria persistente automática

MEMORY.md es el sistema de memoria automática de Claude Code. Vive en dos posibles ubicaciones:

• ~/.claude/memory/MEMORY.md — Memoria global (aplica a todos los proyectos).
• .claude/memory/MEMORY.md — Memoria del proyecto (específica para este repo).

Claude Code actualiza MEMORY.md automáticamente cuando detecta información que vale la pena recordar: decisiones técnicas, preferencias del usuario, estado de tareas, errores resueltos. No necesitas pedirlo explícitamente (aunque puedes).

# MEMORY.md (ejemplo real)

## Proyecto
- Stack: Next.js 14 + Supabase + Tailwind
- Deploy: Cloudflare Pages
- Testing: vitest + playwright

## Decisiones
- 2026-05-10: Migrar de CSS Modules a Tailwind (ADR-012)
- 2026-05-08: Usar Server Components por defecto

## Preferencias del usuario
- Respuestas en español
- Conventional commits
- Prefiere código conciso sobre comentarios extensos

## Tareas pendientes
- Implementar dark mode (issue #45)
- Fix: timeout en API de pagos (prioridad alta)

Puedes editar MEMORY.md manualmente. Es un archivo Markdown normal. Si algo está mal o desactualizado, corrígelo directamente con cualquier editor de texto.

Qué guarda MEMORY.md automáticamente:

• Decisiones técnicas que tomas durante la sesión ("usemos Tailwind en vez de CSS Modules")
• Errores encontrados y sus soluciones ("el timeout era por falta de index en la tabla X")
• Preferencias que expresas ("siempre usa conventional commits")
• Estado de tareas en progreso ("migración al 60%, faltan los tests")
• Configuraciones específicas del entorno ("deploy en branch main, staging en develop")

Qué NO guarda automáticamente:

• Código completo (demasiado largo, consume contexto)
• Conversaciones triviales
• Información que ya está en CLAUDE.md

CLAUDE.md como memoria estática

Mientras MEMORY.md es dinámico (Claude Code lo actualiza), CLAUDE.md es estático (tú lo escribes y controlas). Son complementarios:

• CLAUDE.md: Reglas del proyecto que no cambian frecuentemente (stack, convenciones, restricciones, naming).
• MEMORY.md: Contexto que evoluciona (decisiones recientes, estado de tareas, errores encontrados).

El anti-pattern es poner información que cambia frecuentemente en CLAUDE.md. Si una tarea se completa o una decisión se revierte, tienes que actualizar CLAUDE.md manualmente. MEMORY.md se encarga de eso solo.

Buenas prácticas para CLAUDE.md

Un buen CLAUDE.md es la diferencia entre un Claude Code que entiende tu proyecto y uno que pregunta lo mismo cada sesión. Estas son las prácticas que mejor funcionan:

1. Estructura clara con secciones

# CLAUDE.md

## Stack
- Backend: FastAPI + Python 3.11
- Frontend: Next.js 14 + React + Tailwind
- DB: Supabase PostgreSQL con RLS
- Deploy: Cloudflare Pages (frontend) + Hetzner (backend)

## Convenciones
- Conventional commits (feat/fix/docs/refactor)
- Tests obligatorios para endpoints nuevos
- TypeScript strict mode en frontend

## Restricciones
- NUNCA usar CSS modules (solo Tailwind)
- NUNCA instalar lodash (usar es-toolkit)
- API keys solo en .env, nunca hardcoded

## Naming
- Componentes: PascalCase
- Utilidades: camelCase
- Archivos de test: nombre.test.ts

2. Sé conciso. Cada línea de CLAUDE.md consume tokens de tu ventana de contexto. Menos es más. Un CLAUDE.md de 50 líneas bien escritas supera a uno de 300 líneas con redundancia.

3. Usa imperativos. "Usa Tailwind" es mejor que "El proyecto usa Tailwind y nos gustaría que siempre se usara Tailwind en vez de otras alternativas de CSS". Claude Code responde mejor a instrucciones directas.

4. Incluye anti-patterns. Los "NUNCA" son tan importantes como los "SIEMPRE". Si hay errores recurrentes, documéntalos como restricciones explícitas.

5. Versiona con git. CLAUDE.md en la raíz del proyecto se commitea en git. Todo el equipo comparte las mismas reglas. Los cambios se revisan en PR como cualquier otro código.

El sistema de auto-memoria

Claude Code tiene un sistema de auto-memoria que decide qué información vale la pena persistir entre sesiones. Funciona de forma transparente, pero entender sus reglas te permite aprovecharlo mejor.

Cuándo se activa la auto-memoria:

• Cuándo tomas una decisión técnica explícita ("vamos a usar Redis para el cache")
• Cuándo resuelves un problema complejo (guarda el problema y la solución)
• Cuándo expresas una preferencia ("prefiero funciones pequeñas de una responsabilidad")
• Cuándo cambias el estado de una tarea ("la migración está completa")
• Al final de sesiones largas con muchas decisiones

Cómo forzar la escritura en memoria:

# Pedirle explícitamente que guarde algo
> Guarda en MEMORY.md: decidimos usar Stripe para pagos,
  webhook en /api/webhooks/stripe, secreto en STRIPE_WEBHOOK_SECRET

# Pedirle que resuma la sesión
> Resume las decisiones de esta sesión en MEMORY.md

# Pedirle que actualice el estado de una tarea
> Actualiza MEMORY.md: el refactoring del módulo auth está completo

Auto-memoria vs memoria explícita: la auto-memoria es útil para el 80% de los casos. Pero para información crítica que NO puedes permitirte perder, pídelo explícitamente. No confíes en que Claude Code detecte automáticamente que algo es importante para ti.

Gestionar el contexto: /compact y compresión

En sesiones largas, el contexto se llena. Cuando Claude Code alcanza el límite de la ventana de contexto, pierde los mensajes más antiguos (sliding window). Esto puede hacer que "olvide" decisiones tomadas al principio de la sesión.

El comando /compact resuelve esto. Comprime toda la conversación en un resumen más corto, liberando espacio para nuevas interacciones.

# Cuando usar /compact
> /compact

# Claude Code resume la conversación y libera contexto.
# Pierdes detalle fino pero mantienes las decisiones clave.

# Compact con instrucción específica
> /compact Mantén el foco en la migración de auth y los endpoints pendientes

Cómo funciona la compresión internamente:

1. Claude Code analiza toda la conversación actual
2. Identifica: decisiones clave, código modificado, errores encontrados, tareas pendientes
3. Descarta: mensajes intermedios, explicaciones ya consumidas, intentos fallidos
4. Genera un resumen estructurado que reemplaza la conversación
5. La sesión continúa con el resumen como contexto base

Qué se pierde con /compact:

• El detalle fino de explicaciones intermedias
• Los intentos fallidos y su razonamiento
• Los matices de discusiones que llevaron a una decisión
• Código que se mostró pero no se guardó en archivos

Qué se mantiene:

• Decisiones técnicas tomadas
• Estado actual de las tareas
• Archivos modificados y cambios realizados
• Errores encontrados y sus soluciones

Estrategias para sesiones largas

Si trabajas en tareas que requieren sesiones de horas, estas estrategias te ahorrarán problemas:

1. Checkpoint de memoria

Cada 20-30 interacciones, pide a Claude Code que resuma las decisiones clave en MEMORY.md:

> Resume las decisiones y cambios de esta sesión en MEMORY.md

Si la sesión se corta inesperadamente (timeout, crash, cierre accidental), la información crítica ya está persistida.

2. Sesiones temáticas

En lugar de una sesión de 3 horas que hace de todo, divide en sesiones temáticas: una para refactoring, otra para tests, otra para features. Cada sesión empieza limpia pero con el contexto de MEMORY.md. Ventaja adicional: si una sesión se corrompe, no pierdes todo.

3. /compact preventivo

No esperes a que el contexto se llene. Usa /compact cada 25-30 interacciones de forma preventiva. Es mejor comprimir cuando aún tienes buena calidad de respuestas que esperar al degradamiento.

4. Documentar en CLAUDE.md las decisiones permanentes

Si tomas una decisión que aplica para siempre ("siempre usar Tailwind", "nunca CSS modules"), ponla en CLAUDE.md, no solo en MEMORY.md. MEMORY.md puede limpiarse o sobrescribirse. CLAUDE.md persiste bajo tu control.

5. Usar archivos intermedios como extensión de memoria

Para sesiones muy complejas, pide a Claude Code que escriba un archivo temporal con el estado actual:

> Escribe en .claude/session-notes.md el estado actual:
  qué hemos hecho, qué falta, decisiones pendientes

En la siguiente sesión, puedes pedirle que lea ese archivo para retomar donde lo dejaste.

Memoria compartida en equipos

Cuándo trabajas en equipo, la gestión de memoria tiene consideraciones adicionales:

Qué compartir (en git):

• CLAUDE.md en la raíz del proyecto: reglas del proyecto, stack, convenciones. Todo el equipo lo usa.
• .claude/skills/: skills compartidos (code review, tests, deploy).
• CLAUDE.md en subdirectorios: reglas específicas de módulos o capas.

Qué NO compartir (personal):

• ~/.claude/CLAUDE.md: preferencias personales (idioma, estilo).
• ~/.claude/memory/MEMORY.md: memoria global personal.
• .claude/memory/MEMORY.md: aunque es del proyecto, es personal. Añádelo a .gitignore.

Patrón recomendado para equipos:

# .gitignore
.claude/memory/     # Memoria personal de cada developer
.claude/settings.*  # Settings personales

# SÍ commitear:
# CLAUDE.md          → Reglas del proyecto
# .claude/skills/    → Skills compartidos

Así cada desarrollador tiene su MEMORY.md personal (con sus decisiones, errores y preferencias), pero todos comparten las reglas del proyecto via CLAUDE.md y los skills via .claude/skills/.

Errores comunes

• Nunca revisar MEMORY.md: Claude Code puede guardar información incorrecta o desactualizada. Revisa MEMORY.md periódicamente (semanal) y corrige lo que no sea válido.
• MEMORY.md demasiado largo: Si MEMORY.md crece sin control (>200 líneas), consume contexto al cargarse. Haz limpieza mensual: elimina tareas completadas y decisiones obsoletas.
• Confiar solo en el contexto de sesión: Si no usas MEMORY.md ni CLAUDE.md, cada sesión empieza de cero. Es como tener un compañero de equipo con amnesia permanente.
• No usar /compact: Sesiones largas sin /compact degradan la calidad de las respuestas. El modelo "olvida" lo del principio cuando la ventana se llena.
• Poner información volátil en CLAUDE.md: Estado de tareas, fechas de sprints, o bugs actuales cambian constantemente. Mejor en MEMORY.md donde se actualiza solo.
• CLAUDE.md duplicando MEMORY.md: Si la misma información está en ambos, consumes doble contexto sin beneficio. CLAUDE.md para lo estable, MEMORY.md para lo dinámico.
• No usar .gitignore para memoria personal: Si commiteas .claude/memory/, otros developers ven tu historial de errores y decisiones personales. Y además genera conflictos de merge.

Preguntas frecuentes

Claude Code recuerda lo que hice ayer?

Solo si está en MEMORY.md o CLAUDE.md. El contexto de sesión se pierde al cerrar. Si trabajaste en algo importante, verifica que quedó registrado en MEMORY.md antes de cerrar.

Puedo borrar MEMORY.md y empezar de cero?

Sí. Borra el archivo y la próxima sesión empieza sin memoria previa. A veces es útil cuando el proyecto ha cambiado tanto que la memoria antigua confunde más que ayuda.

MEMORY.md consume tokens de mi sesión?

Sí. Se carga al inicio y ocupa espacio en la ventana de contexto. Por eso es importante mantenerlo conciso. Un MEMORY.md de 100 líneas bien escritas es mejor que uno de 500 con información redundante.

Puedo tener múltiples archivos CLAUDE.md en un proyecto?

Sí. Puedes tener CLAUDE.md en la raíz, en src/, en tests/, etc. Claude Code carga los relevantes según el directorio donde estés trabajando. Es útil para proyectos monorepo o con múltiples módulos con reglas distintas.

Qué pasa si CLAUDE.md y MEMORY.md se contradicen?

Claude Code prioriza CLAUDE.md (instrucciones explícitas del usuario) sobre MEMORY.md (notas automáticas). Si hay conflicto, gana CLAUDE.md. Pero lo ideal es resolver la contradicción editando el archivo incorrecto.

Siguiente paso

Configura tu sistema de memoria ahora: crea un CLAUDE.md con las reglas estáticas y deja que MEMORY.md se encargue del contexto dinámico. Revisa tu MEMORY.md actual para limpiar información obsoleta.

Después explora los skills de Claude Code para crear comandos que interactúen con la memoria, y los subagents para tareas que requieren dividir contexto entre múltiples agentes.