Memento MCP

Um sistema de memória de grafo de conhecimento escalável para LLMs com recuperação semântica e consciência temporal, utilizando Neo4j como backend.

GitHub

425

Experimente este MCPPatrocinado

Documentação

Memento MCP: Um Sistema de Memória de Grafo de Conhecimento para LLMs

Sistema de memória de grafo de conhecimento escalável e de alto desempenho com recuperação semântica, recordação contextual e consciência temporal. Fornece a qualquer cliente LLM que suporte o protocolo de contexto de modelo (ex.: Claude Desktop, Cursor, Github Copilot) memória ontológica resiliente, adaptativa e persistente de longo prazo.

Conceitos Principais

Entidades

Entidades são os nós primários no grafo de conhecimento. Cada entidade possui:

Um nome único (identificador)
Um tipo de entidade (ex.: "pessoa", "organização", "evento")
Uma lista de observações
Embeddings vetoriais (para busca semântica)
Histórico completo de versões

Exemplo:

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

Relações

Relações definem conexões direcionadas entre entidades com propriedades aprimoradas:

Indicadores de força (0.0-1.0)
Níveis de confiança (0.0-1.0)
Metadados ricos (fonte, carimbos de data/hora, tags)
Consciência temporal com histórico de versões
Decaimento de confiança baseado no tempo

Exemplo:

{
  "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 Armazenamento

O Memento MCP usa o Neo4j como backend de armazenamento, fornecendo uma solução unificada tanto para armazenamento de grafos quanto para capacidades de busca vetorial.

Por que Neo4j?

Armazenamento Unificado: Consolida tanto o armazenamento de grafos quanto o vetorial em um único banco de dados
Operações Nativas de Grafo: Construído especificamente para travessia e consultas de grafos
Busca Vetorial Integrada: Busca por similaridade vetorial para embeddings diretamente integrada ao Neo4j
Escalabilidade: Melhor desempenho com grafos de conhecimento grandes
Arquitetura Simplificada: Design limpo com um único banco de dados para todas as operações

Pré-requisitos

Neo4j 5.13+ (necessário para capacidades de busca vetorial)

Configuração do Neo4j Desktop (Recomendado)

A maneira mais fácil de começar com o Neo4j é usar o Neo4j Desktop:

Baixe e instale o Neo4j Desktop de https://neo4j.com/download/
Crie um novo projeto
Adicione um novo banco de dados
Defina a senha como memento_password (ou sua senha preferida)
Inicie o banco de dados

O banco de dados Neo4j estará disponível em:

URI Bolt: bolt://127.0.0.1:7687 (para conexões de driver)
HTTP: http://127.0.0.1:7474 (para a interface do Neo4j Browser)
Credenciais padrão: nome de usuário: neo4j, senha: memento_password (ou o que você configurou)

Configuração do Neo4j com Docker (Alternativa)

Alternativamente, você pode usar o Docker Compose para executar o 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

Ao usar Docker, o banco de dados Neo4j estará disponível em:

URI Bolt: bolt://127.0.0.1:7687 (para conexões de driver)
HTTP: http://127.0.0.1:7474 (para a interface do Neo4j Browser)
Credenciais padrão: nome de usuário: neo4j, senha: memento_password

Persistência e Gerenciamento de Dados

Os dados do Neo4j persistem entre reinicializações de contêiner e até mesmo atualizações de versão devido à configuração de volume Docker no arquivo docker-compose.yml:

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

Esses mapeamentos garantem que:

O diretório /data (contém todos os arquivos do banco de dados) persiste no seu host em ./neo4j-data
O diretório /logs persiste no seu host em ./neo4j-logs
O diretório /import (para importar arquivos de dados) persiste em ./neo4j-import

Você pode modificar esses caminhos no seu arquivo docker-compose.yml para armazenar dados em locais diferentes, se necessário.

Atualizando a Versão do Neo4j

Você pode alterar edições e versões do Neo4j sem perder dados:

Atualize a versão da imagem Neo4j em docker-compose.yml
Reinicie o contêiner com docker-compose down && docker-compose up -d neo4j
Reinitialize o esquema com npm run neo4j:init

Os dados persistirão durante esse processo, desde que os mapeamentos de volume permaneçam os mesmos.

Redefinição Completa do Banco de Dados

Se você precisar redefinir completamente seu banco de dados 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

Fazendo Backup de Dados

Para fazer backup dos seus dados Neo4j, você pode simplesmente copiar o diretório de dados:

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

Utilitários de CLI do Neo4j

O Memento MCP inclui utilitários de linha de comando para gerenciar operações do Neo4j:

Testando a Conexão

Teste a conexão com seu banco de dados 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

Inicializando o Esquema

Para operação normal, a inicialização do esquema Neo4j acontece automaticamente quando o Memento MCP se conecta ao banco de dados. Você não precisa executar nenhum comando manual para uso regular.

Os seguintes comandos são necessários apenas para cenários de desenvolvimento, teste ou personalização avançada:

# 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

Recursos Avançados

Busca Semântica

Encontre entidades semanticamente relacionadas com base no significado, em vez de apenas palavras-chave:

Embeddings Vetoriais: Entidades são automaticamente codificadas em espaço vetorial de alta dimensão usando os modelos de embedding da OpenAI
Similaridade de Cosseno: Encontre conceitos relacionados mesmo quando usam terminologia diferente
Limiares Configuráveis: Defina pontuações mínimas de similaridade para controlar a relevância dos resultados
Busca Cross-Modal: Consulte com texto para encontrar entidades relevantes, independentemente de como foram descritas
Suporte Multi-Modelo: Compatível com múltiplos modelos de embedding (OpenAI text-embedding-3-small/large)
Recuperação Contextual: Recupere informações com base no significado semântico, em vez de correspondências exatas de palavras-chave
Padrões Otimizados: Parâmetros ajustados para equilíbrio entre precisão e recall (limiar de similaridade 0.6, busca híbrida habilitada)
Busca Híbrida: Combina busca semântica e por palavras-chave para resultados mais abrangentes
Busca Adaptativa: O sistema escolhe inteligentemente entre busca apenas vetorial, apenas por palavras-chave ou híbrida com base nas características da consulta e nos dados disponíveis
Otimização de Desempenho: Prioriza a busca vetorial para compreensão semântica, mantendo mecanismos de fallback para resiliência
Processamento Ciente da Consulta: Ajusta a estratégia de busca com base na complexidade da consulta e nos embeddings de entidades disponíveis

Consciência Temporal

Rastreie o histórico completo de entidades e relações com recuperação de grafo em um ponto específico no tempo:

Histórico Completo de Versões: Cada alteração em uma entidade ou relação é preservada com carimbos de data/hora
Consultas em Ponto no Tempo: Recupere o estado exato do grafo de conhecimento em qualquer momento no passado
Rastreamento de Alterações: Registra automaticamente carimbos de data/hora createdAt, updatedAt, validFrom e validTo
Consistência Temporal: Mantenha uma visão historicamente precisa de como o conhecimento evoluiu
Atualizações Não Destrutivas: Atualizações criam novas versões em vez de sobrescrever dados existentes
Filtragem Baseada em Tempo: Filtre elementos do grafo com base em critérios temporais
Exploração de Histórico: Investigue como informações específicas mudaram ao longo do tempo

Decaimento de Confiança

Relações decaem automaticamente em confiança ao longo do tempo com base em meia-vida configurável:

Decaimento Baseado em Tempo: A confiança nas relações diminui naturalmente ao longo do tempo se não for reforçada
Meia-Vida Configurável: Defina a rapidez com que a informação se torna menos certa (padrão: 30 dias)
Pisos Mínimos de Confiança: Defina limiares para evitar decaimento excessivo de informações importantes
Metadados de Decaimento: Cada relação inclui informações detalhadas de cálculo de decaimento
Não Destrutivo: Valores originais de confiança são preservados junto com valores decaídos
Aprendizado por Reforço: Relações recuperam confiança quando reforçadas por novas observações
Flexibilidade de Tempo de Referência: Calcule o decaimento com base em tempos de referência arbitrários para análise histórica

Metadados Avançados

Suporte rico a metadados para entidades e relações com campos personalizados:

Rastreamento de Fonte: Registre onde a informação se originou (entrada do usuário, análise, fontes externas)
Níveis de Confiança: Atribua pontuações de confiança (0.0-1.0) a relações com base na certeza
Força da Relação: Indique importância ou força de relacionamentos (0.0-1.0)
Metadados Temporais: Rastreie quando a informação foi adicionada, modificada ou verificada
Tags Personalizadas: Adicione tags arbitrárias para classificação e filtragem
Dados Estruturados: Armazene dados estruturados complexos dentro de campos de metadados
Suporte a Consultas: Busque e filtre com base em propriedades de metadados
Esquema Extensível: Adicione campos personalizados conforme necessário sem modificar o modelo de dados principal

Ferramentas de API MCP

As seguintes ferramentas estão disponíveis para hosts de clientes LLM através do Protocolo de Contexto de Modelo:

Gerenciamento de Entidades

create_entities
- Crie múltiplas novas entidades no grafo de conhecimento
- Entrada: entities (array de objetos)
  - Cada objeto contém:
    - name (string): Identificador da entidade
    - entityType (string): Classificação de tipo
    - observations (string[]): Observações associadas
add_observations
- Adicione novas observações a entidades existentes
- Entrada: observations (array de objetos)
  - Cada objeto contém:
    - entityName (string): Entidade alvo
    - contents (string[]): Novas observações a adicionar
delete_entities
- Remova entidades e suas relações
- Entrada: entityNames (string[])
delete_observations
- Remova observações específicas de entidades
- Entrada: deletions (array de objetos)
  - Cada objeto contém:
    - entityName (string): Entidade alvo
    - observations (string[]): Observações a remover

Gerenciamento de Relações

create_relations
- Crie múltiplas novas relações entre entidades com propriedades aprimoradas
- Entrada: relations (array de objetos)
  - Cada objeto contém:
    - from (string): Nome da entidade de origem
    - to (string): Nome da entidade de destino
    - relationType (string): Tipo de relacionamento
    - strength (número, opcional): Força da relação (0.0-1.0)
    - confidence (número, opcional): Nível de confiança (0.0-1.0)
    - metadata (objeto, opcional): Campos de metadados personalizados
get_relation
- Obtenha uma relação específica com suas propriedades aprimoradas
- Entrada:
  - from (string): Nome da entidade de origem
  - to (string): Nome da entidade de destino
  - relationType (string): Tipo de relacionamento
update_relation
- Atualize uma relação existente com propriedades aprimoradas
- Entrada: relation (objeto):
  - Contém:
    - from (string): Nome da entidade de origem
    - to (string): Nome da entidade de destino
    - relationType (string): Tipo de relacionamento
    - strength (número, opcional): Força da relação (0.0-1.0)
    - confidence (número, opcional): Nível de confiança (0.0-1.0)
    - metadata (objeto, opcional): Campos de metadados personalizados
delete_relations
- Remova relações específicas do grafo
- Entrada: relations (array de objetos)
  - Cada objeto contém:
    - from (string): Nome da entidade de origem
    - to (string): Nome da entidade de destino
    - relationType (string): Tipo de relacionamento

Operações de Grafo

read_graph
- Leia o grafo de conhecimento inteiro
- Nenhuma entrada necessária
search_nodes
- Busque nós com base na consulta
- Entrada: query (string)
open_nodes
- Recupere nós específicos pelo nome
- Entrada: names (string[])

Busca Semântica

semantic_search
- Busque entidades semanticamente usando embeddings vetoriais e similaridade
- Entrada:
  - query (string): A consulta de texto para buscar semanticamente
  - limit (número, opcional): Máximo de resultados a retornar (padrão: 10)
  - min_similarity (número, opcional): Limiar mínimo de similaridade (0.0-1.0, padrão: 0.6)
  - entity_types (string[], opcional): Filtre resultados por tipos de entidade
  - hybrid_search (booleano, opcional): Combine busca por palavras-chave e semântica (padrão: true)
  - semantic_weight (número, opcional): Peso dos resultados semânticos na busca híbrida (0.0-1.0, padrão: 0.6)
- Recursos:
  - Seleciona inteligentemente o método de busca ideal (vetorial, por palavras-chave ou híbrido) com base no contexto da consulta
  - Lida graciosamente com consultas sem correspondências semânticas através de mecanismos de fallback
  - Mantém alto desempenho com decisões automáticas de otimização
get_entity_embedding
- Obtém o embedding vetorial para uma entidade específica
- Entrada:
  - entity_name (string): O nome da entidade para a qual obter o embedding

Recursos Temporais

get_entity_history
- Obtém o histórico completo de versões de uma entidade
- Entrada: entityName (string)
get_relation_history
- Obtém o histórico completo de versões de uma relação
- Entrada:
  - from (string): Nome da entidade de origem
  - to (string): Nome da entidade de destino
  - relationType (string): Tipo de relacionamento
get_graph_at_time
- Obtém o estado do grafo em um timestamp específico
- Entrada: timestamp (number): Timestamp Unix (milissegundos desde a época)
get_decayed_graph
- Obtém o grafo com valores de confiança decaídos no tempo
- Entrada: options (object, opcional):
  - reference_time (number): Timestamp de referência para cálculo de decaimento (milissegundos desde a época)
  - decay_factor (number): Substituição opcional do fator de decaimento

Configuração

Variáveis de Ambiente

Configure o Memento MCP com estas variáveis de ambiente:

# 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

Opções de Linha de Comando

As ferramentas CLI do Neo4j suportam as seguintes opções:

--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 OpenAI disponíveis:

text-embedding-3-small: Eficiente, econômico (1536 dimensões)
text-embedding-3-large: Maior precisão, mais caro (3072 dimensões)
text-embedding-ada-002: Modelo legado (1536 dimensões)

Configuração da API OpenAI

Para usar a busca semântica, você precisará configurar as credenciais da API OpenAI:

Obtenha uma chave de API em OpenAI
Configure seu ambiente com:

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

Nota: Para ambientes de teste, o sistema simulará a geração de embeddings se nenhuma chave de API for fornecida. No entanto, o uso de embeddings reais é recomendado para testes de integração.

Integração com o Claude Desktop

Configuração

Adicione isto ao seu 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 desenvolvimento local, você pode 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: Sempre especifique explicitamente o modelo de embedding na sua configuração do Claude Desktop para garantir um comportamento consistente.

Prompts de Sistema Recomendados

Para uma integração ideal com o Claude, adicione estas declarações ao seu 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.

Testando a Busca Semântica

Uma vez configurado, o Claude pode acessar os recursos de busca semântica por meio de linguagem natural:

Para criar entidades com 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 semanticamente:

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

Para recuperar informações específicas:

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

O poder dessa abordagem é que os usuários podem interagir naturalmente, enquanto o LLM lida com a complexidade de selecionar e usar as ferramentas de memória apropriadas.

Aplicações no Mundo Real

Os recursos de busca adaptativa do Memento fornecem benefícios práticos:

Versatilidade de Consulta: Os usuários não precisam se preocupar com a forma de formular perguntas - o sistema se adapta automaticamente a diferentes tipos de consulta
Resiliência a Falhas: Mesmo quando correspondências semânticas não estão disponíveis, o sistema pode recorrer a métodos alternativos sem intervenção do usuário
Eficiência de Desempenho: Ao selecionar inteligentemente o método de busca ideal, o sistema equilibra desempenho e relevância para cada consulta
Melhor Recuperação de Contexto: As conversas com LLM se beneficiam de uma melhor recuperação de contexto, pois o sistema pode encontrar informações relevantes em grafos de conhecimento complexos

Por exemplo, quando um usuário pergunta "O que você sabe sobre aprendizado de máquina?", o sistema pode recuperar entidades conceitualmente relacionadas, mesmo que elas não mencionem explicitamente "aprendizado de máquina" - talvez entidades sobre redes neurais, ciência de dados ou algoritmos específicos. Mas se a busca semântica produzir resultados insuficientes, o sistema ajusta automaticamente sua abordagem para garantir que informações úteis ainda sejam retornadas.

Solução de Problemas

Diagnóstico de Busca Vetorial

O Memento MCP inclui recursos de diagnóstico integrados para ajudar a solucionar problemas de busca vetorial:

Verificação de Embedding: O sistema verifica se as entidades têm embeddings válidos e os gera automaticamente se estiverem ausentes
Status do Índice Vetorial: Verifica se o índice vetorial existe e está no estado ONLINE
Busca de Fallback: Se a busca vetorial falhar, o sistema recorre à busca baseada em texto
Registro Detalhado: Registro abrangente das operações de busca vetorial para solução de problemas

Ferramentas de Depuração (quando DEBUG=true)

Ferramentas de diagnóstico adicionais ficam disponíveis quando o modo de depuração está habilitado:

diagnose_vector_search: Informações sobre o índice vetorial do Neo4j, contagens de embeddings e funcionalidade de busca
force_generate_embedding: Força a geração de um embedding para uma entidade específica
debug_embedding_config: Informações sobre a configuração atual do serviço de embeddings

Redefinição para Desenvolvedores

Para redefinir completamente seu banco de dados Neo4j durante o desenvolvimento:

# 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

Compilação e Desenvolvimento

# 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

Instalação

Instalação via Smithery

Para instalar o memento-mcp para Claude Desktop automaticamente via Smithery:

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

Instalação Global com npx

Você pode executar o Memento MCP diretamente usando npx sem instalá-lo globalmente:

npx -y @gannonh/memento-mcp

Este método é recomendado para uso com Claude Desktop e outros clientes compatíveis com MCP.

Instalação Local

Para desenvolvimento ou contribuição ao projeto:

# 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

Licença

MIT