agentic_huge_data_base / wiki
页面 Mem0 · 7.3 API 版本管理·DeepWiki 中文全文译文
DeepWiki 中文译文 / Mem0 / 7.3

7.3 · API 版本管理

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

项目Mem0 章节7.3 状态全文译文 模块检索、召回与索引、接口与服务契约、界面与交互、文档对象与元数据
项目要点页2.5 参考项目 项目章节目录Mem0 DeepWiki 原始章节API 版本管理 上一章7.2 下一章7.4
源码线索
  • docs/api-reference.mdx
  • docs/api-reference/entities/delete-user.mdx
  • docs/api-reference/entities/get-users.mdx
  • docs/api-reference/events/get-event.mdx
  • docs/api-reference/events/get-events.mdx
  • docs/cookbooks/frameworks/llamaindex-react.mdx
  • docs/cookbooks/integrations/agents-sdk-tool.mdx
  • docs/migration/api-changes.mdx
  • docs/migration/oss-to-platform.mdx
  • docs/openapi.json
模块标签
  • 检索、召回与索引
  • 接口与服务契约
  • 界面与交互
  • 文档对象与元数据
  • 智能体运行时

章节正文

API 版本管理

原始 DeepWiki 页面https://deepwiki.com/mem0ai/mem0/7.3-api-versioning

API 版本管理

相关源文件

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

  • docs/api-reference.mdx
  • docs/api-reference/entities/delete-user.mdx
  • docs/api-reference/entities/get-users.mdx
  • docs/api-reference/events/get-event.mdx
  • docs/api-reference/events/get-events.mdx
  • docs/cookbooks/frameworks/llamaindex-react.mdx
  • docs/cookbooks/integrations/agents-sdk-tool.mdx
  • docs/migration/api-changes.mdx
  • docs/migration/oss-to-platform.mdx
  • docs/openapi.json
  • docs/platform/features/advanced-retrieval.mdx
  • docs/platform/features/async-client.mdx
  • docs/platform/features/criteria-retrieval.mdx
  • docs/platform/features/custom-categories.mdx
  • docs/platform/features/custom-instructions.mdx
  • docs/platform/features/direct-import.mdx
  • docs/platform/quickstart.mdx
  • mem0/client/main.py

本文档记录了 Mem0 平台 API 使用的版本管理策略，包括 API 端点版本管理（v1、v2 和 v3）和输出格式版本管理（v1.0 与 v1.1）。内容涵盖如何在客户端 SDK 中指定版本以及在不同版本之间进行迁移。

概述

Mem0 平台实现了两个独立的版本管理维度：

  1. API 端点版本管理：基于 URL 路径的版本管理（/v1/、/v2/ 和 /v3/），决定了端点结构以及请求/响应的处理方式。
  2. 输出格式版本管理：响应格式版本管理（v1.0 与 v1.1），控制返回数据的结构。

对于大多数操作，平台会自动默认使用最新的稳定格式（v1.1）。对于 add 操作，SDK 会强制使用 v1.1 输出格式 mem0/client/main.py:202。

来源： mem0/client/main.py:202，docs/platform/quickstart.mdx:75

API 端点版本管理

版本对比
特性v1 端点v2 端点v3 端点
获取所有记忆GET /v1/memories/POST /v2/memories/不适用
搜索记忆POST /v1/memories/search/POST /v2/memories/search/POST /v3/memories/search/
添加记忆POST /v1/memories/不适用POST /v3/memories/add/
实体管理GET /v1/entities/DELETE /v2/entities/{type}/{id}/不适用
过滤查询参数JSON 请求体嵌套过滤器增强的请求体过滤器

版本选择流程：

Mem0 · 版本对比 · 图 1
Mem0 · 版本对比 · 图 1

来源： mem0/client/main.py:203，mem0/client/main.py:276-304，mem0/client/main.py:330-353，docs/platform/quickstart.mdx:75

v1 端点

主要用于标准检索、元数据过滤以及向后兼容。过滤器通常通过 GET 请求的查询字符串传递 docs/openapi.json:95-112。

Python 中的用法：

# 使用 /v1/ping/ 进行验证
client = MemoryClient(api_key="your-api-key")

来源： mem0/client/main.py:144，docs/openapi.json:89-112

v2 端点

引入 v2 端点是为了处理复杂的过滤和特定的实体管理。

  • 实体删除：支持按类型（用户、代理、应用、运行）删除特定实体 docs/api-reference/entities/delete-user.mdx:4。
  • 记忆检索：使用 POST 方法，以便在请求体中支持复杂的基于 JSON 的过滤 mem0/client/main.py:299。

来源： docs/openapi.json:225-245，mem0/client/main.py:299

v3 端点

v3 端点是当前平台核心记忆操作的标准端点。

  • 添加记忆：POST /v3/memories/add/ docs/platform/quickstart.mdx:75。
  • 搜索记忆：POST /v3/memories/search/ docs/platform/quickstart.mdx:107。

来源： docs/platform/quickstart.mdx:75，docs/platform/quickstart.mdx:107，mem0/client/main.py:203

输出格式版本管理

输出格式版本管理控制 API 响应的结构，与端点版本无关。

格式对比

v1.0 格式（旧版）： 返回一个扁平的记忆对象列表。

[
    {
        "id": "mem_1",
        "memory": "Loves coffee"
    }
]

v1.1 格式（当前版本）： 返回一个包含 results 键的字典。

{
    "results": [
        {
            "id": "mem_1",
            "memory": "Loves coffee"
        }
    ]
}
SDK 标准化逻辑

MemoryClient 包含确保为用户提供一致输出格式的逻辑，无论原始 API 响应如何。

Mem0 · SDK 标准化逻辑 · 图 2
Mem0 · SDK 标准化逻辑 · 图 2

来源： mem0/client/main.py:202，mem0/client/main.py:300-304，mem0/client/main.py:348-353

迁移指南

从开源版迁移到平台版

从开源版（OSS）迁移到平台版时，检索调用需要进行重大更新，因为平台版使用嵌套过滤。

方法开源版（OSS）平台版（MemoryClient）
search()m.search(query, user_id="alex")client.search(query, filters={"user_id": "alex"})
get_all()m.get_all(user_id="alex")client.get_all(filters={"user_id": "alex"})
limit 参数limit=10top_k=10

来源： docs/migration/oss-to-platform.mdx:80-95

平台 API 的关键变更
  • 过滤器必填：get_all() 现在需要指定过滤器；如果没有指定作用域，它将不再返回整个数据库 docs/platform/features/direct-import.mdx:70。
  • Top_k：在所有平台 SDK 中，limit 参数已被 top_k 替代 docs/migration/oss-to-platform.mdx:84-86。
  • 嵌套过滤器：平台版在 filters 字典中支持逻辑运算符，如 AND、OR 和 NOT docs/migration/oss-to-platform.mdx:114-119。

迁移示例（搜索）：

# 开源版（旧）
results = m.search("preferences", user_id="user123")

# 平台版（新）
results = client.search("preferences", filters={"user_id": "user123"})

来源： docs/migration/oss-to-platform.mdx:101-121

API 类别参考

类别版本关键端点
记忆v3/v3/memories/add/、/v3/memories/search/
实体v1/v2/v1/entities/、/v2/entities/{type}/{id}/
事件v1/v1/events/
项目v1/v1/projects/

来源： docs/openapi.json:25-89，docs/openapi.json:225，docs/api-reference/events/get-events.mdx:4，docs/platform/quickstart.mdx:75