MCP Memory Server with Qdrant Vector Database

🎉 STATUS: PRODUCTION READY ✅ | All 9 Implementation Steps Complete

A Model Context Protocol (MCP) server that provides intelligent memory management capabilities using Qdrant vector database for semantic search and storage. Built specifically for Cursor IDE integration with comprehensive policy governance.

🌟 Complete Feature Set

🧠 Multiple Memory Types

• Global Memory: Shared across all agents for common knowledge

• Learned Memory: Lessons learned and mistakes to avoid

• Agent-Specific Memory: Individual agent contexts and specialized knowledge

🔍 Advanced Search & Processing

• Vector-based similarity search using sentence transformers

• Duplicate detection to prevent redundant content

• Configurable similarity thresholds

• Markdown processing with intelligent content cleaning

• YAML front matter extraction and section organization

🏛️ Policy Governance System (NEW)

• 75 Enforceable Rules across 4 categories (Principles, Forbidden Actions, Requirements, Style Guide)

• Semantic Policy Search with vector embeddings for contextual rule discovery

• Compliance Tracking with violation logging and agent accountability

• Version Management with SHA-256 integrity verification

• Schema Validation enforcing required sections and data consistency

📋 Prompt Management System (NEW)

• Dynamic Template Engine with variable substitution and conditional logic

• Agent-Specific Prompts with custom configurations and role definitions

• Validation Framework ensuring prompt consistency and formatting standards

• Context Integration with memory and policy systems for enhanced prompts

🔧 Complete MCP Integration

• 9 MCP Tools: Memory management, markdown processing, policy compliance, prompt generation

• 4 MCP Resources: Read-only access to memory, policies, prompts, and system status

• Standard MCP protocol compliance for Cursor IDE

• stdin/stdout communication with comprehensive error handling

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│                 │    │                  │    │                 │
│   Cursor IDE    │◄──►│  MCP Server      │◄──►│  Qdrant Vector  │
│                 │    │  (stdin/stdout)  │    │  Database       │
│                 │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌──────────────────┐
                       │ Sentence         │
                       │ Transformers     │
                       │ (Embeddings)     │
                       └──────────────────┘

Installation

Prerequisites

1. Python 3.10+ with pip

2. Qdrant Database (can run locally with Docker)

3. Cursor IDE for MCP integration

Setup Qdrant Database

Using Docker (recommended):

docker run -p 6333:6333 -v $(pwd)/qdrant_storage:/qdrant/storage qdrant/qdrant

Or install Qdrant locally following their installation guide.

Install Dependencies

Using Poetry (recommended):

# Install dependencies using Poetry
poetry install

Or using pip:

# Install Python dependencies
pip install -r requirements.txt

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your settings:

# Qdrant Configuration
QDRANT_HOST=localhost
QDRANT_PORT=6333
QDRANT_API_KEY=

# Embedding Model Configuration  
EMBEDDING_MODEL=all-MiniLM-L6-v2
EMBEDDING_DIMENSION=384

# Memory Configuration
SIMILARITY_THRESHOLD=0.8
MAX_RESULTS=10

# Agent Configuration
DEFAULT_AGENT_ID=default

# Server Configuration
LOG_LEVEL=INFO

Usage

Starting the Server

python server.py

The server will:

1. Connect to Qdrant database

2. Initialize vector collections

3. Load the embedding model

4. Start listening for MCP commands via stdin/stdout

Cursor IDE Integration

Add the server to your Cursor MCP configuration:

{
  "mcpServers": {
    "memory-server": {
      "command": "/media/hannesn/storage/Code/MCP/.venv/bin/python",
      "args": ["/media/hannesn/storage/Code/MCP/server.py"],
      "cwd": "/media/hannesn/storage/Code/MCP",
      "env": {
        "PYTHONPATH": "/media/hannesn/storage/Code/MCP",
        "QDRANT_HOST": "localhost",
        "QDRANT_PORT": "6333",
        "EMBEDDING_MODEL": "all-MiniLM-L6-v2",
        "SIMILARITY_THRESHOLD": "0.8",
        "MAX_RESULTS": "10",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Alternatively, you can run the server using Poetry:

poetry run python server.py

MCP Tools

1. set_agent_context

Initialize agent context from a markdown file.

Parameters:

• agent_id (string): Unique identifier for the agent

• context_file_path (string): Path to markdown file with agent context

• description (string, optional): Description of the context

Example:

{
  "tool": "set_agent_context",
  "arguments": {
    "agent_id": "frontend_dev",
    "context_file_path": "./contexts/frontend_agent.md",
    "description": "Frontend development agent context"
  }
}

2. add_to_global_memory

Add content to global memory shared across all agents.

Parameters:

• file_path (string): Path to markdown file

• description (string, optional): Content description

Example:

{
  "tool": "add_to_global_memory", 
  "arguments": {
    "file_path": "./docs/coding_standards.md",
    "description": "Company coding standards"
  }
}

3. add_to_learned_memory

Store lessons learned to avoid repeated mistakes.

Parameters:

• file_path (string): Path to markdown file with lessons

• lesson_type (string): Type of lesson (e.g., "deployment", "security")

• description (string, optional): Lesson description

Example:

{
  "tool": "add_to_learned_memory",
  "arguments": {
    "file_path": "./lessons/deployment_issues.md", 
    "lesson_type": "deployment",
    "description": "Critical deployment lessons"
  }
}

4. add_to_agent_memory

Add content to agent-specific memory.

Parameters:

• agent_id (string): Target agent identifier

• file_path (string): Path to markdown file

• description (string, optional): Content description

Example:

{
  "tool": "add_to_agent_memory",
  "arguments": {
    "agent_id": "backend_dev",
    "file_path": "./docs/api_patterns.md",
    "description": "Backend API design patterns"
  }
}

5. query_memory

Search memory collections for relevant content.

Parameters:

• query (string): Search query

• memory_type (string): "global", "learned", "agent", or "all"

• agent_id (string, optional): Agent ID for agent-specific queries

• max_results (integer, optional): Maximum results (default: 10)

Example:

{
  "tool": "query_memory",
  "arguments": {
    "query": "authentication best practices",
    "memory_type": "all",
    "max_results": 5
  }
}

6. compare_against_learned_memory

Check proposed actions against past lessons learned.

Parameters:

• action_description (string): Description of proposed action

• agent_id (string, optional): Agent making the request

Example:

{
  "tool": "compare_against_learned_memory",
  "arguments": {
    "action_description": "Deploy database migration on Friday afternoon",
    "agent_id": "devops_agent"
  }
}

Memory Types Explained

Global Memory

• Purpose: Store knowledge shared across all agents

• Content: Coding standards, documentation, best practices

• Access: All agents can query this memory

• Use Case: Company-wide policies, architectural decisions

Learned Memory

• Purpose: Store lessons learned from past mistakes

• Content: Incident reports, post-mortems, anti-patterns

• Access: Most agents (exclude "human-like" testers)

• Use Case: Avoid repeating past mistakes, improve decisions

Agent-Specific Memory

• Purpose: Store knowledge specific to individual agents

• Content: Role definitions, specialized knowledge, context

• Access: Only the specific agent

• Use Case: Agent initialization, specialized expertise

Testing

Run Basic Functionality Tests

python tests/test_basic_functionality.py

This will test:

• Qdrant connection and collection setup

• Memory operations (add, query, duplicate detection)

• Markdown processing and content cleaning

• Vector embedding and similarity search

Manual Testing with Sample Data

1. Start the server:

python server.py

2. Use the provided sample markdown files in sample_data/:

   • frontend_agent_context.md: Frontend agent context

   • backend_agent_context.md: Backend agent context

   • deployment_lessons.md: Learned lessons

   • global_standards.md: Global development standards

Troubleshooting

Common Issues

Qdrant Connection Failed

❌ Failed to initialize Qdrant: ConnectionError

• Ensure Qdrant is running on configured host/port

• Check firewall settings

• Verify API key if using Qdrant Cloud

Embedding Model Download Issues

❌ Failed to load embedding model

• Ensure internet connection for first download

• Check available disk space (models can be large)

• Try alternative model in configuration

Memory Full / Performance Issues

• Reduce EMBEDDING_DIMENSION for smaller models

• Increase SIMILARITY_THRESHOLD to reduce results

• Consider pruning old content from collections

Debugging

Enable debug logging:

export LOG_LEVEL=DEBUG
python server.py

Check Qdrant collections:

curl http://localhost:6333/collections

Configuration Reference

Environment Variables

Collection Names

• Global Memory: global_memory

• Learned Memory: learned_memory

• Agent Memory: agent_specific_memory_{agent_id}

Development

Project Structure

mcp-memory-server/
├── server.py                 # Main MCP server
├── src/
│   ├── __init__.py
│   ├── config.py             # Configuration management
│   ├── memory_manager.py     # Qdrant operations
│   └── markdown_processor.py # Markdown handling
├── tests/
│   └── test_basic_functionality.py
├── sample_data/              # Example markdown files
├── docs/                     # Additional documentation
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Poetry configuration
└── README.md                # This file

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Run tests: python -m pytest tests/

5. Submit a pull request

Adding New Tools

1. Add tool function to MCPMemoryServer._register_tools()

2. Update _list_tools() method with tool schema

3. Add tests for the new functionality

4. Update this README

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section above

2. Review Qdrant documentation for database issues

3. Check MCP protocol documentation for integration issues

4. Open an issue with detailed logs and configuration