KuzuMem-MCP

Uma ferramenta MCP de banco de memória distribuída que armazena memórias em um banco de dados gráfico KùzuDB, com capacidades de filtragem por repositório e branch.

GitHub
24
Experimente este MCPPatrocinado

Documentação

KuzuMem-MCP

Uma implementação em TypeScript de um banco de memória distribuído como ferramenta MCP (Model Context Protocol), armazenando memórias em um banco de dados gráfico KùzuDB com capacidades de filtragem por repositório e branch. O isolamento de branch é alcançado usando um identificador único no grafo para entidades, permitindo um banco de memória centralizado enquanto possibilita visualizações específicas por repositório e branch. Totalmente compatível com a especificação MCP para integração perfeita com IDEs e agentes de IA.

Principais Recursos

  • 🧠 Otimização de Memória com IA - Modelos avançados de raciocínio (OpenAI o3/o4-mini, Claude 4) com amostragem MCP para gerenciamento inteligente de memória
  • 🛡️ Segurança Pronta para Produção - Sistema automático de snapshots com garantia de rollback
  • 🎯 Inteligência Contextual - Amostragem MCP analisa o estado real da memória para estratégias adaptativas de otimização
  • 🔧 Arquitetura Unificada de Ferramentas - 12 ferramentas consolidadas cobrindo todas as operações do banco de memória
  • 🧵 Padrão Singleton com Thread Safety - Garante que cada recurso seja instanciado apenas uma vez, com segurança adequada para threads
  • 📊 Estrutura de Grafo Distribuída - Segue a especificação avançada de banco de memória usando um grafo KùzuDB
  • 🌿 Consciência de Repositório e Branch - Todas as operações são contextualizadas pelo nome do repositório e branch
  • ⚡ Operações Assíncronas - Usa async/await para melhor desempenho
  • 🔌 Múltiplas Interfaces de Acesso - Acesso via CLI e múltiplas implementações de servidor MCP
  • 💾 Backend KùzuDB - Utiliza KùzuDB para armazenamento e consulta de memória baseada em grafo
  • ✅ Totalmente Compatível com MCP - Todas as ferramentas seguem o Model Context Protocol para integração com clientes
  • 📡 Streaming Progressivo de Resultados - Suporta streaming para operações de grafo de longa duração
  • 🏠 Isolamento da Raiz do Projeto do Cliente - Cada projeto cliente recebe sua própria instância isolada de banco de dados
  • 🧠 Análise de Alto Raciocínio - Aproveita o raciocínio HIGH da OpenAI e o pensamento estendido da Anthropic para otimização de memória
  • 🗑️ Operações em Massa Seguras - Exclusão em massa avançada com validação de dependências e capacidade de dry-run

Ferramentas Unificadas

O sistema atualmente transmite 12 ferramentas unificadas que consolidam todas as operações do banco de memória:

  1. memory-bank - Inicializa e gerencia metadados do banco de memória
  2. entity - Cria, atualiza, exclui e recupera todos os tipos de entidades (componentes, decisões, regras, arquivos, tags)
  3. introspect - Explora o esquema do grafo e metadados
  4. context - Gerencia o contexto da sessão de trabalho
  5. query - Busca unificada em contextos, entidades, relacionamentos, dependências, governança, histórico e tags
  6. associate - Cria relacionamentos entre entidades
  7. analyze - Executa algoritmos de grafo (PageRank, K-Core, Louvain, Caminho Mais Curto)
  8. detect - Detecta padrões (componentes fortemente/fracamente conectados)
  9. bulk-import - Importação eficiente de entidades em massa
  10. search - Busca de texto completo em todos os tipos de entidades com integração FTS do KuzuDB
  11. delete - Exclusão segura de entidades com validação de dependências e operações em massa
  12. memory-optimizer - 🧠 Otimização de memória central com IA usando amostragem MCP, snapshots e rollback

Para documentação detalhada das ferramentas, consulte Documentação das Ferramentas Unificadas.

Documentação

Instalação

# Clone the repository
git clone git@github.com:Jakedismo/KuzuMem-MCP.git
cd kuzumem-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuração

Crie um arquivo .env no diretório raiz (copie de .env.example):

# Database Configuration
DB_FILENAME="memory-bank.kuzu"

# Server Configuration
HTTP_STREAM_PORT=3001
HOST=localhost

# Debug Logging (0=Error, 1=Warn, 2=Info, 3=Debug, 4=Trace)
DEBUG=1

# Core Memory Optimization Agent - AI Provider Configuration
# Required for memory optimization features
OPENAI_API_KEY=sk-your-openai-api-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-api-key-here

# Optional: Custom API endpoints
# OPENAI_BASE_URL=https://api.openai.com/v1
# ANTHROPIC_BASE_URL=https://api.anthropic.com

Configuração da Otimização de Memória Central

O Agente de Otimização de Memória Central requer chaves de API para modelos de alto raciocínio:

Modelos Suportados:

  • OpenAI: o3, o4-mini (com raciocínio HIGH, 32.768 tokens)
  • Anthropic: claude-4 (com pensamento estendido, 2.048 tokens)

Para instruções detalhadas de configuração, consulte o Guia de Configuração da Otimização de Memória Central.

Adicione à configuração MCP do seu IDE:

{
  "mcpServers": {
    "KuzuMem-MCP": {
      "command": "npx",
      "args": ["-y", "ts-node", "/absolute/path/to/kuzumem-mcp/src/mcp-stdio-server.ts"],
      "env": {
        "PORT": "3000",
        "HOST": "localhost",
        "DB_FILENAME": "memory-bank.kuzu",
        "HTTP_STREAM_PORT": "3001"
      }
    }
  }
}

Início Rápido

1. Inicializar o Banco de Memória

{
  "tool": "memory-bank",
  "operation": "init",
  "clientProjectRoot": "/path/to/your/project",
  "repository": "my-app",
  "branch": "main"
}

2. Criar Entidades

{
  "tool": "entity",
  "operation": "create",
  "entityType": "component",
  "repository": "my-app",
  "branch": "main",
  "data": {
    "id": "comp-auth-service",
    "name": "Authentication Service",
    "kind": "service",
    "depends_on": ["comp-user-service"]
  }
}

3. Consultar Dependências

{
  "tool": "query",
  "type": "dependencies",
  "repository": "my-app",
  "branch": "main",
  "componentId": "comp-auth-service",
  "direction": "dependencies"
}

4. Executar Análise

{
  "tool": "analyze",
  "type": "pagerank",
  "repository": "my-app",
  "branch": "main",
  "projectedGraphName": "component-importance",
  "nodeTableNames": ["Component"],
  "relationshipTableNames": ["DEPENDS_ON"]
}

🧠 Agente de Otimização de Memória Central

O Agente de Otimização de Memória Central fornece otimização do grafo de memória com IA, capacidades avançadas de raciocínio e recursos de segurança prontos para produção:

Recursos

  • 🧠 Análise de Alto Raciocínio: Usa OpenAI o3/o4-mini (raciocínio HIGH) ou Claude (pensamento estendido) para análise inteligente de memória
  • 🎯 Amostragem MCP: Prompts sensíveis ao contexto que se adaptam ao estado real da memória e às características do projeto
  • 🛡️ Snapshots Automáticos: Segurança pronta para produção com backup automático antes da otimização
  • 🔄 Rollback Garantido: Restauração completa do estado com segurança transacional
  • ⚖️ Otimização Segura: Estratégias conservadora, equilibrada e agressiva com validação de segurança
  • 🔍 Detecção de Entidades Obsoletas: Identifica entidades desatualizadas com base na idade e padrões de uso
  • 🔗 Remoção de Redundâncias: Encontra e consolida entidades duplicadas ou redundantes
  • 📊 Otimização de Dependências: Otimiza cadeias de relacionamentos preservando a integridade
  • 👀 Modo Dry-Run: Visualiza otimizações sem fazer alterações
  • 📈 Inteligência de Projeto: Análise automática de maturidade, atividade e complexidade do projeto

Início Rápido

1. Analisar o Grafo de Memória (com Amostragem MCP)

{
  "tool": "memory-optimizer",
  "operation": "analyze",
  "repository": "my-app",
  "branch": "main",
  "llmProvider": "openai",
  "model": "o4-mini",
  "strategy": "conservative",
  "enableMCPSampling": true,
  "samplingStrategy": "representative"
}

2. Visualizar Otimização (Dry Run)

{
  "tool": "memory-optimizer",
  "operation": "optimize",
  "repository": "my-app",
  "branch": "main",
  "dryRun": true,
  "strategy": "conservative"
}

3. Executar Otimização (com Snapshot Automático)

{
  "tool": "memory-optimizer",
  "operation": "optimize",
  "repository": "my-app",
  "branch": "main",
  "dryRun": false,
  "confirm": true,
  "strategy": "conservative"
}

4. Listar Snapshots Disponíveis

{
  "tool": "memory-optimizer",
  "operation": "list-snapshots",
  "repository": "my-app",
  "branch": "main"
}

5. Rollback para o Estado Anterior

{
  "tool": "memory-optimizer",
  "operation": "rollback",
  "repository": "my-app",
  "branch": "main",
  "snapshotId": "snapshot-1703123456789-xyz789"
}

Estratégias de Otimização

  • Conservadora: Máximo de 5 exclusões, limite de obsolescência de 6 meses (recomendada para produção)
  • Equilibrada: Máximo de 20 exclusões, limite de obsolescência de 3 meses (recomendada para desenvolvimento)
  • Agressiva: Máximo de 50 exclusões, limite de obsolescência de 1 mês (usar com cautela)

Estratégias de Amostragem MCP

  • Representativa: Amostra equilibrada em todos os tipos de entidades (padrão)
  • Problemática: Foco em entidades obsoletas, desconectadas ou descontinuadas
  • Recente: Amostra entidades recém-criadas (< 30 dias) para análise de segurança
  • Diversa: Garante representação de todos os tipos de entidades para sistemas complexos

Recursos de Segurança

  • 🛡️ Snapshots Automáticos: Criados antes de cada otimização (exceto em dry-run)
  • 🔄 Rollback Transacional: Restauração completa do estado com consistência do banco de dados
  • ✅ Sistema de Validação: Verificações de integridade do snapshot antes das operações de rollback
  • 📊 Segurança Contextual: Medidas de segurança baseadas em nível de atividade e complexidade

Para instruções completas de configuração e uso, consulte:

Testes

# Run unit tests
npm test

# Run E2E tests (requires API keys)
npm run test:e2e

# Run specific E2E tests
npm run test:e2e:stdio
npm run test:e2e:httpstream

# Run memory optimizer E2E tests
npm run test:e2e -- --testNamePattern="Memory Optimizer E2E Tests"

# Run all tests
npm run test:all

Requisitos de Teste E2E

Para testes E2E do otimizador de memória, defina as variáveis de ambiente:

export OPENAI_API_KEY="your-actual-openai-api-key"
export ANTHROPIC_API_KEY="your-actual-anthropic-api-key"

Nota: Toda a funcionalidade central está operacional com cobertura abrangente de testes E2E para os protocolos stdio e HTTP stream.

Arquitetura

KuzuMem-MCP segue padrões oficiais do SDK TypeScript do MCP com arquitetura limpa:

┌─────────────────────────────────────────────────────────────┐
│                    MCP Protocol Layer                       │
├─────────────────────────────────────────────────────────────┤
│     HTTP Stream Server     │      Stdio Server             │
│   (StreamableHTTPTransport) │   (StdioTransport)            │
├─────────────────────────────────────────────────────────────┤
│                    Tool Handlers                            │
├─────────────────────────────────────────────────────────────┤
│                   Memory Service                            │
├─────────────────────────────────────────────────────────────┤
│                   Repository Layer                          │
├─────────────────────────────────────────────────────────────┤
│                    KuzuDB Client                            │
└─────────────────────────────────────────────────────────────┘

Componentes Principais

  • Servidores MCP: Implementações oficiais do SDK usando McpServer com transportes HTTP Stream e Stdio
  • Handlers de Ferramentas: Lógica de negócio para cada ferramenta MCP com tratamento simplificado de contexto
  • Serviço de Memória: Orquestração central e gerenciamento de repositórios
  • Camada de Repositórios: Singletons com thread safety para cada tipo de entidade
  • Camada de Banco de Dados: Banco de dados gráfico embutido KùzuDB

Conformidade com o SDK Oficial

✅ Gerenciamento de Sessão: Usa o gerenciamento de sessão integrado do SDK ✅ Registro de Ferramentas: Usa o método oficial tool() com validação Zod ✅ Tratamento de Transporte: Aproveita as implementações de transporte do SDK ✅ Tratamento de Erros: Segue os padrões de erro e melhores práticas do SDK

Para informações detalhadas sobre a arquitetura, consulte a Documentação Estendida.

Loop de Desenvolvimento do Agente (Imposto por Regras)

Quando tanto as "Regras de Espaço de Trabalho Sempre Aplicadas" no nível do repositório (project_config_updated.md) quanto as regras de fluxo de trabalho de curto prazo (workflow_state_updated.mdc) estão ativas, todo IDE ou agente de IA que se comunica com KuzuMem-MCP deve seguir o loop de máquina de estados finitos de cinco fases abaixo. Cada transição é observável através da ferramenta unificada context e é respaldada por chamadas MCP obrigatórias que mantêm o banco de dados gráfico sincronizado e as regras de governança aplicadas.

  1. ANALISAR – Obter o contexto mais recente, inspecionar a vizinhança de 1 salto e, opcionalmente, executar uma análise PageRank. Produzir uma declaração de problema de alto nível.
  2. BLUEPRINT – Elaborar um plano de implementação numerado e persistir como uma entidade Decision (status: proposed, tag architecture). Aguardar aprovação explícita do usuário.
  3. CONSTRUIR – Executar as etapas do plano, aplicar edições de código e espelhar imediatamente as alterações através de chamadas de ferramentas entity, associate e context, respeitando as regras de dependência e tags.
  4. VALIDAR – Executar a suíte completa de testes e linters. Se estiver verde, atualizar Decision para implemented; se estiver vermelho, registrar o contexto e voltar para CONSTRUIR.
  5. ROLLBACK – Acionado automaticamente em erros irrecuperáveis, revertendo o trabalho parcial antes de retornar para ANALISAR.

Diagrama de Fases

stateDiagram-v2
    [*] --> ANALYZE
    ANALYZE --> BLUEPRINT: blueprint drafted
    BLUEPRINT --> CONSTRUCT: approved
    CONSTRUCT --> VALIDATE: steps complete
    VALIDATE --> DONE: tests pass
    VALIDATE --> CONSTRUCT: tests fail
    CONSTRUCT --> ROLLBACK: unrecoverable error
    ROLLBACK --> ANALYZE

Licença

Apache-2.0

Contribuição

Contribuições são bem-vindas! Por favor, garanta:

  • Todos os testes passam (ou crie issues para testes com falha)
  • O código segue o estilo existente
  • Novos recursos incluem testes
  • A documentação é atualizada

Melhorias Futuras

  • Embeddings Vetoriais - Busca por similaridade semântica (aguardando atualizações de colunas vetoriais do KuzuDB)
  • Algoritmos de Grafo Avançados - Capacidades adicionais de análise
  • Atualizações do Esquema do Grafo - Com base no desempenho do loop de desenvolvimento automatizado, o esquema do grafo pode precisar ser atualizado para suportar novos recursos
  • Busca Semântica Completa - Implementação da ferramenta de busca semântica (atualmente placeholder - os Índices Vetoriais do KuzuDB são imutáveis e tornariam o desenvolvimento deste recurso difícil, pois atualizar memórias não atualizaria os índices vetoriais)

Revisão MCP

Este MCP é verificado pela Revisão MCP

https://mcpreview.com/mcp-servers/Jakedismo/KuzuMem-MCP

Revisões de Código Automáticas com Codrabbit

CodeRabbit Pull Request Reviews