Zero-Vector MCP
Zero-Vector MCP acts like a high-powered digital brain for AI assistants, giving them the ability to remember past conversations and user preferences long after a session has ended. Instead of an AI "forgetting" everything once a chat window is closed, this tool provides a persistent filing cabinet where it can …
About this Protocol
How to Use
1. Installation
Zero-Vector MCP requires Node.js 18.0.0 or higher and approximately 2GB of RAM. The installation involves setting up both the core database server and the MCP interface.
Step 1: Clone the repository
git clone https://github.com/MushroomFleet/zero-vector-MCP.git
cd zero-vector-MCP
Step 2: Set up the Zero-Vector server
cd zero-vector/server
npm install
npm run setup:database
npm run generate:api-key # Note the generated key for the MCP config
cp env.example .env # Add your OpenAI API key to this file
npm start
Step 3: Set up the MCP server
# Open a new terminal
cd MCP
npm install
cp env.example .env
# Edit .env with your Zero-Vector server URL and the API key generated in Step 2
npm start
2. Configuration
To integrate Zero-Vector MCP with clients like Cline, add the following to your MCP settings configuration file:
{
"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"
}
}
}
}
Environment Variables for MCP Server:
* ZERO_VECTOR_BASE_URL: The URL where the core server is running (default: http://localhost:3000).
* ZERO_VECTOR_API_KEY: The key generated during the server setup.
* LOG_LEVEL: Logging verbosity (e.g., info).
3. Available Tools
The MCP server provides 13 specialized tools for persona and memory management:
Persona Management Tools:
* create_persona: Configure a new AI persona with custom behavior settings.
* list_personas: List all existing personas.
* get_persona: Retrieve details for a specific persona.
* update_persona: Modify persona settings.
* delete_persona: Remove a persona.
Memory & Conversation Tools:
* add_memory: Store context-aware memory with importance scoring.
* search_persona_memories: Find relevant memories using semantic vector similarity.
* add_conversation: Log conversation history.
* get_conversation_history: Retrieve complete conversation tracking.
* cleanup_persona_memories: Automated cleanup of low-importance or old memories.
Utility Tools:
* get_system_health: Check database and server status.
* get_persona_stats: View statistics for a specific persona.
* test_connection: Verify the link between the MCP server and the vector database.
4. Example Prompts
Creating a Persona
"Create a new persona named 'Technical Assistant' for a coding assistant role. Set the system prompt to 'You are a helpful technical assistant specializing in TypeScript' and limit its memory to 1000 items."
Adding a Memory
"Add a memory for the 'Technical Assistant' persona. The user prefers using Tailwind CSS for styling and TypeScript for all frontend logic. Set the importance to 0.9."
Retrieving Relevant Context
"Search the 'Technical Assistant' memories for any information related to the user's coding preferences or preferred frontend frameworks."
Checking Health
"Check the system health and performance statistics for the Zero-Vector MCP server."
Use Cases
Use Case 1: Persistent Developer Preferences for Coding Assistants
Problem: AI coding assistants like Cline or Claude often "forget" a developer's specific workflow, preferred libraries, or naming conventions once a new chat session starts. Re-explaining that you prefer "functional components over classes" or "Tailwind CSS with specific brand colors" every time is inefficient.
Solution: Zero-Vector MCP allows the AI to create a "Developer Persona" that stores these preferences as high-importance memories. By using semantic search, the assistant can retrieve relevant coding standards at the start of a session or when a specific task is initiated.
Example: A developer tells the AI, "I always use Vitest for testing." The AI uses add_memory with an importance score of 0.9. In a new session, when the developer says "Write a test for this utility," the AI calls search_persona_memories for "testing framework" and automatically generates Vitest code instead of Jest.
Use Case 2: Context-Aware Documentation Retrieval (Local RAG)
Problem: When working on large projects, developers cannot fit thousands of lines of documentation or architectural ADRs (Architecture Decision Records) into the AI's limited context window without slowing down the model or hitting token limits.
Solution: The MCP functions as a local RAG (Retrieval-Augmented Generation) system. You can store project-specific documentation snippets in the vector database. The AI can then perform high-speed similarity searches (sub-50ms) to find only the relevant pieces of documentation needed to answer a specific query.
Example: A developer asks, "How is the authentication flow structured here?" The AI uses search_persona_memories with the query "authentication flow." It retrieves the specific vector-stored documentation and provides an accurate answer without having the entire manual in its active context.
Use Case 3: Dynamic Character Consistency in Narrative Design
Problem: In game development or creative writing, AI-driven NPCs (Non-Player Characters) often lose track of plot points, player relationships, or their own backstories as the conversation history grows, leading to immersion-breaking contradictions.
Solution: By creating individual personas for each character using create_persona, developers can store key narrative events as memories. The "Importance Scoring" feature ensures that critical plot points stay in memory while trivial chatter can be removed via cleanup_persona_memories.
Example: A player betrays an NPC. The AI adds a memory: "Player lied about the stolen artifact" with a type of "relationship_event" and high importance. Fifty chat turns later, the AI searches the NPC's memory for "player trust" and accurately reflects the character's lingering resentment in the dialogue.
Use Case 4: Intelligent Long-Term Research and Brainstorming
Problem: During a multi-day research project, an AI user might gather hundreds of facts, links, and insights. It is difficult to synthesize this information later if the AI cannot recall specific connections made in previous days.
Solution: Zero-Vector MCP acts as a "Second Brain" for the AI. Users can store research findings, and the AI can use the get_conversation_history and semantic search tools to find links between a new piece of information and something discussed days ago.
Example: A user is researching "solid-state batteries." Days later, they mention "electrolyte stability." The AI calls search_persona_memories and says, "This connects to the research paper you mentioned on Tuesday regarding ceramic separators; would you like me to compare the two?"
Use Case 5: Resource-Efficient AI Persona Management
Problem: Running large-scale vector databases can be resource-heavy and complex to set up for local development tools.
Solution: Zero-Vector MCP provides a high-capacity (349k+ vectors), memory-efficient (2GB RAM) solution specifically optimized for the Model Context Protocol. This allows developers to run a production-grade memory system locally or on a small server without the overhead of enterprise cloud vector databases.
Example: A developer integrates the Zero-Vector MCP into their local CLI tool. Using get_system_health and get_persona_stats, the tool monitors memory usage and automatically triggers cleanup_persona_memories for low-importance items once the vector count exceeds a certain threshold, ensuring the system remains fast and responsive.