Claude-Mem: plugin de memoria persistente para Claude Code
Claude-Mem es un plugin de terceros que observa lo que hace tu agente, tiene un segundo agente que lo comprime en observaciones e inyecta un índice breve de ellas en la siguiente sesión. Esto es lo que hace realmente, cómo instalarlo y configurarlo, y dónde acaba y dónde empieza CLAUDE.md.
Claude-Mem de un vistazo
- Es una capa de memoria, no un archivo de reglas: los hooks pasan cada llamada de herramienta a un worker local, un segundo agente convierte esa actividad en observaciones breves y la siguiente sesión arranca con un índice compacto de ellas.
- Dos rutas de instalación compatibles: npx claude-mem install (prepara el entorno de ejecución y abre una configuración en el navegador), o el par /plugin marketplace add thedotmack/claude-mem y después /plugin install claude-mem.
- Apache-2.0, TypeScript, mantenido por Alex Newman (thedotmack). La memoria se guarda en local, en SQLite, en ~/.claude-mem/claude-mem.db; la sincronización en la nube es opcional.
- No sustituye a CLAUDE.md ni a la memoria automática de Claude Code: las tres se cargan al inicio de la sesión y responden a preguntas distintas. La tabla comparativa de abajo es la versión corta.
thedotmack/claude-mem — README
Fuentegithub.comchecked 2026-11-13
.claude-plugin/marketplace.json — claude-mem 15.18.3
Fuenteraw.githubusercontent.comchecked 2026-11-13
Installation Guide
Fuentedocs.claude-mem.aichecked 2026-11-13
Configuration
Fuentedocs.claude-mem.aichecked 2026-11-13
Telemetry — what is collected and how to opt out
Fuentedocs.claude-mem.aichecked 2026-11-13
How Claude remembers your project — CLAUDE.md vs auto memory
Fuentecode.claude.comchecked 2026-11-13
dsh-claude-mem — DeepSeek Harness port (unofficial)
Fuentedeepseekharnessplugins.comchecked 2026-11-13
Los comandos, ajustes, valores por defecto y rutas de esta página se leyeron del repositorio upstream y de la documentación oficial el 2026-11-13. Los comandos y los nombres de los ajustes se dejan sin traducir a propósito, porque un comando traducido es un comando roto.
Datos del repositorio según la API de GitHub el 2026-11-13: 116,640 estrellas, 10,120 forks, creado el 2025-08-31, última versión v15.18.3 publicada el 2026-11-12. El número de estrellas cambia a diario: tómalo como una instantánea, no como una puntuación.
Qué es Claude-Mem en realidad
Claude-Mem es un plugin de código abierto para Claude Code (y para una docena de otros agentes de programación) que le da al agente memoria de su propio trabajo. El proyecto describe el problema sin rodeos: cada sesión nueva empieza de cero, vuelve a leer los mismos archivos, repite las mismas preguntas y regresa a errores que ya habías corregido junto al agente.
Su respuesta es un segundo agente que corre junto al tuyo. Los hooks instalados en el agente anfitrión pasan cada llamada de herramienta —lo que se leyó, se editó y se ejecutó— a un pequeño worker local. Ese worker ejecuta un modelo observador sobre la actividad, escribe observaciones estructuradas breves y un resumen de fin de sesión, y las guarda en una base de datos SQLite local. Cuando empieza una sesión nueva, el agente anfitrión recibe un índice compacto de las observaciones que importan para este proyecto y solo recupera los detalles completos cuando los pide.
Así que la unidad de memoria aquí es una observación sobre trabajo que ocurrió, no una instrucción que escribiste tú. Ahí está toda la diferencia con CLAUDE.md, y es la razón por la que los dos conviven en lugar de competir.
- Licencia
- Apache-2.0
- Última versión
- v15.18.3 · 2026-11-12
- La memoria vive en
~/.claude-mem/claude-mem.db- Estrellas (2026-11-13)
- 116,640
Cómo funciona, en tres movimientos
El README expone el bucle en tres frases, y todas las demás funciones cuelgan de él:
- 1
Tu agente trabaja
Los hooks de ciclo de vida del agente anfitrión pasan cada llamada de herramienta a un pequeño worker local. En Claude Code, los hooks cubren SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop, SubagentStop y SessionEnd, además de una entrada Setup para claude --init y --maintenance. Cada hook es un único comando sin shell, claude-mem hook claude-code <event>.
- 2
El observador toma notas
Un segundo agente convierte esa actividad en observaciones breves y escribe un resumen cuando termina la sesión. Por defecto, el modelo de compresión es Haiku (CLAUDE_MEM_MODEL=haiku), que se ejecuta con tu plan de Anthropic; también puedes apuntarlo a una clave de OpenRouter o de Gemini, o al observador alojado del proveedor.
- 3
La siguiente sesión empieza con ellas
En SessionStart el agente recibe un índice compacto de las observaciones de este proyecto —50 por defecto, ajustable con CLAUDE_MEM_CONTEXT_OBSERVATIONS— y obtiene los detalles completos solo cuando los necesita. La inyección empieza en tu segunda sesión en un proyecto, porque la primera aún no tiene nada que inyectar.
La búsqueda usa la misma idea por capas. Tres herramientas MCP —search, timeline, get_observations— devuelven primero un índice, después el contexto cronológico y por último los registros completos, de modo que el agente paga por el detalle solo en las filas que eligió. La skill mem-search maneja esas herramientas por ti, y las propias cifras del README sitúan una fila de índice en unos 50–100 tokens frente a 500–1.000 de un registro completo: una proporción por fila que el README dice explícitamente que no es un ahorro medido de extremo a extremo.
Qué más te da el worker
El worker local sirve un visor en la URL que imprime al arrancar —memoria, sesiones y ajustes en /viewer, además de My Work en la raíz— y expone herramientas más allá de la búsqueda: smart_search, smart_outline y smart_unfold para navegar por el código, save_memory para escribir una nota a propósito, y seguimiento del estado del trabajo. Cada observación tiene un ID que puedes citar a través de la API del worker.
Instalar y verificar
Las dos rutas de abajo están copiadas de la documentación upstream. La del instalador es la que recomienda el proyecto, porque prepara el entorno de ejecución y compila el lanzador de hooks; la del plugin son dos prompts dentro de Claude Code.
Ruta 1 — el instalador
Ejecuta esto en una terminal. El instalador comprueba Bun y uv, copia los archivos del plugin, instala las dependencias, pone el lanzador claude-mem en tu PATH y abre una configuración en el navegador donde eliges agentes, integraciones, skills y el proveedor de memoria. Mantén la terminal en marcha mientras usas esa página.
npx claude-mem installNo lo instales con npm install -g claude-mem. El README es explícito: una instalación global con npm solo deja el SDK/la librería en tu máquina —no registra ningún hook de plugin ni arranca ningún worker, y puede tapar el lanzador real en el PATH.
Ruta 2 — el marketplace de plugins
Envía estos como dos prompts separados dentro de Claude Code y luego reinícialo. Ambas rutas configuran los hooks y arrancan el worker; a partir de ahí, el contexto de sesiones anteriores aparece automáticamente en las nuevas sesiones.
/plugin marketplace add thedotmack/claude-mem/plugin install claude-memUna instalación solo desde el marketplace no tiene paso de instalador, así que el plugin coloca su lanzador en el primer inicio de sesión mientras compila: esa primera sesión puede correr sin contexto de memoria, y la siguiente ya lo tiene. Ejecutar npx claude-mem install una vez elimina esa brecha.
Comprobar que está corriendo de verdad
Ejecuta npx claude-mem doctor: comprueba Bun, uv, el lanzador de hooks y el worker, y te dice qué arreglar. claude-mem --version imprime el número de protocolo del lanzador, y la URL del worker que se imprime al arrancar sirve el visor. Si los hooks informan de "Executable not found in $PATH", doctor muestra qué claude-mem se resuelve en el PATH y si es el lanzador.
npx claude-mem doctorclaude-mem --versionRequisitos antes de empezar
- 1Node.js 20.19 o posterior dentro de la línea 20.x, o 22.12 o posterior.
- 2Bun 1.2.16 o superior: el lanzador de hooks se compila con él; el instalador instala Bun si falta.
- 3uv, que se instala automáticamente si falta: aporta la parte de Python del servicio de embeddings de Chroma para la búsqueda semántica.
- 4Claude Code 2.1.139 o posterior: la primera versión que ejecuta argumentos de hook en forma exec. Las versiones anteriores ignoran los args y ejecutan un claude-mem pelado, así que no se captura nada. SQLite viene incluido vía bun:sqlite.
Los ajustes que de verdad cambian el comportamiento
Todo vive en ~/.claude-mem/settings.json, que se crea automáticamente con los valores por defecto en la primera ejecución, y una variable de entorno con el mismo nombre tiene prioridad sobre el archivo. Estas son las filas que conviene conocer; la página de configuración documenta el resto.
| Ajuste | Valor por defecto | Qué hace |
|---|---|---|
CLAUDE_MEM_MODEL | haiku | Modelo usado para comprimir las observaciones cuando el proveedor es Claude. haiku sigue al Haiku más reciente; un ID completo fija una versión. |
CLAUDE_MEM_PROVIDER | claude | Qué proveedor ejecuta el observador: claude, codex, gemini, openrouter u openai-compatible. |
CLAUDE_MEM_CONTEXT_OBSERVATIONS | 50 | Cuántas observaciones se inyectan al inicio de la sesión. Bájalo si el bloque de arranque te parece pesado. |
CLAUDE_MEM_MODE | code | Perfil de flujo de trabajo y idioma de las observaciones generadas, p. ej. code, code--chill para menos observaciones, o code--zh para chino. |
CLAUDE_MEM_DATA_DIR | ~/.claude-mem | Raíz de datos. Todas las demás rutas —base de datos, índice de Chroma, logs, ajustes, archivos de pid y de puerto del worker— se derivan de ella. |
CLAUDE_MEM_WORKER_PORT | 37700 + (uid % 100) | Puerto del worker. El valor por defecto es por usuario, así que dos usuarios en una misma máquina no chocan; fija un puerto si haces scripts contra la API HTTP. |
CLAUDE_MEM_CONTEXT_PROJECTS | current | Para qué proyectos lee la memoria SessionStart: current significa este checkout, all significa todos los proyectos salvo los que excluyas con un patrón glob. |
CLAUDE_MEM_SKIP_TOOLS | ListMcpResourcesTool, SlashCommand, Skill, TodoWrite, AskUserQuestion | Herramientas excluidas de las observaciones. Útil para herramientas cuyo resultado es ruido y no conocimiento. |
CLAUDE_MEM_SESSION_START_INCLUDE_ALL_SOURCES | false | Si el contexto de SessionStart incluye observaciones de todos los harness, no solo del que estás usando. Por defecto, false. |
CLAUDE_MEM_SKILLS_DISABLED | (none) | Oculta skills incluidas del listado y de los comandos de barra de Claude Code, por nombre de carpeta simple. |
Otros dos que conviene conocer: CLAUDE_MEM_SKIP_BASH_PATTERNS acepta una expresión regular que se compara con cada comando de shell, para que los comandos ruidosos nunca se conviertan en observaciones, y CLAUDE_MEM_REDACT_ENABLED (desactivado por defecto) activa la redacción automática de los patrones de secretos reconocidos antes de guardarlos.
Claude-Mem frente a la memoria integrada de Claude Code
Claude Code ya transporta conocimiento entre sesiones de dos maneras, y la documentación de Anthropic las trata como complementarias: los archivos CLAUDE.md que escribes tú y la memoria automática que escribe Claude. Claude-Mem es una tercera capa independiente por encima.
| Dimensión | Integrado en Claude Code | Plugin Claude-Mem |
|---|---|---|
| Quién lo escribe | Tú escribes CLAUDE.md; Claude escribe la memoria automática a partir de tus correcciones. | Un segundo agente observador, a partir de la actividad de herramientas que produjo tu sesión. |
| Dónde vive | CLAUDE.md en la raíz del proyecto o ~/.claude/CLAUDE.md; la memoria automática en ~/.claude/projects/<project>/memory/ con un índice MEMORY.md. | SQLite en ~/.claude-mem/claude-mem.db, más ajustes y logs en la misma carpeta. Índice Chroma opcional para la búsqueda semántica. |
| Qué contiene | Instrucciones y reglas; la memoria automática guarda aprendizajes y patrones, y solo se cargan sus primeras 200 líneas o 25 KB. | Observaciones sobre trabajo que ocurrió —decisiones, correcciones de bugs, qué se leyó y qué se cambió— comprimidas por un modelo. |
| Cuándo se carga | En cada sesión, automáticamente, como contexto después del prompt del sistema. | En SessionStart mediante un hook, desde tu segunda sesión en un proyecto en adelante. |
| Cómo se lee | El archivo completo o el índice de memoria automática simplemente están presentes en el contexto; /memory lista y abre los archivos. | Se inyecta un índice compacto; los detalles vuelven a través de tres herramientas MCP —search, timeline, get_observations. |
| Dependencias y coste | Nada extra: viene con Claude Code. | Node, Bun y uv, un proceso worker local y un modelo que comprime: tu plan de Anthropic por defecto, tu propia clave, o el observador alojado de pago. |
El reparto práctico: las reglas y convenciones van en CLAUDE.md, la memoria automática recoge preferencias y Claude-Mem lleva el historial de lo que realmente hiciste. Si el detalle de una sesión importa una sola vez, ninguno de los tres lo necesita; si una regla debe cumplirse siempre, solo CLAUDE.md es su sitio. Ni siquiera son excluyentes en el almacenamiento: la ingesta de memoria de claude-mem importa los archivos de temas de la memoria automática de Claude Code a su propia base de datos como observaciones, sin gastar tokens del modelo.
Tutorial de memoria de Claude CodePrivacidad, límites y advertencias honestas
Este plugin graba tus sesiones de trabajo, así que conviene leer los valores por defecto antes de que aterrice en un repositorio de trabajo.
- 1Local por defecto. Las sesiones, observaciones y resúmenes se escriben en SQLite en ~/.claude-mem/claude-mem.db; los ajustes y logs están en la misma carpeta. La sincronización en la nube es opcional, no automática.
- 2Envuelve cualquier cosa en etiquetas <private> y nunca se guarda — así lo dice el README. La redacción automática de patrones de secretos reconocidos es otro interruptor opcional, CLAUDE_MEM_REDACT_ENABLED, y viene desactivado por defecto.
- 3La telemetría anónima está activada por defecto (PostHog, vinculada solo a un UUID de instalación aleatorio). Desactívala con npx claude-mem telemetry disable; DO_NOT_TRACK se respeta y tiene prioridad sobre todo lo demás.
- 4La compresión es una llamada a un modelo, así que la actividad de herramientas sale de la máquina hacia el proveedor que hayas elegido: tu plan de Anthropic, tu clave de OpenRouter o de Gemini, o el observador alojado del proveedor. Elige a conciencia.
- 5Es software de terceros, no un producto de Anthropic, e instala hooks ejecutables. Lee plugin/hooks/hooks.json y los ajustes antes de desplegarlo en un equipo; trata el plugin como código que estás ejecutando, porque eso es lo que es.
- 6Cuesta contexto además de tokens: un índice inyectado, un proceso worker y Bun y uv en la máquina. Si tus sesiones ya son cortas y autónomas, la ganancia es pequeña: mide en tu propio repositorio en vez de fiarte de una cifra de titular.
Nada de eso lo convierte en una mala instalación. Solo lo convierte en una herramienta para probar primero en un proyecto real —con los repositorios que nunca quieras registrar excluidos por patrón glob y la telemetría desactivada si lo prefieres— antes de convertirlo en el valor por defecto de todo lo que abras.
La telemetría se desactiva con un solo comando:
npx claude-mem telemetry disable