MCP Memory Server with Qdrant Vector Database

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.

Features

🧠 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

🔍 Semantic Search

• Vector-based similarity search using sentence transformers

• Duplicate detection to prevent redundant content

• Configurable similarity thresholds

📝 Markdown Processing

• Intelligent content cleaning and optimization

• YAML front matter extraction

• Section-based content organization

🔧 MCP Integration

• Standard MCP protocol compliance for Cursor

• stdin/stdout communication

• Comprehensive tool set for memory operations

Architecture

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):

Or install Qdrant locally following their installation guide.

Install Dependencies

Using Poetry (recommended):

Or using pip:

Configuration

1. Copy the example environment file:

2. Edit .env with your settings:

Usage

Starting the Server

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:

Alternatively, you can run the server using Poetry:

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:

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:

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:

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:

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:

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:

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

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:

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

• Ensure Qdrant is running on configured host/port

• Check firewall settings

• Verify API key if using Qdrant Cloud

Embedding Model Download Issues

• 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:

Check Qdrant 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

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