memem

Memoria persistente y autoevolutiva para Claude Code. Deja de explicar tu proyecto en cada sesión.

Para el descubrimiento de herramientas LLM/IA, consulta llms.txt.

  ███╗   ███╗███████╗███╗   ███╗███████╗███╗   ███╗
  ████╗ ████║██╔════╝████╗ ████║██╔════╝████╗ ████║
  ██╔████╔██║█████╗  ██╔████╔██║█████╗  ██╔████╔██║
  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║██╔══╝  ██║╚██╔╝██║
  ██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║███████╗██║ ╚═╝ ██║
  ╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝╚══════╝╚═╝     ╚═╝
  persistent memory for Claude Code

¿Qué es memem?

memem es un plugin de Claude Code que le proporciona a Claude memoria persistente entre sesiones. Un minero en segundo plano extrae lecciones duraderas (decisiones, convenciones, correcciones de errores, preferencias) de tus sesiones completadas, las almacena como markdown en un vault de Obsidian y muestra automáticamente las relevantes al inicio de cada nueva sesión mediante un resumen adaptado a la consulta.

Es local-first: sin servicios en la nube, sin necesidad de claves API, sin dependencia de proveedores. Todo reside en ~/obsidian-brain/memem/memories/ como markdown legible por humanos.

¿Cuándo debería usar memem?

Usa memem si:

• Usas Claude Code a diario y tienes que volver a explicar tu proyecto en cada sesión nueva

• Quieres una memoria duradera que puedas explorar y editar como markdown

• Te gustan las herramientas local-first sin dependencia de proveedores

• Ya usas Obsidian (memem se integra directamente en tu vault)

No uses memem si:

• CLAUDE.md te funciona bien y no quieres un demonio en segundo plano

• Necesitas memoria sincronizada en la nube entre máquinas (memem es solo local)

• Estás en una versión de Python < 3.11

¿En qué se diferencia memem de CLAUDE.md?

CLAUDE.md es un único archivo editado manualmente por proyecto. memem te ofrece:

• Extracción automática — sin toma de notas manual, el minero captura lecciones de cada sesión completada

• Contexto consciente de la consulta — solo se inyectan los recuerdos relevantes para tu pregunta actual, no un volcado estático

• Autoevolutivo — los recuerdos se fusionan, actualizan y deprecian automáticamente a medida que tu proyecto evoluciona

• Multi-proyecto — funciona en todos los proyectos de Claude Code que utilices, no limitado a un solo repositorio

• Escaneo de seguridad — cada escritura se escanea en busca de inyección de prompts y exfiltración de credenciales

• Explorable — vault de Obsidian con vista de grafo y enlaces retroactivos gratuitos

¿Cómo instalo memem?

/plugin marketplace add TT-Wang/memem
/plugin install memem

Eso es todo. En la primera ejecución, bootstrap.sh repara todo automáticamente:

1. Verifica Python ≥ 3.11

2. Instala uv si falta (a través del instalador oficial de Astral)

3. Sincroniza las dependencias en un .venv local del plugin (con hash verificado contra uv.lock)

4. Crea y prueba ~/.memem/ y ~/obsidian-brain/

5. Escribe ~/.memem/.capabilities (usado para decisiones en modo degradado)

6. Ejecuta el servidor MCP real

Primera ejecución: ~5 segundos. Ejecuciones posteriores: ~100ms. Sin pasos de pip install por separado.

¿Qué sucede en mi primera sesión de Claude Code?

Escribes tu primer mensaje. El hook UserPromptSubmit se activa y ve que no hay recuerdos (acabas de instalarlo), por lo que inyecta un banner de bienvenida en el contexto de Claude. Claude lee el banner, te dice que memem está activo y, si tienes sesiones previas de Claude Code, te ofrece minarlas mediante /memem-mine-history.

Trabajas normalmente. El demonio minero se ejecuta silenciosamente en segundo plano. Cuando tu sesión termina y permanece inactiva durante 5 minutos, el minero extrae recuerdos de la transcripción usando Claude Haiku y los escribe en tu vault.

A partir de la segunda sesión: el hook envía tu primer mensaje a context_assemble, que proporciona a Haiku los recuerdos relevantes y le pide que sintetice un resumen adaptado. Verás un banner de estado como [memem] 12 memories · miner OK · assembly OK seguido del resumen. Claude comienza con el contexto completo, sin necesidad de volver a explicar.

¿Qué guarda memem?

Guarda conocimiento duradero, no registros de sesión:

• Decisiones de arquitectura con justificación ("usamos RS256 JWTs porque...")

• Convenciones ("las pruebas van en tests/ no en spec/")

• Correcciones de errores que podrías olvidar ("bcrypt.compare es asíncrono — debe usar await")

• Preferencias de usuario ("prefiero commits individuales, no PRs apiladas")

• Problemas conocidos ("JWT_SECRET por defecto es 'secret' si no se establece — rastreado en #123")

NO guarda:

• Transcripciones de sesión sin procesar (son buscables mediante transcript_search, no almacenadas como recuerdos)

• Hechos triviales u obvios

• Resultados de la sesión ("hoy trabajé en X")

¿Dónde almacena memem mis recuerdos?

Puedes apuntar memem a otro lugar mediante las variables de entorno MEMEM_DIR y MEMEM_OBSIDIAN_VAULT.

¿Qué herramientas MCP puede llamar Claude?

¿Qué comandos de barra diagonal añade memem?

• /memem — bienvenida, estado, ayuda

• /memem-status — conteo de recuerdos, proyectos, tamaño de la base de datos de búsqueda, salud del minero

• /memem-doctor — verificación de salud previa con instrucciones de reparación para cualquier bloqueador

• /memem-mine — inicia el demonio minero manualmente (normalmente se inicia solo)

• /memem-mine-history — opt-in: mina todas tus sesiones de Claude Code previas a la instalación

¿Qué pasa si la CLI claude no está en mi PATH?

memem entra en modo degradado — sigue funcionando, solo que sin el ensamblaje de contexto potenciado por Haiku y la recuperación inteligente. Obtienes recuperación por palabras clave solo mediante FTS en lugar de resúmenes adaptados a la consulta. Cada sesión muestra [memem] N memories · miner OK · assembly degraded (claude CLI missing — FTS-only recall) en la parte superior del contexto, para que sepas por qué.

Esto es intencional: las dependencias opcionales faltantes deberían degradar el servicio, no fallar.

¿Cómo diagnostico problemas?

Ejecuta /memem-doctor. Ejecuta la misma verificación previa que el shim de bootstrap (versión de Python, mcp importable, CLI claude en PATH, capacidad de escritura en directorios, uv disponible), luego imprime un informe etiquetado como HEALTHY, DEGRADED o FAILING con instrucciones de reparación explícitas para cada bloqueador.

Para una depuración más profunda:

tail -f ~/.memem/bootstrap.log   # first-run shim log
tail -f ~/.memem/miner.log       # miner daemon log
cat ~/.memem/events.jsonl        # memory operation audit trail
python3 -m memem.server --status   # detailed status dump

¿Cómo funciona la tubería de minería?

Session ends → miner daemon sees the JSONL file in ~/.claude/projects/
  → Waits 5 minutes for the file to "settle" (no more writes)
  → Filters to human messages + assistant prose (strips tool calls, system reminders)
  → One Haiku call with the full context: "extract durable lessons"
  → Haiku returns JSON array of memory candidates
  → Each candidate runs: security scan → dedup check → contradiction detection → save
  → Index rebuilt, per-project playbooks grown and refined
  → Session marked COMPLETE in ~/.memem/.mined_sessions

¿Cómo funciona la tubería de recuperación?

First message in a new session → auto-recall.sh hook fires
  → Reads ~/.memem/.capabilities for status banner
  → If claude CLI is available → sends (message, memories) to Haiku
      → Haiku synthesizes a focused briefing (300-800 tokens usually)
      → Brief injected into Claude's context as "memem context briefing"
  → If claude CLI is missing → falls back to FTS-only keyword recall
  → Either way, Claude starts its reply with relevant context already loaded

Arquitectura

memem está dividido en módulos pequeños y enfocados:

• models.py — tipos de datos, constantes de ruta

• security.py — escaneo de inyección de prompts + exfiltración de credenciales

• telemetry.py — seguimiento de acceso, registro de eventos (escrituras atómicas, bloqueado por fcntl)

• search_index.py — índice SQLite FTS5

• obsidian_store.py — E/S de recuerdos, puntuación de deduplicación, detección de contradicciones

• playbook.py — crecimiento + refinamiento de playbooks por proyecto

• assembly.py — ensamblaje de contexto mediante Haiku

• capabilities.py — detección de características en tiempo de ejecución para modo degradado

• storage.py — ayudantes de ciclo de vida del servidor (gestión de PID, inicio automático del minero)

• server.py — punto de entrada MCP ligero (FastMCP importado de forma perezosa)

• cli.py — despachador de comandos para puntos de entrada no MCP

• mining.py — tubería de minería de sesiones

Puntuación de recuperación de señales múltiples:

• 50% relevancia FTS

• 15% recencia (decaimiento 0.995^horas)

• 15% historial de acceso (refuerzo de uso)

• 20% importancia (escala 1-5 de Haiku)

Esquema de memoria (frontmatter de markdown):

---
id: uuid
schema_version: 1
title: "descriptive title"
project: project-name
tags: [mined, project-name]
related: [id1, id2, id3]
created: 2026-04-13
updated: 2026-04-13
source_type: mined | user | import
source_session: abc12345
importance: 1-5
status: active | deprecated
valid_to:                     # set when deprecated
contradicts: [id1]            # flagged conflicts
---

Configuración

Configurar Obsidian (opcional, recomendado)

memem funciona sin Obsidian — simplemente escribe markdown. Pero Obsidian te da vista de grafo y enlaces retroactivos gratis:

1. Descarga: https://obsidian.md (gratis)

2. Abre ~/obsidian-brain como un vault

3. Los recuerdos aparecen en memem/memories/, los playbooks en memem/playbooks/

4. Usa la Vista de Grafo para ver cómo se vinculan los recuerdos mediante el campo related

Requisitos

• Claude Code

• Python ≥ 3.11

• uv (instalado automáticamente por bootstrap.sh en la primera ejecución)

• CLI claude en PATH (opcional — requerido para el ensamblaje potenciado por Haiku; el modo degradado funciona sin él)

Desarrollo

git clone https://github.com/TT-Wang/memem.git
cd memem
pip install -e ".[dev]"
pytest             # 54 tests
ruff check .       # lint
mypy memem # type check (strict)

Consulta CONTRIBUTING.md para el proceso de PR y CHANGELOG.md para el historial de versiones.

Licencia

MIT