使用说明

零向量MCP v3.0：具有LangGraph工作流的混合向量图AI存储系统

🚀 状态：生产就绪 | 基础设施：已验证 | 语言图：操作

一个完整的AI角色内存管理系统，将高性能混合矢量图数据库服务器与先进的LangGraph工作流编排和模型上下文协议（MCP）接口相结合，用于复杂的AI内存、关系理解和多代理协调。

🔗 GitHub存储库： https://github.com/MushroomFleet/zero-vector-MCP

🎯 系统状态：运行

上次基础设施验证：2025年6月21日
当前版本：v3.0生产就绪
零矢量v2服务器: ✅ 活动（端口3000）
零向量v3语言图: ✅ 活动（端口3001）
MCP服务器: ✅ 主动（多服务器协调）

✅ 最近验证的基础设施

LangGraph状态图架构：通过适当的Zod集成解决
多代理编排：7节点工作流图可操作
人在循环处理：审批工作流功能正常
性能缓存：Redis与PostgreSQL的集成已激活
服务协调：v2/v3系统协调已验证
MCP集成：24个工具在两个系统中全面运行

📊 确认的绩效指标

启动时间：2-3秒完成系统初始化
LangGraph编译：对于7节点工作流图，<3ms
向量运算：10000+矢量搜索小于50ms
工作流执行：对于标准AI对话，<2s
内存集成：混合内存检索<500ms
缓存命中率：95%以上的性能优化

🎯 概述

Zero Vector MCP v3.0提供了一种生产就绪的混合矢量图解决方案，具有用于AI角色管理的高级LangGraph工作流功能，其特点是：

混合矢量图引擎 -将语义搜索与知识图遍历相结合
LangGraph工作流编排 -多智能体协同与人在环处理
AI人物记忆与关系 -具有实体提取和图构建的上下文感知内存
增强的MCP集成 -24种专业工具，包括工作流管理、图形探索和高级内容访问
多步推理 -具有审批门和性能监控的复杂推理链
知识图谱智能 -自动实体识别和关系映射
生产就绪架构 -功能标志、全面监控和零停机部署

🏗️ 系统架构

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

🚀 快速开始

先决条件

Node.js 18.0.0或更高版本
4GB以上可用RAM（建议用于v3.0）
PostgreSQL（用于LangGraph检查点）
Redis（用于性能缓存）
Git

安装

# 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

快速测试

# 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

📚 组件文档

该系统由三个主要部分组成，每个部分都有详细的文档：

🗄️ Zero Vector v2服务器（原始系统）

地点： zero-vector/README.md

核心矢量数据库服务器提供：

高性能矢量存储和相似性搜索
用于向量运算的RESTful API
SQLite元数据持久化
身份验证和安全中间件
实时监控和健康检查

🤖 零向量v3服务器（LangGraph系统）

地点： zero-vector-3/README.md

先进的LangGraph工作流服务器提供：

多代理工作流编排
人工参与审批流程
高级推理链和状态管理
性能缓存和监控
PostgreSQL检查点和Redis缓存

🔌 MCP服务器v3.0

地点： MCP/README.md

模型上下文协议接口提供：

24个用于角色、内存、图形和工作流管理的专用工具
v2和v3系统之间的多服务器协调
LangGraph工作流管理功能
与AI开发工具无缝集成
全面的错误处理和验证

✨ 主要特点

LangGraph工作流管理（v3.0中的新功能）

多代理编排：与状态管理进行复杂的代理协调
人在循环处理：具有简历功能的审批工作流
多步推理：具有可配置深度的复杂推理链
性能监控：用于工作流优化的实时指标和分析
线程连续性：会话间持续的对话状态
工作流缓存：重复操作的性能优化

混合矢量图性能

内存效率：2GB优化存储，支持349525+个矢量
混合搜索：结合向量相似性和图扩展的Sub-300ms搜索
实体提取：自动识别人、概念、事件和关系
图的遍历：具有可配置限制的多深度关系探索
可扩展体系结构：具有零停机回滚功能的标记部署

基于知识图的人工智能人物管理

人物角色创建：具有记忆和图形功能的可配置AI角色
增强的内存存储：具有自动实体提取功能的上下文感知内存
混合搜索：使用向量相似度和图形关系查找相关记忆
知识图谱构建：自动实体识别和关系映射
对话历史：通过实体链接完成对话跟踪
内存清理：自动清理旧内存和孤立的图形实体

MCP集成工具（共24个）

人物角色工具（5）: create_persona, list_personas, get_persona, update_persona, delete_persona
记忆工具（6）: add_memory, search_persona_memories, get_full_memory, add_conversation, get_conversation_history, cleanup_persona_memories
图形工具（4）: explore_knowledge_graph, hybrid_memory_search, get_graph_context, get_graph_stats
工作流工具（6）: execute_workflow, get_workflow_status, resume_workflow, cancel_workflow, list_active_workflows, get_workflow_metrics
实用工具（3）: get_system_health, get_persona_stats, test_connection

安全与生产特性

API密钥验证：使用基于角色的权限安全生成密钥
速率限制：多层速率限制（全局、每个密钥、每个端点）
输入验证：全面的请求验证和清理
结构化日志记录：基于Winston的日志记录和性能指标
健康监测：针对不同监控需求的多个健康检查端点
多服务器协调：v2和v3系统之间的无缝集成

🎮 用例

LangGraph工作流操作（v3.0）

与工作流的基本AI对话

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

具有人类认可的多步推理

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

工作流性能监控

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

带有知识图的AI助手内存（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
  }
});

增强的内存上下文发现

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

与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"
      }
    }
  }
}

🛠️ 发展

项目结构

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

开发设置

# 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

环境配置

零矢量v2服务器：

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

零矢量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

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

📊 性能特征

矢量存储（v2系统）

矢量存储器：每1000个向量约6MB（1536维）
搜索性能：对于10000+矢量语料库，<50ms
内存效率：分配的缓冲区空间利用率为99.9%
吞吐量：1000+矢量/秒插入率
容量：2GB配置中的349525个矢量

工作流性能（v3系统）

工作流执行：对于标准对话，<2s
多步推理：对于复杂的推理链，<10s
内存集成：混合内存检索<500ms
审批处理：对于人工审批工作流，<1s
高速缓存性能：重复操作的缓存命中率超过95%

🔒 安全功能

认证：具有安全生成功能的基于API密钥的身份验证
授权：基于角色的访问控制，具有细粒度权限
速率限制：多个速率限制层（全局、每个密钥、每个端点）
输入验证：全面的请求验证和清理
安全标头：使用CSP策略实现Helmet.js
审计日志：所有业务的完整审计跟踪
多服务器安全：跨v2和v3系统协调安全
工作流审批：敏感操作的人在环安全

🤝 贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
进行更改
添加新功能的测试
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

遵循现有的代码风格和模式
为新功能添加全面的测试
针对任何API更改更新文档
在提交PR之前，确保所有测试都通过
包括矢量操作的性能考虑因素
彻底测试工作流集成
考虑新功能的人工审批场景

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持

文档

矢量数据库：参见 zero-vector/README.md 有关v2服务器的详细文档
LangGraph系统：参见 zero-vector-3/README.md v3工作流文档
MCP服务器：参见 MCP/README.md 用于MCP设置和工具文档

故障排除

连接问题：

# 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

工作流程问题：

# 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

常见问题：

确保已安装Node.js 18+
验证MCP中的API密钥配置 .env 文件
启动MCP服务器之前，请检查两个Zero Vector服务器是否都在运行
确保足够的内存分配（v3.0建议使用4GB以上）
验证PostgreSQL和Redis是否正在为v3工作流运行

获取帮助

GitHub问题：报告错误和功能请求
讨论：提问并分享想法
维基：附加文件和示例

零矢量MCP v3.0 - 具有先进LangGraph工作流编排和多智能体智能的生产就绪混合矢量图AI存储系统