8.1 · Python SDK

Python SDK

Python SDK

相关源文件

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

• 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 类。

代码实体映射

来源： 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() 方法时的内部数据流。

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

常见操作

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

核心方法表

作用域与过滤器

操作支持 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