MemoryMesh

Um servidor de grafo de conhecimento para modelos de IA, focado em RPGs baseados em texto e narrativas interativas.

GitHub
352
Experimente este MCPPatrocinado

Documentação

MemoryMesh

Release TypeScript License: MIT GitHub Stars

MemoryMesh é um servidor de grafo de conhecimento projetado para modelos de IA, com foco em RPGs baseados em texto e narrativas interativas. Ele ajuda a IA a manter uma memória consistente e estruturada entre conversas, permitindo interações mais ricas e dinâmicas.

O projeto é baseado no Knowledge Graph Memory Server do repositório de servidores MCP e mantém sua funcionalidade principal.

MemoryMesh MCP server

MseeP.ai Security Assessment

IMPORTANTE

Atualização v0.3.0: O SDK MCP foi atualizado da versão v1.0.4 para v1.25.2 para estar em conformidade com a especificação atual do Model Context Protocol (2025-11-25). Esta é uma atualização importante que traz compatibilidade com os clientes MCP mais recentes, incluindo Claude Desktop, ChatGPT, Cursor, Gemini e VS Code. Após a atualização, execute npm install para buscar as novas dependências.

Desde v0.2.7, o local padrão dos esquemas foi alterado para dist/data/schemas. Não se espera que este local mude no futuro, mas se você estiver atualizando de uma versão anterior, certifique-se de mover seus arquivos de esquema para o novo local.

Links Rápidos

Visão Geral

MemoryMesh é um servidor local de grafo de conhecimento que permite criar e gerenciar informações estruturadas para modelos de IA. Embora seja particularmente adequado para RPGs baseados em texto, seu design adaptável o torna útil para diversas aplicações, incluindo simulações de redes sociais, planejamento organizacional ou qualquer cenário que envolva dados estruturados.

Principais Recursos

  • Ferramentas Dinâmicas Baseadas em Esquemas: Defina sua estrutura de dados com esquemas, e o MemoryMesh gera automaticamente ferramentas para adicionar, atualizar e excluir dados.
  • Design Intuitivo de Esquemas: Crie esquemas que orientam a IA na geração e conexão de nós, usando campos obrigatórios, tipos enumerados e definições de relacionamentos.
  • Metadados para Orientação da IA: Use metadados para fornecer contexto e estrutura, ajudando a IA a entender o significado e os relacionamentos dentro dos seus dados.
  • Gerenciamento de Relacionamentos: Defina relacionamentos em seus esquemas para incentivar a IA a criar conexões (arestas) entre pontos de dados relacionados (nós).
  • Feedback Informativo: Fornece feedback de erros à IA, permitindo que ela aprenda com os erros e melhore suas interações com o grafo de conhecimento.
  • Suporte a Eventos: Um sistema de eventos rastreia operações, fornecendo insights sobre como o grafo de conhecimento está sendo modificado.

Nós

Os nós representam entidades ou conceitos dentro do grafo de conhecimento. Cada nó possui:

  • name: Um identificador único.
  • nodeType: O tipo do nó (por exemplo, npc, artifact, location), definido pelos seus esquemas.
  • metadata: Uma matriz de strings fornecendo detalhes descritivos sobre o nó.
  • weight: (Opcional) Um valor numérico entre 0 e 1 representando a força do relacionamento, com padrão de 1.

Exemplo de Nó:

    {
      "name": "Aragorn",
      "nodeType": "player_character",
      "metadata": [
        "Race: Human",
        "Class: Ranger",
        "Skills: Tracking, Swordsmanship",
        "Affiliation: Fellowship of the Ring"
      ]
    }

Arestas

As arestas representam relacionamentos entre nós. Cada aresta possui:

  • from: O nome do nó de origem.
  • to: O nome do nó de destino.
  • edgeType: O tipo de relacionamento (por exemplo, owns, located_in).
{
  "from": "Aragorn",
  "to": "Andúril",
  "edgeType": "owns"
}

Esquemas

Os esquemas são o coração do MemoryMesh. Eles definem a estrutura dos seus dados e impulsionam a geração automática de ferramentas.

Localização dos Arquivos de Esquema

Coloque seus arquivos de esquema (.schema.json) no diretório dist/data/schemas do seu projeto MemoryMesh compilado. O MemoryMesh detectará e processará automaticamente esses arquivos na inicialização.

Estrutura do Esquema

Nome do arquivo: [name].schema.json. Por exemplo, para um esquema que define um 'npc', o nome do arquivo seria add_npc.schema.json.

  • name - Identificador para o esquema e tipo de nó dentro da memória. IMPORTANTE: O nome do esquema deve começar com add_ para ser reconhecido.
  • description - Usado como descrição para a ferramenta add_<name>, fornecendo contexto para a IA. (As ferramentas delete e update têm uma descrição genérica)
  • properties - Cada propriedade inclui seu tipo, descrição e restrições adicionais.
    • property
      • type - Os valores suportados são string ou array.
      • description - Ajuda a orientar a IA sobre o propósito da entidade.
      • required - Booleano. Se true, a IA é forçada a fornecer esta propriedade ao criar um nó.
      • enum - Uma matriz de strings. Se presente, a IA deve escolher uma das opções fornecidas.
      • relationship - Define uma conexão com outro nó. Se uma propriedade for obrigatória e tiver um relacionamento, a IA sempre criará tanto o nó quanto a aresta correspondente.
        • edgeType - Tipo do relacionamento a ser criado.
        • description - Ajuda a orientar a IA sobre o propósito do relacionamento.
  • additionalProperties - Booleano. Se true, permite que a IA adicione atributos extras além daqueles definidos como obrigatórios ou opcionais.
Exemplo de Esquema (add_npc.schema.json):
{
  "name": "add_npc",
  "description": "Schema for adding an NPC to the memory" ,
  "properties": {
    "name": {
      "type": "string",
      "description": "A unique identifier for the NPC",
      "required": true
    },
    "race": {
      "type": "string",
      "description": "The species or race of the NPC",
      "required": true,
      "enum": [
        "Human",
        "Elf",
        "Dwarf",
        "Orc",
        "Goblin"
      ]
    },
    "currentLocation": {
      "type": "string",
      "description": "The current location of the NPC",
      "required": true,
      "relationship": {
        "edgeType": "located_in",
        "description": "The current location of the NPC"
      }
    }
  },
  "additionalProperties": true
}

Com base neste esquema, o MemoryMesh cria automaticamente:

  • add_npc: Para adicionar novos nós de NPC.
  • update_npc: Para modificar nós de NPC existentes.
  • delete_npc: Para remover nós de NPC.

O MemoryMesh inclui 11 esquemas pré-construídos projetados para RPGs baseados em texto, fornecendo uma base pronta para uso no desenvolvimento de jogos.

Ferramenta SchemaManager

O MemoryMesh inclui uma ferramenta SchemaManager para simplificar a criação e edição de esquemas. Ela fornece uma interface visual, facilitando a definição de suas estruturas de dados sem escrever JSON diretamente.

image

Ferramentas Dinâmicas

O MemoryMesh simplifica a interação com seu grafo de conhecimento por meio de ferramentas dinâmicas. Essas ferramentas não são codificadas manualmente, mas são geradas automaticamente diretamente das suas definições de esquema. Isso significa que quando você define a estrutura dos seus dados usando esquemas, o MemoryMesh cria inteligentemente um conjunto de ferramentas adaptadas para trabalhar com essa estrutura de dados específica.

Pense assim: Você fornece um modelo (o esquema), e o MemoryMesh constrói automaticamente as ferramentas necessárias para criar, modificar e remover elementos com base nesse modelo.

Como funciona nos bastidores?

O MemoryMesh possui um sistema inteligente que lê suas definições de esquema. Ele analisa a estrutura que você definiu, incluindo as propriedades das suas entidades e seus relacionamentos. Com base nessa análise, ele cria automaticamente um conjunto de ferramentas para cada tipo de entidade:

  • add_<entity>: Uma ferramenta para criar novas instâncias de uma entidade.
  • update_<entity>: Uma ferramenta para modificar entidades existentes.
  • delete_<entity>: Uma ferramenta para remover entidades.

Essas ferramentas são então disponibilizadas através de um hub central dentro do MemoryMesh, garantindo que possam ser facilmente acessadas e usadas por qualquer cliente ou IA conectado.

Em essência, o sistema de ferramentas dinâmicas do MemoryMesh fornece uma maneira poderosa e eficiente de gerenciar seu grafo de conhecimento, permitindo que você se concentre no conteúdo e na lógica da sua aplicação, em vez dos mecanismos subjacentes de manipulação de dados.

Arquivo de Memória

Por padrão, os dados são armazenados em um arquivo JSON em dist/data/memory.json.

Memory Viewer

O Memory Viewer é uma ferramenta separada projetada para ajudar você a visualizar e inspecionar o conteúdo do grafo de conhecimento gerenciado pelo MemoryMesh. Ele fornece uma interface amigável para explorar nós, arestas e suas propriedades.

Principais Recursos:
  • Visualização de Grafo: Veja o grafo de conhecimento como um diagrama interativo de nós e links.
  • Inspeção de Nós: Selecione nós para ver seu nodeType, metadados e arestas conectadas.
  • Exploração de Arestas: Examine relacionamentos entre nós, incluindo edgeType e direção.
  • Busca e Filtragem: Encontre rapidamente nós específicos ou filtre-os por tipo.
  • Visualização em Tabela: Permite encontrar e inspecionar facilmente nós e arestas específicos, ou todos de uma vez.
  • Visualização JSON Bruto: Permite visualizar os dados JSON brutos do arquivo de memória.
  • Painel de Estatísticas: Fornece métricas e informações principais sobre o grafo de conhecimento: total de nós, total de arestas, tipos de nós e tipos de arestas.
  • Busca e Filtro: Permite filtrar por tipo de nó ou tipo de aresta e filtrar se deseja mostrar nós, arestas ou ambos.
Acessando o Memory Viewer

O Memory Viewer é um aplicativo web independente. Discussão do Memory Viewer

Usando o Memory Viewer
  • Selecionar Arquivo de Memória: No Memory Viewer, clique no botão "Select Memory File".
  • Escolher Arquivo: Navegue até o diretório do seu projeto MemoryMesh e selecione o arquivo memory.json (localizado em dist/data/memory.json por padrão).
  • Explorar: O Memory Viewer carregará e exibirá o conteúdo do seu grafo de conhecimento.

Fluxo de Memória

image

Prompt

Para obter resultados ideais, use o recurso "Projects" do Claude com instruções personalizadas. Aqui está um exemplo de prompt com o qual você pode começar:

You are a helpful AI assistant managing a knowledge graph for a text-based RPG. You have access to the following tools: add_npc, update_npc, delete_npc, add_location, update_location, delete_location, and other tools for managing the game world.

When the user provides input, first process it using your available tools to update the knowledge graph. Then, respond in a way that is appropriate for a text-based RPG.

Você também pode instruir a IA a realizar ações específicas diretamente no chat.

Experimente diferentes prompts para encontrar o que funciona melhor para o seu caso de uso!

Exemplo

  1. Um exemplo simples com instruções personalizadas.
  2. Um exemplo apenas para fins de exemplo, com visualização (NÃO faz parte da funcionalidade)

Adicione algumas cidades, alguns npcs, alguns locais ao redor da cidade para explorar, esconda um artefato ou dois em algum lugar

image

Instalação

Pré-requisitos

  • Node.js: Versão 18 ou superior. Você pode baixá-lo em nodejs.org.
  • npm: Geralmente incluído com o Node.js.
  • Claude for Desktop: Certifique-se de ter a versão mais recente instalada em claude.ai/download.

Etapas de Instalação

  1. Clone o Repositório:

    git clone https://github.com/CheMiguel23/memorymesh.git
cd memorymesh

  2. Instale as Dependências:

    npm install

  3. Compile o Projeto:

    npm run build

    Este comando compila o código TypeScript em JavaScript no diretório dist e copia arquivos de esquema e dados de exemplo para ele também.

  4. Verifique a Cópia dos Arquivos (Opcional):

    • O processo de compilação deve copiar automaticamente a pasta data para dist.
    • Verifique se dist/data existe e contém arquivos .json. Também verifique se dist/data/schemas existe e contém arquivos .schema.json.

  5. Configure o Claude Desktop:

    Abra seu arquivo de configuração do Claude Desktop:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • Adicione uma entrada para memorymesh na seção mcpServers. Você pode escolher uma das seguintes opções de configuração:
    "mcpServers": {
  "memorymesh": {
    "command": "node", 
    "args": ["/ABSOLUTE/PATH/TO/YOUR/PROJECT/memorymesh/dist/index.js"]
  }
}
    • Substitua /ABSOLUTE/PATH/TO/YOUR/PROJECT/ pelo caminho absoluto real para o diretório do seu projeto memorymesh.
    • Exemplo (macOS): 
      "command": "node",
"args": ["/Users/yourusername/Projects/memorymesh/dist/index.js"]
    • Exemplo (Windows): 
      "command": "node",
"args": ["C:\\Projects\\memorymesh\\dist\\index.js"]

  6. Reinicie o Claude Desktop: Reinicie completamente o Claude Desktop para que as alterações entrem em vigor.

Verificar Instalação

  1. Inicie o Claude Desktop.
  2. Abra um novo chat.
  3. Procure o ícone do plugin MCP no canto superior direito. Se estiver lá, sua configuração provavelmente está correta.
  4. Clique no ícone . Você deve ver "memorymesh" na lista de servidores conectados.
  5. Clique no ícone . Se você vir ferramentas listadas (por exemplo, add_npc, update_npc, etc.), seu servidor está funcionando e expondo as ferramentas corretamente.

Atualização

Antes de atualizar, certifique-se de fazer backup do diretório dist/data para evitar a perda dos seus dados de memória.

Solução de Problemas

  • Servidor não aparecendo no Claude:

    • Verifique novamente os caminhos no seu claude_desktop_config.json. Certifique-se de que são caminhos absolutos e corretos.
    • Confirme que o diretório dist existe e contém os arquivos JavaScript compilados, incluindo index.js.
    • Verifique os logs do Claude Desktop para erros:
      • macOS: ~/Library/Logs/Claude/mcp-server-memorymesh.log (e mcp.log)
      • Windows: (Provavelmente em uma pasta Logs dentro de %AppData%\Claude)

  • Ferramentas não aparecendo:

    • Certifique-se de que seu comando npm run build foi concluído sem erros.
    • Verifique se seus arquivos de esquema estão corretamente posicionados em dist/data/schemas e seguem a convenção de nomenclatura correta (add_[entity].schema.json).
    • Verifique a saída do console do seu servidor ou os logs para quaisquer erros durante a inicialização.

Configuração Avançada

O MemoryMesh oferece várias maneiras de personalizar seu comportamento além da configuração básica:

Variáveis

Você pode substituir as configurações padrão usando em /config/config.ts

  • MEMORY_FILE: Especifica o caminho para o arquivo JSON usado para armazenar os dados do grafo de conhecimento. (Padrão: dist/data/memory.json)
  • SCHEMAS_DIR: Caminho para o diretório de arquivos de esquema. (Padrão: dist/data/schemas/memory.json)

Limitações

  1. Exclusão de Nós: A IA pode hesitar em excluir nós do grafo de conhecimento. Incentive-a por meio de prompts, se necessário.

  2. Conhecimento Conflitante: O MemoryMesh atualmente usa uma abordagem de "última escrita vence" para lidar com dados. Se informações conflitantes forem fornecidas sobre a mesma entidade, a atualização mais recente substituirá os valores anteriores. Aqui estão estratégias para gerenciar informações conflitantes:

    Abordagens Atuais:

    • Use metadados para rastrear fontes: Adicione entradas de metadados como "Source: Character testimony" ou "Source: Official records" para rastrear de onde as informações vieram.
    • Use metadados temporais: Inclua carimbos de data/hora ou marcadores temporais narrativos (por exemplo, "As of Chapter 3") nos metadados para rastrear quando as informações eram válidas.
    • Crie nós separados para perspectivas: Para informações subjetivas ou disputadas, crie nós separados representando diferentes pontos de vista (por exemplo, rumor_about_villain vs truth_about_villain).
    • Use pesos de aresta: Aproveite a propriedade opcional weight nas arestas (intervalo 0-1) para indicar confiança ou confiabilidade dos relacionamentos.

    Exemplo - Rastreando informações incertas:

    {
  "name": "VillainOrigin_Rumor",
  "nodeType": "information",
  "metadata": [
    "Source: Tavern gossip",
    "Reliability: Low",
    "Claims: Villain came from the northern mountains"
  ]
}

    Considerações Futuras: Para aplicações que exigem resolução sofisticada de conflitos, considere implementar uma camada personalizada que:

    • Mantenha o histórico de versões das alterações nos nós
    • Rastreie a proveniência (fonte) de cada informação
    • Implemente pontuações de confiança para afirmações
    • Suporte períodos de validade temporal para fatos

Contribuição

Contribuições, feedback e ideias são bem-vindos! Este projeto é uma exploração pessoal sobre a integração de dados estruturados com capacidades de raciocínio de IA. Contribuições, feedback e ideias são bem-vindos para avançá-lo ou inspirar novos projetos.