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

长期记忆与上下文管理 · 本章是 Mem0 DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目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

翻译时间：2026-05-27T08:44:53.518Z

翻译模型：deepseek-chat

原文字符数：8273

项目：Mem0 (mem0)

---

MemoryClient（平台）

架构总览

客户端在系统中的位置

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

graph TB
    App["应用程序代码"]
    subgraph "SDK（代码实体空间）"
        Client["MemoryClient<br/>(mem0/client/main.py / src/client/mem0.ts)"]
        HTTPClient["httpx.Client / axios"]
        ProjectEntity["项目管理器<br/>(mem0/client/project.py)"]
    end
    API["平台 API<br/>(https://api.mem0.ai)"]

    App --> Client
    Client --> HTTPClient
    HTTPClient --> API

    Client --> Telemetry["PostHog 遥测<br/>capture_client_event()"]
    Client --> ProjectEntity

    API --> VectorDB["托管向量存储"]
    API --> GraphDB["托管图存储"]
    API --> Dashboard["Web 仪表盘<br/>(app.mem0.ai)"]

来源：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

初始化与认证

构造函数签名

classDiagram
    class MemoryClient {
        +str api_key
        +str host
        +str org_id
        +str project_id
        +str user_id
        +httpx.Client client
        +Project project
        +__init__(api_key, host, client)
        +_validate_api_key() str
    }

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

认证流程

sequenceDiagram
    participant App as 应用程序
    participant MC as MemoryClient (SDK)
    participant API as api.mem0.ai (平台)

    App->>MC: new MemoryClient(api_key="m0-...")
    MC->>MC: 将 API 密钥哈希为 telemetryId/user_id
    MC->>API: GET /v1/ping/
    API-->>MC: {org_id, project_id, user_email}
    MC->>MC: 存储 org_id、project_id
    MC-->>App: 客户端初始化完成

来源：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 状态码	描述
`AuthenticationError`	401	API 密钥无效 `mem0-ts/src/client/index.ts:38`
`RateLimitError`	429	请求频率超限 `mem0-ts/src/client/index.ts:39`
`MemoryQuotaExceededError`	402	平台存储配额已满 `mem0-ts/src/client/index.ts:44`
`ValidationError`	400	载荷或参数无效 `mem0-ts/src/client/index.ts:40`

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