3.1 · 记忆类 (开源)（Memory Class (Open Source)）

记忆类 (开源)

记忆类（开源版）

相关源文件

以下文件为本 Wiki 页面的上下文来源：

• mem0-ts/src/oss/src/memory/index.ts
• mem0-ts/src/oss/src/tests/better-sqlite3-migration.test.ts
• mem0-ts/src/oss/src/tests/sqlite-backward-compat.test.ts
• mem0-ts/src/oss/src/utils/entity_extraction.ts
• mem0-ts/src/oss/src/vector_stores/memory.ts
• mem0-ts/src/oss/src/vector_stores/redis.ts
• mem0-ts/src/oss/tests/vector-store.unit.test.ts
• mem0-ts/src/oss/tests/vector-stores-compat.test.ts
• mem0/__init__.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

目的与范围

Memory 类是自托管 Mem0 部署的核心接口。它通过可配置的大语言模型（LLM）提供商、向量存储、嵌入向量模型和存储后端，提供对内存操作的完全控制。本文档介绍 Memory 和 AsyncMemory 类、它们的初始化方式、组件架构以及运行时行为。

对于使用 Mem0 API 的平台托管部署，请参阅 MemoryClient（平台版）。有关详细的内存操作生命周期（添加、搜索、更新、删除），请参阅 内存操作。

来源：mem0/memory/main.py:172-234、mem0/memory/main.py:1120-1121

类概述

Memory 类定义于 mem0/memory/main.py:172-234，继承自 MemoryBase。它通过协调以下组件来编排所有内存操作：

• 大语言模型（LLM）提供商：提取事实并确定内存操作（添加、更新、删除）mem0/memory/main.py:38-39。
• 嵌入向量模型：生成用于语义搜索的向量嵌入 mem0/memory/main.py:37。
• 向量存储：存储和检索内存嵌入向量及元数据 mem0/memory/main.py:40。
• 图谱存储（可选）：维护用于关系型内存的实体关系图 mem0/memory/main.py:41。
• 历史数据库：使用 SQLiteManager 记录所有内存修改，用于审计追踪 mem0/memory/storage.py:11-19。
• 重排序器（可选）：对搜索结果进行重排序，提高相关性 mem0/memory/main.py:39。

记忆类组件架构

来源：mem0/memory/main.py:172-234、mem0/utils/factory.py:36-41

初始化

基本初始化

初始化 Memory 类最简单的方式是使用默认配置。默认情况下，这需要设置 OPENAI_API_KEY 环境变量。

from mem0 import Memory

m = Memory()

这会创建一个使用默认设置的 Memory 实例：

• 大语言模型（LLM）：OpenAI gpt-4o
• 嵌入向量模型：OpenAI text-embedding-3-small（1536 维）
• 向量存储：Qdrant（本地存储于 ~/.mem0/qdrant）
• 历史记录：SQLite 数据库位于 ~/.mem0/history.db

来源：mem0/memory/main.py:173-174、mem0/memory/setup.py:25-57

基于配置的初始化

对于自定义部署，可以通过 from_config 方法传入 MemoryConfig 对象或字典。

from mem0 import Memory
from mem0.configs.base import MemoryConfig

config = MemoryConfig(
    llm={"provider": "ollama", "config": {"model": "llama3"}},
    vector_store={"provider": "chroma", "config": {"collection_name": "my_memories"}}
)
m = Memory(config=config)

来源：mem0/memory/main.py:235-243、mem0/configs/base.py:15-16

组件初始化流程

创建 Memory 实例时，组件会通过工厂进行实例化。系统还会初始化一个独立的遥测向量存储，用于追踪迁移和系统事件。

初始化时序图

来源：mem0/memory/main.py:173-234、mem0/memory/storage.py:11-18

核心方法

Memory 类提供用于 CRUD 操作的同步方法。

来源：mem0/memory/main.py:281-1100

AsyncMemory 类

AsyncMemory 提供所有核心方法的异步版本，适用于 FastAPI 或 Web 服务器等高并发环境。它继承自 Memory，并使用 async 实现覆盖了父类方法 mem0/memory/main.py:1120-1121。

实现模式

AsyncMemory 对阻塞操作（如 SQLite 写入）使用 asyncio.to_thread，对支持异步的提供商使用原生 async 调用。

from mem0 import AsyncMemory

async def main():
    m = AsyncMemory()
    await m.add("我喜欢旅行", user_id="user_123")
    results = await m.search("我喜欢什么？", user_id="user_123")

来源：mem0/memory/main.py:1120-1490

存储与历史记录管理

SQLiteManager

SQLiteManager 类负责处理两种不同类型数据的持久化存储：

1. 历史记录：内存变更的审计追踪（添加、更新、删除）mem0/memory/storage.py:102-127。
2. 消息：用于事实提取上下文的原始对话历史记录 mem0/memory/storage.py:128-148。

遥测与脱敏

Memory 类包含一个遥测系统，用于捕获 mem0.init 和 mem0.add 等事件。为确保安全，_safe_deepcopy_config 函数在将配置数据发送到遥测系统之前，会对敏感字段（如 api_key、access_token、password）进行脱敏处理 mem0/memory/main.py:58-88、mem0/memory/main.py:187-217。

来源：mem0/memory/main.py:58-88、mem0/memory/storage.py:11-19

数据流：自然语言到向量空间

下图展示了自然语言输入如何在代码中转换为存储的实体。

来源：mem0/memory/main.py:380-450、mem0/memory/utils.py:61-70

校验与约束

Memory 类对标识符施加了以下约束：

• 无空白字符：user_id、agent_id 和 run_id 不能包含内部空格 mem0/memory/main.py:137-141。
• 非空：标识符不能为空字符串或仅包含空白字符的字符串 mem0/memory/main.py:133-136。
• 顶层参数拒绝：实体参数必须通过 filters 传递，不能作为 search() 或 add() 等方法的顶层关键字参数 mem0/memory/main.py:103-110。

来源：mem0/memory/main.py:103-141