MCP内存服务

一个 MCP 服务器，使用 ChromaDB 和句子转换器为 Claude Desktop 提供语义记忆和持久存储功能。该服务支持长期记忆存储和语义搜索功能，非常适合跨对话和实例维护上下文。

特征

使用句子转换器进行语义搜索
基于自然语言时间的回忆（例如，“上周”，“昨天早上”）
基于标签的记忆检索系统
使用 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 的文件共享：

打开 Docker 桌面
前往“设置”（首选项）
导航至资源 -> 文件共享
添加您需要共享的任何其他路径
点击“应用并重新启动”

Smithery 集成

该服务通过smithery.yaml配置为与 Smithery 集成。此配置支持与 Claude Desktop 等 MCP 客户端进行基于 stdio 的通信。

与 Smithery 一起使用：

确保您的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"
    }
  }
}

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

使用 Claude Desktop 进行测试

要验证基于 Docker 的内存服务是否与 Claude Desktop 正常工作：

使用docker build -t mcp-memory-service .
创建持久存储所需的目录：
mkdir -p $HOME/mcp-memory/chroma_db $HOME/mcp-memory/backups
更新您的 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
重启Claude桌面
当 Claude 启动时，您应该看到内存服务初始化并显示一条消息：
MCP Memory Service initialization completed
测试记忆功能：
- 让克劳德记住一件事：“请记住我最喜欢的颜色是蓝色”
- 在稍后的对话中或在新的对话中，问：“我最喜欢的颜色是什么？”
- 克劳德应该从记忆服务中检索信息

如果您遇到任何问题：

检查 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"
    }
  }
}

包装脚本将：

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

硬件兼容性

平台	建筑学	加速器	地位
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	中央处理器	✅ 支持回退

内存操作

内存服务通过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

获取帮助

如果您遇到任何问题：

查看我们的故障排除指南
查看安装指南
对于 Windows 特定问题，请参阅我们的Windows 安装指南
通过 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+
使用数据类作为模型
模块和函数的三重引号文档字符串
所有 I/O 操作的异步/等待模式
遵循 PEP 8 样式指南
包括新功能的测试

执照

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

致谢

ChromaDB矢量数据库团队
用于嵌入模型的句子转换器项目
协议规范的 MCP 项目

接触

t.me/doobidoo

MCP Memory Service

Integrations