Memoria persistente en Claude Code: claude-mem frente a la memoria nativa

Respuesta corta: claude-mem es un plugin de terceros (Apache 2.0, autor Alex Newman) que da a Claude Code memoria automática entre sesiones: registra lo que hace el agente mediante hooks, lo comprime con un modelo y lo vuelve a inyectar al abrir la siguiente sesión. Se instala con npx claude-mem install o desde Claude Code con /plugin marketplace add thedotmack/claude-mem y /plugin install claude-mem. Sigue activo: la versión v13.34.2 se publicó el 6 de octubre de 2026.

Antes de instalarlo, conviene saber que Claude Code ya trae memoria persistente de serie: los ficheros CLAUDE.md (los escribes tú), la auto memory (la escribe Claude y está activada por defecto) y la posibilidad de retomar cualquier conversación con claude --continue o claude --resume. Esta guía explica qué cubre cada mecanismo, qué añade claude-mem y qué decidir al instalarlo, porque su instalador preselecciona un servicio alojado de pago.

Qué conserva Claude Code entre sesiones sin plugins

Cada sesión de Claude Code arranca con una ventana de contexto vacía. La documentación oficial de memoria describe dos mecanismos que se cargan al inicio de cada conversación, y la de sesiones añade un tercero: reabrir la conversación entera.

CLAUDE.md: instrucciones que escribes tú

Son ficheros Markdown que Claude lee al empezar cada sesión. Hay varios ámbitos:

• Usuario: ~/.claude/CLAUDE.md, para tus preferencias en todos los proyectos.
• Proyecto: ./CLAUDE.md o ./.claude/CLAUDE.md, compartido con el equipo por control de versiones.
• Local: ./CLAUDE.local.md, preferencias personales del proyecto que conviene añadir a .gitignore.
• Reglas: ficheros en .claude/rules/, que pueden limitarse a ciertas rutas con el campo paths del frontmatter y solo se cargan cuando Claude trabaja con ficheros que coinciden.

/init genera un primer CLAUDE.md analizando el repositorio, y un CLAUDE.md puede importar otros ficheros con la sintaxis @ruta/al/fichero. La documentación recomienda mantener cada fichero por debajo de 200 líneas, porque los ficheros largos consumen más contexto y reducen la adherencia. Si el repositorio usa AGENTS.md y no hay CLAUDE.md, .claude/CLAUDE.md ni CLAUDE.local.md en el directorio de trabajo o en los superiores, Claude Code lee AGENTS.md en su lugar (desde la v2.1.277). Tu ~/.claude/CLAUDE.md global no cuenta para esa comprobación y se carga junto a él.

Auto memory: notas que escribe Claude

Es la memoria persistente nativa propiamente dicha. Mientras trabaja, Claude guarda notas de cuatro tipos (user, feedback, project y reference): tu rol y preferencias, las correcciones que le das, decisiones y plazos que no se deducen del código, y dónde está la información externa al proyecto.

• Dónde: ~/.claude/projects/<proyecto>/memory/, con un índice MEMORY.md y un fichero por tema. Todas las worktrees y subdirectorios del mismo repositorio git comparten un único directorio.
• Qué se carga: las primeras 200 líneas o 25 KB de MEMORY.md, lo que llegue antes. Los ficheros de tema se leen bajo demanda.
• Cómo se controla: está activada por defecto en sesiones locales. /memory lista los ficheros de memoria, permite abrirlos y activa o desactiva la auto memory. Para un proyecto concreto, "autoMemoryEnabled": false en su configuración; globalmente, la variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.
• Qué no guarda: lo que Claude puede deducir del código (arquitectura, rutas de ficheros, arreglos de depuración) ni lo que ya dicen tus CLAUDE.md. Tampoco guarda algo en todas las sesiones.

Si le pides a Claude que recuerde algo ("usa siempre pnpm, no npm"), lo guarda en auto memory. Si quieres que vaya a CLAUDE.md, pídelo explícitamente o edítalo desde /memory.

Retomar la conversación completa: --continue y --resume

Claude Code guarda cada sesión como transcripción JSONL en ~/.claude/projects/<proyecto>/<session-id>.jsonl y la conserva 30 días por defecto (ajustable con cleanupPeriodDays). Para volver a ella:

# Reabre la conversación más reciente del directorio actual
claude --continue

# Abre el selector de sesiones, o reanuda una por nombre
claude --resume
claude --resume migracion-app-router

# Pon nombre a la sesión al arrancar para encontrarla después
claude -n migracion-app-router

Dentro de una sesión, /resume cambia a otra conversación y /rename le pone nombre. Al reanudar se restaura el historial completo, incluidas las llamadas a herramientas y sus resultados. Es la opción más fiel, pero también la más cara en contexto: arrastras toda la conversación, no un resumen.

/compact y qué sobrevive a la compactación

/compact [instrucciones] sustituye el historial por un resumen, opcionalmente centrado en lo que indiques (por ejemplo, /compact céntrate en la migración del router). Claude Code también compacta solo al acercarse al límite. Según la guía de la ventana de contexto, tras compactar se vuelven a inyectar desde disco el CLAUDE.md de la raíz, las reglas sin paths y la auto memory, y se releen hasta cinco de los ficheros modificados más recientemente. Lo que solo dijiste en el chat queda reducido a lo que recoja el resumen: si una instrucción tiene que sobrevivir, va en CLAUDE.md.

Qué añade claude-mem

La diferencia de fondo está en qué se guarda. La auto memory nativa guarda pocas notas seleccionadas y evita a propósito lo que se puede deducir del código. claude-mem registra la actividad del agente (los usos de herramientas, salvo unas pocas excluidas por defecto como TodoWrite o Skill) y la convierte en observaciones consultables. Según su documentación de hooks, se engancha a cinco eventos del ciclo de vida de Claude Code:

Las observaciones se guardan en SQLite (con búsqueda FTS5) dentro de ~/.claude-mem/, junto con una base vectorial Chroma para búsqueda semántica. Un worker local gestionado con Bun sirve una API HTTP y un visor web con el flujo de memoria. Además, expone herramientas MCP para que Claude consulte la memoria en tres pasos:

1. search: devuelve un índice compacto con IDs (unos 50-100 tokens por resultado, según el README).
2. timeline: muestra el contexto cronológico alrededor de una observación.
3. get_observations: trae el detalle completo solo de los IDs elegidos (unos 500-1.000 tokens por resultado).

La idea es que al arrancar solo entre un resumen y que el detalle se pida cuando haga falta. Por defecto se inyectan 50 observaciones al inicio de sesión (CLAUDE_MEM_CONTEXT_OBSERVATIONS en ~/.claude-mem/settings.json).

Cómo instalar claude-mem

Requisitos según el README: Node.js 20 o superior y una versión de Claude Code con soporte de plugins. Bun y uv se instalan solos si faltan; SQLite va incluido.

# Opción 1: instalador interactivo
npx claude-mem install

# Opción 1b: mismo instalador, pero la compresión usa tu plan de Anthropic
# y se salta el inicio de sesión en cmem.ai
npx claude-mem install --provider claude

# Opción 2: desde dentro de Claude Code, vía marketplace de plugins
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Después reinicia Claude Code; el contexto de sesiones anteriores aparece automáticamente en las nuevas. No uses npm install -g claude-mem: según la documentación del proyecto, eso instala solo la librería, sin registrar los hooks ni arrancar el worker.

Qué proveedor elegir al instalar

Comprimir observaciones requiere llamar a un modelo, y alguien paga esas llamadas. El instalador interactivo pide iniciar sesión en cmem.ai y preselecciona CMEM Pro, el servicio alojado del proyecto. Las opciones que documenta la guía de instalación:

Con --provider claude, la documentación indica que a cmem.ai solo llega, una vez, un resumen numérico de uso (recuentos de observaciones y totales de tokens, sin prompts, rutas ni nombres de proyecto), y que con CMEM Pro la compresión se ejecuta en la pasarela de cmem.ai. Son descripciones del proyecto, no un análisis del tráfico de red del instalador. El proyecto también ofrece Cloud Sync para copiar las memorias a cmem.ai. Si tu código no puede salir hacia terceros, decide el proveedor antes de pulsar Enter en el instalador.

Comparativa: qué mecanismo usar para qué

Para una tarea que dura varios días, la combinación nativa cubre bastante: decisiones estables en CLAUDE.md, preferencias y correcciones en auto memory, y claude --resume con nombre de sesión cuando necesitas el hilo exacto. claude-mem encaja cuando lo que quieres recuperar es el historial de lo que se hizo (qué ficheros se tocaron, qué comandos se ejecutaron, qué se resolvió) entre muchas sesiones y poder buscarlo, que es justo lo que la auto memory nativa evita guardar. A cambio, añade un worker, una base de datos local y un coste de compresión por observación.

Problemas habituales

• Los hooks no se disparan tras instalar con npm. npm install -g claude-mem no registra los hooks. Reinstala con npx claude-mem install o con los comandos /plugin.
• Faltan dependencias del runtime. npx claude-mem repair vuelve a instalar las dependencias (Bun, uv y paquetes del plugin), según la guía de instalación. Los logs del worker están en ~/.claude-mem/logs/worker-AAAA-MM-DD.log.
• Aparece memoria de otro proyecto, o no aparece la del tuyo. En la v13.34.2, claude-mem nombra el proyecto, por defecto, con el nombre de la carpeta raíz del repositorio git (aunque arranques desde un subdirectorio). Fuera de git busca hacia arriba un marcador .claude-mem-project o .claude-mem.json y, si no lo encuentra, usa la carpeta de trabajo. Como lo que cuenta es el nombre de la carpeta, dos repositorios con la misma carpeta raíz comparten identidad; con CLAUDE_MEM_PROJECT_NAME_SOURCE=git-remote el nombre sale del remoto origin (org/repo).
• Datos sensibles en la memoria. Las etiquetas <private> evitan que ese contenido llegue a las observaciones y a la base de datos, y en settings.json puedes excluir herramientas (CLAUDE_MEM_SKIP_TOOLS) o comandos de shell por patrón (CLAUDE_MEM_SKIP_BASH_PATTERNS). No lo tomes como garantía de que nada toca el disco: en la v13.34.2, el hook escribe el evento completo en una cola local (~/.claude-mem/state/hook-spool/) antes de filtrarlo, y si su procesamiento falla la entrada puede quedarse ahí. En la memoria nativa, los ficheros son Markdown que puedes revisar y borrar desde /memory.
• Una instrucción se pierde tras /compact. Solo estaba en la conversación. Pásala al CLAUDE.md de la raíz, que se reinyecta tras cada compactación.
• Claude no sigue tu CLAUDE.md. Ejecuta /context y comprueba que aparece en Memory files. Si algo tiene que ocurrir siempre, conviértelo en un hook en lugar de una instrucción; aquí se explica cómo con hooks en Claude Code para checks automáticos.

Si quieres comparar con otro enfoque basado en MCP, este artículo sobre auto memory y Engram en Claude Code cubre esa alternativa, y la guía general de memoria persistente en agentes de IA amplía el tema fuera de Claude Code.

Preguntas frecuentes

¿Claude Code tiene memoria persistente sin instalar nada?

Sí. Los ficheros CLAUDE.md se cargan en cada sesión y la auto memory, activada por defecto en sesiones locales, guarda notas en ~/.claude/projects/<proyecto>/memory/ y carga las primeras 200 líneas o 25 KB de MEMORY.md al empezar cada conversación.

¿Cómo se instala claude-mem?

Con npx claude-mem install, o dentro de Claude Code con /plugin marketplace add thedotmack/claude-mem seguido de /plugin install claude-mem, y reiniciando Claude Code después. Requiere Node.js 20 o superior.

¿claude-mem envía mis datos fuera de mi máquina?

Depende del proveedor. La base de datos vive en ~/.claude-mem/, pero la compresión la hace un modelo. Según la documentación del proyecto, con CMEM Pro (preseleccionado en el instalador) se ejecuta en la pasarela de cmem.ai; con --provider claude usa tu plan de Anthropic y a cmem.ai solo llega un resumen numérico de uso; con OpenRouter o Gemini, el proveedor de tu clave.

¿Qué diferencia hay entre CLAUDE.md, la auto memory y claude-mem?

CLAUDE.md contiene instrucciones que escribes tú. La auto memory son notas que Claude decide guardar sobre tus preferencias y decisiones, sin incluir lo que se deduce del código. claude-mem registra los usos de herramientas mediante hooks (salvo las excluidas por configuración), los comprime y permite buscarlos en sesiones posteriores.

¿Cómo retomo una sesión anterior de Claude Code?

claude --continue reabre la conversación más reciente del directorio actual y claude --resume abre un selector de sesiones. Si nombras la sesión con claude -n nombre o /rename, puedes reanudarla con claude --resume nombre.

¿Por qué claude-mem no funciona tras instalarlo con npm install -g?

Porque ese comando instala solo la librería: no registra los hooks de Claude Code ni arranca el worker. Hay que instalarlo con npx claude-mem install o con los comandos /plugin.