Memoria persistente en Claude Code: guía claude-mem 2026

TL;DR: Claude Code arranca cada sesión en frío y olvida lo que decidiste ayer. La memoria persistente entre sesiones, con plugins como claude-mem, captura observaciones vía hooks, las comprime con el agent SDK y las reinyecta en sesiones futuras. Ahorra tokens, evita reexplicar arquitectura y mantiene coherencia en tareas que duran días.

El problema: cada sesión empieza de cero

Empiezas una migración el lunes. Claude Code explora el repo, identifica patrones, propone una estrategia y avanzas un 30%. El miércoles abres una sesión nueva y, sorpresa, el agente no recuerda nada. Vuelve a leer los mismos archivos, reabre debates ya cerrados y propone soluciones que ya descartaste.

Este no es un problema del modelo, es un problema de continuidad operativa. CLAUDE.md te da instrucciones estáticas, pero no memoria viva de lo que el agente hizo, decidió o aprendió en sesiones previas. Para tareas cortas no duele; para una migración de varios días, el coste oculto se acumula en tokens, repetición y riesgo de rehacer decisiones ya tomadas.

¿Qué es la memoria persistente en Claude Code?

La memoria persistente en Claude Code es una capa que captura observaciones durante la sesión, las comprime y las inyecta selectivamente cuando arrancas una sesión nueva en el mismo proyecto. No reemplaza CLAUDE.md ni el contexto de trabajo, los complementa con un historial estructurado de decisiones, archivos tocados y patrones aplicados.

La diferencia clave frente a CLAUDE.md es la fuente: CLAUDE.md lo escribes tú, la memoria persistente la genera el agente automáticamente a partir de su propio comportamiento. Si quieres entender cómo encaja con el resto de configuración del agente, este post sobre hooks en Claude Code para checks automáticos explica el mecanismo de eventos que usan estos plugins por debajo.

Tres opciones reales en 2026

A mayo de 2026 hay tres enfoques predominantes para añadir memoria persistente:

Herramienta	Enfoque	Almacenamiento	Cuándo usarla
claude-mem	Plugin con hooks de Claude Code	SQLite + vector DB local	Uso individual, todo en tu máquina
MemClaw (Felo)	Skill multi-agente	API remota (Felo)	Cambias entre Claude Code, Codex, Gemini CLI
MCP custom	Servidor MCP propio	Lo que decidas	Necesitas control total, equipos grandes

Voy a centrarme en claude-mem porque es la opción más madura para uso individual y la que tiene menor fricción de instalación. Es el repo de Alex Newman (@thedotmack) con tracción real en GitHub y un ciclo de releases activo, v12.6.4 a 5 de mayo de 2026.

Cómo funciona claude-mem: 3 capas y 5 hooks

El plugin se engancha a cinco eventos del ciclo de vida de Claude Code:

SessionStart: recupera observaciones relevantes e inyecta contexto comprimido.
UserPromptSubmit: registra qué pediste tú.
PostToolUse: captura cada tool call (lecturas, edits, comandos).
Stop: registra pausas de sesión.
SessionEnd: genera un resumen final y lo guarda.

Las observaciones capturadas se comprimen con el agent SDK de Claude y se almacenan en SQLite más un índice vectorial dentro de ~/.claude-mem/. La recuperación usa lo que se llama progressive disclosure de 3 capas:

Capa 1, priming (menos de 500 tokens): resumen ligero del proyecto y decisiones recientes, inyectado al arrancar la sesión.
Capa 2, índice de búsqueda (50-100 tokens por resultado): el agente consulta con la tool search cuando necesita más detalle, recibe solo IDs y títulos.
Capa 3, detalle completo (500-1000 tokens por observación): con get_observations pide solo lo relevante.

El resultado es que la memoria no come tu ventana de contexto. Solo se trae al frente lo que el agente decide consultar, no un dump de todo lo que pasó la semana pasada.

Instalación paso a paso

Hay dos caminos. El recomendado pasa por el marketplace de plugins de Claude Code:

# Instalar claude-mem desde el marketplace oficial del repo
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Después reinicia Claude Code. La instalación con npx claude-mem install también funciona y deja todo cableado:

# Alternativa con npx, útil si quieres scriptear el setup
npx claude-mem install

Un error que he visto repetir es lanzar npm install -g claude-mem. Eso instala solo el SDK, no registra los hooks ni arranca el worker, y nada funciona. El único prerrequisito real es Node.js 18 o superior. El resto (Bun, uv, SQLite) se autoinstala en el primer arranque.

Cuándo merece la pena (y cuándo no)

Vale el coste de configurarlo cuando se cumple alguna de estas condiciones:

Tareas que duran más de un día (migraciones, refactors grandes, features con varias subtareas).
Trabajas en varios proyectos en paralelo y necesitas que el agente no mezcle contextos.
Sueles arrancar sesiones nuevas para evitar el bloat de contexto y pierdes hilo cada vez.
Tienes decisiones de arquitectura que necesitas que el agente respete sesión tras sesión.

No vale la pena si tus sesiones son cortas (menos de una hora), si trabajas en código throwaway o si ya tienes un sistema de librería de Claude Skills bien aceitado que cubre los patrones repetitivos. La memoria persistente resuelve continuidad, no reutilización.

Caso real: una migración que dura una semana

Imagina una migración de un dashboard de Next.js Pages Router a App Router. Sin memoria persistente, cada mañana repites el ritual: explicas qué páginas ya están convertidas, qué patrón de Server Components estás usando, qué casos raros encontraste con los layouts.

Con claude-mem activo, el hook PostToolUse capturó cada edición. El worker comprime esas observaciones en frases tipo: "convertido /pages/dashboard a /app/dashboard/page.tsx usando Server Components para data fetching". Al abrir la sesión del martes, el agente ya sabe que la migración está al 60%, qué patrón aplicar y qué archivos quedan pendientes.

El cambio práctico: pasas de quemar 10 minutos reexplicando contexto a entrar directo a la siguiente tarea. Si combinas esto con la separación de responsabilidades en arquitectura que ya tienes documentada en CLAUDE.md, el agente respeta tanto reglas estáticas como decisiones dinámicas.

En producción

Algunas cosas que no aparecen en el README y conviene saber:

Coste de tokens: la compresión usa tu autenticación de Claude Code, no una API key aparte. Cada observación comprimida consume tokens del worker. En proyectos activos puede sumar, vigila el consumo durante la primera semana.
Privacidad: todo queda en ~/.claude-mem/. No sale de tu máquina, pero ese directorio acaba teniendo trozos de tu código y decisiones. Trátalo como tratarías .env: fuera de backups públicos.
Tamaño del almacenamiento: en datos reales, cientos de sesiones caben en torno a 30-40 MB. Bajo para un SQLite.
Staleness: el problema más sutil es la memoria temporalmente obsoleta. Decisiones superadas siguen apareciendo por similitud semántica. Si una observación ya no aplica, bórrala manualmente o redecide explícitamente en la sesión actual para que la nueva entrada pese más.
Compatibilidad con cambios de modelo: si pasas de Opus 4.7 a Sonnet 4.6 a mitad de tarea, el contexto persistente se mantiene, pero conviene revisar lo que pasa al cambiar modelo en Claude Code para evitar sorpresas.

Errores comunes y depuración

Error: hooks no se disparan. Causa: instalado vía npm install -g en lugar del marketplace. Solución: desinstala y reinstala con /plugin install claude-mem o npx claude-mem install.
Error: "Setting up runtime" se queda colgado. Causa: primer arranque descargando Bun/uv. Solución: espera unos 30 segundos, es normal en la primera instalación.
Error: contexto inyectado irrelevante o de otro proyecto. Causa: el workspace no está bien aislado. Solución: verifica que arrancas Claude Code desde la raíz del repo correcto, claude-mem usa el cwd para particionar memoria.
Error: tras claude plugin update deja de funcionar. Solución: ejecuta npx claude-mem repair para reinstalar el runtime.

Preguntas frecuentes

¿Cuál es la diferencia entre CLAUDE.md y claude-mem?

CLAUDE.md contiene instrucciones estáticas que tú escribes y se cargan en cada sesión. claude-mem captura automáticamente lo que el agente hace y reinyecta lo relevante en sesiones futuras. Son complementarios: CLAUDE.md fija reglas, claude-mem aporta memoria operativa.

¿Funciona con otros agentes además de Claude Code?

Sí. npx claude-mem install --ide gemini-cli o --ide opencode habilitan Gemini CLI y OpenCode. Si quieres compartir memoria entre varios agentes simultáneamente, MemClaw es una alternativa con almacenamiento centralizado en la API de Felo.

¿Mis datos se suben a un servidor externo?

No. claude-mem es 100% local: SQLite e índice vectorial viven en ~/.claude-mem/. Las llamadas de compresión usan tu sesión autenticada de Claude Code, no una integración externa.

Cierre

La memoria persistente deja de ser un nice-to-have cuando una tarea pasa de horas a días. Si trabajas con migraciones, refactors largos o varios hilos en paralelo, instalar claude-mem es una de esas mejoras silenciosas que se notan a la semana, no al minuto. La clave operativa: empezar con un proyecto piloto, vigilar consumo de tokens y limpiar observaciones obsoletas cuando aparezcan.

¿Has probado claude-mem o algún otro sistema de memoria persistente en tu flujo? Cuéntamelo en los comentarios o en Twitter @sergiomarquezp_. En el próximo post toca aterrizar la orquestación multiagente con dashboards, qué cambia cuando tienes tres agentes corriendo en paralelo y necesitas no perderte entre ellos.