7 · 平台与 API（Platform and API）

平台与 API（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mem0ai/mem0/7-platform-and-api

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

翻译模型：deepseek-chat

原文字符数：9285

项目：Mem0 (mem0)

---

平台与 API

相关源文件

以下文件被用作生成此维基页面的上下文：

• 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/openapi.json
• docs/platform/quickstart.mdx
• mem0/client/main.py

Mem0 平台是一个完全托管的记忆服务，通过 REST API 提供持久化记忆能力。应用程序使用 API 密钥进行认证，并与 https://api.mem0.ai 上的服务交互，而平台则管理所有基础设施，包括向量存储、图数据库、大语言模型（LLM）提供商以及扩展能力。

本节概述了平台的 API 架构、认证模型和关键特性。有关部署的具体细节：

• 托管平台：请参阅下面的子章节，了解 API 参考、Webhook 和项目管理。
• 自托管部署：请参阅自托管服务器了解设置和配置。
• 客户端 SDK：请参阅客户端 SDK了解 Python/TypeScript/JavaScript 的使用。

平台架构

Mem0 平台提供多层架构，将客户端应用程序、API 网关认证、租户作用域和托管基础设施分离开来。客户端 SDK 中的 MemoryClient 类将 HTTP 请求包装上认证头，并将它们路由到版本化的 API 端点。

平台请求流程

graph TB
    App["应用程序代码"]
    MemoryClient["MemoryClient<br/>mem0/client/main.py"]
    HTTPClient["httpx.Client<br/>(HTTP 传输层)"]

    subgraph "API 网关 (api.mem0.ai)"
        AuthHeader["Authorization: Token {api_key}"]
        UserIDHeader["Mem0-User-ID: {hashed_key}"]
        Ping["/v1/ping/<br/>(验证)"]
    end

    subgraph "版本化端点"
        V1Memories["/v1/memories/<br/>(CRUD)"]
        V2Memories["/v2/memories/<br/>(实体)"]
        V3Memories["/v3/memories/add/<br/>(增量管线)"]
        V1Events["/v1/events/<br/>(审计/轮询)"]
    end

    subgraph "作用域层级"
        OrgID["org_id<br/>(组织)"]
        ProjectID["project_id<br/>(组织内项目)"]
        EntityID["user_id / agent_id / run_id<br/>(实体隔离)"]
    end

    subgraph "托管基础设施"
        VectorStores["向量存储<br/>(托管)"]
        GraphStores["图存储<br/>(托管)"]
        LLMProviders["大语言模型提供商<br/>(托管)"]
    end

    App --> MemoryClient
    MemoryClient --> HTTPClient
    HTTPClient --> AuthHeader
    HTTPClient --> UserIDHeader

    AuthHeader --> Ping
    Ping --> V1Memories
    Ping --> V2Memories
    Ping --> V3Memories
    Ping --> V1Events

    V1Memories --> OrgID
    V3Memories --> OrgID
    OrgID --> ProjectID
    ProjectID --> EntityID

    EntityID --> VectorStores
    EntityID --> GraphStores
    EntityID --> LLMProviders

关键组件：

• MemoryClient：Python/JavaScript 类，用于包装 API 请求 mem0/client/main.py:62-139。
• 认证：基于令牌，使用 MD5 哈希的 API 密钥作为 Mem0-User-ID mem0/client/main.py:105-126。
• 端点版本：v1/v2 用于传统 CRUD/搜索，v3 用于现代增量管线 docs/api-reference/memory/add-memories.mdx:4-15。
• 多租户：组织 -> 项目 -> 实体的层级结构 mem0/client/main.py:98-100。

来源： mem0/client/main.py:62-139，docs/openapi.json:14-23，docs/platform/quickstart.mdx:32-51，docs/api-reference/memory/add-memories.mdx:4-15

认证

平台使用基于令牌的认证。客户端 SDK 会自动使用提供的 API 密钥为所有请求处理认证头。

认证流程

sequenceDiagram
    participant App as "应用程序"
    participant MC as "MemoryClient"
    participant API as "api.mem0.ai"

    App->>MC: "MemoryClient(api_key='your-api-key')"
    MC->>MC: "生成 API 密钥的 MD5 哈希"
    MC->>API: "GET /v1/ping/<br/>Authorization: Token sk-...<br/>Mem0-User-ID: {hash}"
    API-->>MC: "{org_id, project_id, user_email}"
    MC->>MC: "存储 org_id, project_id"
    MC-->>App: "客户端就绪"

认证头：

• Authorization: Token {api_key} - 主认证 mem0/client/main.py:122。
• Mem0-User-ID: {md5_hash} - 从 API 密钥派生的客户端标识符 mem0/client/main.py:123。

来源： mem0/client/main.py:96-126，docs/platform/quickstart.mdx:32-51，docs/openapi.json:19-23

API 端点概览

平台提供版本化的 REST 端点。v3 端点引入了用于记忆的增量管线，其中处理通常是异步的。

核心记忆操作

SDK 方法	HTTP 端点	用途
client.add()	POST /v3/memories/add/	添加记忆，支持异步处理 docs/api-reference/memory/add-memories.mdx:4-7
client.search()	POST /v3/memories/search/	混合检索（语义 + BM25） docs/api-reference/memory/search-memories.mdx:4-7
client.get_all()	POST /v3/memories/	列出记忆，支持高级过滤器 docs/api-reference/memory/get-memories.mdx:4-9
client.delete()	DELETE /v1/memories/{id}/	删除单条记忆 docs/api-reference/memory/delete-memory.mdx:4
client.history()	GET /v1/memories/{id}/history/	追踪记忆演化 docs/api-reference/memory/history-memory.mdx:4

有关完整的端点规范，请参阅 REST API 参考。

来源： mem0/client/main.py:164-382，docs/openapi.json:24-150，docs/api-reference/memory/add-memories.mdx:4-15，docs/api-reference/memory/search-memories.mdx:4-7

高级检索与过滤

v3 API 支持复杂的逻辑操作和多信号检索。

搜索与过滤逻辑

• 混合搜索：结合语义嵌入向量、BM25 关键词匹配和实体匹配 docs/api-reference/memory/search-memories.mdx:7。
• 逻辑运算符：在 filters 对象内支持 AND、OR 和 NOT docs/api-reference/memory/get-memories.mdx:9-19。
• 比较运算符：包括 gte、lte、ne、icontains 和通配符 * docs/api-reference/memory/search-memories.mdx:11-19。

有关迁移和输出格式的详细信息，请参阅 API 版本化。

来源： docs/api-reference/memory/get-memories.mdx:7-19，docs/api-reference/memory/search-memories.mdx:7-19

组织与项目

平台实现了层级化多租户。组织包含项目，项目用于隔离记忆和配置。

作用域规则

作用域级别	参数	用途
组织	org_id	顶级团队/公司隔离 mem0/client/main.py:98
项目	project_id	环境/应用程序隔离 mem0/client/main.py:99
实体	user_id	单个用户隔离 mem0/client/main.py:33
实体	agent_id	AI 代理隔离 mem0/client/main.py:33

有关详细的层级管理，请参阅组织与项目。

来源： mem0/client/main.py:33-100，docs/openapi.json:97-111

Webhook 与事件

平台将操作追踪为事件。异步操作（如 v3/memories/add/）会返回一个 event_id，可以对其进行轮询。

事件轮询工作流

sequenceDiagram
    participant Client as "MemoryClient"
    participant API as "api.mem0.ai"

    Client->>API: "POST /v3/memories/add/"
    API-->>Client: "{'status': 'PENDING', 'event_id': 'evt-123'}"
    Loop 直到 SUCCEEDED 或 FAILED
        Client->>API: "GET /v1/events/evt-123/"
        API-->>Client: "{'status': 'SUCCEEDED', ...}"
    End

有关配置详情，请参阅 Webhook 与事件。

来源： docs/api-reference/memory/add-memories.mdx:62-85，docs/api-reference/events/get-events.mdx:1-13

记忆导出

平台提供导出已存储记忆的功能，用于数据可移植性或外部分析。

有关导出模式与过程的文档，请参阅记忆导出。