8.1 · Python SDK

Python SDK（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/mem0ai/mem0/8.1-python-sdk

翻译时间：2026-05-27T08:45:00.588Z

翻译模型：deepseek-chat

原文字符数：8641

项目：Mem0 (mem0)

---

Python SDK

相关源文件

以下文件被用作生成此 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/__init__.py
• mem0/client/main.py
• mem0/configs/prompts.py
• mem0/memory/main.py
• mem0/memory/storage.py
• mem0/memory/utils.py
• tests/configs/test_prompts.py
• tests/memory/test_main.py
• tests/test_chatty_llm_parsing.py
• tests/test_main.py
• tests/test_memory.py
• tests/test_proxy.py

Mem0 Python SDK 为 AI 应用提供了对 Mem0 记忆层的编程访问接口。它通过统一的接口同时支持自托管（开源版）和云托管（平台版）两种部署方式。

来源： mem0/memory/main.py:1-50, mem0/client/main.py:1-50, mem0/__init__.py:1-7

安装

使用 pip 安装 SDK：

pip install mem0ai

包名为 mem0ai。特定向量存储或图数据库等高级功能需要安装项目配置中定义的可选依赖。

来源： docs/platform/quickstart.mdx:16-23, mem0/__init__.py:3-3

SDK 架构

SDK 分为两个主要实现路径：用于本地/开源使用的 Memory 类和用于与 Mem0 平台 API 交互的 MemoryClient 类。

代码实体映射

graph TD
    subgraph "自然语言空间"
        User["开发者 / AI 智能体"]
        Msg["对话消息"]
        Query["搜索查询"]
    end

    subgraph "代码实体空间（Python SDK）"
        subgraph "开源版（mem0/memory/main.py）"
            Memory["class Memory"]
            AsyncMemory["class AsyncMemory"]
        end

        subgraph "平台版（mem0/client/main.py）"
            MemoryClient["class MemoryClient"]
            AsyncMemoryClient["class AsyncMemoryClient"]
        end

        subgraph "核心逻辑与存储"
            SQLite["class SQLiteManager（mem0/memory/storage.py）"]
            Factories["工厂类（mem0/utils/factory.py）"]
        end
    end

    User -->|调用| Memory
    User -->|调用| MemoryClient
    Memory -->|管理| SQLite
    Memory -->|实例化| Factories
    MemoryClient -->|请求| API["api.mem0.ai"]

来源： mem0/memory/main.py:172-172, mem0/client/main.py:62-62, mem0/memory/storage.py:11-11, mem0/utils/factory.py:36-41

核心类

记忆（开源版同步类）

Memory 类为自托管部署提供同步记忆操作。它在本地管理向量存储、大语言模型（LLM）提供程序和嵌入向量。

• 初始化： 它使用 MemoryConfig 来校验设置，并通过工厂类初始化组件。mem0/memory/main.py:173-207
• 存储： 使用 SQLiteManager 进行历史记录追踪和消息持久化。mem0/memory/main.py:187-187
• 生命周期： 支持 reset() 方法，用于清除所有记忆并重新初始化向量存储。mem0/memory/main.py:245-279

来源： mem0/memory/main.py:172-243, tests/test_main.py:19-32

MemoryClient（平台版同步类）

MemoryClient 类提供基于 HTTP 的同步访问方式，用于与托管的 Mem0 平台 API 交互。

• 认证： 需要 api_key。如果未提供，它会查找 MEM0_API_KEY 环境变量。mem0/client/main.py:96-103
• 网络： 使用 httpx.Client，默认超时时间为 300 秒。mem0/client/main.py:119-126
• 项目管理： 包含一个 Project 实例，用于管理项目级别的设置。mem0/client/main.py:130-135

来源： mem0/client/main.py:62-112, docs/platform/quickstart.mdx:32-38

数据流：添加记忆（开源版）

下图展示了在 Memory 类上调用 add() 方法时的内部数据流。

sequenceDiagram
    participant App as 应用
    participant Mem as Memory（main.py）
    participant VS as 向量存储（通过工厂类）
    participant LLM as 大语言模型（通过工厂类）
    participant SQL as SQLiteManager（storage.py）

    App->>Mem: add(messages, user_id="user1")
    Mem->>Mem: _build_filters_and_metadata()
    Mem->>SQL: save_messages(messages)
    Mem->>LLM: generate_response(提取提示词)
    LLM-->>Mem: 提取的事实（JSON）
    Mem->>VS: search(已有事实用于去重)
    Mem->>VS: add(新事实)
    Mem->>SQL: add_history(event="ADD")
    Mem-->>App: 结果 JSON

来源： mem0/memory/main.py:281-384, mem0/memory/main.py:441-550, mem0/memory/storage.py:150-192

常见操作

Memory 和 MemoryClient 都实现了统一的接口，用于核心记忆操作。

核心方法表

方法	描述	实现（开源版）	实现（平台版）
add()	从消息中提取并存储记忆。	mem0/memory/main.py:281	mem0/client/main.py:164
search()	根据查询检索相关记忆。	mem0/memory/main.py:758	mem0/client/main.py:252
get()	根据 ID 检索特定记忆。	mem0/memory/main.py:610	mem0/client/main.py:178
get_all()	列出用户/智能体的所有记忆。	mem0/memory/main.py:642	mem0/client/main.py:206
update()	手动更新记忆内容。	mem0/memory/main.py:1045	mem0/client/main.py:298
delete()	删除特定记忆。	mem0/memory/main.py:1077	mem0/client/main.py:339
history()	获取记忆的审计追踪记录。	mem0/memory/main.py:1130	mem0/client/main.py:392

作用域与过滤器

操作支持 user_id、agent_id、app_id 和 run_id。

• 校验： 实体 ID 通过 _validate_and_trim_entity_id 进行校验，确保其不为空且不包含内部空白字符。mem0/memory/main.py:113-141
• 过滤： filters 参数允许在 search 等方法中进行基于元数据的高级检索。mem0/memory/main.py:804-814

来源： mem0/memory/main.py:87-165, mem0/client/main.py:32-34

异步操作

SDK 提供了 AsyncMemory 和 AsyncMemoryClient，用于高并发环境。

• AsyncMemory： 在 mem0/memory/main.py 中实现了核心操作（如 add、search 和 update）的异步版本。tests/memory/test_main.py:118-168
• AsyncMemoryClient： 使用 httpx.AsyncClient 向平台发起非阻塞 API 请求。mem0/client/main.py:10

来源： mem0/__init__.py:5-6, tests/memory/test_main.py:118-168

智能记忆处理

开源版 Memory 类使用单次提取管线（v3 版本）来确定记忆操作。

1. 事实提取： 系统使用 USER_MEMORY_EXTRACTION_PROMPT 等提示词，从用户消息中提取事实。mem0/configs/prompts.py:63-114
2. 操作判定： 在 _add_to_vector_store 调用过程中，大语言模型（LLM）根据新信息决定是 ADD（添加）、UPDATE（更新）还是 DELETE（删除）已有记忆。mem0/memory/main.py:441-550
3. JSON 处理： SDK 包含实用工具，可以稳健地从大语言模型（LLM）响应中提取和解析 JSON，即使响应被包裹在 Markdown 代码块中也能正确处理。mem0/memory/utils.py:125-142

来源： mem0/memory/main.py:441-550, mem0/memory/utils.py:125-142, mem0/configs/prompts.py:63-114

记忆代理集成

SDK 包含一个 Mem0 代理类，它与 litellm 集成，提供增强记忆的补全功能。

• 记忆注入： 它会自动搜索相关记忆，并在 Completions.create 中将其注入到大语言模型（LLM）的上下文中。mem0/proxy/main.py:63-84
• 自动捕获： 如果配置了该功能，它可以在生成响应后自动将当前对话添加到记忆存储中。mem0/proxy/main.py:73-73

来源： mem0/proxy/main.py:6-101, tests/test_proxy.py:63-84