Zero-Vector v3

Um servidor para o sistema híbrido de persona e gerenciamento de memória vetor-grafo da Zero-Vector, com recursos avançados de fluxo de trabalho LangGraph.

GitHubExperimente este MCPPatrocinado

Documentação

Zero-Vector MCP v3.0: Sistema Híbrido de Memória de IA com Vetores e Grafos com Workflows LangGraph

🚀 STATUS: PRONTO PARA PRODUÇÃO | Infraestrutura: VALIDADA | LangGraph: OPERACIONAL

Um sistema completo de gerenciamento de memória de persona de IA que combina um servidor de banco de dados híbrido de vetores e grafos de alta performance com orquestração avançada de workflows LangGraph e uma interface Model Context Protocol (MCP) para memória sofisticada de IA, compreensão de relacionamentos e coordenação multi-agente.

🔗 Repositório GitHub: https://github.com/MushroomFleet/zero-vector-MCP

🎯 Status do Sistema: OPERACIONAL

Última Validação de Infraestrutura: 21 de junho de 2025
Versão Atual: v3.0 Pronto para Produção
Servidor Zero-Vector v2: ✅ Ativo (Porta 3000)
Zero-Vector v3 LangGraph: ✅ Ativo (Porta 3001)
Servidor MCP: ✅ Ativo (Coordenação multi-servidor)

✅ Infraestrutura Recentemente Validada

  • Esquema LangGraph StateGraph: Resolvido com integração adequada de Zod
  • Orquestração Multi-Agente: Grafo de workflow de 7 nós operacional
  • Processamento com Intervenção Humana: Workflows de aprovação funcionais
  • Cache de Performance: Integração Redis/PostgreSQL ativa
  • Coordenação de Serviços: Coordenação dos sistemas v2/v3 validada
  • Integração MCP: 24 ferramentas totalmente operacionais em ambos os sistemas

📊 Métricas de Performance Confirmadas

  • Tempo de Inicialização: 2-3 segundos para inicialização completa do sistema
  • Compilação LangGraph: <3ms para grafos de workflow de 7 nós
  • Operações de Vetores: <50ms para 10.000+ buscas de vetores
  • Execução de Workflows: <2s para conversas padrão de IA
  • Integração de Memória: <500ms para recuperação híbrida de memória
  • Taxa de Acerto de Cache: Otimização de performance de 95%+

🎯 Visão Geral

O Zero-Vector MCP v3.0 fornece uma solução híbrida de vetores e grafos pronta para produção com capacidades avançadas de workflows LangGraph para gerenciamento de persona de IA, apresentando:

  • Mecanismo Híbrido de Vetores e Grafos - Combina busca semântica com travessia de grafo de conhecimento
  • Orquestração de Workflows LangGraph - Coordenação multi-agente com processamento com intervenção humana
  • Memória de Persona de IA com Relacionamentos - Memória sensível ao contexto com extração de entidades e construção de grafos
  • Integração MCP Aprimorada - 24 ferramentas especializadas incluindo gerenciamento de workflows, exploração de grafos e acesso avançado a conteúdo
  • Raciocínio Multi-Etapa - Cadeias de raciocínio sofisticadas com portões de aprovação e monitoramento de performance
  • Inteligência de Grafo de Conhecimento - Reconhecimento automático de entidades e mapeamento de relacionamentos
  • Arquitetura Pronta para Produção - Flags de recursos, monitoramento abrangente e implantação sem tempo de inatividade

🏗️ Arquitetura do Sistema

graph TB
    subgraph "AI Development Environment"
        A[Cline AI Assistant] --> B[MCP Client]
    end
    
    subgraph "Zero-Vector MCP v3.0 System"
        B --> C[MCP Server v3.0]
        C --> D[Zero-Vector v2 API]
        C --> E[Zero-Vector v3 API]
        
        subgraph "Zero-Vector v2 (Original System)"
            D --> F[Hybrid Vector Store]
            D --> G[Graph Database]
            D --> H[SQLite Metadata]
        end
        
        subgraph "Zero-Vector v3 (LangGraph System)"
            E --> I[LangGraph Workflow Engine]
            I --> J[Multi-Agent Orchestration]
            I --> K[Human Approval Service]
            I --> L[Performance Cache Manager]
            I --> M[State Management]
        end
        
        subgraph "v3.0 Core Services"
            N[Hybrid Memory Manager]
            O[Entity Extractor]
            P[Graph Service]
            Q[Embedding Service]
            R[Feature Flags]
            S[Workflow Manager]
            T[Approval Service]
        end
        
        D --> N
        D --> O
        D --> P
        D --> Q
        D --> R
        E --> S
        E --> T
        
        subgraph "LangGraph Agents"
            U[Hybrid Retrieval Agent]
            V[Persona Memory Agent]
            W[Multi-Step Reasoning Agent]
            X[Human Approval Agent]
        end
        
        J --> U
        J --> V
        J --> W
        J --> X
        
        subgraph "Knowledge Graph"
            Y[Entities]
            Z[Relationships]
            AA[Graph Traversal]
        end
        
        G --> Y
        G --> Z
        G --> AA
    end
    
    subgraph "External Services"
        BB[OpenAI Embeddings]
        CC[Local Transformers]
        DD[PostgreSQL Checkpointer]
        EE[Redis Cache]
    end
    
    Q --> BB
    Q --> CC
    M --> DD
    L --> EE
    
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style F fill:#e8f5e8
    style G fill:#ffeb3b
    style I fill:#e3f2fd
    style J fill:#e8f5e8
    style N fill:#fff3e0
    style O fill:#e1f5fe
    style P fill:#e1f5fe
    style Q fill:#fff3e0
    style R fill:#f3e5f5
    style S fill:#e3f2fd
    style T fill:#ffcdd2

🚀 Início Rápido

Pré-requisitos

  • Node.js 18.0.0 ou superior
  • 4GB+ de RAM disponível (recomendado para v3.0)
  • PostgreSQL (para checkpointing LangGraph)
  • Redis (para cache de performance)
  • Git

Instalação

# Clone the repository
git clone https://github.com/MushroomFleet/zero-vector-3.git
cd zero-vector-3

# 1. Set up the Zero-Vector v2 server (Original System)
cd zero-vector/server
npm install
npm run setup:database
npm run generate:api-key  # Generate API key for MCP
cp env.example .env  # Add your OpenAI API key
npm start  # Runs on port 3000

# 2. Set up the Zero-Vector v3 server (LangGraph System)
cd zero-vector-3/server
npm install
cp env.example .env  # Configure environment
npm run setup:postgres # install postgre16.9 & redis first
npm run setup:infrastructure  # Setup PostgreSQL and Redis
npm start  # Runs on port 3001

# 3. Set up the MCP server (in a new terminal)
cd MCP
npm install
cp env.example .env
# Edit .env with both server URLs and API keys
npm start

Teste Rápido

# Test the vector database (v2)
curl http://localhost:3000/health

# Test the LangGraph system (v3)
curl http://localhost:3001/health

# Test MCP server connection (both systems)
cd MCP
npm run test:connection

📚 Documentação dos Componentes

Este sistema consiste em três componentes principais, cada um com documentação detalhada:

🗄️ Servidor Zero-Vector v2 (Sistema Original)

Localização: zero-vector/README.md

O servidor de banco de dados de vetores principal fornecendo:

  • Armazenamento de vetores de alta performance e busca por similaridade
  • API RESTful para operações de vetores
  • Persistência de metadados SQLite
  • Autenticação e middleware de segurança
  • Monitoramento em tempo real e verificações de saúde

🤖 Servidor Zero-Vector v3 (Sistema LangGraph)

Localização: zero-vector-3/README.md

O servidor avançado de workflows LangGraph fornecendo:

  • Orquestração de workflows multi-agente
  • Processamento de aprovação com intervenção humana
  • Cadeias de raciocínio avançadas e gerenciamento de estado
  • Cache de performance e monitoramento
  • Checkpointing PostgreSQL e cache Redis

🔌 Servidor MCP v3.0

Localização: MCP/README.md

A interface Model Context Protocol fornecendo:

  • 24 ferramentas especializadas para gerenciamento de persona, memória, grafo e workflow
  • Coordenação multi-servidor entre os sistemas v2 e v3
  • Capacidades de gerenciamento de workflows LangGraph
  • Integração perfeita com ferramentas de desenvolvimento de IA
  • Tratamento abrangente de erros e validação

✨ Principais Recursos

Gerenciamento de Workflows LangGraph (NOVO na v3.0)

  • Orquestração Multi-Agente: Coordenação sofisticada de agentes com gerenciamento de estado
  • Processamento com Intervenção Humana: Workflows de aprovação com capacidades de retomada
  • Raciocínio Multi-Etapa: Cadeias de raciocínio complexas com profundidade configurável
  • Monitoramento de Performance: Métricas e análises em tempo real para otimização de workflows
  • Continuidade de Threads: Estado de conversa persistente entre sessões
  • Cache de Workflows: Otimização de performance para operações repetidas

Performance Híbrida de Vetores e Grafos

  • Eficiência de Memória: Armazenamento otimizado de 2GB suportando 349.525+ vetores
  • Busca Híbrida: Busca abaixo de 300ms combinando similaridade de vetores com expansão de grafos
  • Extração de Entidades: Reconhecimento automático de pessoas, conceitos, eventos e relacionamentos
  • Travessia de Grafos: Exploração de relacionamentos em múltiplas profundidades com limites configuráveis
  • Arquitetura Escalável: Implantação com flags de recursos e rollback sem tempo de inatividade

Gerenciamento de Persona de IA com Grafos de Conhecimento

  • Criação de Personas: Personas de IA configuráveis com capacidades de memória e grafos
  • Armazenamento Aprimorado de Memória: Memória sensível ao contexto com extração automática de entidades
  • Busca Híbrida: Encontre memórias relevantes usando similaridade de vetores e relacionamentos de grafos
  • Construção de Grafos de Conhecimento: Reconhecimento automático de entidades e mapeamento de relacionamentos
  • Histórico de Conversas: Rastreamento completo de conversas com vinculação de entidades
  • Limpeza de Memória: Limpeza automatizada de memórias antigas e entidades de grafos órfãs

Ferramentas de Integração MCP (24 no total)

  • Ferramentas de Persona (5): create_persona, list_personas, get_persona, update_persona, delete_persona
  • Ferramentas de Memória (6): add_memory, search_persona_memories, get_full_memory, add_conversation, get_conversation_history, cleanup_persona_memories
  • Ferramentas de Grafo (4): explore_knowledge_graph, hybrid_memory_search, get_graph_context, get_graph_stats
  • Ferramentas de Workflow (6): execute_workflow, get_workflow_status, resume_workflow, cancel_workflow, list_active_workflows, get_workflow_metrics
  • Ferramentas Utilitárias (3): get_system_health, get_persona_stats, test_connection

Recursos de Segurança e Produção

  • Autenticação por Chave de API: Geração segura de chaves com permissões baseadas em papéis
  • Limitação de Taxa: Limitação de taxa em múltiplas camadas (global, por chave, por endpoint)
  • Validação de Entrada: Validação abrangente de solicitações e sanitização
  • Registro Estruturado: Registro baseado em Winston com métricas de performance
  • Monitoramento de Saúde: Múltiplos endpoints de verificação de saúde para diferentes necessidades de monitoramento
  • Coordenação Multi-Servidor: Integração perfeita entre os sistemas v2 e v3

🎮 Casos de Uso

Operações de Workflows LangGraph (v3.0)

Conversa Básica de IA com Workflow

// Execute a basic conversation workflow
const workflowResult = await mcpClient.executeWorkflow({
  query: "Explain machine learning fundamentals for beginners",
  persona: "helpful_assistant",
  user_id: "user123",
  workflow_type: "zero_vector_conversation",
  config: {
    enable_approval: false,
    cache_enabled: true,
    confidence_threshold: 0.8,
    max_reasoning_steps: 5
  }
});

// Monitor workflow execution
const status = await mcpClient.getWorkflowStatus({
  workflow_id: workflowResult.workflow_id,
  thread_id: workflowResult.thread_id,
  include_metadata: true
});

Raciocínio Multi-Etapa com Aprovação Humana

// Execute complex reasoning workflow
const complexWorkflow = await mcpClient.executeWorkflow({
  query: "Compare machine learning approaches for NLP and recommend the best approach for a chatbot system, considering scalability, cost, and performance",
  persona: "technical_expert", 
  user_id: "user456",
  workflow_type: "multi_step_reasoning",
  config: {
    enable_approval: true,
    max_reasoning_steps: 10,
    confidence_threshold: 0.9,
    enable_memory_maintenance: true
  },
  thread_id: "conversation_abc123"
});

// Resume after human approval
const resumeResult = await mcpClient.resumeWorkflow({
  thread_id: "conversation_abc123",
  workflow_id: complexWorkflow.workflow_id,
  approval_result: {
    approved: true,
    feedback: "Add more details about implementation complexity",
    modifications: {
      add_implementation_details: true,
      focus_areas: ["complexity", "scalability", "cost"]
    }
  }
});

Monitoramento de Performance de Workflows

// Get comprehensive workflow metrics
const metrics = await mcpClient.getWorkflowMetrics({
  time_range: "24h",
  workflow_type: "multi_step_reasoning",
  user_id: "user123",
  include_detailed: true
});

// List active workflows for monitoring
const activeWorkflows = await mcpClient.listActiveWorkflows({
  user_id: "user123",
  status: "running",
  workflow_type: "multi_step_reasoning",
  limit: 10
});

// Cancel workflow if needed
await mcpClient.cancelWorkflow({
  workflow_id: "workflow_xyz789",
  thread_id: "conversation_abc123",
  reason: "User requested cancellation due to changed requirements"
});

Memória de Assistente de IA com Grafos de Conhecimento (v2.0 + v3.0)

// Create a persona for an AI assistant
const persona = await mcpClient.createPersona({
  name: "Technical Assistant",
  description: "Helpful coding assistant with memory and graph knowledge",
  systemPrompt: "You are a helpful technical assistant with access to knowledge graphs...",
  maxMemorySize: 1000
});

// Add important information to memory (automatically extracts entities)
await mcpClient.addMemory({
  personaId: persona.id,
  content: "John Smith from Microsoft called about the Azure project. He mentioned working with Sarah Johnson on cloud architecture.",
  type: "conversation",
  importance: 0.8
});

// Hybrid search combining vector similarity with graph expansion
const hybridResults = await mcpClient.hybridMemorySearch({
  personaId: persona.id,
  query: "cloud architecture project",
  limit: 5,
  useGraphExpansion: true,
  graphDepth: 2,
  threshold: 0.7
});

// Use workflow to process complex queries with memory integration
const workflowWithMemory = await mcpClient.executeWorkflow({
  query: "Based on my previous conversations about Azure, what are the key architectural considerations for our project?",
  persona: persona.id,
  user_id: "user123",
  workflow_type: "zero_vector_conversation",
  config: {
    use_memory_integration: true,
    enable_graph_expansion: true,
    memory_context_depth: 3
  }
});

Descoberta Aprimorada de Contexto de Memória

// Get comprehensive context for specific entities
const context = await mcpClient.getGraphContext({
  personaId: persona.id,
  entityIds: ["entity-john-smith-uuid", "entity-microsoft-uuid"],
  includeRelationships: true,
  maxDepth: 2
});

// Search with configurable content display
const searchWithFullContent = await mcpClient.searchPersonaMemories({
  personaId: persona.id,
  query: "white hat tales",
  limit: 5,
  show_full_content: true,  // No truncation
  threshold: 0.3
});

Integração com Cline (v3.0)

{
  "mcpServers": {
    "zero-vector-v3": {
      "command": "node",
      "args": ["C:/path/to/zero-vector-MCP/MCP/src/index.js"],
      "env": {
        "ZERO_VECTOR_BASE_URL": "http://localhost:3000",
        "ZERO_VECTOR_API_KEY": "your_zero_vector_2_api_key",
        "ZERO_VECTOR_V3_BASE_URL": "http://localhost:3001",
        "ZERO_VECTOR_V3_API_KEY": "your_zero_vector_3_api_key"
      }
    }
  }
}

🛠️ Desenvolvimento

Estrutura do Projeto

zero-vector-MCP/
├── zero-vector/                 # Vector database server (v2)
│   ├── server/                  # Node.js backend
│   │   ├── src/                 # Source code
│   │   ├── scripts/             # Setup scripts
│   │   ├── data/                # Database files
│   │   └── README.md            # Server documentation
│   └── README.md                # Server overview
├── zero-vector-3/               # LangGraph workflow server (v3)
│   ├── server/                  # Node.js backend
│   │   ├── src/                 # Source code
│   │   │   ├── agents/          # LangGraph agents
│   │   │   ├── graphs/          # Workflow graphs
│   │   │   ├── services/        # Core services
│   │   │   └── state/           # State management
│   │   ├── scripts/             # Setup scripts
│   │   └── README.md            # v3 documentation
│   └── README.md                # v3 overview
├── MCP/                         # Model Context Protocol server
│   ├── src/                     # MCP server source
│   │   ├── tools/               # MCP tool implementations
│   │   │   ├── workflows.js     # NEW: Workflow tools
│   │   │   ├── personas.js      # Persona management
│   │   │   ├── memories.js      # Memory operations
│   │   │   ├── graph.js         # Graph operations
│   │   │   └── utilities.js     # System utilities
│   │   └── utils/               # Utilities
│   ├── .env.example             # Environment template
│   └── README.md                # MCP documentation
├── DOCS/                        # Internal documentation
└── README.md                    # This file

Configuração de Desenvolvimento

# Start Zero-Vector v2 server in development mode
cd zero-vector/server
npm run dev  # Port 3000

# Start Zero-Vector v3 server in development mode (new terminal)
cd zero-vector-3/server
npm run dev  # Port 3001

# Start MCP server in development mode (new terminal)
cd MCP
npm run dev

# Run tests
npm test

Configuração de Ambiente

Servidor Zero-Vector v2:

NODE_ENV=development
PORT=3000
MAX_MEMORY_MB=2048
DEFAULT_DIMENSIONS=1536
LOG_LEVEL=info

Servidor Zero-Vector v3:

NODE_ENV=development
PORT=3001
POSTGRES_URL=postgresql://localhost:5432/zerovector3
REDIS_URL=redis://localhost:6379/0
LANGSMITH_TRACING=true
OPENAI_API_KEY=your_openai_key
LOG_LEVEL=info

Servidor MCP:

# v2 Server Configuration
ZERO_VECTOR_BASE_URL=http://localhost:3000
ZERO_VECTOR_API_KEY=your_zero_vector_2_api_key

# v3 Server Configuration
ZERO_VECTOR_V3_BASE_URL=http://localhost:3001
ZERO_VECTOR_V3_API_KEY=your_zero_vector_3_api_key

# MCP Configuration
MCP_SERVER_NAME=zero-vector-mcp-v3
LOG_LEVEL=info

📊 Características de Performance

Armazenamento de Vetores (Sistema v2)

  • Armazenamento de Vetores: ~6MB por 1000 vetores (1536 dimensões)
  • Performance de Busca: <50ms para corpus de 10.000+ vetores
  • Eficiência de Memória: Utilização de 99,9% do espaço de buffer alocado
  • Taxa de Transferência: Taxa de inserção de 1000+ vetores/segundo
  • Capacidade: 349.525 vetores em configuração de 2GB

Performance de Workflows (Sistema v3)

  • Execução de Workflows: <2s para conversas padrão
  • Raciocínio Multi-Etapa: <10s para cadeias de raciocínio complexas
  • Integração de Memória: <500ms para recuperação híbrida de memória
  • Processamento de Aprovações: <1s para workflows de aprovação humana
  • Performance de Cache: Taxa de acerto de cache de 95%+ para operações repetidas

🔒 Recursos de Segurança

  • Autenticação: Autenticação baseada em chave de API com geração segura
  • Autorização: Controle de acesso baseado em papéis com permissões granulares
  • Limitação de Taxa: Múltiplas camadas de limitação de taxa (global, por chave, por endpoint)
  • Validação de Entrada: Validação abrangente de solicitações e sanitização
  • Cabeçalhos de Segurança: Implementação Helmet.js com políticas CSP
  • Registro de Auditoria: Trilha de auditoria completa para todas as operações
  • Segurança Multi-Servidor: Segurança coordenada entre os sistemas v2 e v3
  • Aprovação de Workflows: Segurança com intervenção humana para operações sensíveis

🤝 Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade (git checkout -b feature/amazing-feature)
  3. Faça suas alterações
  4. Adicione testes para novas funcionalidades
  5. Faça commit das suas alterações (git commit -m 'Add amazing feature')
  6. Envie para o branch (git push origin feature/amazing-feature)
  7. Abra um Pull Request

Diretrizes de Desenvolvimento

  • Siga o estilo e os padrões de código existentes
  • Adicione testes abrangentes para novos recursos
  • Atualize a documentação para quaisquer alterações de API
  • Garanta que todos os testes passem antes de enviar o PR
  • Inclua considerações de performance para operações de vetores
  • Teste as integrações de workflows minuciosamente
  • Considere cenários de aprovação humana para novos recursos

📄 Licença

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

🆘 Suporte

Documentação

  • Banco de Dados de Vetores: Consulte zero-vector/README.md para documentação detalhada do servidor v2
  • Sistema LangGraph: Consulte zero-vector-3/README.md para documentação de workflows v3
  • Servidor MCP: Consulte MCP/README.md para configuração MCP e documentação de ferramentas

Solução de Problemas

Problemas de Conexão:

# Check Zero-Vector v2 server health
curl http://localhost:3000/health

# Check Zero-Vector v3 server health
curl http://localhost:3001/health

# Test MCP server connection
cd MCP && npm run test:connection

Problemas de Workflow:

# Check workflow status
cd MCP && node -e "console.log('Check workflow metrics via MCP tools')"

# Review workflow logs
tail -f zero-vector-3/server/logs/combined.log

Problemas Comuns:

  • Garanta que o Node.js 18+ esteja instalado
  • Verifique a configuração da chave de API no arquivo .env do MCP
  • Verifique se ambos os servidores Zero-Vector estão em execução antes de iniciar o servidor MCP
  • Garanta alocação de memória suficiente (4GB+ recomendado para v3.0)
  • Verifique se PostgreSQL e Redis estão em execução para workflows v3

Obtendo Ajuda

  • Issues do GitHub: Reporte bugs e solicitações de recursos
  • Discussões: Faça perguntas e compartilhe ideias
  • Wiki: Documentação adicional e exemplos

Zero-Vector MCP v3.0 - Sistema híbrido de memória de IA com vetores e grafos pronto para produção com orquestração avançada de workflows LangGraph e inteligência multi-agente