7.2 · REST 接口参考（REST API Reference）

REST 接口参考

REST 接口参考

相关源文件

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

• 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/api-reference/memory/add-memories.mdx
• docs/api-reference/memory/delete-memories.mdx
• docs/api-reference/memory/delete-memory.mdx
• docs/api-reference/memory/get-memories.mdx
• docs/api-reference/memory/get-memory.mdx
• docs/api-reference/memory/history-memory.mdx
• docs/api-reference/memory/search-memories.mdx
• docs/api-reference/memory/update-memory.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 平台 REST API 的完整参考，涵盖所有可用的端点、请求/响应格式、认证方式和版本管理。通过 REST API，您可以通过 HTTP 请求以编程方式使用 Mem0 的记忆管理功能。

关于封装这些端点的客户端 SDK 信息，请参见 Python SDK 和 TypeScript/JavaScript SDK。关于 Webhook 和组织等平台特有功能，请参见 托管平台概览。

API 架构

Mem0 REST API 遵循 RESTful 原则，使用 JSON 格式的请求/响应载荷和基于令牌的认证方式。当前生产环境的基础 URL 为 https://api.mem0.ai。

API 结构图

来源： docs/openapi.json:14-18, mem0/client/main.py:97, docs/api-reference/memory/add-memories.mdx:4, docs/api-reference/memory/search-memories.mdx:4

认证

所有 API 请求都需要使用从 Mem0 平台仪表盘 获取的 API 密钥进行基于令牌的认证。

认证请求头

Authorization: Token <your-api-key>

MemoryClient 通过设置认证请求头和一个基于 API 密钥的 MD5 哈希值生成的自定义 Mem0-User-ID 请求头来处理认证 mem0/client/main.py:106-126。

认证流程

来源： mem0/client/main.py:96-106, mem0/client/main.py:113-134, mem0/client/main.py:140-153, docs/openapi.json:19-23

API 版本管理

Mem0 使用带版本号的路径来区分不同的处理范式和实体管理模型。

来源： docs/api-reference/memory/add-memories.mdx:4-7, docs/api-reference/memory/search-memories.mdx:4-7, docs/api-reference/entities/delete-user.mdx:4

记忆端点（V3）

V3 API 是当前高性能记忆操作的标准，采用异步增量管线。

添加记忆

端点： POST /v3/memories/add/

从对话消息中提取事实。V3 使用单次提取，在此过程中记忆被严格添加，不会被覆盖或删除 docs/api-reference/memory/add-memories.mdx:7-15。

• 推断模式： 设置 infer: false 可以启用"直接导入"，绕过大语言模型（LLM）提取，将文本原样存储 docs/platform/features/direct-import.mdx:7-9。
• 异步特性： 返回一个 event_id。使用 GET /v1/event/{event_id}/ 轮询 SUCCEEDED 或 FAILED 状态 docs/api-reference/memory/add-memories.mdx:60-85。

搜索记忆

端点： POST /v3/memories/search/

执行混合检索，结合语义相似度、BM25 关键词匹配和实体匹配 docs/api-reference/memory/search-memories.mdx:7。

• 过滤器： 实体 ID（user_id、agent_id 等）必须放在 filters 对象内部 docs/api-reference/memory/search-memories.mdx:9。
• 重排序： 可选的深度语义重排序（会增加约 150-200 毫秒的延迟）docs/platform/features/advanced-retrieval.mdx:12-44。

获取记忆

端点： POST /v3/memories/

检索分页的记忆列表。需要指定过滤器 docs/api-reference/memory/get-memories.mdx:7-20。

来源： docs/api-reference/memory/add-memories.mdx:1-85, docs/api-reference/memory/search-memories.mdx:1-117, docs/api-reference/memory/get-memories.mdx:1-68, mem0/client/main.py:164-249

实体和事件端点

实体管理（V1/V2）

• 列出实体： GET /v1/entities/ 检索所有实体及其关联的记忆计数 docs/openapi.json:89-181。
• 删除实体： DELETE /v2/entities/{entity_type}/{entity_id}/ 删除实体及其所有记忆 docs/api-reference/entities/delete-user.mdx:1-5。

事件和历史记录（V1）

• 获取事件： GET /v1/events/ 追踪后台任务的状态 docs/api-reference/events/get-events.mdx:1-13。
• 记忆历史记录： GET /v1/memories/{memory_id}/history/ 提供特定记忆生命周期的审计追踪 docs/api-reference/memory/history-memory.mdx:1-5。

实现流程

此图展示了 SDK 方法如何映射到内部 REST 路由和后台处理逻辑。

来源： mem0/client/main.py:164-186, docs/api-reference/memory/add-memories.mdx:15-16, docs/api-reference/memory/search-memories.mdx:7-9, docs/platform/features/async-client.mdx:32-56

错误处理

API 使用标准的 HTTP 状态码来表示成功或失败。

来源： mem0/client/utils.py:19, docs/api-reference/memory/add-memories.mdx:73-80, docs/api-reference/memory/get-memories.mdx:7-8