memory engine

Una memoria viva que decae, aprende y evoluciona con tu IA.

Documentación

🧠 Memory Engine MCP

Memoria de largo plazo local-first y consciente del grafo para asistentes de IA.
SQLite + búsqueda semántica + grafo de conocimiento + herramientas MCP para agentes que necesitan continuidad.

Funciona con Claude Desktop · Claude Code · Cursor · Cline · Windsurf · OpenClaw · cualquier cliente MCP

¿Por qué Memory Engine?

La mayoría de los servidores de memoria MCP son simples almacenes clave-valor o envoltorios de búsqueda de texto plano.

Memory Engine es diferente: modela la memoria como átomos tipados conectados por enlaces tipados, y luego recupera contexto con un pipeline de clasificación híbrido que combina:

búsqueda de texto completo (SQLite FTS5)
similitud semántica mediante embeddings locales de Ollama
confianza, recencia y peso
expansión de grafo a partir de memorias relacionadas

El objetivo no es solo el almacenamiento. El objetivo es un sistema de memoria que pueda recordar, conectar, decaer, curar y aprender con el tiempo.

Destacados

Local-first — base de datos SQLite, embeddings locales opcionales vía Ollama, sin API en la nube requerida.
Nativo MCP — expone 35 herramientas a través de FastMCP.
Recuperación consciente del grafo — expande los mejores resultados mediante enlaces bidireccionales para un contexto más rico.
Búsqueda semántica — recuperación basada en significado con nomic-embed-text.
Coexistencia con Markdown — importa notas existentes de forma unidireccional sin reemplazar tu memoria legible por humanos.
Memoria de errores — recuerda errores y correcciones, con promoción automática a preferencias tras fallos repetidos.
Curador cognitivo — pasada de mantenimiento no destructiva para compactación, sugerencias de enlaces, detección de duplicados y clasificación de átomos aislados.
Vigilante de sesiones — ingesta canónica de SQLite de OpenClaw (esquema 17), resúmenes conscientes de reinicio y respaldo JSONL heredado.
Copia de seguridad y restauración — instantáneas completas de SQLite, exportación/importación JSON, restauraciones verificadas con copias de seguridad automáticas.
Autenticación y endurecimiento — token API opcional, enlace seguro, validación de entrada, limitación de velocidad.
Suite de pruebas — 144 pruebas que cubren CRUD, clasificación, migraciones, autenticación, copias de seguridad, concurrencia e ingesta de transcripciones.
Benchmark — suite CLI de calidad de recuperación con Precision@K, MRR, percentiles de latencia.

Arquitectura

AI assistant / MCP client
        │
        ▼
FastMCP server — 35 tools
        │
        ▼
Memory engine — hybrid ranking, graph recall, decay, learning
        │
        ├── SQLite — atoms, bonds, FTS5, JSON metadata, versions
        ├── Ollama — optional local embeddings
        ├── Curator — conservative maintenance
        └── Session watcher — OpenClaw SQLite + JSONL fallback

Herramientas MCP

Memoria

Herramienta	Propósito
`remember`	Crear o actualizar un átomo
`recall`	Recuperación híbrida inteligente con expansión de grafo
`working_set`	Construir un paquete de contexto orientado a tareas
`semantic_search`	Búsqueda semántica pura
`get_atom`	Leer un átomo con sus enlaces
`list_atoms`	Explorar átomos por dominio/tipo/estado
`merge_atoms`	Fusionar átomos duplicados
`export_atom`	Exportar un átomo como markdown

Grafo de conocimiento

Herramienta	Propósito
`link` / `unlink`	Crear o eliminar enlaces tipados
`search_graph`	Recorrer el grafo desde un átomo
`suggest_bonds`	Sugerir enlaces para un átomo
`suggest_bonds_all`	Sugerir o crear enlaces en lote

Aprendizaje y mantenimiento

Herramienta	Propósito
`curator_run`	Pasada de curación conservadora
`cognitive_status`	Métricas de salud del grafo y la memoria
`learning_run`	Detectar contradicciones, átomos débiles, candidatos a fusión, vacíos
`ask_pending` / `answer_human`	Aclaración con intervención humana
`decay_run`	Ejecutar ciclo de decaimiento
`cleanup_sessions`	Eliminar átomos de sesión expirados
`cleanup_duplicates`	Eliminar átomos de sesión duplicados
`reindex_embeddings`	Reconstruir embeddings

Memoria de errores y preferencias

Herramienta	Propósito
`error_check`	Verificar fallos pasados antes de realizar una tarea
`error_log`	Registrar un error y la corrección
`error_list`	Explorar errores no resueltos/resueltos
`preference_search`	Buscar preferencias estructuradas

Importación e introspección

Herramienta	Propósito
`import_markdown`	Importar notas markdown en átomos
`memory_summary`	Resumen de 3 niveles: global → dominio → detalle
`stats`	Estadísticas de la base de datos
`version`	Versión del servidor
`recall_session`	Buscar una sesión de OpenClaw
`session_summary`	Resumir una sesión de OpenClaw
`memory_contradict`	Reemplazar un átomo antiguo con uno más nuevo y contradictorio
`list_contradictions`	Listar registros explícitos de contradicción/reemplazo
`classify_memory_tier`	Inferir la clase de 3 niveles (episódica/semántica/procedimental)
`memory_impact`	Análisis de impacto: qué depende de este átomo

Copia de seguridad, restauración y exportación

Herramienta	Propósito
`backup_database`	Crear, listar, verificar o limpiar instantáneas SQLite
`restore_database`	Restaurar desde una copia de seguridad (con copia de seguridad automática)
`export_all`	Exportar todos los datos de memoria como JSON portátil
`import_data`	Importar desde JSON (modo fusión o reemplazo)

Interfaz web (opcional)

Memory Engine incluye una interfaz web opcional para exploración de grafos, inspección de átomos, navegación de contradicciones y análisis de impacto.

# In docker-compose.yml, add:
#   environment:
#     - MEM_UI_PORT=6000
#   expose:
#     - "6000"

O ejecutar de forma independiente:

python3 web_ui.py
# Open http://localhost:6000

Memory Engine Web UI — graph explorer
Interfaz web: grafo interactivo, detalles de átomos, navegador de contradicciones, panel de estadísticas

Inicio rápido con Docker

Opción A — Usar la imagen preconstruida (recomendado)

# docker-compose.yml
services:
  memory-engine:
    image: ghcr.io/simoneb79/memory-engine-mcp:1.9.0
    ports:
      - "8085:8085"
    volumes:
      - memory-data:/data
    restart: unless-stopped

volumes:
  memory-data:

docker compose up -d

Fija la versión. Usa una etiqueta explícita como :1.7.0 en producción. Evita :latest — puede cambiar sin previo aviso.

Opción B — Compilar desde el código fuente

git clone https://github.com/SimoneB79/memory-engine-mcp.git
cd memory-engine-mcp
cp docker-compose.yml docker-compose.local.yml
# Edit volume paths in docker-compose.local.yml if needed
docker compose -f docker-compose.local.yml up -d --build

Endpoint predeterminado:

http://localhost:8085/sse

Ejemplo de configuración de cliente MCP:

{
  "mcpServers": {
    "memory-engine": {
      "url": "http://localhost:8085/sse",
      "transport": "sse"
    }
  }
}

Consulta docs/INSTALL.md para ejemplos de Docker, Python local, Claude Desktop, Cursor y OpenClaw.

Python local

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

Configuración

Archivo de configuración principal: config.json

Variables de entorno importantes:

Variable	Predeterminado	Propósito
`MEMORY_DB_PATH`	`/data/memory.db`	Ruta de la base de datos SQLite
`MARKDOWN_SOURCE`	`/workspace/memory`	Directorio Markdown para importación
`MEMORY_HOST`	`127.0.0.1`	Dirección de enlace del servidor (predeterminado seguro)
`MEMORY_PORT`	`8085`	Puerto SSE
`MEMORY_API_TOKEN`	(ninguno)	Token API opcional para autenticación (ver Seguridad)
`OPENCLAW_AGENT_DB`	(ninguno)	Base de datos SQLite de OpenClaw preferida por agente (esquema 17)
`OPENCLAW_SESSIONS_DIR`	`/sessions`	Respaldo JSONL heredado cuando no hay base de datos de agente configurada
`SESSION_DIGEST_DIR`	`/data/session_digests`	Salida opcional de resumen de sesión

Para el montaje SQLite, manejo de WAL/SHM, filtrado y límite de seguridad, consulta Ingesta de transcripciones de OpenClaw.

La búsqueda semántica requiere que Ollama sea accesible desde el contenedor o el host. Predeterminado:

{
  "ollama": {
    "enabled": true,
    "host": "http://ollama:11434",
    "model": "nomic-embed-text"
  }
}

Si no usas Ollama, establece ollama.enabled a false; la recuperación FTS sigue funcionando.

Modelo de memoria

Los átomos tienen:

title
body
type: fact, decision, event, preference, log, procedure, note, etc.
domain: espacio de nombres de proyecto o tema
confidence
weight
tags
TTL opcional

Los enlaces conectan átomos con tipos de relación:

is_a · part_of · depends_on · contradicts · refines · derived_from · detail_of · related_to

Ejemplo de uso

remember(
    title="Use PostgreSQL for analytics",
    body="SQLite is kept for local memory, PostgreSQL is used for multi-user analytics.",
    type="decision",
    domain="project:analytics",
    confidence=0.9,
    tags=["database", "architecture"]
)

recall(query="what database did we choose for analytics?", limit=5)

working_set(
    query="continue the analytics backend work",
    domain="project:analytics",
    limit=8,
    graph_depth=1
)

Seguridad

Por defecto, Memory Engine se ejecuta en modo abierto (sin autenticación) — seguro para stdio o entornos locales de confianza.

Para habilitar la autenticación con token API:

// config.json
{
  "security": {
    "api_token": "your-secret-token",
    "allow_remote": false
  }
}

O mediante variable de entorno:

MEMORY_API_TOKEN=your-secret-token

Cuando la autenticación está habilitada:

Las solicitudes MCP SSE deben incluir Authorization: Bearer <token>
Los endpoints de la API de la interfaz web requieren ?token=<token> o encabezado Bearer
El servidor se enlaza a 127.0.0.1 a menos que allow_remote: true
La validación de entrada (límites de tamaño de título/cuerpo) y la limitación de velocidad están siempre activas

Consulta CHANGELOG.md para la lista completa de funciones de seguridad.

Publicación y registros

Este repositorio está preparado para el descubrimiento MCP:

Nombre del registro MCP: io.github.simoneb79/memory-engine-mcp
Metadatos del registro: server.json
Etiqueta de verificación Docker/OCI: incluida en Dockerfile
Ejemplo de configuración de cliente: mcp.json

Consulta docs/PUBLISHING.md para la lista de verificación de publicación.

Estado del repositorio

Repositorio público de GitHub: https://github.com/SimoneB79/memory-engine-mcp
Listado existente: https://mcpmarket.com/server/memory-engine
Licencia: MIT

Licencia

MIT — consulta LICENSE.

Hecho con 🧠 por SimoneB79