AI导哈

向量数据库内存管理服务

一个基于Qdrant向量数据库的智能内存管理服务，提供语义搜索、策略治理和提示管理功能，专为Cursor IDE集成设计。

  • by hannesnortje
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 hannesnortje/MCP

使用说明

带Qdrant矢量数据库的MCP内存服务器

🎉 状态：生产就绪 ✅ | 完成所有9个实施步骤

一种模型上下文协议（MCP）服务器，使用Qdrant向量数据库进行语义搜索和存储，提供智能内存管理功能。专为Cursor IDE集成而构建，具有全面的策略治理功能。

🌟 完整功能集

🧠 多种内存类型

  • 全局内存：所有代理共享共同知识
  • 学习记忆：吸取的教训和应避免的错误
  • 代理特定内存：个体代理人背景和专业知识

🔍 高级搜索和处理

  • 基于向量的句子变换相似度搜索
  • 重复检测，防止冗余内容
  • 可配置的相似性阈值
  • Markdown处理与智能内容清理
  • YAML前体提取与节组织

🏛️ 政策治理体系 新

  • 75可执行规则 分为4类（原则、禁止的行为、要求、风格指南）
  • 语义策略搜索 基于向量嵌入的上下文规则发现
  • 合规性跟踪 有违规记录和代理责任
  • 版本管理 SHA-256完整性验证
  • 架构验证 强制执行所需的部分和数据一致性

📋 提示管理系统 新

  • 动态模板引擎 变量替换和条件逻辑
  • 代理商特定提示 具有自定义配置和角色定义
  • 验证框架 确保及时的一致性和格式标准
  • 上下文集成 具有增强提示的内存和策略系统

🔧 完成MCP集成

  • 9 MCP工具：内存管理、降价处理、策略合规性、提示生成
  • 4 MCP资源：对内存、策略、提示和系统状态的只读访问
  • Cursor IDE符合标准MCP协议
  • 具有全面错误处理功能的stdin/stdout通信

建筑

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

安装

先决条件

  1. Python 3.10+ 使用pip
  2. Qdrant数据库 （可以用Docker在本地运行）
  3. 光标IDE 用于MCP集成

设置Qdrant数据库

使用Docker（推荐）：

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

或者按照以下步骤在本地安装Qdrant 安装指南.

再进行

使用诗歌（推荐）：

# Install dependencies using Poetry
poetry install

或者使用pip：

# Install Python dependencies
pip install -r requirements.txt

配置

  1. 复制示例环境文件：
cp .env.example .env
  1. 编辑 .env 使用您的设置：
# 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

用法

启动服务器

python server.py

服务器将：

  1. 连接到Qdrant数据库
  2. 初始化向量集合
  3. 加载嵌入模型
  4. 通过stdin/stdout开始监听MCP命令

游标IDE集成

将服务器添加到Cursor MCP配置中：

{
  "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"
      }
    }
  }
}

或者，您可以使用Poetry运行服务器：

poetry run python server.py

MCP工具

1. set_agent_context

从markdown文件初始化代理上下文。

参数：

  • agent_id （string）：代理的唯一标识符
  • context_file_path （string）：带有代理上下文的markdown文件的路径
  • description （字符串，可选）：上下文描述

例子：

{
  "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

将内容添加到所有代理共享的全局内存中。

参数：

  • file_path （string）：markdown文件的路径
  • description （字符串，可选）：内容描述

例子：

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

3. add_to_learned_memory

储存经验教训，避免重复错误。

参数：

  • file_path （string）：包含课程的markdown文件的路径
  • lesson_type （string）：课程类型（例如“部署”、“安全”）
  • description （字符串，可选）：课程描述

例子：

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

4. add_to_agent_memory

将内容添加到特定于代理的内存中。

参数：

  • agent_id （string）：目标代理标识符
  • file_path （string）：markdown文件的路径
  • description （字符串，可选）：内容描述

例子：

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

5. query_memory

在内存集合中搜索相关内容。

参数：

  • query （string）：搜索查询
  • memory_type （string）：“全局”、“已学习”、“代理”或“全部”
  • agent_id （字符串，可选）：特定于代理的查询的代理ID
  • max_results （整数，可选）：最大结果（默认值：10）

例子：

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

6. compare_against_learned_memory

对照过去的经验教训检查拟议的行动。

参数：

  • action_description （string）：拟议行动的描述
  • agent_id （string，可选）：发出请求的代理

例子：

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

内存类型说明

全局内存

  • 目的：存储所有代理共享的知识
  • 内容：编码标准、文件、最佳做法
  • 访问：所有代理都可以查询此内存
  • 用例：公司范围内的政策、架构决策

学习记忆

  • 目的：从过去的错误中吸取教训
  • 内容：事故报告、尸检、反模式
  • 访问：大多数代理（不包括“类人”测试人员）
  • 用例：避免重复过去的错误，改进决策

代理特定内存

  • 目的：存储特定于单个代理的知识
  • 内容：角色定义、专业知识、背景
  • 访问：只有特定代理人
  • 用例：代理初始化，专业知识

测试

运行基本功能测试

python tests/test_basic_functionality.py

这将测试：

  • Qdrant连接和收集设置
  • 内存操作（添加、查询、重复检测）
  • Markdown处理和内容清理
  • 矢量嵌入与相似性搜索

使用样本数据进行手动测试

  1. 启动服务器：
python server.py
  1. 在中使用提供的示例markdown文件 sample_data/:
    • frontend_agent_context.md：前端代理上下文
    • backend_agent_context.md：后端代理上下文
    • deployment_lessons.md：吸取的经验教训
    • global_standards.md：全球发展标准

故障排除

常见问题

Qdrant连接失败

❌ Failed to initialize Qdrant: ConnectionError
  • 确保Qdrant在配置的主机/端口上运行
  • 检查防火墙设置
  • 如果使用Qdrant Cloud，请验证API密钥

嵌入模型下载问题

❌ Failed to load embedding model
  • 确保首次下载时有互联网连接
  • 检查可用磁盘空间（型号可能很大）
  • 在配置中尝试替代模型

内存已满/性能问题

  • 减少 EMBEDDING_DIMENSION 对于较小的型号
  • 增加 SIMILARITY_THRESHOLD 减少结果
  • 考虑从集合中删除旧内容

调试

启用调试日志记录：

export LOG_LEVEL=DEBUG
python server.py

检查Qdrant集合：

curl http://localhost:6333/collections

配置参考

环境变量

变量 默认值 描述
QDRANT_HOST localhost Qdrant服务器主机
QDRANT_PORT 6333 Qdrant服务器端口
QDRANT_API_KEY Qdrant Cloud的API密钥
EMBEDDING_MODEL 全MiniLM-L6-v2 句子转换模型
EMBEDDING_DIMENSION 384 矢量维度大小
SIMILARITY_THRESHOLD 0.8 重复检测阈值
MAX_RESULTS 10 默认最大查询结果
DEFAULT_AGENT_ID 默认 默认代理标识符
LOG_LEVEL 信息 记录详细信息

集合名称

  • 全局内存: global_memory
  • 学习记忆: learned_memory
  • 代理内存: agent_specific_memory_{agent_id}

发展

项目结构

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

贡献

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 运行测试： python -m pytest tests/
  5. 提交拉取请求

添加新工具

  1. 添加工具功能 MCPMemoryServer._register_tools()
  2. 更新 _list_tools() 带有工具模式的方法
  3. 为新功能添加测试
  4. 更新此自述文件

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

  1. 检查上面的故障排除部分
  2. 查看Qdrant文档以了解数据库问题
  3. 检查MCP协议文档是否存在集成问题
  4. 打开一个包含详细日志和配置的问题

相关 MCP