claude-memory

Memoria + seguimiento de proyectos para Claude Code. Un servidor MCP.

• Búsqueda semántica sobre todas las transcripciones pasadas de Claude Code — las nuevas sesiones recuerdan las antiguas, mucho más allá de la ventana de contexto

• Notas duraderas (remember) — por proyecto o globales

• Seguimiento estructurado: proyectos → hitos → épicas → tickets → tareas, representado como hoja de ruta

• Elementos de seguimiento incrustados en el mismo espacio vectorial — los tickets aparecen en la búsqueda semántica

• Prompts de sistema por proyecto, almacenados en la base de datos, inyectables al inicio de la sesión

Stack: Voyage AI embeddings + Qdrant base de datos vectorial + SQLite + FastMCP. Todo gratis: el nivel gratuito de Voyage cubre fácilmente el uso personal, el nivel gratuito de Qdrant Cloud almacena 1M de vectores (o ejecuta docker local). $0 de operación.

Configuración

Dos claves:

• Voyage → https://dashboard.voyageai.com

• Qdrant → clúster gratuito en https://cloud.qdrant.io, o docker run -p 6333:6333 qdrant/qdrant

git clone https://github.com/mathis-sperlich/claude-memory
cd claude-memory
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env
# fill VOYAGE_API_KEY, QDRANT_URL, QDRANT_API_KEY

Apunta SCAN_PROJECTS en ingest.py a tus directorios de transcripciones (Claude Code los escribe en ~/.claude/projects/<encoded-project-dir>/*.jsonl).

Ingesta

.venv/bin/python ingest.py --dry-run   # sanity-check chunking
.venv/bin/python ingest.py             # embed + upsert

Idempotente — las re-ejecuciones solo incrustan fragmentos nuevos. Seguro como trabajo cron. Plantilla launchd por hora: launchd/com.mathis.claude-memory.plist (edita las rutas, cp a ~/Library/LaunchAgents/, launchctl load).

Prueba la recuperación desde la CLI:

.venv/bin/python query.py "how did the auth token refresh bug get fixed?"

¿Malos resultados? Baja MAX_CHUNK_CHARS en ingest.py, o prueba un EMBED_MODEL más grande en .env y vuelve a ingestar con --reset.

Conectar con Claude Code

~/.claude/settings.json:

{
  "mcpServers": {
    "claude-memory": {
      "command": "/path/to/claude-memory/.venv/bin/python",
      "args": ["/path/to/claude-memory/mcp_server.py"]
    }
  }
}

Reinicia Claude Code. Listo — Claude ahora tiene query_history, remember, herramientas de seguimiento y herramientas de prompt de sistema.

Herramientas

Memoria

Seguimiento

Jerarquía: proyecto → hito (opcional) → épica → ticket → tarea.

status: open / in_progress / done. priority: P0–P3.

Prompts de sistema

set_system_prompt(content, project=) / get_system_prompt(project=) / list_system_prompts() / delete_system_prompt(project=). Capas globales + por proyecto, compuestas al leer. Se almacenan en tracking.db. Usa docs/usage.md como respaldo cuando no está definido.

Hooks (opcionales, deterministas)

Las herramientas MCP se disparan cuando el modelo decide. Los hooks se disparan siempre. hooks/session_start.py inyecta los tickets abiertos del proyecto actual + el prompt de sistema en cada inicio de sesión:

{
  "hooks": {
    "SessionStart": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "/path/to/claude-memory/.venv/bin/python /path/to/claude-memory/hooks/session_start.py"
      }]
    }]
  }
}

Acceso remoto (opcional)

Por defecto = stdio local, cero red. ¿Quieres la misma memoria desde claude.ai u otras máquinas? Transporte HTTP + túnel Cloudflare + OAuth de GitHub con lista de permitidos para iniciar sesión:

.venv/bin/python mcp_server.py --transport http --port 8765

Guía completa, incl. servicios launchd + watchdog auto-reparable: CLOUD_SETUP.md.

Notas

• Privacidad: Voyage ve el texto al incrustar (sin entrenamiento con datos de clientes según los TOS), Qdrant Cloud almacena vectores + payloads. Si ambos te preocupan → Qdrant local + embedder local, mismo código.

• Las solicitudes de incrustación estancadas están limitadas por las variables de entorno VOYAGE_TIMEOUT / VOYAGE_MAX_RETRIES (por defecto 20s / 2).