claude-memory-fts

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 semántica de vectores) e inyección automática de contexto.

Características

• Búsqueda híbrida — búsqueda por palabras clave FTS5 + similitud semántica de vectores, combinadas mediante Fusión de Rango Recíproco (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 hook
• Clasificación por importancia — los hechos se clasifican por frecuencia de acceso, decaimiento por antigüedad y peso de categoría
• Seguimiento de accesos — registra la frecuencia con la que se accede a cada recuerdo
• Upsert — actualiza automáticamente hechos existentes en lugar de duplicarlos
• Categorizado — organiza por tipo: preferencia, decisión, técnico, proyecto, flujo de trabajo, personal, general
• Recursos MCP — expone el recurso memory://context para el contexto de 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 automáticamente:

1. Crea ~/.claude/scripts/memory-context.sh
2. Añade un hook de UserPromptSubmit a ~/.claude/settings.json
3. Los 30 recuerdos principales se inyectan en cada prompt automáticamente

Comandos CLI

Comando	Descripción
npx claude-memory-fts	Inicia el servidor MCP (usado por Claude Code)
npx claude-memory-fts --context	Muestra los 30 hechos principales (usado por el script del hook)
npx claude-memory-fts --setup-hook	Configura automáticamente el hook de inyección de contexto

Configuración

Variable de entorno	Valor predeterminado	Descripción
MEMORY_DB_PATH	~/.claude/memory.db	Ruta al archivo de base de datos SQLite

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.

Parámetro	Tipo	Obligatorio	Descripción
fact	string	sí	La información a recordar
category	string	no	Uno de: preference, decision, personal, technical, project, workflow, general

memory_search

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

Parámetro	Tipo	Obligatorio	Descripción
keyword	string	sí	Palabra clave o frase de búsqueda
limit	number	no	Máximo de resultados (predeterminado: 10)

memory_update

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

Parámetro	Tipo	Obligatorio	Descripción
id	number	sí	ID del recuerdo
fact	string	no	Nuevo contenido (omitir para mantener el actual)
category	string	no	Nueva categoría (omitir para mantener la actual)

memory_list

Lista todos los recuerdos guardados agrupados por categoría.

Parámetro	Tipo	Obligatorio	Descripción
category	string	no	Filtrar por categoría
limit	number	no	Máximo de resultados (predeterminado: 50)

memory_delete

Elimina un recuerdo por ID.

Parámetro	Tipo	Obligatorio	Descripción
id	number	sí	ID del recuerdo

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 puntúan más alto (máximo 20 puntos)
• Actualidad — los hechos actualizados recientemente puntúan más alto (10 puntos, decae en 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 semántica de vectores se ejecutan en paralelo
2. Los resultados se combinan y deduplican mediante Fusión de Rango Recíproco (k=60)
3. Los hechos que aparecen en ambas listas reciben un impulso natural
4. Si ambas devuelven vacío, se recurre a coincidencia de subcadenas con LIKE
5. El contador de accesos se registra en cada resultado de búsqueda

Embeddings

• Modelo: all-MiniLM-L6-v2 (384 dimensiones, ~23MB)
• Generados localmente mediante @xenova/transformers — sin llamadas a API, sin que los datos salgan de tu máquina
• Los embeddings se crean al guardar y se rellenan al iniciar el servidor
• Similitud 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 triggers 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