Sistema de Memoria

Claude Code persiste información entre sesiones usando un sistema de memoria en archivos dentro de ~/.claude/. Usa 4 categorías tipadas y un archivo índice (MEMORY.md) que siempre se carga en el contexto.

4 tipos de memoria 200 límite de líneas en MEMORY.md 25KB límite de tamaño en MEMORY.md

Tipos de memoria

user

Usuario

· Rol, preferencias, nivel de conocimiento

Ejemplo: "Es data scientist, nuevo en React. Explica conceptos frontend mediante analogías con el backend."

Cuándo guardar: Cuando aprendes algo sobre el rol, objetivos o estilo de trabajo del usuario.

feedback

Feedback

· Correcciones y enfoques validados

Ejemplo: "No mockees la base de datos en tests. Un incidente anterior mostró que la divergencia mock/prod rompe migraciones."

Cuándo guardar: Cuando el usuario corrige un enfoque O confirma que una decisión no obvia funcionó bien.

project

Proyecto

· Trabajo en curso, plazos, incidentes

Ejemplo: "El freeze de merges empieza el 2026-03-05 para el corte de release mobile. Avisar de PRs no críticos después de esa fecha."

Cuándo guardar: Cuando aprendes quién hace qué, por qué o para cuándo. Las fechas relativas se convierten a absolutas.

reference

Referencia

· Punteros a sistemas externos

Ejemplo: "Los bugs del pipeline se registran en el proyecto Linear INGEST."

Cuándo guardar: Cuando aprendes sobre recursos en herramientas externas (Linear, Grafana, canales de Slack, etc.).

Estructura de archivos

Cada memoria se guarda en un archivo markdown separado con frontmatter YAML. MEMORY.md es el índice.

~/.claude/projects/<slug>/memory/

├── MEMORY.md # índice, máx 200 líneas / 25KB

├── user_role.md

├── feedback_testing.md

└── reference_tools.md

Qué NO se guarda en memoria

× Patrones de código, convenciones o rutas de archivos (se pueden derivar del código)

× Historial de git o quién cambió qué (usa git log / git blame)

× Soluciones a bugs o recetas de arreglos (el fix está en el código)

× Cualquier cosa ya documentada en CLAUDE.md

× Detalles de tareas efímeras de la sesión actual

× Listas de PRs o resúmenes de actividad (quedan obsoletos rápidamente)

Extracción automática de memoria

Se ejecuta en segundo plano : Un fork del agente principal gestiona la extracción sin bloquear tu sesión.

Se activa tras turnos silenciosos : Se activa cuando el modelo principal completa un turno sin realizar ninguna llamada a herramientas.

Máximo 5 turnos : El agente de extracción tiene un máximo de 5 turnos para identificar y guardar memorias relevantes.

Permisos limitados : Read/Grep/Glob son libres. Bash es de solo lectura. Write/Edit están restringidos al directorio de memoria.

Deduplicación : No se ejecuta si el agente principal ya escribió en memoria durante la sesión, evitando duplicados.

Caché compartida : Comparte la caché del prompt con la sesión padre para mayor eficiencia.

! MEMORY.md se trunca silenciosamente a las 200 líneas

Si el índice MEMORY.md supera las 200 líneas o 25KB, se trunca sin aviso. Las entradas que superan el límite simplemente no se cargan en el contexto. Mantén el índice conciso: una línea por archivo de memoria, con menos de 150 caracteres cada una.