$ man how-to/how-to-build-persistent-ai-memory

Cada sesion de AI empieza con amnesia. Claude Code abre, lee tu CLAUDE.md y conoce las convenciones de tu proyecto. Pero no sabe en que trabajaste ayer, que decisiones se tomaron, que esta bloqueado o cual es el siguiente paso. Re-explicas el contexto en cada sesion. Esto desperdicia tiempo y tokens. La solucion es un sistema de memoria - documentos estructurados que llevan estado entre sesiones. No un volcado de historial de chat. No un resumen vago. Un sistema que le da a cada nueva sesion exactamente el contexto que necesita para continuar donde la ultima lo dejo.

PATTERN

Un sistema de memoria de AI de grado produccion tiene tres capas. Cada una sirve un proposito diferente y persiste de manera diferente. Capa 1: Handoffs de Sesion (memoria episodica). Que paso en la ultima sesion. Que se construyo, que decisiones se tomaron, cual es el estado actual, que deberia pasar despues. Se escribe al final de cada sesion. Se lee al inicio de la siguiente. De corta vida - el handoff de ayer importa, el de la semana pasada no. Capa 2: Auto-Memoria (memoria semantica). Hechos estables sobre el proyecto y el usuario. Preferencias, convenciones, decisiones arquitectonicas clave, rutas de archivos importantes. Persiste indefinidamente. Se actualiza cuando nuevos hechos se confirman a traves de multiples sesiones. Este es el archivo MEMORY.md que Claude Code gestiona en su directorio de proyectos. Capa 3: Base de Conocimiento (memoria procedural). Como hacer las cosas. Skills, flujos de trabajo, patrones, plantillas. El CLAUDE.md, archivos de skills y entradas de wiki. Persiste mientras el proyecto exista. Evoluciona lentamente a traves de actualizaciones deliberadas. La Capa 1 cambia diariamente. La Capa 2 cambia semanalmente. La Capa 3 cambia mensualmente. Cada capa se carga en un momento diferente y sirve una funcion diferente en la ventana de contexto.

CODE

Un handoff de sesion es un documento Markdown estructurado que se escribe al final de cada sesion de Claude Code. Responde cinco preguntas: 1. Que se hizo? - Lista de trabajo completado con archivos especificos cambiados 2. Cual es el estado actual? - Rama de git, cambios sin commit, estado del build 3. Que decisiones se tomaron? - Elecciones clave y su razonamiento 4. Que esta bloqueado? - Dependencias, esperando input externo, preguntas abiertas 5. Que deberia pasar despues? - Lista priorizada de proximos pasos El handoff va a un archivo con marca de tiempo: ~/.claude/handoffs/YYYY-MM-DD_HHMMSS_slug.md. Los nombres con marca de tiempo previenen conflictos cuando multiples sesiones se ejecutan en paralelo. Al inicio de sesion, Claude Code lee todos los handoffs no consumidos (archivos que no terminan en _done.md), los procesa y luego renombra cada uno a file_done.md. Los handoffs consumidos antiguos se limpian despues de 7 dias. Esto es seguro para ejecucion paralela. Dos sesiones de Claude Code en diferentes terminales pueden ambas escribir handoffs sin sobreescribirse mutuamente. La siguiente sesion lee todos y obtiene el contexto combinado.

PATTERN

Claude Code tiene un sistema de auto-memoria incorporado. Escribe en un archivo MEMORY.md en su directorio de configuracion del proyecto. Este archivo se carga en el contexto al inicio de sesion. Reglas para auto-memoria efectiva: Guarda patrones estables confirmados en multiples interacciones. No cada dato aislado - patrones que ves recurrentes. "El usuario prefiere indentacion de 2 espacios" es estable. "El usuario esta trabajando en el modulo auth hoy" es especifico de sesion y pertenece a un handoff, no a la memoria. Organiza por tema, no cronologicamente. Crea archivos separados para diferentes dominios (debugging.md, infrastructure.md, voice-rules.md) y enlazalos desde MEMORY.md. Esto mantiene el archivo de memoria raiz liviano. Mantén MEMORY.md bajo 200 lineas. Las lineas despues de 200 se truncan cuando se cargan en el contexto. Pon los hechos mas importantes primero. Mueve detalles a archivos por tema. Actualiza o elimina memorias obsoletas. Si una convencion cambia, actualiza la memoria. Si una decision se revirtio, elimina la memoria antigua. Las memorias obsoletas causan mas daño que no tener memorias porque la AI sigue instrucciones desactualizadas con confianza. Guarda solicitudes explicitas del usuario inmediatamente. Si el usuario dice "siempre usa bun en lugar de npm," guardalo ahora. No esperes multiples confirmaciones.

PRO TIP

Asi es como las tres capas trabajan juntas en un flujo de trabajo diario real. 9 AM: Abro Claude Code. Lee CLAUDE.md (Capa 3 - conoce el proyecto). Lee MEMORY.md (Capa 2 - conoce mis preferencias). Lee el handoff de ayer (Capa 1 - sabe que paso ayer). En 10 segundos, Claude tiene el contexto de un compañero de equipo que estuvo aqui ayer. Durante la sesion: Claude usa la Capa 3 para seguir convenciones del proyecto. Usa la Capa 2 para coincidir con mis preferencias. Usa la Capa 1 para continuar el trabajo de la sesion anterior sin que yo re-explique nada. Fin de sesion: Claude escribe un nuevo handoff (Capa 1). Si se descubrieron patrones estables, actualiza MEMORY.md (Capa 2). Si un flujo de trabajo cambio, el skill relevante se actualiza (Capa 3). El efecto compuesto: despues de una semana de esto, el sistema conoce mi proyecto profundamente. Despues de un mes, maneja el 80% del trabajo rutinario sin que yo proporcione contexto. Despues de tres meses, una nueva sesion de Claude es mas productiva en su primer minuto que un nuevo desarrollador humano en su primer dia. La idea clave: la memoria no es un solo archivo. Son tres capas que sirven diferentes horizontes temporales. Construye las tres y el efecto compuesto es dramatico.