agentic_huge_data_base / wiki
页面 Mem0 · 15.2 OpenMemory MCP 服务端·DeepWiki 中文全文译文
DeepWiki 中文译文 / Mem0 / 15.2

15.2 · OpenMemory MCP 服务端（OpenMemory MCP Server）

长期记忆与上下文管理 · 聚焦本章的模块关系、源码依据与实现要点。

项目Mem0 章节15.2 状态全文译文 模块界面与交互、安装与启动、记忆与上下文、检索、召回与索引
项目要点页2.5 参考项目 项目章节目录Mem0 DeepWiki 原始章节OpenMemory MCP Server 上一章15.1 下一章16
源码线索
  • openmemory/.gitignore
  • openmemory/api/alembic/versions/add_config_table.py
  • openmemory/api/alembic/versions/afd00efbd06b_add_unique_user_id_constraints.py
  • openmemory/api/app/mcp_server.py
  • openmemory/api/app/models.py
  • openmemory/api/app/routers/__init__.py
  • openmemory/api/app/routers/backup.py
  • openmemory/api/app/routers/config.py
  • openmemory/api/app/routers/memories.py
  • openmemory/api/app/utils/memory.py
模块标签
  • 界面与交互
  • 安装与启动
  • 记忆与上下文
  • 检索、召回与索引
  • 接口与服务契约

章节正文

OpenMemory MCP 服务端

原始 DeepWiki 页面https://deepwiki.com/mem0ai/mem0/15.2-openmemory-mcp-server

OpenMemory MCP 服务器

相关源文件

本章引用的主要源码文件：

  • openmemory/.gitignore
  • openmemory/api/alembic/versions/add_config_table.py
  • openmemory/api/alembic/versions/afd00efbd06b_add_unique_user_id_constraints.py
  • openmemory/api/app/mcp_server.py
  • openmemory/api/app/models.py
  • openmemory/api/app/routers/__init__.py
  • openmemory/api/app/routers/backup.py
  • openmemory/api/app/routers/config.py
  • openmemory/api/app/routers/memories.py
  • openmemory/api/app/utils/memory.py
  • openmemory/api/main.py
  • openmemory/api/tests/__init__.py
  • openmemory/api/tests/test_mcp_server.py
  • openmemory/compose/chroma.yml
  • openmemory/compose/elasticsearch.yml
  • openmemory/compose/faiss.yml
  • openmemory/compose/milvus.yml
  • openmemory/compose/opensearch.yml
  • openmemory/compose/pgvector.yml
  • openmemory/compose/qdrant.yml
  • openmemory/compose/redis.yml
  • openmemory/compose/weaviate.yml
  • openmemory/ui/components/dashboard/Install.tsx
  • openmemory/ui/components/form-view.tsx
  • openmemory/ui/components/shared/source-app.tsx
  • openmemory/ui/hooks/useAppsApi.ts
  • openmemory/ui/hooks/useFiltersApi.ts
  • openmemory/ui/hooks/useMemoriesApi.ts
  • openmemory/ui/hooks/useStats.ts
  • openmemory/ui/public/images/augment.png

OpenMemory MCP 服务器通过模型上下文协议（MCP）为 AI 模型提供了一个标准化的接口，使其能够与记忆层进行交互。它充当了兼容 MCP 的客户端（如 Claude Desktop、Cursor 或 Windsurf）与 Mem0 记忆引擎之间的桥梁，使智能体能够在多个会话之间持久化和检索信息。

概述与实现

该服务器使用 FastMCP 框架实现 openmemory/api/app/mcp_server.py:43-43。它采用弹性架构设计，通过 get_memory_client_safe 函数延迟初始化记忆客户端 openmemory/api/app/mcp_server.py:46-52。这样可以防止在启动期间，如果外部依赖（如本地 Ollama 实例）暂时不可用，导致服务器崩溃 openmemory/api/app/mcp_server.py:5-9。

关键架构组件
  • FastMCP 实例：名为 mem0-mcp-server 的核心服务器对象 openmemory/api/app/mcp_server.py:43-43。
  • 传输方式：支持通过 /mcp/messages/ 的 SSE（服务器发送事件）openmemory/api/app/mcp_server.py:62-62，以及根据 2025-03-26 MCP 规范定义的可流式 HTTP，用于无状态 JSON-RPC 交互 openmemory/api/tests/test_mcp_server.py:3-5。
  • 上下文管理：使用 contextvars（user_id_var 和 client_name_var）在异步请求之间隔离身份，确保同一服务器进程内的多租户支持 openmemory/api/app/mcp_server.py:54-56。
  • 数据库集成：与 SessionLocal 交互，记录记忆访问并通过 get_user_and_app 验证应用状态 openmemory/api/app/mcp_server.py:80-87。
系统数据流

下图展示了来自 MCP 客户端的自然语言请求如何转换为代码实体和数据库操作。

MCP 请求到代码实体的映射

Mem0 · 系统数据流 · 图 1
Mem0 · 系统数据流 · 图 1

来源：openmemory/api/app/mcp_server.py:64-95, openmemory/api/app/utils/memory.py:38-40, openmemory/api/app/models.py:85-100

MCP 工具（API）

该服务器暴露了多个工具，供大语言模型（LLM）调用来管理记忆。

工具名称描述关键参数
add_memories从文本中提取事实并存储。text（字符串），infer（布尔值）
search_memory对存储的记忆执行语义搜索。query（字符串）
list_memories检索用户的分页记忆列表。page（整数），page_size（整数）
delete_memories根据 ID 删除特定记忆。memory_id（字符串）
delete_all_memories清除当前用户的所有记忆。-

来源：openmemory/api/app/mcp_server.py:64-150, openmemory/api/tests/test_mcp_server.py:162-163

记忆处理逻辑

当调用 add_memories 时，服务器执行双重更新策略：

  1. Mem0 核心：调用 memory_client.add()，该函数处理嵌入向量和向量存储 openmemory/api/app/mcp_server.py:89-95。
  2. 本地状态同步：遍历 Mem0 响应结果。如果事件是 ADD，则在本地数据库中创建或更新一个 Memory 记录，状态设置为 MemoryState.active openmemory/api/app/mcp_server.py:103-112。同时创建一个 MemoryStatusHistory 条目来跟踪该变更 openmemory/api/app/mcp_server.py:118-124。

配置与环境

MCP 服务器依赖于存储在 configs 表中的全局 OpenMemory 配置 openmemory/api/app/models.py:74-82。该配置决定了底层 mem0 客户端使用的 LLM 和嵌入向量提供者。

配置流程

Mem0 · 配置与环境 · 图 2
Mem0 · 配置与环境 · 图 2

来源：openmemory/ui/components/form-view.tsx:32-68, openmemory/api/app/routers/config.py:120-133, openmemory/api/app/utils/memory.py:102-126

Docker 环境处理

OpenMemory MCP 实现的一个关键特性是能够在 Docker 内部运行时解析 localhost。_get_docker_host_url 函数尝试通过以下方式找到宿主机：

  1. OLLAMA_HOST 环境变量 openmemory/api/app/utils/memory.py:56-59。
  2. 针对 Docker Desktop 用户的 host.docker.internal openmemory/api/app/utils/memory.py:72-74。
  3. Docker 桥接网关 IP（从 /proc/net/route 获取）openmemory/api/app/utils/memory.py:79-89。

面向旧版用户的客户端设置

MCP 服务器在 FastAPI 应用启动期间通过 main.py 中的 setup_mcp_server(app) 自动注册 openmemory/api/main.py:79-79。

连接详情
  • 基础 URL：通常为 http://localhost:8765/mcp
  • SSE 端点：http://localhost:8765/mcp/messages/ openmemory/api/app/mcp_server.py:62-62
  • 无状态 HTTP：POST /mcp/{client_name}/http/{user_id} openmemory/api/tests/test_mcp_server.py:82-84
通过 UI 安装

仪表盘提供了一个专用的"安装"选项卡，用于生成各种 MCP 客户端的安装命令 openmemory/ui/components/dashboard/Install.tsx:9-18。

  • 直接链接：{URL}/mcp/openmemory/sse/{user} openmemory/ui/components/dashboard/Install.tsx:135-136
  • 安装脚本：npx @openmemory/install local {URL}/mcp/{tab}/sse/{user} --client {tab} openmemory/ui/components/dashboard/Install.tsx:55-55

来源：openmemory/api/app/mcp_server.py:1-40, openmemory/api/app/utils/memory.py:1-30, openmemory/api/main.py:1-13, openmemory/ui/components/dashboard/Install.tsx:46-80