零向量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种专业工具,包括工作流管理、图形探索和高级内容访问
- 多步推理 -具有审批门和性能监控的复杂推理链
- 知识图谱智能 -自动实体识别和关系映射
- 生产就绪架构 -功能标志、全面监控和零停机部署
🏗️ 系统架构```mermaid
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
### 安装```bash
# 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
快速测试```bash
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对话```javascript
// 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
});
具有人类认可的多步推理```javascript
// 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"]
}
}
});
#### 工作流性能监控```javascript
// 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)```javascript
// 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
}
});
### 增强的内存上下文发现```javascript
// 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)```json
{
"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
开发设置```bash
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服务器:**```bash
NODE_ENV=development
PORT=3000
MAX_MEMORY_MB=2048
DEFAULT_DIMENSIONS=1536
LOG_LEVEL=info
零矢量v3服务器:```bash
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服务器:**```bash
# 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.mdv3工作流文档 - MCP服务器:参见
MCP/README.md用于MCP设置和工具文档
故障排除
连接问题:```bash
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
**工作流程问题:**```bash
# 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存储系统
