Todo desarrollador que utiliza agentes de programación con IA lo ha experimentado: pasas una hora explicando la arquitectura de tu proyecto, preferencias y convenciones a Claude Code. La sesión termina. Inicias una nueva. Es un lienzo en blanco. Claude-Mem es el plugin de código abierto que resuelve este problema — y se ha convertido en una de las herramientas más populares en el ecosistema de programación con IA. Lo investigamos en GitHub, Reddit, Twitter/X y el propio código fuente — aquí tienes la guía definitiva.
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
1. Por qué es importante
Claude-Mem es uno de los plugins con más estrellas (most-starred) en el ecosistema de Claude Code, con decenas de miles de estrellas en GitHub, cientos de lanzamientos y miles de forks. Para un plugin que esencialmente añade memoria a un agente de codificación de IA, es una adopción extraordinaria. No es un framework ni una librería — es una aumentación de comportamiento para Claude Code.
Por qué esto es importante
Los agentes de IA son stateless por diseño — cada sesión comienza desde cero. Pero los proyectos de desarrollo reales abarcan semanas y meses. Cada re-explicación cuesta tokens, tiempo e introduce el riesgo de que el agente no entienda algo que ya has aclarado. Claude-Mem cierra esta brecha automáticamente.
El proyecto está construido principalmente con TypeScript, con JavaScript, Shell scripts, y HTML para su visor web. Está bajo la licencia AGPL-3.0, lo que significa que puedes usarlo y modificarlo libremente, pero las obras derivadas desplegadas en una red también deben ser de código abierto.
2. La historia del origen
Claude-Mem fue creado por Alex Newman, conocido en línea como @thedotmack. La trayectoria de Newman abarca AI Product Management, Solutions Architecture y Forward Deployed Engineering — una combinación que explica por qué claude-mem se siente menos como un proyecto personal y más como infraestructura de producción.
El proyecto surgió de una observación sencilla: Claude Code es increíblemente potente, pero trata cada sesión como si fuera la primera vez que te conoce. Newman creó claude-mem para resolver su propio problema — y la comunidad de desarrolladores lo validó masivamente.
La idea clave
Newman se dio cuenta de que el problema no era almacenar memorias — sino comprimirlas y recuperarlas de manera eficiente. Los registros de conversación sin procesar son demasiado extensos y poco enfocados. Claude-Mem utiliza la propia IA para generar resúmenes semánticos de lo ocurrido en cada sesión, y luego recupera solo el contexto relevante para la siguiente.
El proyecto tiene una cuenta oficial de X/Twitter (@Claude_Memory), una comunidad de Discord, e incluso un sitio web oficial en claude-mem.ai con documentación completa.
3. El problema que resuelve
Si has usado Claude Code, Cursor o cualquier agente de programación con IA por más de un día, conoces bien el problema:
Problema 1: Amnesia de contexto
Explicas la arquitectura de tu proyecto, el esquema de la base de datos y las convenciones de código. La sesión termina. Siguiente sesión: “¿Qué tipo de proyecto es este?” Una. Y. Otra. Vez.
Problema 2: Decisiones repetidas
Decides usar un patrón específico (por ejemplo, “usar siempre server actions, nunca API routes”). En la siguiente sesión, el agente genera API routes porque no recuerda tu preferencia.
Problema 3: Pérdida del contexto de los errores
Pasaste 30 minutos depurando una race condition complicada. La solución requería entender tres servicios que interactúan entre sí. En la siguiente sesión, el agente sugiere exactamente el mismo enfoque que ya probaste y rechazaste.
Problema 4: Desperdicio de tokens
Cada reexplicación consume tokens. Si tienes un plan basado en el uso, el coste de restablecer el contexto aumenta rápidamente a lo largo de docenas de sesiones diarias.
Claude-Mem resuelve estos cuatro problemas. Se ejecuta silenciosamente en segundo plano, capturando lo que Claude hace (no solo lo que tú dices), comprimiendo esas observaciones en resúmenes semánticos e inyectando los más relevantes al inicio de cada nueva sesión.
4. Cómo funciona
Claude-Mem opera a través de 6 componentes principales, que trabajan en conjunto para crear una capa de memoria fluida:
| Componente | Qué hace |
|---|---|
| 5 Lifecycle Hooks | SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd — capturan eventos en cada etapa |
| Instalación inteligente | Verificador de dependencias en caché que se ejecuta antes de los hooks (asegura que Bun, uv y las dependencias estén listos) |
| Servicio Worker | API HTTP en el puerto 37777 con interfaz de visor web y 10 endpoints de búsqueda, gestionada por Bun |
| Base de datos SQLite | Almacena sesiones, observaciones y resúmenes localmente con búsqueda de texto completo FTS5 |
| Habilidad mem-search | Consultas en lenguaje natural con divulgación progresiva para consultar el historial del proyecto |
| Chroma Vector DB | Búsqueda híbrida semántica + palabras clave para la recuperación inteligente de contexto |
El flujo del ciclo de vida
Esto es lo que sucede durante una sesión típica:
1. Hook SessionStart
→ El servicio Worker se inicia (si no está en ejecución)
→ Recupera observaciones pasadas relevantes
→ Inyecta contexto comprimido en la sesión
2. Hook UserPromptSubmit
→ Registra lo que el usuario preguntó
3. Hook PostToolUse (se ejecuta después de CADA llamada a una herramienta)
→ Captura el nombre de la herramienta + entrada + salida
→ Comprime la observación con IA
→ Almacena en SQLite + DB de vectores
4. Stop Hook
→ Captura eventos de pausa de la sesión
5. SessionEnd Hook
→ Genera un resumen de la sesión
→ Almacena una instantánea final del contexto
La clave fundamental aquí es PostToolUse. Claude-Mem no solo registra tus mensajes — registra lo que el agente hace: archivos leídos, código escrito, pruebas ejecutadas, errores encontrados. Esto le otorga una comprensión mucho más rica del estado del proyecto que solo los registros de conversación.
5. Divulgación progresiva
Este es el patrón de diseño más innovador de claude-mem. En lugar de volcar toda la memoria en la ventana de contexto (lo que dispararía los costos de tokens), utiliza un sistema de recuperación de 3 capas:
Capa 1: Session Priming (<500 tokens)
→ Resumen ligero del proyecto
→ Decisiones clave de sesiones recientes
→ Inyectado automáticamente en SessionStart
Capa 2: Índice de búsqueda (~50-100 tokens/resultado)
→ IDs de observación compactos + títulos
→ El agente busca cuando necesita más contexto
→ Solo lo suficiente para decidir “¿es esto relevante?”
Capa 3: Detalles completos (~500-1000 tokens/resultado)
→ Contenido completo de la observación
→ Obtenido SOLO para los IDs relevantes
→ El agente solicita explícitamente lo que necesita
Resultado: ~10x de ahorro de tokens frente al enfoque de volcarlo todo
Esta es la arquitectura que hace que claude-mem sea práctico a escala. Sin la revelación progresiva, los sistemas de memoria consumen demasiados tokens (costoso, diluye el enfoque) o recuperan muy poco (pierden contexto crítico). El sistema de 3 capas de claude-mem permite que el agente sea su propio juez de relevancia.
6. Herramientas de búsqueda MCP
Claude-Mem expone 4 herramientas MCP que Claude puede usar para consultar su propia memoria:
| Herramienta | Propósito | Costo de tokens |
|---|---|---|
search | Búsqueda de texto completo con filtros (tipo, fecha, proyecto) | ~50-100/resultado |
timeline | Contexto cronológico sobre observaciones específicas | ~100-200/resultado |
get_observations | Obtener detalles completos por IDs de observación (lote) | ~500-1000/resultado |
Ejemplo: Buscando en tu memoria
search(query="error de autenticación",
type="bugfix", limit=10)
// Step 2: Review index, identify relevant IDs
// e.g., observations #123, #456 look relevant
// Step 3: Fetch full details ONLY for those
get_observations(ids=[123, 456])
Este flujo de trabajo permite que Claude solo pague el costo de tokens por las observaciones que realmente necesita, no por todo lo que hay en la base de datos. La capa de búsqueda actúa como un filtro, y la capa de recuperación proporciona profundidad.
7. Cómo instalar
Claude-Mem ofrece tres métodos de instalación:
Opción A: npx (Recomendado)
La forma más rápida — un solo comando:
npx claude-mem install
# Instalar para Gemini CLI
npx claude-mem install --ide gemini-cli
Opción B: Marketplace de plugins (Dentro de Claude Code)
/plugin marketplace add thedotmack/claude-mem
# Instalar el plugin
/plugin install claude-mem
Opción C: OpenClaw Gateway
⚠️ Nota importante
npm install -g claude-mem instala el SDK/librería solamente — no registra los hooks del plugin ni configura el servicio worker. Usa siempre npx claude-mem install o los /plugin comandos.
Requisitos del sistema
| Requisito | Detalles |
|---|---|
| Node.js | 18.0.0 o superior |
| Claude Code | Última versión con soporte para plugins |
| Bun | Runtime de JavaScript (se instala automáticamente si falta) |
| uv | Gestor de paquetes de Python para búsqueda vectorial (instalado automáticamente) |
| SQLite 3 | Para almacenamiento persistente (incluido) |
Tras la instalación, reinicia Claude Code o Gemini CLI. El contexto de sesiones anteriores aparecerá automáticamente en las nuevas sesiones — sin necesidad de intervención manual.
8. Análisis profundo de las funciones clave
🧠 Memoria persistente
La función principal: el contexto sobrevive entre sesiones. Al iniciar una nueva sesión, Claude ya sabe en qué archivos trabajaste, qué errores corregiste, qué decisiones de arquitectura tomaste y qué patrones prefieres.
🖥️ Interfaz del visor web
Navega a http://localhost:37777 en tu navegador para ver un flujo de memoria en tiempo real. Puedes explorar observaciones, buscar en el historial y monitorear lo que claude-mem está capturando. El visor también ofrece acceso a funciones beta y cambio de versiones.
🔒 Control de privacidad
Envuelve cualquier contenido en <private> etiquetas para excluirlo del almacenamiento. Claves de API, credenciales, información personal — nada dentro de estas etiquetas se persiste. Los datos permanecen totalmente en tu máquina en SQLite.
🔗 Citas
Cada observación recibe un ID único. Puedes referenciar observaciones pasadas con sus IDs y acceder a ellas a través de http://localhost:37777/api/observation/{id}. exactamente por qué Claude tomó una decisión específica.
🧪 Canal Beta: Endless Mode
El “Endless Mode” experimental implementa una arquitectura de memoria biomimética diseñada para sesiones extendidas que duran horas. Utiliza una estrategia de compresión diferente que evita la saturación de la ventana de contexto durante sesiones de programación maratónicas. Cambia entre stable y beta desde la interfaz de usuario del visor web.
⚙️ Configuración de Contexto
Los ajustes se gestionan en ~/.claude-mem/settings.json. Puedes configurar el modelo de IA utilizado para la compresión, el puerto del worker, el directorio de datos, el nivel de log y tener un control detallado sobre qué contexto se inyecta y cuándo.
9. Descripción General de la Arquitectura
La arquitectura de Claude-Mem's ha evolucionado significativamente a través de múltiples versiones principales. Así es como encajan las piezas:
┌─────────────────────────────────────┐
│ Sesión de Claude Code │
│ │
│ SessionStart → PostToolUse → End │
└────────────────┬────────────────────┘
│ Hooks
▼
┌─────────────────────────────────────┐
│ Servicio Worker (Bun, puerto 37777) │
│ │
│ ┌──────────┐ ┌──────────────────┐ │
│ │ Web UI │ │ 10 Endpoints API │ │
│ └──────────┘ └──────────────────┘ │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Capa de Almacenamiento │
│ │
│ ┌──────────────┐ ┌──────────────┐│
│ │ SQLite + FTS5 │ │ Chroma VecDB ││
│ │ (estructurado)│ │ (semántico) ││
│ └──────────────┘ └──────────────┘│
└─────────────────────────────────────┘
La estrategia de base de datos dual
Claude-Mem utiliza dos bases de datos en conjunto:
- SQLite con FTS5 — Para consultas estructuradas, búsquedas de coincidencia exacta y filtrado por tiempo. Rápido, local, zero-config.
- Base de datos vectorial Chroma — Para búsqueda por similitud semántica. Cuando Claude pregunta “¿qué hicimos con el sistema de auth?”, Chroma encuentra observaciones conceptualmente relacionadas incluso si las palabras exactas no coinciden.
Juntos proporcionan búsqueda híbrida: coincidencias exactas de SQLite y coincidencias difusas/semánticas de Chroma. Este es el mismo patrón de arquitectura de búsqueda utilizado por los sistemas RAG de producción, miniaturizado para uso local.
10. Reacciones de la comunidad
Investigamos discusiones en Reddit (r/ClaudeAI, r/ClaudeCode), Twitter/X y artículos técnicos. Este es el consenso de la comunidad:
El fin de la “página en blanco”
El sentimiento abrumador en Reddit: claude-mem es la mejor solución al problema de la “página en blanco”. Los usuarios reportan que reduce significativamente la fricción de volver a explicar las arquitecturas de los proyectos, ahorrando tiempo, tokens y frustración. Múltiples hilos en r/ClaudeCode lo describen como un plugin “imprescindible”.
El debate sobre la economía de tokens
Algunos usuarios se preocuparon inicialmente por los costos de los tokens — un sistema de memoria activa que comprime observaciones mediante llamadas de IA podría consumir tokens por sí mismo. El consenso de la comunidad: la arquitectura de divulgación progresiva hace que el balance sea positivo. Los tokens ahorrados al no tener que volver a explicar el contexto superan con creces los tokens gastados en la compresión de memoria.
La división entre “Heavy vs. Lite”
Debido a que claude-mem es un sistema completo (que requiere Bun, Python para la búsqueda vectorial y un servicio de worker en segundo plano), algunos desarrolladores han creado alternativas más ligeras como claude-mem-lite y memsearch. Estos utilizan un almacenamiento basado en texto más simple y minimizan las llamadas a LLM. La comunidad los ve como complementarios: claude-mem para proyectos serios de varias semanas, y herramientas más ligeras para experimentos rápidos.
La capa de integración del flujo de trabajo
Los usuarios avanzados en Reddit describen a claude-mem como una capa fundamental para flujos de trabajo personalizados. Construyen “habilidades” especializadas sobre ella — combinando memoria persistente con reglas personalizadas y conocimiento específico del dominio para crear agentes de IA que comprenden profundamente sus proyectos específicos.
Veredicto de la comunidad
Claude-Mem es ampliamente considerada la mejor solución en su clase para la memoria persistente de agentes de IA. La principal crítica es que es “pesada” — un sistema complejo con múltiples dependencias. El contraargumento: la memoria es un problema difícil, y las soluciones simples producen resultados simples.
11. El veredicto: ¿Vale la pena usar Claude-Mem?
Nuestra opinión
Sí, si usas Claude Code para proyectos de varias sesiones. Claude-Mem es la mejor solución de memoria persistente en su clase para agentes de codificación de IA. La arquitectura de divulgación progresiva la hace eficiente en el uso de tokens, la búsqueda dual SQLite + Chroma ofrece recuperación tanto exacta como semántica, y el funcionamiento totalmente automático significa cero sobrecarga manual.
Úsalo si:
- Trabajas en proyectos que abarcan múltiples sesiones (días, semanas, meses)
- Estás cansado de volver a explicar la arquitectura de tu proyecto en cada sesión
- Quieres que Claude recuerde decisiones pasadas, correcciones de errores y enfoques rechazados
- Te sientes cómodo con la huella de dependencias (Node.js, Bun, Python para búsqueda vectorial)
Omítelo si:
- Solo usas Claude Code para tareas rápidas y puntuales
- Prefieres herramientas mínimas y no quieres servicios en segundo plano
- Usas Cursor o Windsurf (claude-mem solo funciona con Claude Code, Gemini CLI y OpenClaw)
- Un archivo
CLAUDE.mdbien mantenido es suficiente para tu flujo de trabajo
12. Alternativas & comparación
¿Cómo se compara claude-mem con otros enfoques para dar memoria a los agentes de IA?
| Enfoque | Pros | Contras |
|---|---|---|
| CLAUDE.md (Manual) | Simple, sin dependencias, totalmente controlado | Mantenimiento manual, sin captura automática, estático |
| Claude-Mem | Automático, búsqueda semántica, revelación progresiva, enriquecido | Configuración compleja, requiere Bun + Python, servicio en segundo plano |
| claude-mem-lite | Ligero, basado en texto, menos dependencias | Sin búsqueda semántica, compresión más simple |
| Scripts personalizados | Totalmente personalizable, sin dependencias externas | DIY para todo, sin soporte del ecosistema |
| Memoria de Claude integrada | Configuración cero, integración nativa | Alcance limitado, sin persistencia específica del proyecto |
Para la mayoría de los desarrolladores que trabajan en proyectos serios de varias sesiones, claude-mem ofrece el conjunto de características más completo. Para experimentos rápidos o desarrolladores que prefieren herramientas mínimas, un archivo CLAUDE.md bien mantenido combinado con un archivo de habilidades (como las habilidades de Karpathy's) puede ser suficiente.
13. El panorama general
De agentes Stateless a Stateful
Claude-Mem representa un cambio en la forma en que pensamos sobre los agentes de programación con IA. La primera generación de asistentes de IA era stateless — cada interacción comenzaba de cero. La generación actual, con herramientas como claude-mem, se está volviendo stateful — agentes que acumulan conocimiento sobre tu proyecto con el tiempo.
Esto tiene implicaciones profundas. Un agente con estado no solo escribe código — sino que entiende tu base de código. Sabe qué patrones funcionaron, cuáles fueron rechazados y por qué. Recuerda que el sistema de autenticación usa un formato de token específico debido a una restricción de migración pasada. Recuerda que la consulta a la base de datos necesita un índice específico porque depuraste un problema de rendimiento hace dos semanas.
El ecosistema de ingeniería de contexto
Claude-Mem es parte de un “ingeniería de contexto” ecosistema que está madurando rápidamente:
- CLAUDE.md / Archivos de reglas — Contexto estático (convenciones del proyecto, estándares de codificación)
- Skills/Plugins — Guías de comportamiento (como el archivo de skills de Karpathy)
- Plugins de memoria — Contexto dinámico (claude-mem, historial de sesión)
- Servidores MCP — Conocimiento externo (bases de datos, APIs, documentación)
Juntas, estas capas crean agentes que están profundamente personalizados para proyectos y desarrolladores específicos. La era del “vibe coding” de interacción con IA laxa y no estructurada está evolucionando hacia la “ingeniería agéntica” — una práctica disciplinada donde la gestión del contexto es tan importante como los propios prompts.
¿Qué sigue?
Con la v12, claude-mem ya soporta Claude Code, Gemini CLI y gateways de OpenClaw. La trayectoria apunta hacia una memoria universal de agentes — una capa de conocimiento persistente que funciona en cualquier herramienta de programación con IA, editor o plataforma. El token $CMEM (un token de Solana impulsado por la comunidad que el creador ha adoptado oficialmente) sugiere planes aún más ambiciosos para el intercambio de datos de agentes en tiempo real y la colaboración entre desarrolladores.
14. Preguntas frecuentes
P: ¿Funciona claude-mem con Gemini CLI o solo con Claude Code?
Claude-Mem es compatible tanto con Claude Code como con Gemini CLI. Instálalo para Gemini CLI con 'npx claude-mem install --ide gemini-cli'. También funciona con gateways de OpenClaw.
P: ¿Envía claude-mem mi código o mis datos a la nube?
No. Todos los datos se almacenan localmente en una base de datos SQLite en ~/.claude-mem/claude-mem.db. Nada sale de tu máquina. La API HTTP en el puerto 37777 también se ejecuta localmente sin necesidad de autenticación.
P: ¿Consume claude-mem tokens adicionales?
Utiliza tokens para comprimir observaciones, pero la arquitectura de divulgación progresiva supone un ahorro neto. Los tokens ahorrados al no tener que volver a explicar el contexto entre sesiones superan con creces el coste de la compresión.
P: ¿Por qué no arranca el worker o por qué está en uso el puerto 37777?
Revisa qué está usando el puerto con 'lsof -i :37777' y finalízalo con 'kill -9 $(lsof -t -i:37777)'. También puedes cambiar el puerto en ~/.claude-mem/settings.json.
P: ¿Cuál es la diferencia entre claude-mem y CLAUDE.md?
CLAUDE.md es un archivo estático que mantienes manualmente con las convenciones del proyecto. Claude-Mem es automático: captura, comprime y recupera el contexto dinámicamente. Se complementan entre sí: usa CLAUDE.md para las reglas y claude-mem para la memoria.
P: ¿Puedo usar claude-mem con Cursor o Windsurf?
No. Claude-Mem está diseñado específicamente para el sistema de plugins/hooks de Claude Code. También es compatible con Gemini CLI y gateways de OpenClaw, pero no con Cursor, Windsurf u otros IDE.
P: ¿Qué es el Endless Mode en claude-mem?
Endless Mode es una función beta que implementa una arquitectura de memoria biomimética para sesiones de programación maratónicas que duran horas. Utiliza una estrategia de compresión diferente para evitar la saturación de la ventana de contexto. Actívalo desde la interfaz de usuario del Web Viewer.
15. Todas las fuentes & enlaces
Este artículo fue investigado utilizando una investigación de múltiples fuentes a través de GitHub, Reddit, Twitter/X, artículos web y el propio código fuente. Aquí están todas las fuentes primarias:
Fuentes primarias
- GitHub: thedotmack/claude-mem — El repositorio
- claude-mem.ai — Sitio web oficial & documentación
- Descripción general de la arquitectura — Componentes del sistema & flujo de datos
- Documentación de divulgación progresiva — Filosofía de context priming
- Guía de ingeniería de contexto — Principios de optimización de agentes de IA
Comunidad y redes sociales
- @Claude_Memory — Cuenta oficial de X/Twitter
- Comunidad de Discord — Servidor oficial de Discord
- Reddit r/ClaudeAI — Discusiones de la comunidad sobre soluciones de memoria de IA
- Reddit r/ClaudeCode — Hilos técnicos sobre arquitectura de plugins y gestión de tokens
Referencias técnicas
- Evolución de la arquitectura — El trayecto de la v3 a la v5+
- Arquitectura de Hooks — Cómo claude-mem utiliza lifecycle hooks
- Arquitectura de búsqueda — Búsqueda híbrida con Chroma
- Guía de herramientas de búsqueda — Ejemplos de uso de herramientas MCP
Autor
- Alex Newman (@thedotmack) — Creador de claude-mem
Artículos relacionados en este sitio
- El archivo de habilidades CLAUDE.md de Karpathy: La guía completa
- La Wiki de LLM de Karpathy: La guía completa de su archivo de ideas
- Cómo configurar habilidades en tu IDE de IA
- La guía completa de prompts de sistema para agentes de IA
- Dominando las habilidades de los agentes
Get the Ultimate Antigravity Cheat Sheet
Join 5,000+ developers and get our exclusive PDF guide to mastering Gemini 3 shortcuts and agent workflows.