Zero-Vector MCP

Zero-Vector MCP: AI Persona Memory & Vector Database System

A complete AI persona memory management system combining a high-performance vector database server with a Model Context Protocol (MCP) interface for seamless integration with AI development tools like Cline.

🔗GitHub Repository:https://github.com/MushroomFleet/zero-vector-MCP

graph TB subgraph "AI Development Environment" A[Cline AI Assistant] --> B[MCP Client] end subgraph "Zero-Vector MCP System" B --> C[MCP Server] C --> D[Zero-Vector API] D --> E[Vector Database] D --> F[SQLite Metadata] subgraph "Core Services" G[Persona Manager] H[Memory Service] I[Embedding Service] end D --> G D --> H D --> I end subgraph "External Services" J[OpenAI Embeddings] K[Local Transformers] end I --> J I --> K style A fill:#e1f5fe style C fill:#f3e5f5 style E fill:#e8f5e8 style G fill:#fff3e0 style H fill:#fff3e0 style I fill:#fff3e0

- Node.js 18.0.0 or higher
- 2GB+ available RAM (recommended)
- Git

# Clone the repository git clone https://github.com/MushroomFleet/zero-vector-MCP.git cd zero-vector-MCP # 1. Set up the Zero-Vector server 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 Open AI API key npm start # 2. Set up the MCP server (in a new terminal) cd MCP npm install cp env.example .env # Edit .env with your Zero-Vector server URL and API key npm start

# Test the vector database curl http://localhost:3000/health # Test MCP server connection cd MCP npm run test:connection

This system consists of two main components, each with detailed documentation:

The core vector database server providing:

- High-performance vector storage and similarity search
- RESTful API for vector operations
- SQLite metadata persistence
- Authentication and security middleware
- Real-time monitoring and health checks

The Model Context Protocol interface providing:

- 13 specialized tools for persona and memory management
- Seamless integration with AI development tools
- Comprehensive error handling and validation
- Structured logging and performance monitoring

- Memory Efficiency: 2GB optimized storage supporting 349,525+ vectors
- High-Speed Search: Sub-50ms query times with cosine similarity
- Scalable Architecture: Three-tier design with comprehensive monitoring
- Multiple Metrics: Cosine, Euclidean, and dot product similarity

- Persona Creation: Configurable AI personas with custom behavior settings
- Memory Storage: Context-aware memory with importance scoring
- Semantic Search: Find relevant memories using vector similarity
- Conversation History: Complete conversation tracking and retrieval
- Memory Cleanup: Automated cleanup of old or low-importance memories

- Persona Tools:create_persona,list_personas,get_persona,update_persona,delete_persona
- Memory Tools:add_memory,search_persona_memories,add_conversation,get_conversation_history,cleanup_persona_memories
- Utility Tools:get_system_health,get_persona_stats,test_connection

- API Key Authentication: Secure key generation with role-based permissions
- Rate Limiting: Multi-tier rate limiting (global, per-key, per-endpoint)
- Input Validation: Comprehensive request validation and sanitization
- Structured Logging: Winston-based logging with performance metrics
- Health Monitoring: Multiple health check endpoints for different monitoring needs

// Create a persona for an AI assistant const persona = await mcpClient.createPersona({ name: "Technical Assistant", description: "Helpful coding assistant with memory", systemPrompt: "You are a helpful technical assistant...", maxMemorySize: 1000 }); // Add important information to memory await mcpClient.addMemory({ personaId: persona.id, content: "User prefers TypeScript over JavaScript", type: "preference", importance: 0.8 }); // Search for relevant memories during conversation const relevantMemories = await mcpClient.searchPersonaMemories({ personaId: persona.id, query: "coding preferences", limit: 5 });

// Direct vector operations through the API const response = await fetch('http://localhost:3000/api/vectors/search', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-API-Key': 'your-api-key' }, body: JSON.stringify({ query: [0.1, 0.2, 0.3, / ... 1536 dimensions /], limit: 10, threshold: 0.7 }) });

{ "mcpServers": { "zero-vector": { "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_api_key_here" } } } }

zero-vector-MCP/ ├── zero-vector/ # Vector database server │ ├── server/ # Node.js backend │ │ ├── src/ # Source code │ │ ├── scripts/ # Setup scripts │ │ ├── data/ # Database files │ │ └── README.md # Server documentation │ └── README.md # Server overview ├── MCP/ # Model Context Protocol server │ ├── src/ # MCP server source │ │ ├── tools/ # MCP tool implementations │ │ └── utils/ # Utilities │ ├── .env.example # Environment template │ └── README.md # MCP documentation ├── DOCS/ # Internal documentation └── README.md # This file

# Start Zero-Vector server in development mode cd zero-vector/server npm run dev # Start MCP server in development mode (new terminal) cd MCP npm run dev # Run tests npm test

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

ZERO_VECTOR_BASE_URL=http://localhost:3000 ZERO_VECTOR_API_KEY=your_api_key_here MCP_SERVER_NAME=zero-vector-mcp LOG_LEVEL=info

- Vector Storage: ~6MB per 1000 vectors (1536 dimensions)
- Search Performance: <50ms for 10,000+ vector corpus
- Memory Efficiency: 99.9% utilization of allocated buffer space
- Throughput: 1000+ vectors/second insertion rate
- Capacity: 349,525 vectors in 2GB configuration

- Authentication: API key-based authentication with secure generation
- Authorization: Role-based access control with granular permissions
- Rate Limiting: Multiple rate limiting layers (global, per-key, per-endpoint)
- Input Validation: Comprehensive request validation and sanitization
- Security Headers: Helmet.js implementation with CSP policies
- Audit Logging: Complete audit trail for all operations
- Fork the repository
- Create a feature branch (git checkout -b feature/amazing-feature)
- Make your changes
- Add tests for new functionality
- Commit your changes (git commit -m 'Add amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

- Follow existing code style and patterns
- Add comprehensive tests for new features
- Update documentation for any API changes
- Ensure all tests pass before submitting PR
- Include performance considerations for vector operations

This project is licensed under the MIT License - see theLICENSEfile for details.

- Vector Database: Seezero-vector/README.mdfor detailed server documentation
- MCP Server: SeeMCP/README.mdfor MCP setup and tool documentation

# Check Zero-Vector server health curl http://localhost:3000/health # Test MCP server connection cd MCP && npm run test:connection

- TranscriptionTools-MCP— Transcript processing
- DeepLucid3D-MCP— Cognitive processing
- UNO-MCP— Narrative enhancement
- gitea-mcp— Gitea integration
- zero-vector-MCP— Procedural generation

Persistent memory, teams, and projects for AI agents. 76 MCP tools for storing, recalling, and sharing knowledge across sessions.