MCP Memory Service

这是一个为 Claude Desktop 提供语义记忆和持久存储功能的 MCP 服务器，使用 ChromaDB 和句子转换器。此服务通过提供具有语义搜索能力的长期记忆存储，使其非常适合于跨对话和实例保持上下文。

特性

• 使用句子转换器进行语义搜索
• 基于自然语言的时间召回（例如，“上周”，“昨天早上”）
• 基于标签的记忆检索系统
• 使用 ChromaDB 进行持久化存储
• 自动数据库备份
• 记忆优化工具
• 精确匹配检索
• 用于相似度分析的调试模式
• 数据库健康监控
• 重复检测与清理
• 可定制的嵌入模型
• 跨平台兼容性（Apple Silicon, Intel, Windows, Linux）
• 针对不同环境的硬件感知优化
• 对于有限硬件资源的优雅回退

快速开始

最快开始的方法：

# Install UV if not already installed
pip install uv

# Clone and install
git clone https://github.com/doobidoo/mcp-memory-service.git
cd mcp-memory-service
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt
uv pip install -e .

# Run the service
uv run memory

Docker 和 Smithery 集成

Docker 使用

该服务可以在 Docker 容器中运行，以实现更好的隔离和部署：

# Build the Docker image
docker build -t mcp-memory-service .

# Run the container
# Note: On macOS, paths must be within Docker's allowed file sharing locations
# Default allowed locations include:
# - /Users
# - /Volumes
# - /private
# - /tmp
# - /var/folders

# Example with proper macOS paths:
docker run -it \
  -v $HOME/mcp-memory/chroma_db:/app/chroma_db \
  -v $HOME/mcp-memory/backups:/app/backups \
  mcp-memory-service

# For production use, you might want to run it in detached mode:
docker run -d \
  -v $HOME/mcp-memory/chroma_db:/app/chroma_db \
  -v $HOME/mcp-memory/backups:/app/backups \
  --name mcp-memory \
  mcp-memory-service

在 macOS 上配置 Docker 的文件共享：

1. 打开 Docker Desktop
2. 转到设置（Preferences）
3. 导航至资源 -> 文件共享
4. 添加您需要共享的任何额外路径
5. 点击“应用并重启”

Smithery 集成

该服务通过 smithery.yaml 配置了 Smithery 集成。此配置允许通过 stdio 与如 Claude Desktop 的 MCP 客户端通信。

要与 Smithery 一起使用：

1. 确保您的 claude_desktop_config.json 指向正确的路径：

{
  "memory": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-v", "$HOME/mcp-memory/chroma_db:/app/chroma_db",
      "-v", "$HOME/mcp-memory/backups:/app/backups",
      "mcp-memory-service"
    ],
    "env": {
      "MCP_MEMORY_CHROMA_PATH": "/app/chroma_db",
      "MCP_MEMORY_BACKUPS_PATH": "/app/backups"
    }
  }
}

1. smithery.yaml 配置自动处理 stdio 通信和环境设置。

使用 Claude Desktop 测试

为了验证您的基于 Docker 的内存服务是否能正确地与 Claude Desktop 工作：

1. 使用 docker build -t mcp-memory-service . 构建 Docker 镜像
2. 创建持久存储所需的目录：

   mkdir -p $HOME/mcp-memory/chroma_db $HOME/mcp-memory/backups
   

3. 更新你的 Claude Desktop 配置文件：
   • 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
   • 在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json
   • 在 Linux 上：~/.config/Claude/claude_desktop_config.json
4. 重启 Claude Desktop
5. 当 Claude 启动时，你应该会看到内存服务初始化的消息：

   MCP Memory Service initialization completed
   

6. 测试记忆功能：
   • 让 Claude 记住某些事情：“请记住我最喜欢的颜色是蓝色”
   • 在稍后的对话中或在新的对话中询问：“我最喜欢的颜色是什么？”
   • Claude 应该从内存服务中检索信息

如果遇到任何问题：

• 检查 Claude Desktop 控制台中的错误消息
• 确认 Docker 是否有访问挂载目录的必要权限
• 确保 Docker 容器以正确的参数运行
• 尝试手动运行容器以查看任何错误输出

有关详细的安装说明、特定于平台的指南和故障排除，请参阅我们的文档：

• 安装指南 - 所有平台的综合安装说明
• 故障排除指南 - 常见问题的解决方案
• 技术文档 - 详细的技术程序和规范
• 脚本文档 - 可用脚本及其使用方法的概述

配置

标准配置（推荐）

将以下内容添加到你的 claude_desktop_config.json 文件中以使用 UV（推荐用于最佳性能）：

{
  "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。请参阅我们的Windows 设置指南以获取详细说明。

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

包装脚本将执行以下操作：

1. 检查是否已安装并正确配置了 PyTorch
2. 如果需要，使用正确的索引 URL 安装 PyTorch
3. 以适当的配置运行内存服务器

硬件兼容性

内存操作

内存服务通过 MCP 服务器提供以下操作：

核心内存操作

1. store_memory - 存储新信息（可选带标签）
2. retrieve_memory - 执行语义搜索以查找相关记忆
3. recall_memory - 使用自然语言时间表达式检索记忆
4. search_by_tag - 使用特定标签查找记忆
5. exact_match_retrieve - 查找内容完全匹配的记忆
6. debug_retrieve - 检索带有相似度分数的记忆

有关标签存储和管理的详细信息，请参阅我们的标签存储文档。

数据库管理

1. create_backup - 创建数据库备份
2. get_stats - 获取内存统计信息
3. optimize_db - 优化数据库性能
4. check_database_health - 获取数据库健康指标
5. check_embedding_model - 验证模型状态

内存管理

1. delete_memory - 通过哈希删除特定记忆
2. delete_by_tag - 删除所有具有特定标签的记忆
3. 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

寻求帮助

如果您遇到任何问题：

1. 查看我们的故障排除指南
2. 浏览安装指南
3. 对于 Windows 特定的问题，请参见我们的Windows 设置指南
4. 通过 Telegram 联系开发者: t.me/doobeedoo

项目结构

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
│   ├── convert_to_uv.py         # Script to migrate to UV
│   └── install_uv.py            # UV installation helper
├── .uv/                         # UV configuration
├── memory_wrapper.py            # Windows wrapper script
├── memory_wrapper_uv.py         # UV-based wrapper script
├── uv_wrapper.py                # UV wrapper script
├── install.py                   # Enhanced installation script
└── tests/                       # Test suite

开发指南

• Python 3.10+ 带类型提示
• 使用 dataclasses 作为模型
• 为模块和函数使用三引号文档字符串
• 对所有 I/O 操作采用异步/等待模式
• 遵循 PEP 8 风格指南
• 为新功能编写测试

许可证

MIT 许可证 - 详情请参阅 LICENSE 文件

致谢

• ChromaDB 团队提供的向量数据库
• Sentence Transformers 项目提供的嵌入模型
• MCP 项目提供的协议规范

联系方式

t.me/doobidoo