Zero Vector 3

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

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

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

🔗 GitHub存储库：

🎯 系统状态：运行

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

✅ 最近验证的基础设施

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

📊 确认的绩效指标

• 启动时间：2-3秒完成系统初始化
• LangGraph编译：对于7节点工作流图，\ 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`](zero-vector/README.md)

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

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

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

**地点：** [`zero-vector-3/README.md`](zero-vector-3/README.md)

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

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

### 🔌 MCP服务器v3.0

**地点：** [`MCP/README.md`](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系统协调安全
- **工作流审批**：敏感操作的人在环安全

## 🤝 贡献

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

### 开发指南

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

## 📄 许可证

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

## 🆘 支持

### 文档

- **矢量数据库**：参见 [`zero-vector/README.md`](zero-vector/README.md) 有关v2服务器的详细文档
- **LangGraph系统**：参见 [`zero-vector-3/README.md`](zero-vector-3/README.md) v3工作流文档
- **MCP服务器**：参见 [`MCP/README.md`](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存储系统*