Memory

Sistema de memória persistente baseado em grafo de conhecimento

GitHub
90.5k

Documentação

Servidor de Memória com Knowledge Graph

Uma implementação básica de memória persistente usando um knowledge graph local. Isso permite que o Claude lembre informações sobre o usuário entre conversas.

Publicado no npm como @modelcontextprotocol/server-memory.

Conceitos Principais

Entidades

Entidades são os nós primários no knowledge graph. 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
  • Anexadas 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"
  ]
}

API

Ferramentas

  • create_entities

    • Cria múltiplas novas entidades no knowledge graph
    • 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
    • Falha se a entidade de origem ou destino não existir

  • 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
    • Nenhum erro se uma entidade não existir; a resposta informa quais nomes não foram encontrados

  • 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
    • Nenhum erro se uma observação não existir; a resposta informa quantas foram excluídas

  • 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
    • Nenhum erro se uma relação não existir; a resposta informa quantas foram excluídas

  • read_graph

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

  • search_nodes

    • Busca 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 por nome
    • Entrada: names (string[])
    • Retorna:
      • Entidades solicitadas
      • Relações entre as entidades solicitadas
    • Ignora silenciosamente nós inexistentes

Recursos

  • knowledge-graph (memory://knowledge-graph)
    • O knowledge graph completo como um Recurso MCP legível
    • Tipo MIME: application/json
    • Retorna a mesma estrutura de read_graph (entidades e relações)
    • Ferramentas de mutação (create_entities, create_relations, add_observations, delete_entities, delete_observations, delete_relations) emitem notifications/resources/updated para este URI, para que clientes inscritos vejam mudanças em tempo real

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"
      ]
    }
  }
}

No Windows, use cmd /c para iniciar npx:

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-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.jsonl"
      }
    }
  }
}

No Windows, use:

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

Instruções de Instalação no VS Code

Para instalação rápida, use um dos botões de instalação com um clique abaixo:

Install with NPX in VS Code Install with NPX in VS Code Insiders

Install with Docker in VS Code Install with Docker in VS Code Insiders

Para instalação manual, você pode configurar o servidor MCP usando um destes métodos:

Método 1: Configuração do Usuário (Recomendado) Adicione a configuração ao seu arquivo de configuração MCP no nível do usuário. Abra a Paleta de Comandos (Ctrl + Shift + P) e execute MCP: Open User Configuration. Isso abrirá seu arquivo mcp.json de usuário onde você pode adicionar a configuração do servidor.

Método 2: Configuração do Workspace Alternativamente, você pode adicionar a configuração a um arquivo chamado .vscode/mcp.json no seu workspace. Isso permitirá que você compartilhe a configuração com outras pessoas.

Para mais detalhes sobre a configuração do MCP no VS Code, consulte a documentação oficial do MCP do VS Code.

NPX

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

No Windows, use:

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

Docker

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

Prompt do Sistema

O prompt para utilizar a 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
     c) Store facts about them as observations

Compilação

Docker:

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

Para Conscientização: um volume mcp/memory anterior contém um arquivo index.js que pode ser sobrescrito pelo novo contêiner. Se você estiver usando um volume docker para armazenamento, exclua o arquivo index.js do volume docker antigo antes de iniciar o novo contêiner.

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.