OpenMemory MCP

适用于跨应用 AI 的私有内存 MCP 服务器

Openmemory

AI 发展日新月异，大型语言模型（LLMs）让很多事情变得简单。然而，它们面临一个根本限制：会话之间会遗忘所有信息。

如果有一个个人专属的、可移植的 LLM “记忆层”，可以本地存储在系统中并完全控制数据，会怎么样？

今天，我们将了解 OpenMemory MCP—— 一个基于 Mem0（AI 代理记忆层）构建的私有、本地优先的记忆层。它支持在 Cursor、Claude Desktop、Windsurf、Cline 等 MCP 兼容客户端中实现持久化、上下文感知的 AI 交互。

本指南将详细介绍如何安装、配置和运行 OpenMemory MCP 服务器，并涵盖其内部架构、流程、底层组件和带示例的实际用例。让我们开始吧。

内容概览

我们将详细探讨以下主题：

• OpenMemory MCP 服务器是什么？为何重要？
• 分步指南：如何设置和运行 OpenMemory。
• 仪表盘功能（及 UI 背后的逻辑）。
• 安全性、访问控制和架构概述。
• 带示例的实际用例。

1. 什么是 OpenMemory？为何重要？

OpenMemory MCP 是面向 MCP 客户端的私有、本地记忆层。它提供基础设施来存储、管理和跨平台利用 AI 记忆，同时将数据完全保留在本地系统中。

简单来说，它就像一个基于向量的 “记忆层”，适用于任何使用标准 MCP 协议的 LLM 客户端，并可直接与 Mem0 等工具配合使用。

核心能力：

• 跨会话存储和检索任意文本块（记忆），让 AI 无需从零开始。
• 底层使用向量存储（Qdrant）实现基于相关性的检索，而非简单关键词匹配。
• 完全在本地基础设施（Docker + Postgres + Qdrant）运行，数据不发送到外部。
• 可在应用或记忆级别暂停或撤销任何客户端的访问权限，并记录每次读写的审计日志。
• 包含一个仪表盘（Next.js & Redux），显示谁在读写记忆以及状态变化历史。

核心流程：

1. 使用单个docker-compose命令启动 OpenMemory（API、Qdrant、Postgres）。
2. API 进程托管一个基于 Mem0 的 MCP 服务器，通过 SSE 协议支持标准 MCP 协议。
3. LLM 客户端通过 SSE 流连接到 OpenMemory 的/mcp/...端点，并调用add_memories()、search_memory()或list_memories()等方法。
4. 所有其他操作（包括向量索引、审计日志和访问控制）均由 OpenMemory 服务处理。

你可以观看官方演示并在mem0.ai/openmemory-mcp了解更多！

2. 分步指南：设置和运行 OpenMemory

项目主要组件：

• api/：后端 API 和 MCP 服务器
• ui/：前端 React 应用（仪表盘）

步骤 1：系统前提条件

确保系统已安装以下工具：

• Docker 和 Docker Compose
• Python 3.9+（后端开发需要）
• Node.js（前端开发需要）
• OpenAI API Key（用于 LLM 交互）
• GNU Make（构建自动化工具，用于设置流程）

注意：开始前请确保 Docker Desktop 已运行。

步骤 2：克隆仓库并设置 OpenAI API Key

git clone https://github.com/mem0ai/mem0.git  
cd mem0/openmemory

提示：此命令仅为当前终端会话设置密钥，关闭终端后失效。

步骤 3：设置后端

后端通过 Docker 容器运行。在根目录执行以下命令：

# 复制环境文件并编辑以更新OPENAI_API_KEY和其他密钥  
make env
# 这里你需要修改api/.env文件，填写正确的OPENAI_API_KEY
vim api/.env
# 构建所有Docker镜像  
make build  
# 启动Postgres、Qdrant、FastAPI/MCP服务器  
make up  

.env文件内容示例：

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=https://example.com/v1

设置完成后，API 将在http://localhost:8765运行。可在 Docker Desktop 中查看运行的容器。

其他后端常用命令：

# 运行数据库迁移  
make migrate  
# 查看日志  
make logs  
# 进入API容器的Shell  
make shell  
# 运行测试  
make test  
# 停止服务  
make down

步骤 4：设置前端

前端是一个 Next.js 应用，执行以下命令启动：

# 使用pnpm安装依赖并运行Next.js开发服务器  
make ui

安装成功后，访问http://localhost:3000查看 OpenMemory 仪表盘，按指引在 MCP 客户端中安装 MCP 服务器。

仪表盘功能：

在仪表盘上，可获取基于所选客户端（如 Cursor、Claude、Cline、Windsurf）的一键安装命令。例如，在 Cursor 中安装的命令类似：

npx install-mcp i http://localhost:8765/user_id/sse --client cursor

安装完成后，可在 Cursor 设置中验证 MCP 服务器连接。在 Cursor 中发送示例提示（如 “我喜欢早上跑步”），触发add_memories()调用存储记忆。刷新仪表盘的 “Memories” 标签页即可查看所有记忆。

MCP 客户端操作：

每个 MCP 客户端可调用以下四种标准记忆操作：

• add_memories(text)：将文本存储到 Qdrant，插入 / 更新Memory行和审计条目
• search_memory(query)：嵌入查询，执行带可选 ACL 过滤的向量搜索，并记录访问
• list_memories()：检索用户的所有存储向量（按 ACL 过滤）并记录列表
• delete_all_memories()：清除所有记忆

所有响应通过同一 SSE 连接流式传输。仪表盘显示所有活动连接、访问记忆的应用以及读写详情。

3. 仪表盘功能（及 UI 背后的逻辑）

OpenMemory 仪表盘包含三个主要路由：

• /：仪表盘
• /memories：查看和管理存储的记忆
• /apps：查看连接的应用

核心功能：

1. 安装 OpenMemory 客户端
   获取唯一的 SSE 端点或使用一键安装命令在 “MCP Link” 和不同客户端标签页（Claude、Cursor、Cline 等）之间切换
2. 查看记忆和应用统计
   显示存储的记忆总数和连接的应用数量实时搜索所有记忆（带防抖功能）
3. 刷新或手动创建记忆
   “Refresh” 按钮：重新调用当前路由的获取器“Create Memory” 按钮：打开模态窗口创建新记忆
4. 过滤和排序记忆
   按应用、类别、归档状态过滤按记忆内容、应用名称或创建时间排序
5. 管理单个记忆
   点击记忆可归档、暂停、恢复或删除查看访问日志和相关记忆支持批量操作（如批量归档、暂停或删除）

前端关键组件：

• ui/app/memories/components/MemoryFilters.tsx：处理搜索输入、过滤对话框触发和批量操作
• ui/app/memories/components/MemoriesSection.tsx：记忆列表的主容器，支持加载、分页和显示
• ui/app/memories/components/MemoryTable.tsx：渲染记忆表格（ID、内容、客户端、标签、创建时间、状态）
• 状态管理和 API 调用通过自定义钩子实现，如useStats.ts、useMemoriesApi.ts、useAppsApi.ts等。

4. 安全性、访问控制和架构概述

安全性

OpenMemory 基于隐私优先原则设计，所有记忆数据本地存储在 Docker 化组件（FastAPI、Postgres、Qdrant）中。

• 敏感输入通过 SQLAlchemy 的参数绑定安全处理，防止注入攻击。
• 每次记忆交互（添加、检索、状态变更）均通过MemoryStatusHistory和MemoryAccessLog表记录，确保可追溯性。
• 虽未内置身份验证，但所有端点均需要user_id，并可通过外部认证网关（如 OAuth 或 JWT）进行安全保护。
• 开发环境中 FastAPI 的 CORS 设置为允许所有来源（allow_origins=["*"]），生产环境应收紧为仅信任客户端。

访问控制

细粒度访问控制是 OpenMemory 的核心特性之一：

• access_controls表定义应用与特定记忆之间的允许 / 拒绝规则。
• 通过check_memory_access_permissions函数强制执行规则，考虑记忆状态（活跃、暂停等）、应用活动状态（是否活跃）和 ACL 规则。
• 可暂停整个应用（禁用写入）、归档或暂停单个记忆，或按类别 / 用户过滤。暂停或非活跃条目会从工具访问和搜索中隐藏。

架构

1. 后端（FastAPI + 基于 SSE 的 FastMCP）
   暴露普通 REST 接口（如/api/v1/memories、/api/v1/apps）和 MCP 工具接口（如/mcp/messages、/mcp/sse/<client>/<user>）
   连接 Postgres 存储关系元数据，Qdrant 存储向量索引
2. 向量存储（通过 Mem0 客户端的 Qdrant）
   所有记忆在 Qdrant 中进行语义索引，查询时应用用户和应用特定的过滤条件
3. 关系型元数据（SQLAlchemy + Alembic）
   跟踪用户、应用、记忆条目、访问日志、类别和访问控制
   Alembic 管理模式迁移，默认数据库为 SQLite（可切换为 Postgres）
4. 前端仪表盘（Next.js）
   Redux 实现实时监控界面
   钩子和 Redux Toolkit 管理状态，Axios 与 FastAPI 端点通信
   使用 Recharts 实现实时图表，React Hook Form 处理表单
5. 基础设施与开发工作流
   docker-compose.yml定义 Qdrant 服务和 API 服务
   Makefile提供迁移、测试、热重载等快捷命令
   测试与后端逻辑共存（通过pytest）

5. 实际用例与示例

OpenMemory 可用于任何需要 AI “记忆” 跨交互信息的场景，实现高度个性化。以下是一些高级应用场景：

带记忆层的多智能体研究助手

想象构建一个工具，不同 LLM 智能体专注于不同研究领域（如学术论文、GitHub 仓库、新闻）。

• 技术流程：
  每个子智能体作为 MCP 客户端，通过add_memories(text)存储检索数据的摘要，并使用 GPT 自动分类标签。
  主智能体通过 SSE 通道调用search_memory("latest papers on diffusion models")检索所有相关上下文。
• 仪表盘功能：显示哪个智能体存储了哪些内容，并通过 ACL 限制智能体间的记忆访问。

具有持久跨会话记忆的智能会议助手

构建一个会议记录工具（如 Zoom、Google Meet 插件）：

• 技术流程：
  每次会议后通过add_memories(text)存储会议记录和待办事项。
  下次会议前调用search_memory("open items for Project X")检索相关记忆，并通过标签分类显示在 UI 中。
• 扩展功能：集成 Google Drive、Notion 等工具，使存储的待办事项链接到实时文档和任务。

随使用进化的智能编码助手

CLI 编码助手通过存储使用模式、常见问题、编码偏好和项目特定提示来学习用户习惯：

• 技术流程：
  用户提问 “为什么我的SQLAlchemy查询会失败？” 时，通过add_memories存储错误和解决方案。
  下次输入 “查询SQLAlchemy又失败了” 时，助手自动调用search_memory("sqlalchemy join issue")检索先前解决方案。
• 扩展功能：连接代码重构工具（如 jscodeshift），根据存储的偏好自动重构代码。

总结

OpenMemory 通过向量搜索（语义召回）、关系型元数据（审计 / 日志）和实时仪表盘（可观测性和访问控制）的组合，让你构建具有真实记忆的上下文感知应用。

现在，你的 MCP 客户端可以跟踪每次访问、暂停任意记忆，并在单个仪表盘中审计所有操作。最棒的是，一切都本地存储在你的系统中。

如有任何问题或反馈，请随时告知！祝你度过愉快的一天！下次见～

译者注

本文详细拆解了 OpenMemory MCP 的技术实现，尽管原文缺乏官方文档，但通过代码库逆向工程整理出了完整的安装和使用流程。OpenMemory 的本地优先架构和细粒度访问控制为 AI 记忆管理提供了安全可控的解决方案，尤其适合对数据隐私要求高的企业场景。