Claude-mem: Memoria Persistente para Claude Code | Instalación y Configuración 2026

claude-mem es un servidor MCP (Model Context Protocol), el protocolo abierto de Anthropic que permite conectar modelos de IA con herramientas externas mediante una interfaz estandarizada. claude-mem usa ese protocolo para añadir una capa de memoria persistente a Claude Code: cada vez que cierras una sesión, guarda automáticamente el contexto relevante en una base de datos local SQLite. La próxima vez que abres Claude Code, recupera solo lo que necesita, sin que tengas que volver a explicar nada.

El resultado es que Claude recuerda la arquitectura de tu proyecto, las decisiones que tomaste, los bugs que ya resolviste y las convenciones que acordasteis — de forma indefinida, sin coste de nube y sin que tus datos salgan de tu máquina.

El problema: amnesia de sesión en Claude Code

Claude Code no retiene ninguna información entre sesiones por defecto. Esto es correcto desde el punto de vista de la privacidad, pero destructivo para la productividad en proyectos de larga duración. Cada mañana empiezas de cero: tienes que volver a explicar la estructura de carpetas, los patrones que usas, qué librerías están en producción y cuáles en prueba, qué errores ya descartasteis y por qué.

En proyectos con más de 100 archivos, esta «puesta en contexto» consume entre 5.000 y 20.000 tokens de input solo para llegar al punto donde la conversación anterior terminó. A $3 por millón de tokens de input con Claude Sonnet 4.6 (tarifa oficial de Anthropic, abril de 2026), eso son entre $0,015 y $0,06 por sesión — aparentemente poco, pero multiplicado por 20 sesiones al mes y varios proyectos simultáneos, el coste real está en el tiempo, no en el dinero: 5-10 minutos de setup manual por sesión que se evitan completamente.

Por qué CLAUDE.md no es suficiente

CLAUDE.md es el archivo de instrucciones persistentes que Claude Code lee al iniciar cada sesión. Es útil para convenciones generales del proyecto, pero tiene tres limitaciones críticas frente a claude-mem:

• No es searchable: Claude lee el archivo completo en cada sesión, sin filtrar por relevancia. Con 500 líneas de CLAUDE.md, estás pagando tokens por contexto que no necesitas en ese momento.
• No crece automáticamente: tienes que actualizar CLAUDE.md a mano cada vez que tomas una decisión importante. claude-mem captura el contexto de forma automática durante la conversación.
• No guarda historial operativo: CLAUDE.md documenta convenciones estáticas; claude-mem guarda decisiones concretas, bugs resueltos y razonamientos que explican por qué el código es como es.

claude-mem combina tres tecnologías de búsqueda local para recuperar el contexto más relevante con el menor número de tokens posible. Todo ocurre en tu máquina — no hay llamadas externas.

Arquitectura: SQLite + FTS5 + búsqueda vectorial local

La base de datos es un archivo SQLite (el motor de base de datos más desplegado del mundo, integrado en el propio sistema operativo de macOS y Linux) almacenado en ~/.claude-mem/memory.db. Sobre SQLite, claude-mem activa la extensión FTS5 (Full-Text Search 5), que permite búsquedas de texto completo con relevancia TF-IDF (Term Frequency-Inverse Document Frequency, el algoritmo estándar para puntuar relevancia textual) sin instalar nada adicional.

Para la búsqueda semántica, claude-mem genera embeddings locales usando un modelo ligero en formato ONNX (Open Neural Network Exchange, el estándar abierto para modelos de IA portables que permite ejecutarlos sin dependencias del proveedor original), lo que permite encontrar memorias conceptualmente relacionadas aunque no compartan las mismas palabras exactas. Este proceso ocurre completamente en CPU, sin necesidad de GPU, aunque en proyectos grandes puede ser el cuello de botella de rendimiento.

El flujo de recuperación en 3 capas

Cuando Claude Code recibe un mensaje, claude-mem ejecuta tres búsquedas en paralelo y fusiona los resultados por relevancia:

1. Búsqueda exacta (FTS5): encuentra memorias que contienen los mismos términos que el mensaje actual. Rápida y precisa para nombres de funciones, rutas de archivos y errores específicos.
2. Búsqueda semántica (vectorial): encuentra memorias conceptualmente relacionadas aunque usen vocabulario diferente. Útil para recuperar decisiones de diseño aunque no recuerdes las palabras exactas con las que las describiste.
3. Memorias recientes: independientemente de la relevancia, incluye las últimas N memorias para mantener la continuidad de la sesión anterior.

El resultado combinado se inyecta al inicio del contexto de Claude, antes de tu mensaje. Típicamente ocupa entre 500 y 2.500 tokens — frente a los 15.000-30.000 tokens que costaría incluir el contexto completo del proyecto.

La instalación completa lleva menos de 3 minutos. Necesitas Node.js instalado y Claude Code funcionando — si ya tienes ambos, son cuatro comandos.

Requisitos previos

• Node.js 18+ — comprueba con node --version
• Claude Code — instalado y con sesión activa
• npm o npx — incluido con Node.js
• macOS, Linux o Windows con WSL2 (Windows nativo tiene limitaciones con SQLite binario)

Instalación del plugin

Instala claude-mem de forma global para que esté disponible en todos tus proyectos:

# Instalar claude-mem globalmente
npm install -g claude-mem

# Verificar que el binario está disponible
claude-mem --version

Si prefieres no instalar nada globalmente, puedes usar npx directamente en la configuración del servidor MCP (ver siguiente paso).

Configuración del servidor MCP en settings.json

Claude Code lee la configuración de servidores MCP desde ~/.claude/settings.json (configuración global) o desde .claude/settings.json en la raíz del proyecto (configuración local). Añade el bloque mcpServers con la entrada para claude-mem:

{
  "mcpServers": {
    "claude-mem": {
      "command": "claude-mem",
      "args": ["serve"],
      "env": {
        "CLAUDE_MEM_DB_PATH": "~/.claude-mem/memory.db",
        "CLAUDE_MEM_WEB_PORT": "37777",
        "CLAUDE_MEM_MAX_RESULTS": "15"
      }
    }
  }
}

Si prefieres usar npx sin instalación global, sustituye el bloque "command" y "args" por:

{
  "mcpServers": {
    "claude-mem": {
      "command": "npx",
      "args": ["-y", "claude-mem", "serve"]
    }
  }
}

Verificación: cómo confirmar que la memoria está activa

El Modo Endless es la función más avanzada de claude-mem: cuando el contexto de la sesión actual se acerca al límite de la ventana de contexto del modelo (200.000 tokens en Claude 4.x), claude-mem comprime y resume automáticamente el historial anterior, lo guarda en la base de datos y libera espacio para continuar la conversación sin interrupciones.

El proceso es transparente: Claude sigue respondiendo con continuidad, usando el resumen comprimido como punto de referencia en lugar del historial completo. Esto permite sesiones de trabajo técnico que duran horas sin perder el hilo, incluso en bases de código grandes con mucho contexto acumulado.

El umbral de compresión es configurable mediante la variable de entorno CLAUDE_MEM_COMPRESS_AT (porcentaje de la ventana de contexto, por defecto 80%). El resumen comprimido ocupa típicamente un 10-15% del contexto original, multiplicando por 6-10 la duración efectiva de cada sesión antes de necesitar reiniciar.

Los porcentajes de ahorro genéricos sin metodología no sirven para tomar una decisión informada. Aquí está el cálculo completo, reproducible, con los precios actuales de Claude Sonnet 4.6 (abril 2026).

Ejemplo con proyecto de 500 archivos

Supuesto: proyecto backend Node.js con 500 archivos, ~80.000 líneas de código. El equipo trabaja con Claude Code durante 20 sesiones al mes. Precios de referencia: $3 por millón de tokens de input con Claude Sonnet 4.6, según la tarifa oficial de Anthropic publicada en abril de 2026.

El ahorro económico directo en tokens es modesto (~$12/año por desarrollador). El beneficio real está en las 160 minutos mensuales de setup eliminados y en la calidad de las respuestas: Claude no necesita hacer suposiciones sobre el proyecto porque ya tiene el contexto guardado.

claude-mem arranca automáticamente una interfaz web local en el puerto 37777 junto al servidor MCP. Esta UI te da control total sobre la base de datos de memorias sin tocar SQL.

Desde el visualizador puedes hacer cuatro cosas concretas:

• Buscar memorias: campo de búsqueda con soporte FTS5 — encuentra cualquier memoria por palabras clave exactas o similares.
• Editar entradas: corrige memorias incorrectas que Claude guardó con información desactualizada o errónea.
• Eliminar memorias: borra entradas individuales o limpia la base de datos completa con un botón de reset.
• Ver metadatos: cada memoria muestra cuándo se guardó, en qué sesión, qué herramienta la creó y cuántas veces se ha recuperado — útil para detectar qué contexto usa más Claude.

El visualizador también muestra el tamaño actual de la base de datos y el número total de memorias almacenadas. En proyectos maduros con meses de uso activo, es normal tener entre 500 y 2.000 entradas, con un tamaño de archivo entre 2 MB y 15 MB — completamente manejable para SQLite.

Antes de instalar claude-mem, conviene entender qué otras opciones existen y en qué escenarios cada una gana.

La memoria nativa de Claude (disponible en planes Pro y Enterprise) es más cómoda porque no requiere instalación, pero los datos se almacenan en los servidores de Anthropic y no tienes control sobre qué se guarda ni cuándo. Para proyectos con datos sensibles (código propietario, arquitecturas internas), esto puede ser un bloqueador.

mem0 es una opción sólida si ya usas su plataforma para otras integraciones de IA, pero introduce una dependencia de red y una suscripción adicional que claude-mem evita por completo.

claude-mem no es la herramienta correcta en todos los escenarios. Instalarla cuando no aplica añade complejidad sin beneficio.

El 95% de los problemas con claude-mem caen en cuatro categorías. Aquí están los síntomas exactos y la solución directa para cada uno.

El servidor MCP no se detecta

Síntoma: Al escribir /mcp en Claude Code, claude-mem no aparece o aparece con estado «failed».

Causas y soluciones:

• JSON malformado en settings.json: valida el archivo con node -e "JSON.parse(require('fs').readFileSync('~/.claude/settings.json','utf8'))". Una coma extra o una llave sin cerrar es suficiente para que Claude Code ignore el archivo completo.
• Binario no encontrado en PATH: si instalaste con npm global, comprueba que $(npm root -g)/../bin está en tu PATH. Ejecuta which claude-mem — si no devuelve nada, usa la variante con npx en el JSON.
• Claude Code no se reinició: los cambios en settings.json no se aplican en sesiones ya abiertas. Reinicia completamente la aplicación.

# Verificar que claude-mem está instalado y en PATH
which claude-mem && claude-mem --version

# Validar el JSON de settings sin lanzar Claude
node -e "JSON.parse(require('fs').readFileSync(process.env.HOME + '/.claude/settings.json','utf8'));console.log('JSON válido')"

# Arrancar el servidor manualmente para ver el error exacto
claude-mem serve --verbose

La base de datos no persiste entre sesiones

Síntoma: Claude guarda memorias durante la sesión, pero en la sesión siguiente no las recupera.

La causa más común es que CLAUDE_MEM_DB_PATH apunta a una ruta relativa interpretada de forma diferente según desde dónde se lanza Claude Code. Usa siempre una ruta absoluta con la home expandida:

"CLAUDE_MEM_DB_PATH": "/Users/tu-usuario/.claude-mem/memory.db"

Comprueba también que el directorio existe: mkdir -p ~/.claude-mem. Si el directorio no existe en el arranque, claude-mem falla silenciosamente y usa una base de datos temporal en memoria que se pierde al cerrar.

Rendimiento lento en proyectos grandes

Síntoma: Las respuestas de Claude tardan varios segundos adicionales al inicio de cada mensaje. El visualizador web muestra más de 3.000 entradas en la base de datos.

El cuello de botella es la generación de embeddings para la búsqueda semántica en bases de datos grandes. Tres ajustes que resuelven el 90% de los casos:

• Reduce CLAUDE_MEM_MAX_RESULTS de 15 a 8 — menos resultados a clasificar por relevancia.
• Activa el modo solo-FTS desactivando embeddings: "CLAUDE_MEM_DISABLE_VECTORS": "true". Pierdes búsqueda semántica pero ganas velocidad de 10x.
• Limpia memorias antiguas desde el visualizador: filtra por fecha y elimina entradas de hace más de 6 meses que ya no son relevantes para el estado actual del proyecto.

Conflicto de puertos: el visualizador no arranca

Síntoma: localhost:37777 no carga o devuelve «connection refused».

Otro proceso ocupa el puerto 37777. Comprueba con lsof -i :37777 y cambia el puerto en la configuración con "CLAUDE_MEM_WEB_PORT": "38888" (o cualquier puerto libre por encima de 1024).

Estas son las dudas que aparecen más frecuentemente al instalar claude-mem por primera vez.