mcp-memory-graph

mcp-memory-graph

Um servidor MCP de memória sensível ao contexto para Claude Code e qualquer agente de IA compatível com MCP.

Vai além da busca vetorial básica ao adicionar ponderação por autoridade, detecção de conflitos e arestas de relacionamento tipadas entre memórias — para que seu agente sempre recupere a resposta certa quando as fontes discordam.

Inspirado na arquitetura de mecanismo de contexto descrita em Unblocked's "How a Context Engine Actually Works".

---

Por que isso existe

Servidores MCP de memória padrão armazenam e recuperam memórias por similaridade semântica. Isso funciona até você ter memórias conflitantes — uma instrução antiga dizendo uma coisa e uma nova dizendo outra. Sem ponderação por autoridade, o agente recupera aquela que está semanticamente mais próxima da consulta, não a mais confiável.

mcp-memory-graph resolve isso com três mecanismos:

Problema	Solução
Todas as memórias tratadas igualmente	Níveis de prioridade: high / medium / low → pontuações de autoridade 1.0 / 0.6 / 0.3
Memórias desatualizadas persistem silenciosamente	Rastreamento de substituição: memórias antigas marcadas como status=superseded com arestas tipadas
Duplicatas se acumulam com o tempo	Detecção de conflitos antes de cada armazenamento; resolução automática por autoridade

---

Instalação

pip install mcp-memory-graph

Ou execute diretamente:

git clone https://github.com/RetroRobAI/mcp-memory-graph
cd mcp-memory-graph
pip install -r requirements.txt
python server.py

---

Configuração do Claude Code

Adicione em ~/.claude.json sob mcpServers:

"mcp-memory-graph": {
  "type": "stdio",
  "command": "mcp-memory-graph",
  "env": {
    "MEMORY_GRAPH_DB_PATH": "/path/to/memories.db"
  }
}

Ou com o script bruto:

"mcp-memory-graph": {
  "type": "stdio",
  "command": "python",
  "args": ["/path/to/mcp-memory-graph/server.py"],
  "env": {
    "MEMORY_GRAPH_DB_PATH": "/path/to/memories.db"
  }
}

---

Migrando de um serviço de memória existente

Se você já possui um serviço de memória existente (mcp-memory-service, Mem0 ou um sistema de memória baseado em Markdown), você pode importar suas memórias para o mcp-memory-graph usando o script de migração incluído.

A migração é manual e opcional — ela nunca é executada automaticamente. Nada é gravado até que você confirme explicitamente.

Execute o script de migração

python -m mcp_memory_graph.migrate

O script irá:

1. Detectar automaticamente qualquer banco de dados SQLite mcp-memory-service existente
2. Perguntar se você tem um diretório de memórias em Markdown para importar
3. Mostrar quantas memórias foram encontradas
4. Apresentar três opções:
   • [1] Migrar — importar tudo para o mcp-memory-graph
   • [2] Executar em paralelo — iniciar o mcp-memory-graph do zero, mantendo seu serviço antigo em execução
   • [3] Pular — não fazer nada
5. Pedir uma confirmação final antes de gravar qualquer coisa

Seu serviço de memória existente nunca é modificado — o script apenas lê dele.

---

Configuração

Todas as configurações via variáveis de ambiente:

Variável	Padrão	Descrição
MEMORY_GRAPH_DB_PATH	~/.mcp-memory-graph/memories.db	Caminho do banco de dados SQLite
MEMORY_GRAPH_MODEL	all-MiniLM-L6-v2	Modelo sentence-transformers
MEMORY_GRAPH_DIM	384	Dimensões do embedding
MEMORY_GRAPH_CONFLICT_THRESHOLD	0.85	Similaridade de cosseno acima da qual memórias são sinalizadas como conflitantes
MEMORY_GRAPH_DEFAULT_RESULTS	10	Limite padrão de recuperação

---

Ferramentas

Ferramenta	Descrição
store_memory	Armazenar com detecção de conflitos e resolução automática opcional
retrieve_memories	Busca semântica classificada por similaridade × autoridade
check_conflicts	Visualizar conflitos antes de armazenar
update_memory	Atualizar conteúdo/prioridade com rastreamento de substituição
delete_memory	Exclusão suave (preserva o histórico)
add_memory_edge	Adicionar manualmente relacionamento tipado
get_related_memories	Percorrer o grafo de relacionamentos de uma memória
list_memories	Listar com filtros (status, tipo, prioridade)

---

Sistema de prioridade

priority="high"    # authority_score=1.0  — explicit instructions, confirmed preferences
priority="medium"  # authority_score=0.6  — inferred preferences, reference data
priority="low"     # authority_score=0.3  — session summaries, historical context

Classificação de recuperação: weighted_score = 1 - (distance / (authority_score + 0.001) / 10)

Uma memória de alta autoridade será classificada acima de uma de baixa autoridade semanticamente mais próxima quando suas pontuações de similaridade estiverem dentro de ~3x uma da outra.

---

Tipos de aresta

• supersedes — esta memória substitui outra
• relates_to — conectada, mas não conflitante
• contradicts — explicitamente conflitante, não resolvida
• referenced_by — outra memória cita esta

---

Stack

• sqlite-vec — busca de similaridade vetorial
• sentence-transformers — embeddings locais, sem necessidade de chave de API
• FastMCP — framework de servidor MCP

---

Licença

MIT