Memento MCP

Un sistema de memoria de grafo de conocimiento escalable para LLMs con recuperación semántica y conciencia temporal, utilizando Neo4j como backend.

GitHub

425

Prueba este MCPPatrocinado

Documentación

Memento MCP: Un Sistema de Memoria de Grafo de Conocimiento para LLMs

Sistema de memoria de grafo de conocimiento escalable y de alto rendimiento con recuperación semántica, recuerdo contextual y conciencia temporal. Proporciona a cualquier cliente LLM que admita el protocolo de contexto de modelo (por ejemplo, Claude Desktop, Cursor, Github Copilot) una memoria ontológica a largo plazo resiliente, adaptable y persistente.

Conceptos Fundamentales

Entidades

Las entidades son los nodos principales en el grafo de conocimiento. Cada entidad tiene:

Un nombre único (identificador)
Un tipo de entidad (por ejemplo, "persona", "organización", "evento")
Una lista de observaciones
Incrustaciones vectoriales (para búsqueda semántica)
Historial de versiones completo

Ejemplo:

{
  "name": "John_Smith",
  "entityType": "person",
  "observations": ["Speaks fluent Spanish"]
}

Relaciones

Las relaciones definen conexiones dirigidas entre entidades con propiedades mejoradas:

Indicadores de fuerza (0.0-1.0)
Niveles de confianza (0.0-1.0)
Metadatos enriquecidos (fuente, marcas de tiempo, etiquetas)
Conciencia temporal con historial de versiones
Decaimiento de confianza basado en el tiempo

Ejemplo:

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at",
  "strength": 0.9,
  "confidence": 0.95,
  "metadata": {
    "source": "linkedin_profile",
    "last_verified": "2025-03-21"
  }
}

Backend de Almacenamiento

Memento MCP utiliza Neo4j como su backend de almacenamiento, proporcionando una solución unificada tanto para el almacenamiento de grafos como para las capacidades de búsqueda vectorial.

¿Por qué Neo4j?

Almacenamiento Unificado: Consolida tanto el almacenamiento de grafos como el vectorial en una sola base de datos
Operaciones de Grafo Nativas: Construido específicamente para recorridos y consultas de grafos
Búsqueda Vectorial Integrada: Búsqueda de similitud vectorial para incrustaciones integrada directamente en Neo4j
Escalabilidad: Mejor rendimiento con grafos de conocimiento grandes
Arquitectura Simplificada: Diseño limpio con una sola base de datos para todas las operaciones

Requisitos Previos

Neo4j 5.13+ (requerido para capacidades de búsqueda vectorial)

Configuración de Neo4j Desktop (Recomendado)

La forma más fácil de comenzar con Neo4j es usar Neo4j Desktop:

Descargue e instale Neo4j Desktop desde https://neo4j.com/download/
Cree un nuevo proyecto
Agregue una nueva base de datos
Establezca la contraseña como memento_password (o su contraseña preferida)
Inicie la base de datos

La base de datos Neo4j estará disponible en:

URI Bolt: bolt://127.0.0.1:7687 (para conexiones de controlador)
HTTP: http://127.0.0.1:7474 (para la interfaz de usuario de Neo4j Browser)
Credenciales predeterminadas: nombre de usuario: neo4j, contraseña: memento_password (o la que haya configurado)

Configuración de Neo4j con Docker (Alternativa)

Alternativamente, puede usar Docker Compose para ejecutar Neo4j:

# Start Neo4j container
docker-compose up -d neo4j

# Stop Neo4j container
docker-compose stop neo4j

# Remove Neo4j container (preserves data)
docker-compose rm neo4j

Al usar Docker, la base de datos Neo4j estará disponible en:

URI Bolt: bolt://127.0.0.1:7687 (para conexiones de controlador)
HTTP: http://127.0.0.1:7474 (para la interfaz de usuario de Neo4j Browser)
Credenciales predeterminadas: nombre de usuario: neo4j, contraseña: memento_password

Persistencia y Gestión de Datos

Los datos de Neo4j persisten entre reinicios de contenedores e incluso actualizaciones de versión debido a la configuración de volúmenes de Docker en el archivo docker-compose.yml:

volumes:
  - ./neo4j-data:/data
  - ./neo4j-logs:/logs
  - ./neo4j-import:/import

Estos mapeos aseguran que:

El directorio /data (contiene todos los archivos de la base de datos) persiste en su host en ./neo4j-data
El directorio /logs persiste en su host en ./neo4j-logs
El directorio /import (para importar archivos de datos) persiste en ./neo4j-import

Puede modificar estas rutas en su archivo docker-compose.yml para almacenar datos en diferentes ubicaciones si es necesario.

Actualización de la Versión de Neo4j

Puede cambiar las ediciones y versiones de Neo4j sin perder datos:

Actualice la versión de la imagen de Neo4j en docker-compose.yml
Reinicie el contenedor con docker-compose down && docker-compose up -d neo4j
Reinicialice el esquema con npm run neo4j:init

Los datos persistirán durante este proceso siempre que los mapeos de volúmenes permanezcan iguales.

Restablecimiento Completo de la Base de Datos

Si necesita restablecer completamente su base de datos Neo4j:

# Stop the container
docker-compose stop neo4j

# Remove the container
docker-compose rm -f neo4j

# Delete the data directory contents
rm -rf ./neo4j-data/*

# Restart the container
docker-compose up -d neo4j

# Reinitialize the schema
npm run neo4j:init

Respaldo de Datos

Para respaldar sus datos de Neo4j, puede simplemente copiar el directorio de datos:

# Make a backup of the Neo4j data
cp -r ./neo4j-data ./neo4j-data-backup-$(date +%Y%m%d)

Utilidades CLI de Neo4j

Memento MCP incluye utilidades de línea de comandos para gestionar operaciones de Neo4j:

Prueba de Conexión

Pruebe la conexión a su base de datos Neo4j:

# Test with default settings
npm run neo4j:test

# Test with custom settings
npm run neo4j:test -- --uri bolt://127.0.0.1:7687 --username myuser --password mypass --database neo4j

Inicialización del Esquema

Para operación normal, la inicialización del esquema de Neo4j ocurre automáticamente cuando Memento MCP se conecta a la base de datos. No necesita ejecutar ningún comando manual para uso regular.

Los siguientes comandos solo son necesarios para escenarios de desarrollo, pruebas o personalización avanzada:

# Initialize with default settings (only needed for development or troubleshooting)
npm run neo4j:init

# Initialize with custom vector dimensions
npm run neo4j:init -- --dimensions 768 --similarity euclidean

# Force recreation of all constraints and indexes
npm run neo4j:init -- --recreate

# Combine multiple options
npm run neo4j:init -- --vector-index custom_index --dimensions 384 --recreate

Funciones Avanzadas

Búsqueda Semántica

Encuentre entidades semánticamente relacionadas basándose en el significado en lugar de solo palabras clave:

Incrustaciones Vectoriales: Las entidades se codifican automáticamente en un espacio vectorial de alta dimensión utilizando los modelos de incrustación de OpenAI
Similitud de Coseno: Encuentre conceptos relacionados incluso cuando usan terminología diferente
Umbrales Configurables: Establezca puntuaciones mínimas de similitud para controlar la relevancia de los resultados
Búsqueda Transmodal: Consulte con texto para encontrar entidades relevantes independientemente de cómo fueron descritas
Soporte Multimodelo: Compatible con múltiples modelos de incrustación (OpenAI text-embedding-3-small/large)
Recuperación Contextual: Recupere información basada en el significado semántico en lugar de coincidencias exactas de palabras clave
Valores Predeterminados Optimizados: Parámetros ajustados para un equilibrio entre precisión y recuperación (umbral de similitud 0.6, búsqueda híbrida habilitada)
Búsqueda Híbrida: Combina búsqueda semántica y por palabras clave para resultados más completos
Búsqueda Adaptativa: El sistema elige inteligentemente entre búsqueda solo vectorial, solo por palabras clave o híbrida según las características de la consulta y los datos disponibles
Optimización de Rendimiento: Prioriza la búsqueda vectorial para la comprensión semántica mientras mantiene mecanismos de respaldo para la resiliencia
Procesamiento Consciente de la Consulta: Ajusta la estrategia de búsqueda según la complejidad de la consulta y las incrustaciones de entidades disponibles

Conciencia Temporal

Realice un seguimiento del historial completo de entidades y relaciones con recuperación de grafos en un punto específico del tiempo:

Historial de Versiones Completo: Cada cambio en una entidad o relación se conserva con marcas de tiempo
Consultas en Punto en el Tiempo: Recupere el estado exacto del grafo de conocimiento en cualquier momento del pasado
Seguimiento de Cambios: Registra automáticamente las marcas de tiempo createdAt, updatedAt, validFrom y validTo
Consistencia Temporal: Mantenga una vista históricamente precisa de cómo evolucionó el conocimiento
Actualizaciones No Destructivas: Las actualizaciones crean nuevas versiones en lugar de sobrescribir datos existentes
Filtrado Basado en el Tiempo: Filtre elementos del grafo según criterios temporales
Exploración del Historial: Investigue cómo cambió información específica a lo largo del tiempo

Decaimiento de Confianza

Las relaciones decaen automáticamente en confianza con el tiempo según una vida media configurable:

Decaimiento Basado en el Tiempo: La confianza en las relaciones disminuye naturalmente con el tiempo si no se refuerza
Vida Media Configurable: Defina qué tan rápido la información se vuelve menos cierta (predeterminado: 30 días)
Límites Mínimos de Confianza: Establezca umbrales para prevenir el decaimiento excesivo de información importante
Metadatos de Decaimiento: Cada relación incluye información detallada del cálculo de decaimiento
No Destructivo: Los valores de confianza originales se conservan junto con los valores decaídos
Aprendizaje por Refuerzo: Las relaciones recuperan confianza cuando se refuerzan con nuevas observaciones
Flexibilidad del Tiempo de Referencia: Calcule el decaimiento basándose en tiempos de referencia arbitrarios para análisis históricos

Metadatos Avanzados

Soporte de metadatos enriquecidos tanto para entidades como para relaciones con campos personalizados:

Seguimiento de Fuente: Registre de dónde se originó la información (entrada del usuario, análisis, fuentes externas)
Niveles de Confianza: Asigne puntuaciones de confianza (0.0-1.0) a las relaciones según la certeza
Fuerza de Relación: Indique la importancia o fuerza de las relaciones (0.0-1.0)
Metadatos Temporales: Realice un seguimiento de cuándo se agregó, modificó o verificó la información
Etiquetas Personalizadas: Agregue etiquetas arbitrarias para clasificación y filtrado
Datos Estructurados: Almacene datos estructurados complejos dentro de los campos de metadatos
Soporte de Consultas: Busque y filtre según las propiedades de los metadatos
Esquema Extensible: Agregue campos personalizados según sea necesario sin modificar el modelo de datos central

Herramientas de API MCP

Las siguientes herramientas están disponibles para los hosts de clientes LLM a través del Protocolo de Contexto de Modelo:

Gestión de Entidades

create_entities
- Cree múltiples entidades nuevas en el grafo de conocimiento
- Entrada: entities (matriz de objetos)
  - Cada objeto contiene:
    - name (cadena): Identificador de la entidad
    - entityType (cadena): Clasificación de tipo
    - observations (cadena[]): Observaciones asociadas
add_observations
- Agregue nuevas observaciones a entidades existentes
- Entrada: observations (matriz de objetos)
  - Cada objeto contiene:
    - entityName (cadena): Entidad objetivo
    - contents (cadena[]): Nuevas observaciones para agregar
delete_entities
- Elimine entidades y sus relaciones
- Entrada: entityNames (cadena[])
delete_observations
- Elimine observaciones específicas de entidades
- Entrada: deletions (matriz de objetos)
  - Cada objeto contiene:
    - entityName (cadena): Entidad objetivo
    - observations (cadena[]): Observaciones para eliminar

Gestión de Relaciones

create_relations
- Cree múltiples relaciones nuevas entre entidades con propiedades mejoradas
- Entrada: relations (matriz de objetos)
  - Cada objeto contiene:
    - from (cadena): Nombre de la entidad fuente
    - to (cadena): Nombre de la entidad objetivo
    - relationType (cadena): Tipo de relación
    - strength (número, opcional): Fuerza de la relación (0.0-1.0)
    - confidence (número, opcional): Nivel de confianza (0.0-1.0)
    - metadata (objeto, opcional): Campos de metadatos personalizados
get_relation
- Obtenga una relación específica con sus propiedades mejoradas
- Entrada:
  - from (cadena): Nombre de la entidad fuente
  - to (cadena): Nombre de la entidad objetivo
  - relationType (cadena): Tipo de relación
update_relation
- Actualice una relación existente con propiedades mejoradas
- Entrada: relation (objeto):
  - Contiene:
    - from (cadena): Nombre de la entidad fuente
    - to (cadena): Nombre de la entidad objetivo
    - relationType (cadena): Tipo de relación
    - strength (número, opcional): Fuerza de la relación (0.0-1.0)
    - confidence (número, opcional): Nivel de confianza (0.0-1.0)
    - metadata (objeto, opcional): Campos de metadatos personalizados
delete_relations
- Elimine relaciones específicas del grafo
- Entrada: relations (matriz de objetos)
  - Cada objeto contiene:
    - from (cadena): Nombre de la entidad fuente
    - to (cadena): Nombre de la entidad objetivo
    - relationType (cadena): Tipo de relación

Operaciones de Grafo

read_graph
- Lea el grafo de conocimiento completo
- No se requiere entrada
search_nodes
- Busque nodos según la consulta
- Entrada: query (cadena)
open_nodes
- Recupere nodos específicos por nombre
- Entrada: names (cadena[])

Búsqueda Semántica

semantic_search
- Busque entidades semánticamente usando incrustaciones vectoriales y similitud
- Entrada:
  - query (cadena): La consulta de texto para buscar semánticamente
  - limit (número, opcional): Máximo de resultados a devolver (predeterminado: 10)
  - min_similarity (número, opcional): Umbral mínimo de similitud (0.0-1.0, predeterminado: 0.6)
  - entity_types (cadena[], opcional): Filtre los resultados por tipos de entidad
  - hybrid_search (booleano, opcional): Combine búsqueda por palabras clave y semántica (predeterminado: true)
  - semantic_weight (número, opcional): Peso de los resultados semánticos en la búsqueda híbrida (0.0-1.0, predeterminado: 0.6)
- Características:
  - Selecciona inteligentemente el método de búsqueda óptimo (vectorial, por palabras clave o híbrido) según el contexto de la consulta
  - Maneja con elegancia consultas sin coincidencias semánticas mediante mecanismos de respaldo
  - Mantiene alto rendimiento con decisiones de optimización automáticas
get_entity_embedding
- Obtiene el embedding vectorial de una entidad específica
- Entrada:
  - entity_name (string): El nombre de la entidad para la cual obtener el embedding

Características Temporales

get_entity_history
- Obtiene el historial completo de versiones de una entidad
- Entrada: entityName (string)
get_relation_history
- Obtiene el historial completo de versiones de una relación
- Entrada:
  - from (string): Nombre de la entidad fuente
  - to (string): Nombre de la entidad destino
  - relationType (string): Tipo de relación
get_graph_at_time
- Obtiene el estado del grafo en una marca de tiempo específica
- Entrada: timestamp (number): Marca de tiempo Unix (milisegundos desde la época)
get_decayed_graph
- Obtiene el grafo con valores de confianza con decaimiento temporal
- Entrada: options (object, opcional):
  - reference_time (number): Marca de tiempo de referencia para el cálculo de decaimiento (milisegundos desde la época)
  - decay_factor (number): Anulación opcional del factor de decaimiento

Configuración

Variables de Entorno

Configure Memento MCP con estas variables de entorno:

# Neo4j Connection Settings
NEO4J_URI=bolt://127.0.0.1:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=memento_password
NEO4J_DATABASE=neo4j

# Vector Search Configuration
NEO4J_VECTOR_INDEX=entity_embeddings
NEO4J_VECTOR_DIMENSIONS=1536
NEO4J_SIMILARITY_FUNCTION=cosine

# Embedding Service Configuration
MEMORY_STORAGE_TYPE=neo4j
OPENAI_API_KEY=your-openai-api-key
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Debug Settings
DEBUG=true

Opciones de Línea de Comandos

Las herramientas CLI de Neo4j admiten las siguientes opciones:

--uri <uri>              Neo4j server URI (default: bolt://127.0.0.1:7687)
--username <username>    Neo4j username (default: neo4j)
--password <password>    Neo4j password (default: memento_password)
--database <n>           Neo4j database name (default: neo4j)
--vector-index <n>       Vector index name (default: entity_embeddings)
--dimensions <number>    Vector dimensions (default: 1536)
--similarity <function>  Similarity function (cosine|euclidean) (default: cosine)
--recreate               Force recreation of constraints and indexes
--no-debug               Disable detailed output (debug is ON by default)

Modelos de Embedding

Modelos de embedding de OpenAI disponibles:

text-embedding-3-small: Eficiente, rentable (1536 dimensiones)
text-embedding-3-large: Mayor precisión, más costoso (3072 dimensiones)
text-embedding-ada-002: Modelo heredado (1536 dimensiones)

Configuración de la API de OpenAI

Para usar la búsqueda semántica, necesitará configurar las credenciales de la API de OpenAI:

Obtenga una clave de API de OpenAI
Configure su entorno con:

# OpenAI API Key for embeddings
OPENAI_API_KEY=your-openai-api-key
# Default embedding model
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

Nota: Para entornos de prueba, el sistema simulará la generación de embeddings si no se proporciona una clave de API. Sin embargo, se recomienda usar embeddings reales para pruebas de integración.

Integración con Claude Desktop

Configuración

Agregue esto a su claude_desktop_config.json:

{
  "mcpServers": {
    "memento": {
      "command": "npx",
      "args": ["-y", "@gannonh/memento-mcp"],
      "env": {
        "MEMORY_STORAGE_TYPE": "neo4j",
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "memento_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

Alternativamente, para desarrollo local, puede usar:

{
  "mcpServers": {
    "memento": {
      "command": "/path/to/node",
      "args": ["/path/to/memento-mcp/dist/index.js"],
      "env": {
        "MEMORY_STORAGE_TYPE": "neo4j",
        "NEO4J_URI": "bolt://127.0.0.1:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "memento_password",
        "NEO4J_DATABASE": "neo4j",
        "NEO4J_VECTOR_INDEX": "entity_embeddings",
        "NEO4J_VECTOR_DIMENSIONS": "1536",
        "NEO4J_SIMILARITY_FUNCTION": "cosine",
        "OPENAI_API_KEY": "your-openai-api-key",
        "OPENAI_EMBEDDING_MODEL": "text-embedding-3-small",
        "DEBUG": "true"
      }
    }
  }
}

Importante: Siempre especifique explícitamente el modelo de embedding en su configuración de Claude Desktop para garantizar un comportamiento consistente.

Prompts de Sistema Recomendados

Para una integración óptima con Claude, agregue estas declaraciones a su prompt de sistema:

You have access to the Memento MCP knowledge graph memory system, which provides you with persistent memory capabilities.
Your memory tools are provided by Memento MCP, a sophisticated knowledge graph implementation.
When asked about past conversations or user information, always check the Memento MCP knowledge graph first.
You should use semantic_search to find relevant information in your memory when answering questions.

Pruebas de Búsqueda Semántica

Una vez configurado, Claude puede acceder a las capacidades de búsqueda semántica a través de lenguaje natural:

Para crear entidades con embeddings semánticos:

User: "Remember that Python is a high-level programming language known for its readability and JavaScript is primarily used for web development."

Para buscar semánticamente:

User: "What programming languages do you know about that are good for web development?"

Para recuperar información específica:

User: "Tell me everything you know about Python."

El poder de este enfoque es que los usuarios pueden interactuar de forma natural, mientras que el LLM maneja la complejidad de seleccionar y usar las herramientas de memoria apropiadas.

Aplicaciones del Mundo Real

Las capacidades de búsqueda adaptativa de Memento proporcionan beneficios prácticos:

Versatilidad de Consultas: Los usuarios no necesitan preocuparse por cómo formular preguntas: el sistema se adapta automáticamente a diferentes tipos de consultas
Resiliencia ante Fallos: Incluso cuando no hay coincidencias semánticas disponibles, el sistema puede recurrir a métodos alternativos sin intervención del usuario
Eficiencia de Rendimiento: Al seleccionar inteligentemente el método de búsqueda óptimo, el sistema equilibra rendimiento y relevancia para cada consulta
Mejora en la Recuperación de Contexto: Las conversaciones con LLM se benefician de una mejor recuperación de contexto, ya que el sistema puede encontrar información relevante en grafos de conocimiento complejos

Por ejemplo, cuando un usuario pregunta "¿Qué sabes sobre aprendizaje automático?", el sistema puede recuperar entidades conceptualmente relacionadas incluso si no mencionan explícitamente "aprendizaje automático" — quizás entidades sobre redes neuronales, ciencia de datos o algoritmos específicos. Pero si la búsqueda semántica produce resultados insuficientes, el sistema ajusta automáticamente su enfoque para garantizar que se devuelva información útil.

Solución de Problemas

Diagnóstico de Búsqueda Vectorial

Memento MCP incluye capacidades de diagnóstico integradas para ayudar a solucionar problemas de búsqueda vectorial:

Verificación de Embeddings: El sistema verifica si las entidades tienen embeddings válidos y los genera automáticamente si faltan
Estado del Índice Vectorial: Verifica que el índice vectorial exista y esté en estado ONLINE
Búsqueda de Respaldo: Si la búsqueda vectorial falla, el sistema recurre a la búsqueda basada en texto
Registro Detallado: Registro completo de operaciones de búsqueda vectorial para solución de problemas

Herramientas de Depuración (cuando DEBUG=true)

Herramientas de diagnóstico adicionales están disponibles cuando el modo de depuración está habilitado:

diagnose_vector_search: Información sobre el índice vectorial de Neo4j, conteos de embeddings y funcionalidad de búsqueda
force_generate_embedding: Fuerza la generación de un embedding para una entidad específica
debug_embedding_config: Información sobre la configuración actual del servicio de embeddings

Restablecimiento para Desarrolladores

Para restablecer completamente su base de datos Neo4j durante el desarrollo:

# Stop the container (if using Docker)
docker-compose stop neo4j

# Remove the container (if using Docker)
docker-compose rm -f neo4j

# Delete the data directory (if using Docker)
rm -rf ./neo4j-data/*

# For Neo4j Desktop, right-click your database and select "Drop database"

# Restart the database
# For Docker:
docker-compose up -d neo4j

# For Neo4j Desktop:
# Click the "Start" button for your database

# Reinitialize the schema
npm run neo4j:init

Compilación y Desarrollo

# Clone the repository
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Check test coverage
npm run test:coverage

Instalación

Instalación mediante Smithery

Para instalar memento-mcp para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @gannonh/memento-mcp --client claude

Instalación Global con npx

Puede ejecutar Memento MCP directamente usando npx sin instalarlo globalmente:

npx -y @gannonh/memento-mcp

Este método se recomienda para usar con Claude Desktop y otros clientes compatibles con MCP.

Instalación Local

Para desarrollo o contribución al proyecto:

# Install locally
npm install @gannonh/memento-mcp

# Or clone the repository
git clone https://github.com/gannonh/memento-mcp.git
cd memento-mcp
npm install

Licencia

MIT