claude-memory-fts

Servidor MCP de memoria a largo plazo para Claude Code. Almacena hechos en una base de datos SQLite local con búsqueda híbrida (FTS5 + similitud vectorial semántica) e inyección automática de contexto.

Características

• Búsqueda híbrida — Búsqueda por palabras clave FTS5 + similitud vectorial semántica, combinadas mediante Reciprocal Rank Fusion (RRF)

• Comprensión semántica — encuentra recuerdos por significado, no solo por palabras clave (impulsado por embeddings all-MiniLM-L6-v2)

• Inyección automática de contexto — los 30 recuerdos más importantes se inyectan en cada prompt mediante un hook

• Clasificación por importancia — hechos clasificados por frecuencia de acceso, decaimiento por recencia y peso de categoría

• Seguimiento de acceso — rastrea con qué frecuencia se accede a cada recuerdo

• Upsert — actualiza automáticamente los hechos existentes en lugar de duplicarlos

• Categorizado — organizado por tipo: preferencia, decisión, técnico, proyecto, flujo de trabajo, personal, general

• Recursos MCP — expone el recurso memory://context para el contexto de la sesión

• Configuración cero — funciona de inmediato, almacena datos en ~/.claude/memory.db

Instalación

# Add to Claude Code
claude mcp add memory -- npx claude-memory-fts

# Auto-configure context injection hook (recommended)
npx claude-memory-fts --setup-hook

El comando --setup-hook realiza automáticamente lo siguiente:

1. Crea ~/.claude/scripts/memory-context.sh

2. Añade un hook UserPromptSubmit a ~/.claude/settings.json

3. Los 30 recuerdos principales se inyectan automáticamente en cada prompt

Comandos CLI

Configuración

Ejemplo con ruta personalizada:

claude mcp add memory -e MEMORY_DB_PATH=/path/to/my/memory.db -- npx claude-memory-fts

Herramientas

memory_save

Guarda un hecho en la memoria a largo plazo.

memory_search

Búsqueda híbrida: ejecuta FTS5 y búsqueda semántica en paralelo, fusiona resultados con RRF. Recurre a LIKE para coincidencias parciales.

memory_update

Actualiza el contenido o la categoría de un recuerdo por ID.

memory_list

Lista todos los recuerdos guardados agrupados por categoría.

memory_delete

Elimina un recuerdo por ID.

Recursos

memory://context

Recurso MCP que expone los 30 hechos principales clasificados por puntuación de importancia:

• Frecuencia de acceso — los hechos accedidos con frecuencia obtienen mayor puntuación (limitado a 20 puntos)

• Recencia — los hechos actualizados recientemente obtienen mayor puntuación (10 puntos, decae a lo largo de 90 días)

• Peso de categoría — preferencia/decisión (3), flujo de trabajo/técnico (2), proyecto/personal (1), general (0)

Cómo funciona

Pipeline de búsqueda

1. FTS5 + BM25 y similitud vectorial semántica se ejecutan en paralelo

2. Los resultados se fusionan y deduplican usando Reciprocal Rank Fusion (k=60)

3. Los hechos que aparecen en ambas listas reciben un impulso natural

4. Si ambos devuelven resultados vacíos, recurre a la coincidencia de subcadenas LIKE

5. El recuento de acceso se rastrea en cada acierto de búsqueda

Embeddings

• Modelo: all-MiniLM-L6-v2 (384 dimensiones, ~23MB)

• Generado localmente mediante @xenova/transformers — sin llamadas a API, ningún dato sale de su máquina

• Los embeddings se crean al guardar y se rellenan al iniciar el servidor

• Similitud de coseno con umbral de 0.3 para filtrar ruido

Almacenamiento

• SQLite con modo WAL para lecturas/escrituras concurrentes rápidas

• Tabla virtual FTS5 sincronizada mediante disparadores para indexación de texto completo en tiempo real

• Embeddings almacenados como columnas BLOB junto a los hechos

Desarrollo

git clone https://github.com/kurovu146/claude-memory-mcp.git
cd claude-memory-mcp
npm install
npm run build
npm test

Licencia

MIT