A server for Zero-Vector's hybrid vector-graph persona and memory management system, featuring advanced LangGraph workflow capabilities.
š STATUS: PRODUCTION READY | Infrastructure: VALIDATED | LangGraph: OPERATIONAL
A complete AI persona memory management system combining a high-performance hybrid vector-graph database server with advanced LangGraph workflow orchestration and a Model Context Protocol (MCP) interface for sophisticated AI memory, relationship understanding, and multi-agent coordination.
š GitHub Repository: https://github.com/MushroomFleet/zero-vector-MCP
Last Infrastructure Validation: June 21, 2025
Current Version: v3.0 Production-Ready
Zero-Vector v2 Server: ā
Active (Port 3000)
Zero-Vector v3 LangGraph: ā
Active (Port 3001)
MCP Server: ā
Active (Multi-server coordination)
Zero-Vector MCP v3.0 provides a production-ready hybrid vector-graph solution with advanced LangGraph workflow capabilities for AI persona management, featuring:
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
# 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
This system consists of three main components, each with detailed documentation:
Location: zero-vector/README.md
The core vector database server providing:
Location: zero-vector-3/README.md
The advanced LangGraph workflow server providing:
Location: MCP/README.md
The Model Context Protocol interface providing:
create_persona, list_personas, get_persona, update_persona, delete_personaadd_memory, search_persona_memories, get_full_memory, add_conversation, get_conversation_history, cleanup_persona_memoriesexplore_knowledge_graph, hybrid_memory_search, get_graph_context, get_graph_statsexecute_workflow, get_workflow_status, resume_workflow, cancel_workflow, list_active_workflows, get_workflow_metricsget_system_health, get_persona_stats, test_connection// 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"
});
// 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
});
{
"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
Zero-Vector v2 Server:
NODE_ENV=development
PORT=3000
MAX_MEMORY_MB=2048
DEFAULT_DIMENSIONS=1536
LOG_LEVEL=info
Zero-Vector v3 Server:
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 Server:
# 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
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)This project is licensed under the MIT License - see the LICENSE file for details.
zero-vector/README.md for detailed v2 server documentationzero-vector-3/README.md for v3 workflow documentationMCP/README.md for MCP setup and tool documentationConnection Issues:
# 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
Workflow Issues:
# 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
Common Issues:
.env fileZero-Vector MCP v3.0 - Production-ready hybrid vector-graph AI memory system with advanced LangGraph workflow orchestration and multi-agent intelligence
A server for CodeFuse-CGM, a graph-integrated large language model designed for repository-level software engineering tasks.
Use command line tools in a secure fashion as MCP tools.
Provides preset prompt templates as tools to assist clients like Cursor and Windsurf in executing various tasks.
Provides local access to Cursor chat history for AI analysis and insights, with no external services or API keys required.
Run code in secure sandboxes hosted by E2B
A lightweight, AI-powered end-to-end testing framework for CI workflows. Requires an OpenAI API key.
An MCP server for managing application context using the Togello API.
Interact with the Unstructured API to manage data sources, destinations, workflows, and jobs.
A code sandbox for AI assistants to safely execute arbitrary code. Requires a 302AI API key for authentication.
A server for Zep, a long-term memory store for AI applications, requiring a ZEP_API_KEY for access.