Zero-Vector v3

Un servidor para el sistema híbrido vector-grafo de gestión de personajes y memoria de Zero-Vector, con capacidades avanzadas de flujo de trabajo LangGraph.

GitHubPrueba este MCPPatrocinado

Documentación

Zero-Vector MCP v3.0: Sistema de Memoria de IA Híbrido Vector-Grafo con Flujos de Trabajo LangGraph

🚀 ESTADO: LISTO PARA PRODUCCIÓN | Infraestructura: VALIDADA | LangGraph: OPERATIVO

Un sistema completo de gestión de memoria de personajes de IA que combina un servidor de base de datos híbrido vector-grafo de alto rendimiento con orquestación avanzada de flujos de trabajo LangGraph y una interfaz de Protocolo de Contexto de Modelo (MCP) para memoria sofisticada de IA, comprensión de relaciones y coordinación multi-agente.

🔗 Repositorio de GitHub: https://github.com/MushroomFleet/zero-vector-MCP

🎯 Estado del Sistema: OPERATIVO

Última Validación de Infraestructura: 21 de junio de 2025
Versión Actual: v3.0 Listo para Producción
Servidor Zero-Vector v2: ✅ Activo (Puerto 3000)
Zero-Vector v3 LangGraph: ✅ Activo (Puerto 3001)
Servidor MCP: ✅ Activo (Coordinación multi-servidor)

✅ Infraestructura Recientemente Validada

  • Esquema StateGraph de LangGraph: Resuelto con integración adecuada de Zod
  • Orquestación Multi-Agente: Grafo de flujo de trabajo de 7 nodos operativo
  • Procesamiento Humano en el Bucle: Flujos de trabajo de aprobación funcionales
  • Caché de Rendimiento: Integración Redis/PostgreSQL activa
  • Coordinación de Servicios: Coordinación del sistema v2/v3 validada
  • Integración MCP: 24 herramientas totalmente operativas en ambos sistemas

📊 Métricas de Rendimiento Confirmadas

  • Tiempo de Inicio: 2-3 segundos para la inicialización completa del sistema
  • Compilación de LangGraph: <3ms para grafos de flujo de trabajo de 7 nodos
  • Operaciones Vectoriales: <50ms para búsquedas de más de 10,000 vectores
  • Ejecución de Flujos de Trabajo: <2s para conversaciones estándar de IA
  • Integración de Memoria: <500ms para recuperación de memoria híbrida
  • Tasa de Aciertos de Caché: Optimización de rendimiento del 95%+

🎯 Descripción General

Zero-Vector MCP v3.0 proporciona una solución híbrida vector-grafo lista para producción con capacidades avanzadas de flujos de trabajo LangGraph para la gestión de personajes de IA, que incluye:

  • Motor Híbrido Vector-Grafo - Combina búsqueda semántica con recorrido de grafos de conocimiento
  • Orquestación de Flujos de Trabajo LangGraph - Coordinación multi-agente con procesamiento humano en el bucle
  • Memoria de Personajes de IA con Relaciones - Memoria consciente del contexto con extracción de entidades y construcción de grafos
  • Integración MCP Mejorada - 24 herramientas especializadas que incluyen gestión de flujos de trabajo, exploración de grafos y acceso avanzado a contenido
  • Razonamiento Multi-Paso - Cadenas de razonamiento sofisticadas con puertas de aprobación y monitoreo de rendimiento
  • Inteligencia de Grafos de Conocimiento - Reconocimiento automático de entidades y mapeo de relaciones
  • Arquitectura Lista para Producción - Banderas de funciones, monitoreo integral y despliegue sin tiempo de inactividad

🏗️ Arquitectura del 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

🚀 Inicio Rápido

Requisitos Previos

  • Node.js 18.0.0 o superior
  • 4GB+ de RAM disponible (recomendado para v3.0)
  • PostgreSQL (para checkpointing de LangGraph)
  • Redis (para caché de rendimiento)
  • Git

Instalación

# 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

Prueba Rápida

# 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

📚 Documentación de Componentes

Este sistema consta de tres componentes principales, cada uno con documentación detallada:

🗄️ Servidor Zero-Vector v2 (Sistema Original)

Ubicación: zero-vector/README.md

El servidor de base de datos vectorial central que proporciona:

  • Almacenamiento vectorial de alto rendimiento y búsqueda de similitud
  • API RESTful para operaciones vectoriales
  • Persistencia de metadatos SQLite
  • Autenticación y middleware de seguridad
  • Monitoreo en tiempo real y verificaciones de salud

🤖 Servidor Zero-Vector v3 (Sistema LangGraph)

Ubicación: zero-vector-3/README.md

El servidor avanzado de flujos de trabajo LangGraph que proporciona:

  • Orquestación de flujos de trabajo multi-agente
  • Procesamiento de aprobación humano en el bucle
  • Cadenas de razonamiento avanzadas y gestión de estado
  • Caché de rendimiento y monitoreo
  • Checkpointing PostgreSQL y caché Redis

🔌 Servidor MCP v3.0

Ubicación: MCP/README.md

La interfaz de Protocolo de Contexto de Modelo que proporciona:

  • 24 herramientas especializadas para gestión de personajes, memoria, grafos y flujos de trabajo
  • Coordinación multi-servidor entre sistemas v2 y v3
  • Capacidades de gestión de flujos de trabajo LangGraph
  • Integración perfecta con herramientas de desarrollo de IA
  • Manejo integral de errores y validación

✨ Características Clave

Gestión de Flujos de Trabajo LangGraph (NUEVO en v3.0)

  • Orquestación Multi-Agente: Coordinación sofisticada de agentes con gestión de estado
  • Procesamiento Humano en el Bucle: Flujos de trabajo de aprobación con capacidades de reanudación
  • Razonamiento Multi-Paso: Cadenas de razonamiento complejas con profundidad configurable
  • Monitoreo de Rendimiento: Métricas y análisis en tiempo real para optimización de flujos de trabajo
  • Continuidad de Hilos: Estado de conversación persistente entre sesiones
  • Caché de Flujos de Trabajo: Optimización de rendimiento para operaciones repetidas

Rendimiento Híbrido Vector-Grafo

  • Eficiencia de Memoria: Almacenamiento optimizado de 2GB que soporta 349,525+ vectores
  • Búsqueda Híbrida: Búsqueda en menos de 300ms que combina similitud vectorial con expansión de grafos
  • Extracción de Entidades: Reconocimiento automático de personas, conceptos, eventos y relaciones
  • Recorrido de Grafos: Exploración de relaciones multi-profundidad con límites configurables
  • Arquitectura Escalable: Despliegue con banderas de funciones y reversión sin tiempo de inactividad

Gestión de Personajes de IA con Grafos de Conocimiento

  • Creación de Personajes: Personajes de IA configurables con capacidades de memoria y grafos
  • Almacenamiento de Memoria Mejorado: Memoria consciente del contexto con extracción automática de entidades
  • Búsqueda Híbrida: Encuentre recuerdos relevantes usando similitud vectorial y relaciones de grafos
  • Construcción de Grafos de Conocimiento: Reconocimiento automático de entidades y mapeo de relaciones
  • Historial de Conversaciones: Seguimiento completo de conversaciones con vinculación de entidades
  • Limpieza de Memoria: Limpieza automatizada de recuerdos antiguos y entidades de grafos huérfanas

Herramientas de Integración MCP (24 en total)

  • Herramientas de Personajes (5): create_persona, list_personas, get_persona, update_persona, delete_persona
  • Herramientas de Memoria (6): add_memory, search_persona_memories, get_full_memory, add_conversation, get_conversation_history, cleanup_persona_memories
  • Herramientas de Grafos (4): explore_knowledge_graph, hybrid_memory_search, get_graph_context, get_graph_stats
  • Herramientas de Flujos de Trabajo (6): execute_workflow, get_workflow_status, resume_workflow, cancel_workflow, list_active_workflows, get_workflow_metrics
  • Herramientas de Utilidad (3): get_system_health, get_persona_stats, test_connection

Características de Seguridad y Producción

  • Autenticación por Clave API: Generación segura de claves con permisos basados en roles
  • Limitación de Tasa: Limitación de tasa multi-nivel (global, por clave, por endpoint)
  • Validación de Entrada: Validación y saneamiento integral de solicitudes
  • Registro Estructurado: Registro basado en Winston con métricas de rendimiento
  • Monitoreo de Salud: Múltiples endpoints de verificación de salud para diferentes necesidades de monitoreo
  • Coordinación Multi-Servidor: Integración perfecta entre sistemas v2 y v3

🎮 Casos de Uso

Operaciones de Flujos de Trabajo LangGraph (v3.0)

Conversación Básica de IA con Flujo de Trabajo

// 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
});

Razonamiento Multi-Paso con Aprobación 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"]
    }
  }
});

Monitoreo de Rendimiento de Flujos de Trabajo

// 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"
});

Memoria de Asistente de IA con Grafos de Conocimiento (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
  }
});

Descubrimiento de Contexto de Memoria Mejorado

// 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
});

Integración con 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"
      }
    }
  }
}

🛠️ Desarrollo

Estructura del Proyecto

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

Configuración de Desarrollo

# 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

Configuración de Entorno

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 Rendimiento

Almacenamiento Vectorial (Sistema v2)

  • Almacenamiento Vectorial: ~6MB por 1000 vectores (1536 dimensiones)
  • Rendimiento de Búsqueda: <50ms para corpus de más de 10,000 vectores
  • Eficiencia de Memoria: Utilización del 99.9% del espacio de búfer asignado
  • Rendimiento: Tasa de inserción de 1000+ vectores/segundo
  • Capacidad: 349,525 vectores en configuración de 2GB

Rendimiento de Flujos de Trabajo (Sistema v3)

  • Ejecución de Flujos de Trabajo: <2s para conversaciones estándar
  • Razonamiento Multi-Paso: <10s para cadenas de razonamiento complejas
  • Integración de Memoria: <500ms para recuperación de memoria híbrida
  • Procesamiento de Aprobaciones: <1s para flujos de trabajo de aprobación humana
  • Rendimiento de Caché: Ratio de aciertos de caché del 95%+ para operaciones repetidas

🔒 Características de Seguridad

  • Autenticación: Autenticación basada en clave API con generación segura
  • Autorización: Control de acceso basado en roles con permisos granulares
  • Limitación de Tasa: Múltiples capas de limitación de tasa (global, por clave, por endpoint)
  • Validación de Entrada: Validación y saneamiento integral de solicitudes
  • Cabeceras de Seguridad: Implementación de Helmet.js con políticas CSP
  • Registro de Auditoría: Rastro de auditoría completo para todas las operaciones
  • Seguridad Multi-Servidor: Seguridad coordinada entre sistemas v2 y v3
  • Aprobación de Flujos de Trabajo: Seguridad humana en el bucle para operaciones sensibles

🤝 Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características (git checkout -b feature/amazing-feature)
  3. Realice sus cambios
  4. Agregue pruebas para la nueva funcionalidad
  5. Confirme sus cambios (git commit -m 'Add amazing feature')
  6. Envíe a la rama (git push origin feature/amazing-feature)
  7. Abra una Solicitud de Extracción

Directrices de Desarrollo

  • Siga el estilo y los patrones de código existentes
  • Agregue pruebas integrales para nuevas características
  • Actualice la documentación para cualquier cambio de API
  • Asegúrese de que todas las pruebas pasen antes de enviar la PR
  • Incluya consideraciones de rendimiento para operaciones vectoriales
  • Pruebe las integraciones de flujos de trabajo a fondo
  • Considere escenarios de aprobación humana para nuevas características

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCIA para más detalles.

🆘 Soporte

Documentación

  • Base de Datos Vectorial: Consulte zero-vector/README.md para documentación detallada del servidor v2
  • Sistema LangGraph: Consulte zero-vector-3/README.md para documentación de flujos de trabajo v3
  • Servidor MCP: Consulte MCP/README.md para configuración de MCP y documentación de herramientas

Solución de Problemas

Problemas de Conexión:

# 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 Flujos de Trabajo:

# 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 Comunes:

  • Asegúrese de que Node.js 18+ esté instalado
  • Verifique la configuración de la clave API en el archivo .env de MCP
  • Compruebe que ambos servidores Zero-Vector estén ejecutándose antes de iniciar el servidor MCP
  • Asegure una asignación de memoria suficiente (4GB+ recomendado para v3.0)
  • Verifique que PostgreSQL y Redis estén ejecutándose para flujos de trabajo v3

Obteniendo Ayuda

  • Problemas de GitHub: Reporte errores y solicitudes de características
  • Discusiones: Haga preguntas y comparta ideas
  • Wiki: Documentación adicional y ejemplos

Zero-Vector MCP v3.0 - Sistema de memoria de IA híbrido vector-grafo listo para producción con orquestación avanzada de flujos de trabajo LangGraph e inteligencia multi-agente