用 OpenMemory MCP 增强客户端上下文意识

用 OpenMemory MCP 增强客户端上下文意识 | 前端进阶之旅

Full translation

完整中文译文

在飞速发展的 AI 领域，大语言模型（LLM）已经彻底改变了我们与技术交互的方式。然而，它们面临一个根本性的限制：每次会话结束后，都会忘记所有内容。

有没有可能构建一个个人化、可移植的 LLM“记忆层”，让它在本地系统中运行，同时让你完全掌控自己的数据？

今天，我们很高兴向大家介绍 OpenMemory MCP——一个由 Mem0 驱动、私有且本地优先的记忆层。它能够让 Cursor、Claude Desktop、Windsurf、Cline 等兼容 MCP 的客户端拥有持久且具备上下文感知能力的 AI。它提供完全在你的计算机上运行的记忆服务，并内置用于查看、审计和控制记忆的 UI。它完全运行在你的本地系统中，在确保数据始终由你掌控的同时，为任何兼容 MCP 的工具带来真正个性化的体验。

本指南将介绍如何安装、配置和运行 OpenMemory MCP Server，同时还会讲解其内部架构、可用功能以及实际应用场景。

OpenMemory MCP Server 是什么，以及它为何重要

分步设置指南

仪表盘功能与 UI 解析

安全性、访问控制与架构概览

包含示例的实际用例

什么是 OpenMemory MCP Server？

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

简单来说，它就像是一个面向所有采用标准 MCP 协议的 LLM 客户端、以向量为基础的记忆层，并且可以直接与 Mem0 等工具配合使用。

通过 MCP Server 工具（add_memories、search_memory、list_memories、delete_all_memories）添加、检索、列出和删除记忆对象。

在底层使用 Qdrant 作为向量存储，以语义索引的方式存储数据。

完全运行在你的本地基础设施上（Docker + Postgres + Qdrant），不会向外部发送任何数据。

可以在应用或记忆层级暂停或撤销任意客户端的访问权限，并为每次读取或写入保留审计日志。

内置用于可观测性和手动控制的 UI。

OpenMemory MCP Server 是具备记忆感知能力的 AI 技术栈的核心支柱，让各个客户端能够使用共享且持久的上下文运行。

🔁 工作原理（基本流程）

以下是实际运行时的核心流程：

只需一条 docker-compose 命令，即可启动 OpenMemory（API、Qdrant、Postgres）。

API 进程本身托管了一个 MCP Server（底层使用 Mem0），通过 SSE 使用标准 MCP 协议进行通信。

你的 MCP 客户端会连接 OpenMemory 的 /mcp/... 端点并建立 SSE 流，然后调用 add_memories()、search_memory() 或 list_memories() 等方法。

其他所有工作，包括向量索引、审计日志和访问控制，都由 OpenMemory 服务处理。

2. 设置并运行 OpenMemory 的分步指南

本节将逐步介绍如何设置 OpenMemory 并在本地运行它。

该项目包含两个需要运行的主要组件：

api/——后端 API 和 MCP Server

ui/——前端 React 应用程序（仪表盘）

第 1 步：系统前置条件

开始之前，请确保系统中已安装以下软件。为了方便你按照说明操作，我附上了相关文档链接。

Docker 和 Docker Compose

Python 3.9+——后端开发所必需

Node.js——前端开发所必需

OpenAI API Key——用于与 LLM 交互

GNU Make 是一种构建自动化工具。我们将在设置过程中使用它。

在继续下一步之前，请确保 Docker Desktop 正在运行。

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

你需要使用以下命令克隆位于 github.com/mem0/openmemory 的仓库。

git clone <https://github.com/mem0ai/mem0.git>
cd

git clone <https://github.com/mem0ai/mem0.git>
cd

git clone <https://github.com/mem0ai/mem0.git>
cd

接下来，将你的 OpenAI API Key 设置为环境变量。

export OPENAI_API_KEY

export OPENAI_API_KEY

export OPENAI_API_KEY

该命令只会为当前终端会话设置密钥。关闭该终端窗口后，此设置就会失效。

第 3 步：设置后端

后端运行在 Docker 容器中。要启动后端，请在根目录中运行以下命令：

# Copy the environment file and edit the file to update OPENAI_API_KEY and other secrets
make env

# Build all Docker images
make build

# Start Postgres, Qdrant, FastAPI/MCP server
make

# Copy the environment file and edit the file to update OPENAI_API_KEY and other secrets
make env

# Build all Docker images
make build

# Start Postgres, Qdrant, FastAPI/MCP server
make

# Copy the environment file and edit the file to update OPENAI_API_KEY and other secrets
make env

# Build all Docker images
make build

# Start Postgres, Qdrant, FastAPI/MCP server
make

.env.local 文件将遵循以下格式：

OPENAI_API_KEY=your_api_key

OPENAI_API_KEY=your_api_key

OPENAI_API_KEY=your_api_key

设置完成后，你的 API 将运行在 http://localhost:8000。

你还应该能在 Docker Desktop 中看到正在运行的容器。

下面是一些你可以使用的其他实用后端命令：

第 4 步：设置前端

前端是一个 Next.js 应用程序。要启动它，只需运行：

# Installs dependencies using pnpm and runs Next.js development server
make

# Installs dependencies using pnpm and runs Next.js development server
make

# Installs dependencies using pnpm and runs Next.js development server
make

成功安装后，你可以访问 http://localhost:3000 查看 OpenMemory 仪表盘。该仪表盘会引导你在自己的 MCP 客户端中安装 MCP Server。

仪表盘的界面如下。

补充一些背景信息：你的 MCP 客户端会向 GET /mcp/{client_name}/sse/{user_id} 建立 SSE 通道，该通道会设置两个上下文变量（user_id、client_name）。

在仪表盘中，你可以根据自己选择的客户端（如 Cursor、Claude、Cline、Windsurf），找到一条用于安装 MCP Server 的单行命令。

让我们在 Cursor 中安装它，命令大致如下：

npx install-mcp i https://mcp.openmemory.ai/xyz_id/sse --client cursor

npx install-mcp i https://mcp.openmemory.ai/xyz_id/sse --client cursor

npx install-mcp i https://mcp.openmemory.ai/xyz_id/sse --client cursor

如果尚未安装 install-mcp，系统会提示你进行安装，之后只需为该服务器指定一个名称即可。

我目前使用的是一条虚拟命令，请忽略它。打开 Cursor 设置，然后检查侧边栏中的 MCP 选项，以验证连接是否成功。

在 Cursor 中打开一个新聊天，并输入一条示例提示词，例如，我让它记住一些关于我的信息（这些信息是从我的 GitHub 个人资料中获取的）。

这会触发 add_memories() 调用并存储记忆。刷新仪表盘，然后进入 Memories 选项卡，即可查看所有这些记忆。

系统会自动为记忆创建分类，它们类似于可选标签（通过 GPT-4o 进行分类）。

你还可以连接 Windsurf 等其他 MCP 客户端。

每个 MCP 客户端都可以“调用”四种标准记忆操作之一：

add_memories(text)：将文本存储在 Qdrant 中，插入或更新一条 Memory 记录及审计条目

search_memory(query)：对查询进行嵌入，使用可选的 ACL 过滤器执行向量搜索，并记录每次访问

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）查看记忆和应用统计信息

查看已存储的记忆数量。

查看已连接的应用数量。

输入任意文本，即可在所有记忆中进行实时搜索（带防抖）。

相关代码位于 ui/components/dashboard/Stats.tsx，其功能包括：

从 Redux 中读取数据（profile.totalMemories、profile.totalApps、profile.apps[]）。

组件挂载时调用 useStats().fetchStats() 来填充 store。

渲染“Total Memories count”和“Total Apps connected”，并显示最多 4 个应用图标。

3）刷新或手动创建记忆

刷新按钮（为当前路由重新调用相应的获取函数）。

创建记忆按钮（打开 CreateMemoryDialog 中的模态框）。

5）你可以打开过滤器面板并选择：

要包含哪些应用。

要包含哪些分类。

是否显示已归档的项目。

按哪一列排序（Memory、App Name、Created On）。

一键清除所有过滤条件。

6）你可以检查和管理单条记忆

点击任意记忆，可以：

归档、暂停、恢复或删除该记忆。

查看访问日志和相关记忆。

你还可以选择多条记忆并执行批量操作。

4. 安全性、访问控制与架构概览

使用 MCP 协议或任何 AI 智能体系统时，安全性都是不可妥协的。因此，我们来简单讨论一下。

OpenMemory 采用隐私优先的设计原则。它使用 Docker 化的组件（FastAPI、Postgres、Qdrant），将所有记忆数据存储在你自己的本地基础设施中。

敏感输入通过 SQLAlchemy 的参数绑定机制安全处理，以防止注入攻击。每一次记忆交互，包括添加、检索和状态变更，都会记录到 MemoryStatusHistory 和 MemoryAccessLog 表中，以便追踪。

虽然它没有内置身份验证，但所有端点都要求提供 user_id，并且已做好接入外部身份验证网关（如 OAuth 或 JWT）的准备。

FastAPI 的 CORS 在本地/开发环境中完全开放（allow_origins=["*"]），但在生产环境中，你应该收紧其默认的开放状态，将访问权限限制在可信客户端范围内。

细粒度访问控制是 OpenMemory 重点关注的核心能力之一。总体而言，access_controls 表定义了应用与特定记忆之间的允许/拒绝规则。

这些规则通过 check_memory_access_permissions 函数强制执行。该函数会综合考虑记忆状态（active、paused 等）、应用的活动状态（is_active）以及当前生效的 ACL 规则。

在实践中，你可以暂停整个应用（禁用写入）、归档或暂停单条记忆，也可以按分类或用户应用过滤条件。已暂停或非活跃的条目不会出现在工具访问和搜索结果中。这种分层访问模型确保你能够放心地在任何层级控制记忆访问。

如你所见，我已经暂停了对这些记忆的访问，因此它们进入了非活跃状态。

下面简要介绍一下系统架构。你随时可以查阅代码库了解更多细节。

1）后端（FastAPI + 基于 SSE 的 FastMCP）

同时提供传统的 REST 接口（/api/v1/memories、/api/v1/apps、/api/v1/stats），以及

一个 MCP“工具”接口（/mcp/messages、/mcp/sse/<client>/<user>），AI 智能体通过 Server-Sent Events（SSE）调用其中的 add_memories、search_memory 和 list_memories。

它连接 Postgres 以存储关系型元数据，并连接 Qdrant 进行向量搜索。

2）向量存储（通过 mem0 客户端使用 Qdrant）

所有记忆都在 Qdrant 中建立语义索引，并在查询时应用用户和应用级别的过滤条件。

3）关系型元数据（SQLAlchemy + Alembic）

跟踪用户、应用、记忆条目、访问日志、分类和访问控制。

Alembic 负责管理数据库模式迁移。

默认数据库是 SQLite（openmemory.db），但你也可以通过 DATABASE_URL 指向 Postgres。

4）前端仪表盘（Next.js）

Redux 为实时可观测性界面提供支持。

Hooks 与 Redux Toolkit 负责管理状态，Axios 与 FastAPI 端点通信。

通过实时图表（Recharts）、轮播组件和表单（React Hook Form）探索你的记忆。

5）基础设施与开发工作流

docker-compose.yml（api/docker-compose.yml）包含 Qdrant 服务和 API 服务。

Makefile 为迁移、测试和热重载提供快捷命令。

测试代码与后端逻辑放在一起（通过 pytest 运行）。

这些组件共同构成了一个自托管的 LLM 记忆平台：

⚡ 同时在关系型数据库和向量索引中存储并对聊天记忆进行版本管理
⚡ 通过应用级 ACL 和状态转换（active/paused/archived）确保安全
⚡ 通过 Qdrant 进行语义搜索
⚡ 通过仪表盘进行观察和控制

下一节中，我们将探索一些可以使用 OpenMemory 构建的高级用例和创新工作流。

5. 带示例的实际用例

熟悉 OpenMemory 后，你会发现，只要希望 AI 能够跨多次交互记住某些内容，就可以使用它，从而实现高度个性化的体验。

下面是 OpenMemory 的一些高级和创新用法。

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

假设你要构建一个工具，其中不同的 LLM 智能体分别专注于不同的研究领域（例如，一个负责学术论文，一个负责 GitHub 仓库，另一个负责新闻）。

每个 AI 智能体都通过 add_memories(text) 存储它发现的内容，之后由一个主 AI 智能体运行 search_memory(query)，在所有历史结果中进行搜索。

技术流程可以如下：

每个子智能体都是一个 MCP 客户端，它会：将检索数据的摘要添加到 OpenMemory。使用自动分类（GPT）为记忆添加标签。

每个子智能体都是一个 MCP 客户端，它会：

将检索数据的摘要添加到 OpenMemory。

使用自动分类（GPT）为记忆添加标签。

主 AI 智能体打开一个 SSE 通道，并使用：search_memory("latest papers on diffusion models") 拉取所有相关上下文。

主 AI 智能体打开一个 SSE 通道，并使用：

search_memory("latest papers on diffusion models") 拉取所有相关上下文。

仪表盘会显示哪些内容由哪个 AI 智能体存储，你还可以使用 ACL 限制 AI 智能体之间的记忆访问权限。

如果你仍然感兴趣，可以查看这个 GitHub 仓库，展示了如何使用 Gemini 2.0 构建研究型多 AI 智能体系统 - 设计模式概览。

提示：我们可以添加一个 LangGraph 编排层，其中每个 AI 智能体是一个节点，内存的读写随时间被追踪。这样我们可以按研究线程可视化知识流和来源。

✅ 具有持久跨会话内存的智能会议助手

我们可以构建类似会议笔记工具（Zoom、Google Meet 等）的东西，能够：

通过 LLMs 提取摘要。

记住跨通话的行动项。

在未来的会议中自动检索相关上下文。

让我们看看技术流程是什么样的：

在每次通话后使用记录文本和行动项调用 add_memories(text)。

下次会议：search_memory("open items for Project X") 在通话开始前运行。

相关的内存（按适当的类别标记）显示在 UI 中，审计日志追踪哪个内存被读取以及何时读取。

提示：与工具集成（如 Google Drive、Notion、GitHub），使存储的行动项链接回活文档和任务。

✅ 随着使用而演进的 AI 智能体编程助手

你基于 CLI 的编程助手可以通过存储使用模式、重复出现的问题、编码偏好和特定项目的提示来学习你的工作方式。

技术流程如下所示：

当你问："我的 SQLAlchemy 查询为什么失败？"时，它通过 add_memories 存储错误和修复。

下次你输入："SQLAlchemy joins 又出问题了，"助手自动运行 search_memory("sqlalchemy join issue") 并检索之前的修复。

你可以通过 /memories 仪表板检查所有存储的内存，并暂停任何过时或不正确的内存。

在每种情况下，OpenMemory 对向量搜索（用于语义回忆）、关系元数据（用于审计/日志记录）和实时仪表板（用于可观测性和即时访问控制）的组合，让你能够构建感起来就像会记忆的上下文感知应用。

现在你的 MCP 客户端拥有真正的内存。

你可以在一个仪表板中追踪每次访问、暂停你想要的内容并审计一切。最好的部分是一切都在本地存储在你的系统上。