DuckDB Knowledge Graph Memory

MCP DuckDB Knowledge Graph Memory Server

Uma versão fork do servidor oficial Knowledge Graph Memory Server.

Instalação

Instalando via Smithery

Para instalar o DuckDB Knowledge Graph Memory Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @IzumiSy/mcp-duckdb-memory-server --client claude

Instalação manual

Caso contrário, adicione @IzumiSy/mcp-duckdb-memory-server no seu claude_desktop_config.json manualmente (MEMORY_FILE_PATH é opcional)

{
  "mcpServers": {
    "graph-memory": {
      "command": "npx",
      "args": [
        "-y",
        "@izumisy/mcp-duckdb-memory-server"
      ],
      "env": {
        "MEMORY_FILE_PATH": "/path/to/your/memory.data"
      }
    }
  }
}

Os dados armazenados nesse caminho são um arquivo de banco de dados DuckDB.

Docker

Compilar

docker build -t mcp-duckdb-graph-memory .

Executar

docker run -dit mcp-duckdb-graph-memory

Uso

Use a instrução de exemplo abaixo

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 search relevant information from your knowledge graph
   - Create a search query from user words, and search things from "memory". If nothing matches, try to break down words in the query at first ("A B" to "A" and "B" for example).
   - 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

Motivação

Este projeto aprimora o servidor original MCP Knowledge Graph Memory Server substituindo seu backend pelo DuckDB.

Por que DuckDB?

O servidor original MCP Knowledge Graph Memory Server usava um arquivo JSON como armazenamento de dados e realizava buscas em memória. Embora essa abordagem funcione bem para conjuntos de dados pequenos, ela apresenta vários desafios:

1. Desempenho: O desempenho da busca em memória degrada à medida que o conjunto de dados cresce
2. Escalabilidade: O uso de memória aumenta significativamente ao lidar com grandes números de entidades e relações
3. Flexibilidade de Consultas: Consultas complexas e buscas condicionais são difíceis de implementar
4. Integridade dos Dados: Garantir atomicidade para transações e operações CRUD é desafiador

O DuckDB foi escolhido para resolver esses desafios:

• Processamento Rápido de Consultas: O DuckDB é otimizado para consultas analíticas e tem bom desempenho mesmo com grandes conjuntos de dados
• Interface SQL: SQL padrão pode ser usado para executar consultas complexas facilmente
• Suporte a Transações: Suporta processamento de transações para manter a integridade dos dados
• Capacidades de Indexação: Permite a criação de índices para melhorar o desempenho das buscas
• Banco de Dados Embutido: Funciona dentro da aplicação sem exigir um servidor de banco de dados externo

Detalhes de Implementação

Esta implementação usa o DuckDB como sistema de armazenamento backend, focando em dois aspectos principais:

Estrutura do Banco de Dados

O grafo de conhecimento é armazenado em uma estrutura de banco de dados relacional, conforme mostrado abaixo:

erDiagram
    ENTITIES {
        string name PK
        string entityType
    }
    OBSERVATIONS {
        string entityName FK
        string content
    }
    RELATIONS {
        string from_entity FK
        string to_entity FK
        string relationType
    }

    ENTITIES ||--o{ OBSERVATIONS : "has"
    ENTITIES ||--o{ RELATIONS : "from"
    ENTITIES ||--o{ RELATIONS : "to"

Este design de esquema permite armazenamento e recuperação eficientes dos componentes do grafo de conhecimento, mantendo as relações entre entidades, observações e relações.

Implementação de Busca Difusa (Fuzzy Search)

A implementação combina consultas SQL com Fuse.js para busca flexível de entidades:

• Consultas SQL do DuckDB recuperam os dados base do banco de dados
• O Fuse.js fornece capacidades de correspondência difusa (fuzzy matching) sobre os dados recuperados
• Essa abordagem híbrida permite tanto consultas estruturadas quanto correspondência flexível de texto
• Os resultados da busca incluem correspondências exatas e parciais, classificadas por relevância

Desenvolvimento

Configuração

pnpm install

Testes

pnpm test

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.