mnemon-mcp

mnemon-mcp

Memoria persistente en capas para agentes de IA. Local primero. Sin nube. Un único archivo SQLite.

Página de inicio · npm · GitHub

Tu agente de IA lo olvida todo después de cada sesión. Mnemon lo soluciona.

Le da a cualquier cliente compatible con MCP — OpenClaw, Claude Code, Cursor, Windsurf, o el tuyo propio — una memoria estructurada a largo plazo respaldada por una única base de datos SQLite en tu máquina. Sin claves API, sin nube, sin telemetría. Solo npm install y tu agente recuerda.

¿Por qué memoria en capas?

Los almacenes planos de clave-valor tratan "lo que pasó ayer" igual que "nunca hagas commit sin pruebas". Eso está mal — diferentes tipos de conocimiento tienen diferentes ciclos de vida y patrones de acceso.

Mnemon organiza los recuerdos en cuatro capas:

Una entrada de diario del martes pasado y una regla de codificación que nunca cambia viven en capas diferentes — porque así debe ser.

Calidad de recuperación

La recuperación se mide contra un conjunto dorado de 50 casos en un corpus bilingüe real (RU/EN) de 797 memorias, a través del servidor MCP real — no una reimplementación. Números actuales (metodología e historial):

El híbrido supera a ambas partes individualmente, que es todo el argumento para fusionarlas: la búsqueda léxica tiene mejor recall bruto, la búsqueda vectorial mejor ranking, y RRF conserva ambas en lugar de promediarlas.

El documento de evaluación también rastrea los fallos — deriva de puntuación bajo crecimiento del corpus, el error de ponderación de campos BM25 que la evaluación detectó, los dos casos donde la fusión aún pierde frente a la búsqueda léxica pura, y lo que el conjunto dorado no cubre. Los números que no se pueden auditar son marketing; lee cómo se producen.

Arquitectura

flowchart LR
    C["MCP client<br/>Claude Code · Cursor · …"] -- "stdio / HTTP" --> T["10 tools · 4 resources · 3 prompts"]
    T --> R["retrieval pipeline<br/>FTS5 · vector · RRF fusion"]
    T --> M["memories + supersede chains"]
    I["KB import pipeline<br/>markdown → memories"] --> M
    M -- triggers --> F["FTS5 index (stemmed EN+RU)"]
    R --> F
    R --> V["sqlite-vec (optional, BYOK)"]

Un único archivo SQLite contiene las memorias, el índice FTS5 y el índice vectorial opcional. Las escrituras pasan por transacciones que mantienen el invariante de la cadena de sustitución; las lecturas ejecutan el pipeline de recuperación escalonado descrito en Búsqueda.

El panorama completo — límites de módulos, rutas de escritura/lectura, invariantes y limitaciones conocidas — está en docs/ARCHITECTURE.md. Las decisiones de diseño se registran como ADR: núcleo SQLite+FTS5, recuperación híbrida RRF, controlador síncrono, modelo de memoria en capas.

Inicio rápido

Instalación

npm install -g mnemon-mcp

O desde el código fuente:

git clone https://github.com/nikitacometa/mnemon-memory-mcp.git
cd mnemon-memory-mcp && npm install && npm run build

Configura tu cliente MCP

openclaw mcp register mnemon-mcp --command="mnemon-mcp"

{
  "mnemon-mcp": {
    "command": "mnemon-mcp"
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mcpServers": {
    "mnemon-mcp": {
      "command": "mnemon-mcp"
    }
  }
}

{
  "mnemon-mcp": {
    "command": "node",
    "args": ["/absolute/path/to/mnemon-mcp/dist/index.js"]
  }
}

Verificación

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | mnemon-mcp

Deberías ver 10 herramientas en la respuesta. La base de datos (~/.mnemon-mcp/memory.db) se crea automáticamente en la primera ejecución.

Eso es todo. Tu agente ahora tiene memoria persistente.

Qué puede hacer

10 herramientas MCP

Recursos y prompts MCP

Recursos — datos en vivo que tu agente puede leer:

Prompts — flujos de trabajo preconstruidos:

Búsqueda

Cuatro modos, todos con soporte de filtros por capa / entidad / alcance / fecha / confianza:

Modo FTS (predeterminado sin embeddings) — búsqueda de texto completo tokenizada con ranking BM25. Las consultas de varias palabras usan AND; si hay muy pocos resultados, OR complementa con una penalización de puntuación. La relajación progresiva de AND prueba los 3 términos más específicos antes de recurrir a OR completo.

Modo híbrido (predeterminado cuando hay embeddings configurados) — combina FTS5 + búsqueda vectorial mediante Fusión de Ranking Recíproco. Detecta entidades entre comillas en las consultas (p. ej., 'Essentialism') y ejecuta subconsultas ponderadas para recuperación de referencias cruzadas.

Modo vectorial — búsqueda pura de similitud coseno sobre embeddings.

Modo exacto — coincidencia de subcadena LIKE para búsquedas precisas de frases.

Puntuaciones: bm25 × (0.3 + 0.7 × importance) × decay(layer) × recency

Impulso de actualidad: 1 / (1 + daysSince / 365) — recompensa suavemente las memorias creadas recientemente sin penalizar las antiguas.

Derivación (Stemming)

Se aplica el derivador Snowball tanto en tiempo de indexación como en tiempo de consulta para inglés y ruso. Esto significa que "running" coincide con "runs", y "книги" coincide con "книга". Las palabras vacías se filtran de las consultas para mejorar la precisión.

Versionado de hechos

El conocimiento evoluciona. Mnemon no elimina hechos antiguos — los encadena:

v1: "Team uses React 17"  →  superseded_by: v2
v2: "Team uses React 19"  →  supersedes: v1 (active)

La búsqueda devuelve solo la versión más reciente. memory_inspect con include_history: true revela la cadena completa. memory_delete reactiva la predecesora — nada se pierde.

Búsqueda vectorial (Opcional, BYOK)

Habilita la búsqueda de similitud semántica proporcionando tu propia API de embeddings:

# OpenAI
MNEMON_EMBEDDING_PROVIDER=openai MNEMON_EMBEDDING_API_KEY=sk-... mnemon-mcp

# Ollama (local, free)
MNEMON_EMBEDDING_PROVIDER=ollama mnemon-mcp

Esto desbloquea dos modos de búsqueda adicionales:

• mode: "vector" — búsqueda pura de similitud coseno
• mode: "hybrid" — FTS5 + vectorial combinados mediante Fusión de Ranking Recíproco

Requiere sqlite-vec (instalado como dependencia opcional). Las nuevas memorias se incrustan al añadirse; las existentes se pueden rellenar retroactivamente.

Importar una base de conocimiento

¿Tienes una carpeta de archivos Markdown? Impórtalos en lote:

cp config.example.json ~/.mnemon-mcp/config.json   # edit this first
npm run import:kb -- --kb-path /path/to/your/kb     # incremental (skips unchanged files)

La configuración asigna patrones glob a capas de memoria:

{
  "owner_name": "your-name",
  "extra_stop_words": [],
  "mappings": [
    {
      "glob": "journal/*.md",
      "layer": "episodic",
      "entity_type": "user",
      "entity_name": "$owner",
      "importance": 0.6,
      "split": "h2"
    },
    {
      "glob": "people/*.md",
      "layer": "semantic",
      "entity_type": "person",
      "entity_name": "from-heading",
      "importance": 0.8,
      "split": "h3"
    }
  ]
}

Campos de configuración

Transporte HTTP

Para configuraciones remotas o de múltiples clientes:

MNEMON_AUTH_TOKEN=your-secret MNEMON_HOST=0.0.0.0 MNEMON_PORT=3000 npm run start:http

Se vincula a 127.0.0.1 por defecto. Vincular a cualquier otro host requiere MNEMON_AUTH_TOKEN — el servidor se niega a exponer el almacén de memoria a la red sin autenticación (anular con MNEMON_ALLOW_INSECURE_HTTP=1 en una red de confianza). Limitación de velocidad (100 req/min/IP por defecto), CORS opcional, límite de cuerpo de 1MB, autenticación a prueba de temporización, apagado elegante en SIGTERM.

Referencia de configuración

Referencia de herramientas

Cómo se compara

Análisis competitivo extendido con fuentes: docs/COMPETITORS.md.

Desarrollo

npm run dev        # run via tsx (no build step)
npm run build      # TypeScript → dist/
npm run lint       # eslint (flat config)
npm test           # vitest — unit + integration + MCP dispatch + HTTP transport + hybrid RRF
npm run bench      # performance benchmarks
npm run db:backup  # backup database

CI ejecuta compilación + lint + pruebas en Node 20 y 22, luego pruebas de humo del servidor compilado sobre JSON-RPC real (tools/list debe coincidir con el conjunto exacto de herramientas).

Stack: TypeScript 5.9 (modo estricto), better-sqlite3, @modelcontextprotocol/sdk, derivador Snowball, Zod, vitest.

Consulta CONTRIBUTING.md para las pautas de código.

Principios de diseño

• Aislado por defecto — cero telemetría, siempre. De fábrica nada sale de la máquina; el único componente que habla con la red es el embedder opcional, y solo con el proveedor que configures (incluido un Ollama local).
• Archivo único — una base de datos SQLite, cero operaciones, copia de seguridad instantánea mediante copia de archivo.
• Búsqueda determinista — FTS5, no embeddings, es el predeterminado. Interpretable, reproducible, sin necesidad de GPU.
• Estructurado sobre plano — las capas codifican patrones de acceso; las cadenas de sustitución codifican el tiempo.
• Mínimo — 4 dependencias de producción. Funciona en cualquier lugar donde Node funcione.
• Medido, no afirmado — los cambios en la recuperación se evalúan contra un conjunto dorado, regresiones incluidas.

Licencia

MIT