Los 4 Sistemas de Memoria: Extracción, Sesión, Docs Vivos y Sueños
Tu asistente de código literalmente tiene un sistema de "sueños". 4 mecanismos de memoria independientes que extraen, organizan, mantienen y consolidan conocimiento — incluyendo uno que reorganiza memorias mientras duermes.
En el artículo anterior analizamos cómo Claude Code comprime el contexto para mantener la ilusión de una conversación infinita. Pero hay una pregunta más profunda: ¿qué pasa cuando cierras la sesión y vuelves mañana?
La respuesta te va a sorprender. Claude Code no simplemente "recuerda" lo que le dijiste. Tiene 4 sistemas de memoria completamente independientes, cada uno con su propio trigger, formato y filosofía. Uno extrae conocimiento en segundo plano después de cada interacción. Otro toma notas periódicas durante la sesión. Un tercero mantiene documentación viva que se actualiza sola. Y el cuarto — el más fascinante — consolida y reorganiza memorias cada noche, como el cerebro humano durante el sueño REM.
No es una metáfora. El sistema se llama literalmente auto-dream.
🧠 Tesis de este artículo
Claude Code implementa 4 sistemas de memoria bio-inspirados: extracción automática en segundo plano (Auto-Memory), notas periódicas de sesión (Session Memory), documentación auto-mantenida (Magic Docs) y consolidación nocturna (Auto-Dream). La analogía con la memoria humana — codificación, memoria de trabajo, externalización y sueño — no es accidental.
Los 4 Sistemas de Memoria
Antes de profundizar en cada uno, aquí está el mapa completo. Cada sistema opera de forma independiente, con su propio trigger, formato de datos y ciclo de vida:
1. Auto-Memory
Extracción en segundo plano
Trigger: al final de cada query loop
Qué guarda: preferencias, correcciones, contexto de proyecto
Formato: YAML frontmatter + markdown
2. Session Memory
Notas periódicas de sesión
Trigger: umbral de tokens + conteo de tool calls
Qué guarda: estado actual, archivos, errores, worklog
Formato: plantilla de 11 secciones
3. Magic Docs
Documentación viva auto-mantenida
Trigger: cambios en código relacionado
Qué guarda: overview, arquitectura, entry points
Formato: archivos con header # MAGIC DOC
4. Auto-Dream
Consolidación nocturna
Trigger: cada 24h o 5 sesiones
Qué hace: merge, deduplicar, organizar por tema
Límite: MEMORY.md < 200 líneas / 25KB
La inspiración biológica es deliberada. Así como el cerebro humano tiene sistemas separados para la codificación (hipocampo), la memoria de trabajo (corteza prefrontal), la externalización (notas escritas) y la consolidación durante el sueño — Claude Code replica estos 4 pilares con agentes en segundo plano y tareas nocturnas.
Auto-Memory — Extracción en Segundo Plano
Auto-Memory es el sistema de memoria más fundamental. Se activa al final de cada "query loop" — cada vez que Claude Code termina de procesar tu petición — a través del hook handleStopHooks. Sin que lo notes, un agente paralelo (fork) analiza la conversación y extrae cualquier dato que debería recordarse.
El truco de ingeniería clave: el agente forked comparte la prompt cache del agente padre. Esto significa que no necesita re-leer toda la conversación — ya tiene el contexto en caché. La extracción es barata en tokens.
Cada memoria extraída se clasifica en uno de 4 tipos:
# Formato de una memoria extraída (YAML frontmatter) --- name: Prefiere TypeScript sobre JavaScript description: El usuario siempre elige TS y pide tipos estrictos type: user # user | feedback | project | reference --- Contexto adicional: usa strict mode, prefiere interfaces sobre types para objetos públicos.
✓ Qué SÍ se guarda
- • user — preferencias de estilo, idioma, herramientas favoritas
- • feedback — correcciones del usuario ("no, así no, hazlo así")
- • project — estructura del proyecto, stack, convenciones
- • reference — URLs, documentación externa, APIs
✗ Qué NO se guarda
- • Patrones de código (re-descubribles leyendo archivos)
- • Historial de git (ya persistido externamente)
- • Soluciones de debugging (efímeras por naturaleza)
- • Cualquier cosa ya en CLAUDE.md
- • Detalles de tareas temporales
💡 Filosofía de diseño: Las memorias capturan conocimiento sobre el usuario, no detalles técnicos que pueden ser re-descubiertos. Si Claude Code puede leer un archivo para obtener la información, no la memoriza. Si necesita recordar que tú prefieres tabs sobre spaces — eso sí se guarda.
Session Memory — Notas Periódicas
Si Auto-Memory es la memoria a largo plazo, Session Memory es la memoria de trabajo. Controlada por el feature gate tengu_session_memory, este sistema toma "notas" periódicas de lo que está pasando en la sesión actual.
El trigger no es temporal — es basado en consumo de tokens y conteo de tool calls. Cuando la sesión cruza cierto umbral de actividad, el sistema genera una snapshot del estado actual usando una plantilla de 11 secciones:
# Plantilla de Session Memory (11 secciones) ## 1. Current State — Qué se está haciendo ahora mismo ## 2. Task Spec — Descripción de la tarea del usuario ## 3. Files — Archivos relevantes tocados/leídos ## 4. Workflow — Pasos completados y pendientes ## 5. Errors — Errores encontrados y su estado ## 6. Codebase Documentation — Notas sobre la codebase ## 7. Learnings — Descubrimientos de esta sesión ## 8. Key Results — Resultados importantes logrados ## 9. Worklog — Log cronológico de acciones ## 10. [Reserved] — Reservado para expansión futura ## 11. [Reserved] — Reservado para expansión futura
Dos constantes gobiernan los límites: MAX_SECTION_LENGTH = 2000 tokens por sección y MAX_TOTAL = 12000 tokens para toda la nota. Esto previene que las notas de sesión se conviertan en un dump completo de la conversación — deben ser concisas.
¿Lo mejor? La plantilla es personalizable. Puedes crear tu propia plantilla en ~/.claude/session-memory/config/template.md para adaptar las secciones a tu flujo de trabajo. Si trabajas en data science, podrías añadir secciones para datasets y métricas. Si trabajas en frontend, secciones para componentes y estados de UI.
Magic Docs — Documentación Viva
Los dos primeros sistemas guardan memorias sobre el usuario y la sesión. Magic Docs es diferente: mantiene documentación sobre el código en sí, y lo hace de forma automática.
El patrón es elegante en su simplicidad. Cualquier archivo que empiece con el header especial se convierte en un "documento mágico":
# MAGIC DOC: API Architecture Overview of the REST API layer... // Este archivo se auto-actualiza cuando el código relacionado cambia. // Un agente en segundo plano lo mantiene sincronizado.
Cuando cambias código que está relacionado con un Magic Doc, un agente en segundo plano detecta el cambio y actualiza el documento. No necesitas pedirlo — simplemente ocurre. El agente sigue una filosofía estricta:
"BE TERSE. High signal only. For OVERVIEWS, ARCHITECTURE, ENTRY POINTS."
Nada de explicaciones largas ni tutoriales. Los Magic Docs son mapas de navegación — te dicen dónde están las cosas y cómo encajan, no cómo funcionan línea por línea. Si necesitas personalizar el comportamiento del agente que mantiene tus docs, puedes crear un prompt custom en ~/.claude/magic-docs/prompt.md.
🎯 Caso de uso clave: Imagina un monorepo con 200 archivos. En lugar de tener un README.md que se queda desactualizado a los 3 días, pones un # MAGIC DOC: Service Map en la raíz. Cada vez que se añade o modifica un servicio, el doc se actualiza solo. Documentación que nunca se desactualiza.
Auto-Dream — Consolidación Nocturna
Y llegamos al sistema más fascinante. Auto-Dream es la razón por la que el título de este artículo dice "sueños" sin comillas. Claude Code literalmente tiene un proceso de consolidación que se ejecuta periódicamente — cada 24 horas o cada 5 sesiones — para reorganizar y limpiar las memorias acumuladas.
La analogía con el sueño humano es precisa. Durante el sueño REM, el cerebro:
- • Consolida memorias del día en memoria a largo plazo
- • Descarta información irrelevante
- • Reorganiza conexiones entre memorias existentes
- • "Compacta" el almacenamiento
Auto-Dream hace exactamente lo mismo, en 4 fases:
Fase 1: Orient
Lee el directorio de memoria completo y el archivo MEMORY.md (el índice principal). Entiende la estructura actual: qué temas existen, cuántas memorias hay, qué tan grande es el índice.
Fase 2: Gather
Escanea los logs diarios y memorias dispersas generadas desde el último "sueño". Recolecta todas las memorias nuevas que Auto-Memory y Session Memory depositaron.
Fase 3: Consolidate
Merge, deduplicación y organización por tema. Si dos memorias dicen lo mismo con diferentes palabras, se fusionan. Si una memoria contradice otra más reciente, la vieja se descarta. Las memorias se agrupan por temas coherentes.
Fase 4: Prune & Index
El paso final asegura que MEMORY.md no supere 200 líneas / 25KB. Si es necesario, se podan memorias antiguas o de baja prioridad y se actualiza el índice.
En el modo KAIROS (la variante avanzada), Auto-Dream usa además los logs diarios como entrada y produce una "destilación nocturna" — un resumen de alto nivel de lo que se aprendió ese día, que se integra en la memoria a largo plazo.
El Directorio de Memoria
Todo se almacena en el filesystem. Nada de bases de datos, nada de servicios cloud — archivos markdown en disco. La estructura:
# Filesystem layout ~/.claude/memory/ ├── MEMORY.md ← Índice principal (max 200 líneas) ├── user-preferences.md ← Memorias tipo "user" ├── project-goals.md ← Memorias tipo "project" └── logs/ └── 2026/ └── 07/ └── 2026-07-04.md ← Log diario # Constantes ENTRYPOINT = 'MEMORY.md' MAX_LINES = 200 MAX_BYTES = 25_600 // 25KB
El archivo MEMORY.md es el punto de entrada. Cuando Claude Code arranca una nueva sesión, lo primero que lee es este archivo para orientarse — igual que tú leerías tus notas de ayer antes de empezar a trabajar.
Hay dos modos de operación: Individual (memorias privadas por usuario) y TEAMMEM (memorias compartidas + privadas). En modo TEAMMEM, existe un directorio compartido para memorias del equipo y uno privado por desarrollador, permitiendo que el conocimiento del proyecto sea colectivo sin perder las preferencias personales.
Memory vs CLAUDE.md — Que No Se Confundan
Una pregunta frecuente: ¿cuál es la diferencia entre el sistema de memoria y CLAUDE.md? Son complementarios pero muy diferentes:
| Característica | Memory | CLAUDE.md |
|---|---|---|
| Escritor | Automático (agente en segundo plano) | Manual (el usuario lo edita) |
| Contenido | Preferencias del usuario, contexto de proyecto | Reglas del proyecto, convenciones |
| Persistencia | Entre sesiones (puede ser podada) | Permanente (version controlled) |
| Actualización | Extracción automática | Ediciones manuales del usuario |
| Promoción | /remember → CLAUDE.md | — |
El comando /remember es el puente: promueve una memoria automática a una regla permanente en CLAUDE.md. Es como cuando una nota provisional se convierte en una política del equipo — deja de ser una observación y se convierte en una instrucción permanente.
Patrones que Puedes Aplicar Hoy
Los 4 sistemas de memoria de Claude Code no son solo internals curiosos. Son patrones de diseño que puedes aplicar a cualquier agente o chatbot:
1. Extracción de memoria en segundo plano
No esperes a que el usuario diga "recuerda esto". Después de cada interacción, usa un agente ligero para extraer memorias implícitas — preferencias, correcciones, contexto. La clave: compartir la prompt cache para que sea barato.
2. Logs append-only + consolidación periódica
Nunca edites logs existentes. Siempre append. Después, un proceso periódico (diario, semanal) lee todos los logs, los consolida y produce un resumen limpio. Este patrón escala infinitamente y es crash-safe.
3. Memorias tipadas (user/feedback/project/reference)
No pongas todas las memorias en un saco. Clasifícalas por tipo. Esto permite que el proceso de consolidación trate cada tipo diferente — las preferencias de usuario se fusionan, las referencias se deducan, el feedback se acumula.
4. Auto-documentación con header patterns
El patrón de Magic Docs es simple y poderoso: define un header canónico (# MAGIC DOC:) y haz que cualquier archivo con ese header sea auto-mantenido. Es documentación viva con cero fricción — poner el header es todo lo que necesitas.
Tu Asistente Tiene Sueños — Y Eso es Bueno
La frontera entre un chatbot que "recuerda" y un agente con memoria real es exactamente esta: 4 sistemas independientes, cada uno optimizado para un tipo diferente de retención. Auto-Memory extrae lo que aprendes. Session Memory mantiene el estado actual. Magic Docs mantiene los mapas actualizados. Y Auto-Dream consolida todo mientras duermes.
Lo más revelador es lo que el sistema no guarda. Las exclusiones explícitas — no guardar patrones de código, no guardar soluciones de debugging, no guardar nada que ya esté en CLAUDE.md — revelan una filosofía precisa: la memoria es para lo que no se puede re-descubrir. Todo lo demás se lee en tiempo real.
En el próximo artículo de esta serie exploraremos las features ocultas de Claude Code — comandos, flags y capacidades que no aparecen en la documentación oficial pero que transforman la experiencia de uso.
📚 Serie Anatomía de Claude Code: Este es el artículo 3 de 6. El anterior cubre la compresión de contexto de 4 niveles. Los siguientes cubren features ocultas, sistema de herramientas y permisos, y el build dual (interno vs público).
¿Construyes agentes con LLMs?
En Cadences diseñamos agentes con los mismos patrones industriales que hemos descubierto en Claude Code. Si quieres aplicar estos principios a tu negocio, hablemos.
Gonzalo Monzón
Fundador de CadencesLab. Ingeniero de software, arquitecto de sistemas multi-agente y eterno estudiante de cómo piensan las máquinas. Esta serie nace de meses de reverse engineering sobre las herramientas que usamos a diario.