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
Access and interact with Harness platform data, including pipelines, repositories, logs, and artifact registries.
š Build iOS Xcode workspace/project and feed back errors to llm.
Advanced code search and transformation powered by ugrep and ast-grep for modern development workflows.
Official Zeplin server for AI-assisted UI development.
The definitive Vibe Coder's sanity check MCP server: Prevents cascading errors by calling a "Vibe-check" agent to ensure alignment and prevent scope creep
Fetch comprehensive information about CRAN packages, including READMEs, metadata, and search functionality.
Interact with Jupyter notebooks running in any JupyterLab environment, supporting real-time control and smart execution of notebook cells.
An MCP server for managing API test data and resources.
MCP server for interacting with the Godot game engine, providing tools for editing, running, debugging, and managing scenes in Godot projects.
Manage Google Apps Script projects, including creation, editing, deployment, and execution. Requires Google Cloud credentials for authentication.