agentic_huge_data_base / wiki
页面 Mem0 · 3.2 MemoryClient（平台）·DeepWiki 中文全文译文
DeepWiki 中文译文 / Mem0 / 3.2

3.2 · MemoryClient（平台）（MemoryClient (Platform)）

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

项目Mem0 章节3.2 状态全文译文 模块界面与交互、系统架构、测试、发布与运维、记忆与上下文
项目要点页2.5 参考项目 项目章节目录Mem0 DeepWiki 原始章节MemoryClient (Platform) 上一章3.1 下一章3.3
源码线索
  • 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/openapi.json
  • docs/platform/quickstart.mdx
  • mem0-ts/package.json
  • mem0-ts/src/client/index.ts
  • mem0-ts/src/client/mem0.ts
  • mem0-ts/src/client/mem0.types.ts
模块标签
  • 界面与交互
  • 系统架构
  • 测试、发布与运维
  • 记忆与上下文
  • 检索、召回与索引

章节正文

MemoryClient（平台）

原始 DeepWiki 页面https://deepwiki.com/mem0ai/mem0/3.2-memoryclient-platform

MemoryClient（平台）

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

  • 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/openapi.json
  • docs/platform/quickstart.mdx
  • mem0-ts/package.json
  • mem0-ts/src/client/index.ts
  • mem0-ts/src/client/mem0.ts
  • mem0-ts/src/client/mem0.types.ts
  • mem0-ts/src/client/telemetry.ts
  • mem0-ts/src/client/tests/memoryClient.webhooks.test.ts
  • mem0/client/main.py

MemoryClient 类提供了 Python 和 TypeScript 的 SDK，用于与 Mem0 平台 API（一种完全托管的记忆服务）进行交互。该客户端负责处理认证、请求格式化以及与记忆操作相关的 API 通信，无需用户自行搭建基础设施。

适用范围：本页面介绍的是用于托管部署的平台客户端（MemoryClient）。如需了解自托管开源部署，请参见记忆类（开源）。如需了解 REST API 详情，请参见REST API 参考。

架构总览

客户端在系统中的位置

MemoryClient 位于应用程序与 Mem0 平台 API 之间，透明地处理序列化、认证和错误处理。

Mem0 · 客户端在系统中的位置 · 图 1
Mem0 · 客户端在系统中的位置 · 图 1

来源：mem0/client/main.py:62-135, mem0-ts/src/client/mem0.ts:81-122, docs/openapi.json:14-18

关键职责
职责实现方式
认证通过 _validate_api_key() 调用 /v1/ping/ 验证 API 密钥 mem0/client/main.py:140-162, mem0-ts/src/client/mem0.ts:214-249
会话管理使用 httpx.Client（Python）或 axios（TS）并设置超时 mem0/client/main.py:119-126, mem0-ts/src/client/mem0.ts:113-117
请求格式化通过 _prepare_payload() 自动构建载荷，并转换蛇形命名法 mem0/client/main.py:186, mem0-ts/src/client/mem0.ts:199-206
错误处理使用 @api_error_handler（Python）或 _fetchWithErrorHandling（TS） mem0/client/utils.py:19-50, mem0-ts/src/client/mem0.ts:182-197
遥测通过 capture_client_event() 捕获事件 mem0/client/main.py:138, mem0-ts/src/client/mem0.ts:124-146

来源：mem0/client/main.py:113-175, mem0-ts/src/client/mem0.ts:113-249

初始化与认证

构造函数签名
Mem0 · 构造函数签名 · 图 2
Mem0 · 构造函数签名 · 图 2

来源：mem0/client/main.py:62-135

认证流程
Mem0 · 认证流程 · 图 3
Mem0 · 认证流程 · 图 3

来源：mem0/client/main.py:140-162, mem0-ts/src/client/mem0.ts:214-249

初始化模式

Python：

from mem0 import MemoryClient
client = MemoryClient(api_key="your-api-key")

TypeScript：

import MemoryClient from 'mem0ai';
const client = new MemoryClient({ apiKey: 'your-api-key' });

来源：docs/platform/quickstart.mdx:32-43, mem0-ts/src/client/mem0.ts:102-122

核心记忆操作

添加操作

add() 方法用于存储新的记忆。在平台中，该方法使用异步管线，从消息中提取记忆。

方法签名：

def add(self, messages, options: Optional[AddMemoryOptions] = None, **kwargs) -> Dict[str, Any]

消息格式处理： 客户端会将各种输入格式规范化为消息对象列表。

输入类型转换方式示例
str[{"role": "user", "content": str}]"Hello" → [{"role": "user", "content": "Hello"}]
dict[dict]{"role": "user", "content": "Hi"} → [{"role": "user", "content": "Hi"}]

来源：mem0/client/main.py:188-192, mem0-ts/src/client/mem0.ts:251-278

搜索操作

search() 方法用于检索相关记忆。对于平台 v3 版本，实体 ID（如 user_id）必须通过 filters 对象或选项参数传入。

# Python 搜索
results = client.search(
    query="What are my dietary restrictions?",
    filters={"user_id": "user123"}
)

来源：mem0/client/main.py:251-296, mem0-ts/src/client/mem0.ts:311-332

获取与列表操作
操作方法API 端点
获取单条get(memory_id)GET /v1/memories/{memory_id}/ mem0/client/main.py:178-204
获取全部get_all(filters=...)GET /v1/memories/ mem0/client/main.py:206-250
历史记录history(memory_id)GET /v1/memories/{memory_id}/history/ mem0/client/main.py:392-413

来源：mem0/client/main.py:178-413, mem0-ts/src/client/mem0.ts:280-310

实体管理

MemoryClient 提供了管理拥有记忆的实体（用户、代理、应用、运行实例）的方法。

方法描述API 端点
users()列出所有用户实体GET /v1/entities/ mem0/client/main.py:415-434
delete_users()删除用户实体及其记忆DELETE /v2/entities/user/{id}/ mem0/client/main.py:471-490

来源：mem0/client/main.py:415-490, docs/openapi.json:89-182

高级平台功能

Webhook（网络钩子）

TypeScript SDK 明确支持用于记忆事件的 Webhook 管理。

import { WebhookEvent } from "mem0ai";

await client.createWebhook({
  name: "my-webhook",
  url: "https://example.com/webhook",
  eventTypes: [WebhookEvent.MEMORY_ADDED]
});

来源：mem0-ts/src/client/mem0.ts:503-530, mem0-ts/src/client/mem0.types.ts:170-175

记忆导出

平台用户可以根据自定义模式和过滤器导出记忆。

await client.createMemoryExport({
  schema: { "name": "string", "preference": "string" },
  filters: { "user_id": "user123" }
});

来源：mem0-ts/src/client/mem0.ts:577-593, mem0-ts/src/client/mem0.types.ts:208-212

错误处理

公开方法使用结构化的错误处理机制，将 HTTP 状态码映射到特定的异常类型。

异常类型HTTP 状态码描述
AuthenticationError401API 密钥无效 mem0-ts/src/client/index.ts:38
RateLimitError429请求频率超限 mem0-ts/src/client/index.ts:39
MemoryQuotaExceededError402平台存储配额已满 mem0-ts/src/client/index.ts:44
ValidationError400载荷或参数无效 mem0-ts/src/client/index.ts:40

来源：mem0/client/utils.py:19-50, mem0-ts/src/client/index.ts:36-46