Documentación completa -- guías, referencia de herramientas, arquitectura y mantenimiento en cachorro.space

mcp-memory

Un reemplazo directo para el servidor de memoria MCP de Anthropic -- con persistencia en SQLite, incrustaciones vectoriales, búsqueda semántica y Puntuación Límbica para una clasificación dinámica.

¿Por qué? El servidor original escribe todo el grafo de conocimiento en un archivo JSONL en cada operación, sin bloqueos ni escrituras atómicas. Bajo acceso concurrente (múltiples clientes MCP), esto causa corrupción de datos. Este servidor reemplaza eso con una base de datos SQLite adecuada.

Características

• Compatible directamente con las 8 herramientas MCP de Anthropic (misma API, mismo comportamiento)

• SQLite + WAL -- acceso concurrente seguro, no más JSONL corruptos

• Búsqueda semántica mediante sqlite-vec + incrustaciones ONNX (más de 94 idiomas)

• Búsqueda híbrida (FTS5 + KNN) -- combina búsqueda de texto completo BM25 y búsqueda vectorial semántica mediante Reciprocal Rank Fusion. Encuentra entidades por términos exactos o similitud semántica, o ambos a la vez.

• Puntuación Límbica -- re-clasificación dinámica con saliencia, decaimiento temporal, señales de co-ocurrencia y puntuaciones de búsqueda híbrida. Transparente para la API.

• Deduplicación semántica -- similarity_flag automático en nuevas observaciones cuando la similitud de coseno >= 0.85 (con puntuación de contención para longitudes de texto asimétricas)

• Informes de consolidación -- comprobaciones de estado de solo lectura para candidatos a división, observaciones marcadas, entidades obsoletas y entidades grandes

• Decaimiento de recencia mejorado -- seguimiento de entity_access_log con señal de consolidación multidía ALPHA_CONS=0.2

• Corrección de contención -- manejo adecuado de longitudes de texto asimétricas (proporción >= 2.0) en la puntuación de deduplicación

• Tipos de observación -- clasificación semántica de observaciones (hallazgo, decision, estado, spec, metrica, metadata, generic)

• Supersedición de observaciones -- cadena de reemplazo explícita: las nuevas observaciones pueden reemplazar a las antiguas, las cuales se marcan con fecha como reemplazadas

• Estado de la entidad -- seguimiento del ciclo de vida: activo, pausado, completado, archivado (con des-priorización de búsqueda consciente del estado)

• Contexto de relación + vigencia -- las relaciones llevan contexto opcional, campos active/ended_at para validez temporal

• Relaciones inversas automáticas -- pares contains/parte_de creados automáticamente

• Reflexiones -- capa narrativa independiente: prosa de forma libre adjunta a entidades/sesiones/relaciones/global, con metadatos de autor y estado de ánimo, buscable mediante búsqueda híbrida semántica + FTS5

• Ligero -- ~500 MB en total frente a ~1.4 GB de soluciones similares

• Migración -- importación con un clic desde el formato JSONL de Anthropic

• Configuración cero -- funciona desde el primer momento, descarga opcional del modelo para búsqueda semántica

Inicio rápido

1. Añadir a tu configuración de MCP

{
  "mcpServers": {
    "memory": {
      "command": ["uvx", "--from", "git+https://github.com/Yarlan1503/mcp-memory", "mcp-memory"]
    }
  }
}

O clona y ejecuta localmente:

{
  "mcpServers": {
    "memory": {
      "command": ["uv", "run", "--directory", "/path/to/mcp-memory", "mcp-memory"]
    }
  }
}

2. Habilitar búsqueda semántica (opcional)

cd /path/to/mcp-memory
uv run python scripts/download_model.py

Esto descarga un modelo de oraciones multilingüe (~465 MB) en ~/.cache/mcp-memory-v2/models/. Sin él, todas las herramientas funcionan bien; solo search_semantic no estará disponible.

3. Migrar datos existentes (opcional)

Si tienes un archivo JSONL de memoria MCP de Anthropic, usa la herramienta migrate o llámala directamente:

uv run python -c "
from mcp_memory.storage import MemoryStore
from mcp_memory.migrate import migrate_jsonl
store = MemoryStore()
store.init_db()
result = migrate_jsonl(store, '~/.config/opencode/mcp-memory.jsonl')
print(result)
"

Herramientas MCP

Núcleo (compatible con Anthropic)

Búsqueda y Análisis

Gestión de Entidades

Reflexiones

Tipos de Entidad

8 tipos canónicos:

Tipos de Observación

Clasificación semántica para observaciones:

Tipos de Relación

4 categorías:

Las relaciones inversas se crean automáticamente para los pares contiene/parte_de.

Arquitectura

server.py (FastMCP)  <--  storage.py (SQLite + sqlite-vec + FTS5)
                               |
                         embeddings.py (ONNX Runtime)
                               |
                         sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
                         (384d, multilingual, cosine similarity)
                               |
                         scoring.py (Limbic Scoring + RRF)
                         salience . temporal decay . co-occurrence

• Almacenamiento: SQLite con registro WAL, tiempo de espera de ocupado de 5 segundos, eliminaciones CASCADE

• Incrustaciones: Modelo ONNX singleton cargado una vez al inicio, búsqueda de coseno normalizada L2

• Puntuación Límbica: Re-clasifica candidatos híbridos (KNN + FTS5) usando señales de importancia, decaimiento temporal, patrones de co-ocurrencia y puntuaciones RRF; transparente para la API

• Concurrencia: SQLite maneja el bloqueo internamente; sin fcntl, sin guerras de fs

• Reflexiones: Índices paralelos FTS5 (reflection_fts) y vectoriales (reflection_embeddings) para la capa narrativa, buscados a través del mismo pipeline híbrido RRF

Cómo funciona

Cada entidad obtiene un vector de incrustación generado a partir de su texto usando una estrategia de selección Head+Tail+Diversity (presupuesto: 480 tokens):

"{name} ({entity_type}) | {obs1} | {obs2} | ... | Rel: type -> target; ..."

Cuando llamas a search_semantic, el pipeline se ejecuta en paralelo:

1. Semántico (KNN) -- la consulta se codifica y se compara con los vectores de entidad mediante sqlite-vec

2. Texto completo (FTS5) -- la consulta se busca en un índice BM25 que cubre nombres, tipos y contenido de observación

3. Fusión (RRF) -- los resultados de ambas ramas se combinan usando Reciprocal Rank Fusion (score(d) = Sum 1/(k + rank))

Los candidatos fusionados son luego re-clasificados por el motor de Puntuación Límbica, que considera:

• Saliencia -- las entidades accedidas frecuentemente y bien conectadas se clasifican más alto

• Decaimiento temporal -- las entidades usadas recientemente se mantienen frescas; las entidades no tocadas se desvanecen

• Co-ocurrencia -- las entidades que aparecen juntas a menudo se refuerzan entre sí

La salida incluye limbic_score, scoring (desglose de importancia/temporal/cooc) y opcionalmente rrf_score cuando FTS5 contribuye con resultados.

Para detalles técnicos completos, consulta DOCUMENTATION.md -- incluye la fórmula de puntuación, constantes RRF, DDL del esquema y diagramas de arquitectura.

Pruebas

uv run pytest tests/ -v

Más de 285 pruebas en 15 archivos de prueba que cubren todas las herramientas, incrustaciones, puntuación y casos extremos. Cero regresiones.

Requisitos

• Python >= 3.12

• uv (gestor de paquetes)

Dependencias

Licencia

MIT