一步一步教你：如何部署和使用OpenMemory MCP（Cursor/Claude Desktop/Windsurf详细攻略）

分类：配置与优化

OpenMemory MCP 是由 Mem0 团队开发的开源项目，可以为你的 MCP兼容客户端（如Cursor、Claude Desktop、Windsurf）添加共享、持久、低摩擦的记忆功能。本教程将详细介绍托管版和自托管两种部署方式，让你的AI在不同会话间保持记忆连续性。

📢 部署方案选择提醒：

目前有 2种方案 来部署OpenMemory MCP Server：

  • 方案一：托管版（⚠️ 不推荐） - 数据托管到OpenMemory官方服务。❌ 不推荐原因：实际使用中发现官方服务频繁出现 504 Gateway Timeout 错误，稳定性较差。此外数据存放在官方服务器，也存在数据泄漏风险。
  • 方案二：本地自托管（✅ 推荐） - 完全本地部署，数据不会上传网络，隐私安全有保障，且稳定性由自己掌控。根据下面的步骤操作也很简单。

💡 建议使用本地自托管方案，虽然需要几分钟配置，但更稳定可靠。

📑 本文目录

🚀 方案一：托管版OpenMemory MCP（不推荐）
🖥️ 方案二：本地自托管方案（✅ 推荐）
🛠️ OpenMemory MCP提供的工具
📊 总结对比

🚀 托管版OpenMemory MCP（不推荐）

托管版是最快速的开始方式——零配置，无需任何本地设置。

托管版特点

  • 兼容所有MCP客户端：支持Claude Desktop、Cursor、Windsurf等
  • 标准记忆操作：支持 add_memories、search_memory 等标准操作
  • 一键部署：无需Docker，几秒钟即可完成配置
  • 由 Mem0 团队提供技术支持

📋 1. 获取API Key

访问 app.openmemory.dev 注册账号并获取你的 OPENMEMORY_API_KEY。

💡 提示：注册后会获得一个唯一的API Key，请妥善保管，后续安装步骤需要使用。

📦 2. 安装并连接到你的客户端

获取API Key后，使用以下命令将OpenMemory连接到你喜欢的客户端（将 your-key 替换为你的实际API Key）：

💡 提示：下面命令会自动安装OpenMemory MCP Server，并连接到你的客户端，无需你在Cursor/Claude Desktop/Windsurf中手动配置MCP Server。

Claude Desktop

npx @openmemory/install --client claude --env OPENMEMORY_API_KEY=your-key

Cursor

npx @openmemory/install --client cursor --env OPENMEMORY_API_KEY=your-key

Windsurf

npx @openmemory/install --client windsurf --env OPENMEMORY_API_KEY=your-key
✅ 完成！执行上述命令后，你的AI客户端现在就拥有了跨会话的持久记忆功能。跳转到 OpenMemory MCP提供的工具 了解如何使用。

🖥️ 本地自托管方案（✅ 推荐）

如果你更倾向于在本地运行OpenMemory，可以按照以下步骤进行自托管部署。

前置条件

  • Docker：用于容器化部署（可以安装Docker Desktop，国内用户访问很慢，可使用代理）
  • OpenAI API Key：用于记忆向量化处理

⚡ 快速启动方式

⚠️ 注意：这种快速启动方式会启动OpenMemory服务器和UI，但删除容器会导致记忆数据丢失。如果需要持久存储，建议使用下面的完整部署步骤。

运行以下命令可以快速启动OpenMemory：

curl -sL https://raw.githubusercontent.com/mem0ai/mem0/main/openmemory/run.sh | bash

你需要将 OPENAI_API_KEY 设置为全局环境变量：

export OPENAI_API_KEY=your_api_key

或者直接在命令中传递API Key作为参数：

curl -sL https://raw.githubusercontent.com/mem0ai/mem0/main/openmemory/run.sh | OPENAI_API_KEY=your_api_key bash

📝 完整部署步骤

步骤1：克隆仓库

# 克隆仓库
git clone https://github.com/mem0ai/mem0.git
cd mem0/openmemory

步骤2：配置环境变量

在运行项目之前，需要为API和UI配置环境变量。你可以通过以下方式之一完成：

方式一：手动创建

在以下目录中创建 .env 文件：

  • /api/.env
  • /ui/.env

方式二：使用示例文件

cp api/.env.example api/.env
cp ui/.env.example ui/.env

方式三：使用Makefile

make env

/api/.env 示例内容

OPENAI_API_KEY=sk-xxx
USER=<user-id> # 你想要关联记忆的用户ID

/ui/.env 示例内容

NEXT_PUBLIC_API_URL=http://localhost:8765
NEXT_PUBLIC_USER_ID=<user-id> # 与api中的用户ID相同

步骤3：构建并运行项目

使用以下两个命令运行项目：

make build # 构建MCP服务器和UI
make up    # 运行OpenMemory MCP服务器和UI
💡 构建报错解决方案：

如果 make build 报错，通常是以下原因：

  • 原因一：Docker未启动
    报错信息：Cannot connect to the Docker daemon at unix:///xxxxx/.docker/run/docker.sock. Is the docker daemon running?
    解决方法：启动 Docker Desktop 或执行 sudo systemctl start docker（Linux）即可。
  • 原因二：/api/.env 或 /ui/.env 文件内容未正确设置，请检查环境变量是否填写完整。
  • 原因三：即使 .env 文件已正确配置，仍提示 "The 'NEXT_PUBLIC_API_URL' variable is not set." 警告。
    解决方法：在执行 make build 前，先手动导出环境变量：
# 先导出环境变量（USER_ID需与你的.env文件保持一致）
export NEXT_PUBLIC_API_URL=http://localhost:8765
export NEXT_PUBLIC_USER_ID=your-user-id

# 然后再执行构建
make build
make up
OpenMemory MCP 构建报错解决方案

运行这些命令后，你将获得：

  • OpenMemory MCP服务器：运行在 http://localhost:8765（API文档：http://localhost:8765/docs）
  • OpenMemory UI：运行在 http://localhost:3000
OpenMemory UI 页面

（OpenMemory UI 页面）

UI无法访问的解决方案

如果UI在 http://localhost:3000 无法正常启动，尝试手动运行：

cd ui
pnpm install
pnpm dev

🔧 配置MCP客户端

使用以下命令配置MCP客户端（将 username 替换为你的用户名, 将 client-name 替换为所需的客户端名称，比如 cursor、claude、windsurf）：

npx @openmemory/install local "http://localhost:8765/mcp/cursor/sse/username" --client client-name
OpenMemory MCP 配置MCP客户端

（OpenMemory MCP 配置MCP客户端）

配置完成后，OpenMemory仪表板将在 http://localhost:3000 可用。你可以在这里：

  • 查看和管理你的记忆
  • 检查与MCP客户端的连接状态
  • 监控记忆操作日志
🔒 隐私保护：自托管方案下，OpenMemory在你的本地机器上运行，确保所有AI记忆保持私密和安全，同时可被任何兼容的MCP客户端访问。

🛠️ OpenMemory MCP 提供的工具

部署完成后，你的AI客户端将获得以下记忆操作工具：

工具名称 功能说明
add_memories 存储新的内存对象，让AI记住重要信息
search_memory 检索相关记忆，根据关键词或上下文查找已存储的信息
list_memories 查看所有已存储的内存，浏览完整记忆列表
delete_all_memories 完全清除内存，重置所有已存储的记忆数据
✅ 使用方法：你可以对Agent说："添加一个记忆，内容是：'项目背景'"，然后Agent就会调用合适的工具记住这个记忆；
你也可以在任何时候，随时让Agent记忆：比如在互动时的一些重要信息，它会自动提炼并记住它。 OpenMemory MCP 提供的工具

📊 总结

方案 优点 缺点 适用场景
托管版
（不推荐）		 零配置、即开即用 官方服务不稳定（504错误）、数据存储在云端 不建议使用
快速启动 一键部署 数据不持久 测试体验
完整部署
（✅ 推荐）		 数据持久、完全控制、稳定可靠 配置步骤较多（约5分钟） 生产环境、长期使用

无论选择哪种方式，OpenMemory MCP都能为你的AI工作流带来跨会话记忆能力，让AI更好地理解你的项目背景和工作偏好。

🔗 GitHub仓库：更多详细信息请访问 https://github.com/mem0ai/mem0/tree/main/openmemory

相关问题