MCP内存服务
一个 MCP 服务器，使用 ChromaDB 和句子转换器为 Claude Desktop 提供语义记忆和持久存储功能。该服务支持长期记忆存储和语义搜索功能，非常适合跨对话和实例维护上下文。
帮助
使用TalkToGitHub与 Repo 对话！
特征
- 使用句子转换器进行语义搜索
- 基于自然语言时间的回忆（例如，“上周”，“昨天早上”）
- 基于标签的记忆检索系统
- 使用 ChromaDB 进行持久存储
- 自动数据库备份
- 内存优化工具
- 精确匹配检索
- 相似性分析的调试模式
- 数据库健康监控
- 重复检测和清理
- 可定制的嵌入模型
- 跨平台兼容性（Apple Silicon、Intel、Windows、Linux）
- 针对不同环境的硬件感知优化
- 有限硬件资源的优雅回退
安装
快速启动（推荐）
增强的安装脚本会自动检测您的系统并安装适当的依赖项：
# Clone the repository
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Run the installation script
python install.py
install.py脚本将：
- 检测您的系统架构和可用的硬件加速器
- 为您的平台安装适当的依赖项
- 为您的环境配置最佳设置
- 验证安装并在需要时提供诊断
Docker 安装
您可以使用 Docker 运行内存服务：
# Using Docker Compose (recommended)
docker-compose up
# Using Docker directly
docker build -t mcp-memory-service .
docker run -p 8000:8000 -v /path/to/data:/app/chroma_db -v /path/to/backups:/app/backups mcp-memory-service
我们针对不同的场景提供了多种 Docker Compose 配置：
docker-compose.yml - 使用 pip install 的标准配置docker-compose.uv.yml - 使用 UV 包管理器的替代配置docker-compose.pythonpath.yml - 具有显式 PYTHONPATH 设置的配置
要使用替代配置：
docker-compose -f docker-compose.uv.yml up
Windows 安装（特殊情况）
由于特定平台的 Wheel 可用性，Windows 用户可能会遇到 PyTorch 安装问题。请使用我们 Windows 专用的安装脚本：
# After activating your virtual environment
python scripts/install_windows.py
该脚本处理：
- 检测 CUDA 可用性和版本
- 从正确的索引 URL 安装适当的 PyTorch 版本
- 安装其他依赖项而不与 PyTorch 冲突
- 验证安装
通过 Smithery 安装
要通过Smithery自动为 Claude Desktop 安装内存服务：
npx -y @smithery/cli install @doobidoo/mcp-memory-service --client claude
详细安装指南
有关全面的安装说明和故障排除，请参阅安装指南。
Claude MCP 配置
标准配置
将以下内容添加到您的claude_desktop_config.json文件中：
{
"memory": {
"command": "uv",
"args": [
"--directory",
"your_mcp_memory_service_directory", // e.g., "C:\\REPOSITORIES\\mcp-memory-service"
"run",
"memory"
],
"env": {
"MCP_MEMORY_CHROMA_PATH": "your_chroma_db_path", // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\chroma_db"
"MCP_MEMORY_BACKUPS_PATH": "your_backups_path" // e.g., "C:\\Users\\John.Doe\\AppData\\Local\\mcp-memory\\backups"
}
}
}
Windows 特定配置（推荐）
对于 Windows 用户，我们建议使用包装器脚本来确保 PyTorch 正确安装：
{
"memory": {
"command": "python",
"args": [
"C:\\path\\to\\mcp-memory-service\\memory_wrapper.py"
],
"env": {
"MCP_MEMORY_CHROMA_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\chroma_db",
"MCP_MEMORY_BACKUPS_PATH": "C:\\Users\\YourUsername\\AppData\\Local\\mcp-memory\\backups"
}
}
}
包装脚本将：
- 检查 PyTorch 是否已安装并正确配置
- 如果需要，使用正确的索引 URL 安装 PyTorch
- 使用适当的配置运行内存服务器
使用指南
有关如何与 Claude Desktop 中的内存服务交互的详细说明：
- 调用指南——了解在 Claude 中触发内存操作的特定关键字和短语
- 安装指南- 详细设置说明
在您与 Claude 的对话中，记忆服务会通过自然语言命令调用。例如：
- 对商店说：“请记住，我的项目截止日期是 5 月 15 日。”
- 检索：“你还记得我告诉你的项目截止日期吗？”
- 删除：“请忘记我告诉你的我的地址。”
请参阅调用指南以获取完整的命令列表和详细的使用示例。
内存操作
内存服务通过MCP服务器提供以下操作：
核心内存操作
store_memory - 使用可选标签存储新信息retrieve_memory - 对相关记忆进行语义搜索recall_memory - 使用自然语言时间表达检索记忆search_by_tag - 使用特定标签查找记忆exact_match_retrieve - 查找内容完全匹配的记忆debug_retrieve - 检索具有相似度分数的记忆
数据库管理
create_backup - 创建数据库备份get_stats获取内存统计信息optimize_db优化数据库性能check_database_health - 获取数据库健康指标check_embedding_model - 验证模型状态
内存管理
delete_memory - 通过哈希删除特定内存delete_by_tag - 删除所有带有特定标签的记忆cleanup_duplicates - 删除重复条目
配置选项
通过环境变量配置：
CHROMA_DB_PATH: Path to ChromaDB storage
BACKUP_PATH: Path for backups
AUTO_BACKUP_INTERVAL: Backup interval in hours (default: 24)
MAX_MEMORIES_BEFORE_OPTIMIZE: Threshold for auto-optimization (default: 10000)
SIMILARITY_THRESHOLD: Default similarity threshold (default: 0.7)
MAX_RESULTS_PER_QUERY: Maximum results per query (default: 10)
BACKUP_RETENTION_DAYS: Number of days to keep backups (default: 7)
LOG_LEVEL: Logging level (default: INFO)
# Hardware-specific environment variables
PYTORCH_ENABLE_MPS_FALLBACK: Enable MPS fallback for Apple Silicon (default: 1)
MCP_MEMORY_USE_ONNX: Use ONNX Runtime for CPU-only deployments (default: 0)
MCP_MEMORY_USE_DIRECTML: Use DirectML for Windows acceleration (default: 0)
MCP_MEMORY_MODEL_NAME: Override the default embedding model
MCP_MEMORY_BATCH_SIZE: Override the default batch size
硬件兼容性
| 平台 | 建筑学 | 加速器 | 地位 |
|---|
| macOS | 苹果硅片 (M1/M2/M3) | 国会议员 | ✅ 完全支持 |
| macOS | Rosetta 2 下的 Apple Silicon | 中央处理器 | ✅ 支持后备 |
| macOS | 英特尔 | 中央处理器 | ✅ 完全支持 |
| 视窗 | x86_64 | CUDA | ✅ 完全支持 |
| 视窗 | x86_64 | DirectML | ✅ 支持 |
| 视窗 | x86_64 | 中央处理器 | ✅ 支持后备 |
| Linux | x86_64 | CUDA | ✅ 完全支持 |
| Linux | x86_64 | ROC | ✅ 支持 |
| Linux | x86_64 | 中央处理器 | ✅ 支持后备 |
| Linux | ARM64 | 中央处理器 | ✅ 支持后备 |
测试
# Install test dependencies
pip install pytest pytest-asyncio
# Run all tests
pytest tests/
# Run specific test categories
pytest tests/test_memory_ops.py
pytest tests/test_semantic_search.py
pytest tests/test_database.py
# Verify environment compatibility
python scripts/verify_environment_enhanced.py
# Verify PyTorch installation on Windows
python scripts/verify_pytorch_windows.py
# Perform comprehensive installation verification
python scripts/test_installation.py
故障排除
有关详细的故障排除步骤，请参阅安装指南。
快速故障排除提示
- Windows PyTorch 错误：使用
python scripts/install_windows.py - macOS Intel 依赖冲突：使用
python install.py --force-compatible-deps - 递归错误：运行
python scripts/fix_sitecustomize.py - 环境验证：运行
python scripts/verify_environment_enhanced.py - 内存问题：设置
MCP_MEMORY_BATCH_SIZE=4并尝试较小的模型 - Apple Silicon ：确保为 ARM64 构建 Python 3.10+，设置
PYTORCH_ENABLE_MPS_FALLBACK=1 - 安装测试：运行
python scripts/test_installation.py
项目结构
mcp-memory-service/
├── src/mcp_memory_service/ # Core package code
│ ├── __init__.py
│ ├── config.py # Configuration utilities
│ ├── models/ # Data models
│ ├── storage/ # Storage implementations
│ ├── utils/ # Utility functions
│ └── server.py # Main MCP server
├── scripts/ # Helper scripts
├── memory_wrapper.py # Windows wrapper script
├── install.py # Enhanced installation script
└── tests/ # Test suite
开发指南
- 带有类型提示的 Python 3.10+
- 使用数据类作为模型
- 模块和函数的三重引号文档字符串
- 所有 I/O 操作的异步/等待模式
- 遵循 PEP 8 样式指南
- 包括新功能的测试
执照
MIT 许可证 - 详情请参阅许可证文件
致谢
- ChromaDB矢量数据库团队
- 用于嵌入模型的句子转换器项目
- 协议规范的 MCP 项目
接触
电报
集成
MCP 内存服务可以通过各种工具和实用程序进行扩展。请参阅集成以获取可用选项列表，包括：