Knowledge Graph Memory Server

Permite memória persistente para Claude usando um grafo de conhecimento armazenado em arquivos JSON locais.

GitHub
52
Experimente este MCPPatrocinado

Documentação

Knowledge Graph Memory Server

smithery badge

Uma implementação básica de memória persistente usando um grafo de conhecimento local. Isso permite que o Claude lembre informações sobre o usuário entre conversas e aprenda com erros passados por meio de um sistema de lições.

Knowledge Graph Memory Server MCP server

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

Exemplo:

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

Relações

Relações definem conexões direcionadas entre entidades. Elas são sempre armazenadas na voz ativa e descrevem como as entidades interagem ou se relacionam entre si.

Exemplo:

{
  "from": "John_Smith",
  "to": "Anthropic",
  "relationType": "works_at"
}

Observações

Observações são informações discretas sobre uma entidade. Elas são:

  • Armazenadas como strings
  • Vinculadas a entidades específicas
  • Podem ser adicionadas ou removidas independentemente
  • Devem ser atômicas (um fato por observação)

Exemplo:

{
  "entityName": "John_Smith",
  "observations": [
    "Speaks fluent Spanish",
    "Graduated in 2019",
    "Prefers morning meetings"
  ]
}

Lições

Lições são entidades especiais que capturam conhecimento sobre erros e suas soluções. Cada lição possui:

  • Um nome único (identificador)
  • Informações do padrão de erro (tipo, mensagem, contexto)
  • Etapas de solução e verificação
  • Acompanhamento da taxa de sucesso
  • Contexto ambiental
  • Metadados (severidade, carimbos de data/hora, frequência)

Exemplo:

{
  "name": "NPM_VERSION_MISMATCH_01",
  "entityType": "lesson",
  "observations": [
    "Error occurs when using incompatible package versions",
    "Affects Windows environments specifically",
    "Resolution requires version pinning"
  ],
  "errorPattern": {
    "type": "dependency",
    "message": "Cannot find package @shadcn/ui",
    "context": "package installation"
  },
  "metadata": {
    "severity": "high",
    "environment": {
      "os": "windows",
      "nodeVersion": "18.x"
    },
    "createdAt": "2025-02-13T13:21:58.523Z",
    "updatedAt": "2025-02-13T13:22:21.336Z",
    "frequency": 1,
    "successRate": 1.0
  },
  "verificationSteps": [
    {
      "command": "pnpm add shadcn@latest",
      "expectedOutput": "Successfully installed shadcn",
      "successIndicators": ["added shadcn"]
    }
  ]
}

API

Ferramentas

  • create_entities

    • Cria 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
    • Ignora entidades com nomes existentes

  • create_relations

    • Cria múltiplas novas relações entre entidades
    • 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 na voz ativa
    • Ignora relações duplicadas

  • add_observations

    • Adiciona novas observações a entidades existentes
    • Entrada: observations (array de objetos)
      • Cada objeto contém:
        • entityName (string): Entidade de destino
        • contents (string[]): Novas observações a adicionar
    • Retorna observações adicionadas por entidade
    • Falha se a entidade não existir

  • delete_entities

    • Remove entidades e suas relações
    • Entrada: entityNames (string[])
    • Exclusão em cascata das relações associadas
    • Operação silenciosa se a entidade não existir

  • delete_observations

    • Remove observações específicas de entidades
    • Entrada: deletions (array de objetos)
      • Cada objeto contém:
        • entityName (string): Entidade de destino
        • observations (string[]): Observações a remover
    • Operação silenciosa se a observação não existir

  • delete_relations

    • Remove 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ção silenciosa se a relação não existir

  • read_graph

    • Lê todo o grafo de conhecimento
    • Nenhuma entrada necessária
    • Retorna a estrutura completa do grafo com todas as entidades e relações

  • search_nodes

    • Busca por nós com base na consulta
    • Entrada: query (string)
    • Busca em:
      • Nomes de entidades
      • Tipos de entidades
      • Conteúdo das observações
    • Retorna entidades correspondentes e suas relações

  • open_nodes

    • Recupera nós específicos pelo nome
    • Entrada: names (string[])
    • Retorna:
      • Entidades solicitadas
      • Relações entre as entidades solicitadas
    • Ignora silenciosamente nós inexistentes

Ferramentas de Gerenciamento de Lições

  • create_lesson

    • Cria uma nova lição a partir de um erro e sua solução
    • Entrada: lesson (objeto)
      • Contém:
        • name (string): Identificador único
        • entityType (string): Deve ser "lesson"
        • observations (string[]): Notas sobre o erro e a solução
        • errorPattern (objeto): Detalhes do erro
          • type (string): Categoria do erro
          • message (string): Mensagem de erro
          • context (string): Onde o erro ocorreu
          • stackTrace (string, opcional): Stack trace
        • metadata (objeto): Informações adicionais
          • severity ("low" | "medium" | "high" | "critical")
          • environment (objeto): Detalhes do sistema
          • frequency (number): Vezes encontrado
          • successRate (number): Taxa de sucesso da solução
        • verificationSteps (array): Verificação da solução
          • Cada etapa contém:
            • command (string): Ação a ser tomada
            • expectedOutput (string): Resultado esperado
            • successIndicators (string[]): Marcadores de sucesso
    • Inicializa automaticamente os carimbos de data/hora dos metadados
    • Valida todos os campos obrigatórios

  • find_similar_errors

    • Encontra erros semelhantes e suas soluções
    • Entrada: errorPattern (objeto)
      • Contém:
        • type (string): Categoria do erro
        • message (string): Mensagem de erro
        • context (string): Contexto do erro
    • Retorna lições correspondentes ordenadas por taxa de sucesso
    • Usa correspondência difusa para mensagens de erro

  • update_lesson_success

    • Atualiza o acompanhamento de sucesso de uma lição
    • Entrada:
      • lessonName (string): Lição a atualizar
      • success (boolean): Se a solução funcionou
    • Atualiza:
      • Taxa de sucesso (média ponderada)
      • Contador de frequência
      • Carimbo de data/hora da última atualização

  • get_lesson_recommendations

    • Obtém lições relevantes para o contexto atual
    • Entrada: context (string)
    • Busca em:
      • Tipo de erro
      • Mensagem de erro
      • Contexto do erro
      • Observações da lição
    • Retorna lições ordenadas por:
      • Relevância do contexto
      • Taxa de sucesso
    • Inclui detalhes completos da solução

Gerenciamento de Arquivos

O servidor agora lida com dois tipos de arquivos:

  • memory.json: Armazena entidades e relações básicas
  • lesson.json: Armazena entidades de lição com padrões de erro

Os arquivos são divididos automaticamente se excederem 1000 linhas para manter o desempenho.

Configuração do Cliente MCP do Cursor

Para integrar este servidor de memória com o cliente MCP do Cursor, siga estas etapas:

  1. Clone o Repositório:
git clone [repository-url]
cd [repository-name]
  1. Instale as Dependências:
pnpm install
  1. Compile o Projeto:
pnpm build
  1. Configure o Servidor:
  • Localize o caminho completo para o arquivo do servidor compilado: /path/to/the/dist/index.js
  • Inicie o servidor usando Node.js: node /path/to/the/dist/index.js
  1. Ative no Cursor:
  • Use o atalho de teclado Ctrl+Shift+P
  • Digite "reload window" e selecione-o
  • Aguarde alguns segundos para o servidor MCP ativar
  • Selecione o tipo stdio quando solicitado

O servidor de memória agora deve estar integrado ao seu cliente MCP do Cursor e pronto para uso.

Uso com Claude Desktop

Configuração

Adicione isto ao seu claude_desktop_config.json:

Docker

{
  "mcpServers": {
    "memory": {
      "command": "docker",
      "args": ["run", "-i", "-v", "claude-memory:/app/dist", "--rm", "mcp/memory"]
    }
  }
}

NPX

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ]
    }
  }
}

NPX com configuração personalizada

O servidor pode ser configurado usando as seguintes variáveis de ambiente:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-memory"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/custom/memory.json"
      }
    }
  }
}
  • MEMORY_FILE_PATH: Caminho para o arquivo JSON de armazenamento de memória (padrão: memory.json no diretório do servidor)

Prompt do Sistema

O prompt para utilização da memória depende do caso de uso. Alterar o prompt ajudará o modelo a determinar a frequência e os tipos de memórias criadas.

Aqui está um exemplo de prompt para personalização de chat. Você pode usar este prompt no campo "Instruções Personalizadas" de um Projeto Claude.ai.

Follow these steps for each interaction:

1. User Identification:
   - You should assume that you are interacting with default_user
   - If you have not identified default_user, proactively try to do so.

2. Memory Retrieval:
   - Always begin your chat by saying only "Remembering..." and retrieve all relevant information from your knowledge graph
   - Always refer to your knowledge graph as your "memory"

3. Memory
   - While conversing with the user, be attentive to any new information that falls into these categories:
     a) Basic Identity (age, gender, location, job title, education level, etc.)
     b) Behaviors (interests, habits, etc.)
     c) Preferences (communication style, preferred language, etc.)
     d) Goals (goals, targets, aspirations, etc.)
     e) Relationships (personal and professional relationships up to 3 degrees of separation)

4. Memory Update:
   - If any new information was gathered during the interaction, update your memory as follows:
     a) Create entities for recurring organizations, people, and significant events
     b) Connect them to the current entities using relations
     b) Store facts about them as observations

Compilação

Docker:

docker build -t mcp/memory -f src/memory/Dockerfile .

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.

Novas Ferramentas

  • create_lesson

    • Cria uma nova lição a partir de um erro e sua solução
    • Entrada: lesson (objeto)
      • Contém padrão de erro, etapas de solução e metadados
      • Rastreia automaticamente o tempo de criação e atualizações
      • Verifica se as etapas da solução estão completas

  • find_similar_errors

    • Encontra erros semelhantes e suas soluções
    • Entrada: errorPattern (objeto)
      • Contém tipo de erro, mensagem e contexto
      • Retorna lições correspondentes ordenadas por taxa de sucesso
      • Inclui soluções relacionadas e etapas de verificação

  • update_lesson_success

    • Atualiza o acompanhamento de sucesso de uma lição
    • Entrada:
      • lessonName (string): Lição a atualizar
      • success (boolean): Se a solução funcionou
    • Atualiza a taxa de sucesso e as métricas de frequência

  • get_lesson_recommendations

    • Obtém lições relevantes para o contexto atual
    • Entrada: context (string)
    • Retorna lições ordenadas por relevância e taxa de sucesso
    • Inclui detalhes completos da solução e etapas de verificação

GRANDES CRÉDITOS AO DONO DESTE REPO PELO CÓDIGO BASE, EU O MELHOREI COM LIÇÕES E GERENCIAMENTO DE ARQUIVOS

Muito obrigado! https://github.com/modelcontextprotocol/servers jerome3o-anthropic https://github.com/modelcontextprotocol/servers/tree/main/src/memory