Memoria de Claude Code: la guía del contexto persistente

Cada sesión de Claude Code empieza igual: sin memoria de ayer. Pasas veinte minutos explicando el flujo de autenticación de tu API el lunes, y el martes lo estás explicando otra vez, porque nada de cómo funciona el modelo lo lleva consigo por su cuenta. Esa brecha es el arreglo más pedido que escuchamos de los equipos que corren Claude Code a diario, y también el más incomprendido, porque "dale memoria a Claude" no es una sola funcionalidad. Son cuatro mecanismos con trabajos, costes y modos de fallo distintos.

Esta guía los ordena: qué resuelve realmente cada capa, qué pertenece a cuál, cómo configurar una skill de memoria como claude-mem, y las matemáticas de tokens que explican por qué recordar es barato mientras que redescubrir los mismos hechos cada sesión no lo es.

El problema del día de la marmota

Un modelo de lenguaje no tiene estado entre llamadas a la API. Cada mensaje que envías incluye toda la conversación hasta el momento, y cuando esa conversación termina, también termina todo lo que el modelo "sabía" sobre tu proyecto. Abre una sesión nueva mañana y vuelves a una hoja en blanco, sin importar qué archivos haya en disco.

Eso estaría bien si las sesiones fueran cortas y autocontenidas. No lo son. El trabajo real se extiende por días: arreglas un bug el lunes, el mismo patrón aparece en un archivo distinto el jueves, y el agente no tiene forma de conectar los dos a menos que algo fuera de la conversación llevara esa conexión hacia adelante. Cada sesión sin eso paga un impuesto de redescubrimiento: leer los mismos archivos, reaprender las mismas convenciones, ocasionalmente repetir un error que ya había arreglado.

El arreglo no es una ventana de contexto más grande. Las ventanas de contexto ya son grandes, y el problema no es capacidad, es continuidad. Lo que quieres es un lugar fuera de la conversación donde sobrevivan los hechos y decisiones, más una forma de que Claude cargue de vuelta la porción correcta de ese lugar cuando importa. Eso es memoria, y Claude Code te da cuatro formas de construirla.

Las cuatro capas de la memoria de Claude

La capa uno es CLAUDE.md: hechos estáticos del proyecto que escribes una vez, que cargan por completo al principio de cada sesión. La capa dos es auto-memoria, un directorio de archivos en el que Claude escribe por sí mismo, acumulando hechos con el tiempo sin que tú los redactes a mano. La capa tres son las skills de memoria, que capturan y comprimen el contexto de sesión automáticamente y lo inyectan de vuelta más tarde. La capa cuatro es la opción de baja tecnología: un archivo de notas plano que el agente lee y actualiza porque se lo dijiste.

No son opciones que compiten. Resuelven problemas distintos, y la mayoría de configuraciones serias corren dos o tres a la vez.

Capa 1: CLAUDE.md, hechos estáticos que siempre cargan

CLAUDE.md es el mecanismo de memoria más antiguo y simple de Claude Code. Es un archivo markdown que Claude Code encuentra subiendo por el árbol de directorios desde tu directorio de trabajo, y carga por completo, cada sesión, antes de que escribas nada. Eso lo convierte en el lugar correcto para hechos que son verdad casi siempre: cómo ejecutar los tests, qué gestor de paquetes usa el repo, qué carpeta es legada y está fuera de límites.

Es el lugar incorrecto para cualquier cosa que cambie a menudo o que aplique de forma ocasional, porque "carga por completo, cada sesión" es también su coste. Un CLAUDE.md de 3.000 líneas son alrededor de 30.000 tokens gravados en cada petición, la necesite esa petición o no. Cubrimos la aritmética completa y un ejemplo anotado real en nuestra guía de mejores prácticas de CLAUDE.md; la versión corta es que CLAUDE.md quiere hechos estables, no un registro que crece.

Ahí es también donde CLAUDE.md se queda sin camino. Es estático: tú lo escribes, Claude lo lee, y actualizarlo es una tarea manual que tienes que acordarte de hacer. Las siguientes tres capas existen para manejar hechos que se acumulan por su cuenta.

Capa 2: auto-memoria y directorios de memoria

La capa intermedia es un directorio de memoria, a menudo ~/.claude/memory/ o un equivalente local al proyecto, donde Claude escribe notas estructuradas sobre lo que aprende y las lee de vuelta al principio de sesiones futuras. A diferencia de CLAUDE.md, nadie redacta a mano la mayoría de estas entradas. El agente decide que algo vale la pena recordar, una decisión que tomaste, una preferencia que expresaste, un hecho que tuvo que rebuscar, y lo archiva con suficiente estructura para recuperarlo después.

Aquí es donde vive la skill de Memory Management, y es la skill mejor puntuada en esta categoría en SkillProof: 9,2 sobre 10. La corrimos durante una semana completa de sesiones reales, no una sola demo, y aguantó bajo uso real. Claude recordó de forma fiable decisiones y preferencias del proyecto que había guardado, y la precisión de recuperación se mantuvo alta incluso cuando el almacén crecía, la parte que suele romperse primero en implementaciones ingenuas.

Lo que separa esta capa de CLAUDE.md es que es selectiva tanto a la entrada como a la salida. Una buena skill de memoria indexa lo que ha guardado y trae la porción relevante para la tarea actual, así el almacén puede crecer hasta miles de entradas sin que cada sesión pague por todas ellas.

Capa 3: skills de memoria, claude-mem y captura automática

La tercera capa lleva la idea más lejos. En vez de que Claude decida a mitad de conversación qué vale la pena guardar, una skill dedicada captura toda la sesión automáticamente, la comprime, e inyecta el contexto relevante de vuelta en la siguiente. Claude-mem es el ejemplo más claro de este patrón. Su propuesta es "contexto persistente entre sesiones para cada agente": observa lo que hace tu agente durante una sesión, comprime esa actividad con un pase de resumen por IA, y muestra la versión comprimida la próxima vez que sea relevante, a través de Claude Code y, según su propia documentación, varios otros runtimes de agentes.

Deberíamos ser directos sobre dónde se sitúa en nuestras pruebas. Claude-mem apareció a través de nuestro rastreador de GitHub con 85.685 estrellas, que es por lo que está en cola para una prueba completa en vez de llevar ya un veredicto; no publicamos una puntuación hasta que hemos instalado una skill limpia y la hemos corrido contra trabajo real, el mismo listón que Memory Management ya superó. Lo que podemos decir ahora es arquitectónico: la captura automática elimina el momento en el que de otro modo pararías y decidirías, a mitad de sesión, si algo vale la pena recordar. La skill decide por ti. Si eso aguanta durante una semana completa en una máquina limpia es lo que existe para responder la cola de pruebas.

Capa 4: archivos planos como memoria

La última capa no necesita ninguna skill: un archivo markdown plano, normalmente llamado algo como notes.md o progress.md, que le pides a Claude que lea al principio de una sesión y actualice al final. Sin indexado, sin captura automática, sin puntuación. Tú eres el sistema de memoria; el archivo es solo dónde lo anotas.

Esta capa se subestima porque suena demasiado simple para importar. No lo es. Para un proyecto individual con un solo colaborador y un puñado de hilos en curso, un archivo de notas que realmente mantienes gana a un sistema de memoria automatizado que nunca miras. El modo de fallo recae por completo en ti, eso sí: nadie lo poda, nadie marca contradicciones, y crece hasta ser un muro de texto con los mismos puntos ciegos que desarrolla cualquier documento sin mantenimiento. Funciona exactamente tan bien como tu disciplina para actualizarlo, ni mejor.

Qué pertenece a dónde: la tabla de decisión

Tipo de memoria	Mejor para	Carga	Mantenimiento
CLAUDE.md	Hechos estables y siempre verdaderos (comandos de build, convenciones, trampas)	Por completo, cada sesión	Manual, editar a mano
Auto-memoria / directorio de memoria	Decisiones y preferencias que se acumulan con el tiempo	Selectivamente, al recuperar	Sobre todo automático (gestionado por skill)
Skills de memoria (claude-mem)	Contexto de sesión completo, capturado sin que tú decidas qué importa	Comprimido, inyectado cuando es relevante	Captura automática, revisión ocasional
Archivo de notas plano	Proyectos individuales, hilos en curso simples	Manual, tú le dices a Claude que lo lea	Totalmente manual

Lee esa tabla según lo que cambia, no según lo que es cómodo de configurar. Si un hecho seguiría siendo verdad en seis meses, pertenece a CLAUDE.md. Si es una decisión tomada esta semana que podría importar de nuevo más tarde, pertenece a la memoria. Si no puedes predecir qué necesitarás recordar y no quieres decidirlo en el momento, ese es el caso para la captura automática. Si nada de eso aplica, un archivo de notas todavía gana a nada.

Configurar claude-mem, paso a paso

El patrón general para una skill de memoria de captura automática se ve así, usando claude-mem como ejemplo concreto:

1. Clona la skill. git clone https://github.com/thedotmack/claude-mem en un directorio de trabajo, y luego sigue el script de instalación del repo en vez de copiar archivos a mano. Las skills de memoria normalmente necesitan registrar un hook, no solo colocar un SKILL.md en su sitio.

2. Reinicia Claude Code. La instalación normalmente conecta un hook de inicio o fin de sesión para que la captura pase sin que tengas que invocar nada. Un reinicio es lo que recoge ese hook.

3. Corre una sesión normal. No la pruebes con una tarea de juguete. Haz trabajo real; el punto es ver qué decide que vale la pena recordar cuando nadie está vigilando para la prueba.

4. Empieza tu siguiente sesión y comprueba qué volvió. Pregúntale a Claude qué recuerda del trabajo de ayer antes de decir nada más. Algo específico y correcto significa que la captura funciona. Cualquier cosa vaga o incorrecta significa comprobar la configuración antes de confiarle algo que importe.

5. Fija un ritmo de revisión. La captura automática sin revisión se convierte en acumulación automática de ruido. Date un espacio recurrente de diez minutos para repasar lo guardado (más sobre esto bajo higiene de memoria, más abajo).

Si prefieres empezar con algo ya puntuado, Memory Management es la ruta manual-pero-probada: instala la carpeta de la skill en ~/.claude/skills/, y crea su propio directorio de memoria en el primer uso, sin instalación de hook por separado.

La economía de tokens de la memoria

Aquí están las matemáticas que hacen que la memoria valga el coste de configurarla. Digamos que un hecho de proyecto tarda 500 palabras en explicarse desde cero: la forma de tu flujo de autenticación, por qué cierta tabla tiene dos claves foráneas, qué hace en realidad el script de despliegue. Explicado de nuevo en el chat, eso son aproximadamente 650 tokens de input cada vez que lo re-explicas, encima del tiempo que pasas escribiéndolo y el tiempo que Claude pasa razonando sobre ello en ese mensaje.

Guardado en memoria en cambio, el mismo hecho cuesta esos 650 tokens una vez, para escribirlo. La recuperación después cuesta una fracción de eso: una capa de memoria bien indexada trae un resumen comprimido, a menudo bajo 100 tokens, solo cuando la tarea actual toca ese hecho. Explícalo en el chat cinco veces en un mes y habrás gastado aproximadamente 3.250 tokens re-enseñando lo que la memoria habría costado 650 tokens aprender y 500 en total recordar cinco veces: una brecha aproximada de cinco a uno que se ensancha cuanto más a menudo se necesita el hecho.

Compara eso con meter todo en CLAUDE.md en cambio: un hecho relevante una sesión de cada veinte igual se carga en las otras diecinueve, sin selectividad para recuperar ese coste. El preámbulo fijo que carga tu configuración en cada turno (CLAUDE.md, esquemas de herramientas, inyecciones de memoria) compite directamente con tu trabajo real por espacio y atención. Medimos esto con más profundidad, con conteos reales de tokens antes/después, en nuestra guía de coste en tokens; la memoria es una línea en ese cuadro más grande, a menudo el arreglo más barato respecto a lo que ahorra.

Higiene de memoria: el ritual de revisión

Un sistema de memoria que solo acumula no es una funcionalidad, es una fuga lenta. Las entradas obsoletas no fallan de forma ruidosa; nada se rompe cuando Claude recuerda una decisión que revertiste hace tres semanas. Simplemente actúa en silencio sobre información desactualizada, y tú quemas tiempo de depuración averiguando por qué el agente está confiadamente equivocado sobre algo que sabes que arreglaste.

Haz un pase mensual, diez minutos, la misma disciplina que el ritual de revisión de CLAUDE.md que recomendamos en otro lugar. Abre el almacén de memoria. Para cada entrada que parezca importante, pregúntate si sigue siendo verdad, si una decisión que describe se revirtió desde entonces, y si es lo bastante específica para actuar. Borra cualquier cosa que falle. Un almacén de memoria del que estás orgulloso es más pequeño un año después de lo que era a los tres meses; el crecimiento debería estar en precisión, no en volumen.

El disparador más fiable para una revisión, sin embargo, no es el calendario. Es el momento en el que Claude hace algo mal por culpa de una memoria obsoleta. Trata eso como un bug: arregla la entrada en el mismo aliento que el error, no en tu próximo pase programado.

Privacidad: qué se captura, dónde vive

Las skills de memoria leen lo que pasa en tus sesiones, así que la pregunta honesta es qué se captura y dónde acaba. Para la memoria basada en archivos, Memory Management, claude-mem y el enfoque de notas planas por igual, la respuesta suele ser la misma: todo se escribe en archivos planos en tu propio disco, típicamente bajo ~/.claude/ o una carpeta de memoria local al proyecto, no en un servidor de terceros. Nada sale de tu máquina a menos que hagas commit de esos archivos a un repo compartido o una skill documente explícitamente una función de sincronización remota.

Eso son buenas noticias para el control y malas noticias para asumir que es automáticamente seguro. Un archivo de memoria es un registro en texto plano de en qué trabajaste, y puede incluir credenciales mencionadas de pasada, nombres de clientes, o detalles de arquitectura que no querrías en un repo público. Lee qué hay realmente en un directorio de memoria antes de comitearlo junto a tu código, y antes de instalar cualquier skill de memoria, comprueba su código fuente para ver qué significa realmente "captura todo lo que hace tu agente", incluyendo si la salida de comandos que contiene secretos también se cuela ahí. La captura automática merece el mismo escrutinio que cualquier herramienta que lee tu terminal.

Preguntas frecuentes

¿Claude Code tiene memoria persistente integrada?

Parcialmente. CLAUDE.md te da memoria estática y siempre cargada de fábrica, y es genuinamente integrado, sin instalación requerida. Cualquier cosa más allá de hechos estáticos, memoria que se acumula, se indexa, y se recupera selectivamente, actualmente viene de una skill en vez de una funcionalidad nativa.

¿Cuál es la diferencia entre CLAUDE.md y una skill de memoria?

CLAUDE.md carga por completo, cada sesión, y lo mantienes a mano. Una skill de memoria escribe y lee un almacén que crece de forma selectiva, trayendo solo lo relevante para la tarea actual, y buena parte de la escritura pasa sin que lo hagas manualmente. Usa CLAUDE.md para hechos que nunca cambian; usa una skill de memoria para hechos que se acumulan.

¿Es seguro instalar claude-mem ahora mismo?

Todavía no podemos darle un veredicto. Está en nuestra cola de pruebas, sin puntuar, a pesar de su gran número de seguidores en GitHub. Instálalo como instalarías cualquier cosa sin puntuar: en un proyecto en el que puedas permitirte experimentar primero, y lee el código fuente antes de confiarle sesiones sensibles.

¿Cuánto cuesta en tokens correr una skill de memoria?

Menos que la alternativa en casi todos los casos. El almacenamiento en sí es casi gratis ya que vive en disco, no en contexto. La recuperación al inicio de sesión típicamente cuesta mucho menos que re-explicar el mismo hecho en el chat, y la brecha se ensancha cuantas más veces ese hecho se re-explicaría de otro modo.

¿Debería usar más de una capa de memoria a la vez?

Sí, y la mayoría de configuraciones que funcionan lo hacen: CLAUDE.md para hechos que nunca cambian, más una skill de memoria o un archivo de notas disciplinado para hechos que se acumulan. Trátalas como complementarias en vez de elegir una favorita. El punto es emparejar cada tipo de hecho con la capa construida para él, no fijarte en un solo mecanismo para todo.