Mem0 深度解析:智能记忆层的架构原理

引言

Mem0(发音为"mem-zero")是一个专为 AI 代理和助手设计的智能记忆层。本文深入剖析其 CRUD(创建、读取、更新、删除)全流程,重点揭示其 LLM 驱动的记忆提取流水线、多信号混合搜索、以及非阻塞容错设计。

快速开始

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

memory = Memory(config=MemoryConfig(
    vector_store="qdrant",      # 或 faiss, pgvector, lancedb
    llm="openai",               # 或 anthropic, azure_openai
    embedder="openai",
    history_db_path="./mem0.db"
))

架构概览

┌─────────────────────────────────────────────────────────────┐
│                         Mem0 Memory Layer                    │
├─────────────┬─────────────┬─────────────┬──────────────────┤
│  Embedding  │   Vector    │     LLM     │   Entity Store   │
│   Model     │   Store     │             │                  │
├─────────────┴─────────────┴─────────────┴──────────────────┤
│                    SQLite History DB                       │
└─────────────────────────────────────────────────────────────┘

核心组件:

  • 嵌入模型:文本 → 向量
  • 向量存储:语义检索(Qdrant/Faiss/pgvector/LanceDB)
  • LLM:关键事实抽取、代词消解、去重决策
  • SQLite 历史库:变更审计、消息回放
  • 实体存储:记忆间图关系、搜索增强

Create(添加记忆)

add() 方法是 Mem0 最复杂的操作,采用 8 阶段流水线 设计:

阶段
内容
作用
Phase 0
从 SQLite 获取最近 10 条历史消息
为 LLM 提供上下文,用于代词/指代消解
Phase 1
向量语义检索已有记忆(top_k=10)
给 LLM 提供去重和关联的参照列表
Phase 2
单次 LLM 抽取调用
结合上下文 + 已有记忆,一次性完成抽取决策
Phase 3
批量 embed 所有抽取文本
合并 embedding 请求,减少 API 调用次数
Phase 4
MD5 哈希去重(跨已有 + 批内)
防止语义等价内容重复写入
Phase 5
批量写入向量库 + 历史库
原子化持久化,单条失败不阻断批次
Phase 6
批量实体抽取 + 知识图谱关联
构建记忆间的实体关联网络
Phase 7
保存原始消息到 SQLite
支持未来 replay / 历史回溯

Phase 0: 上下文收集

输入
输出
关键代码
user_id/Agent_id/run_id
最近 10 条对话消息
self.db.get_last_messages(session_scope, limit=10)

从 SQLite 历史数据库中获取最近 10 条消息,为 LLM 提供对话上下文,帮助解决代词指代问题(如"我喜欢它"中的"它"指代什么)。

Phase 1: 检索现有记忆

输入
输出
关键参数
新消息文本
最相关的 10 条已有记忆
top_k=10

将输入消息转换为向量,在向量存储中搜索最相关的现有记忆。这一步有两个目的:

  • 为 LLM 提供参考,避免重复存储相似信息
  • 识别需要更新的已有记忆
query_embedding = self.embedding_model.embed(parsed_messages, "search")
existing_results = self.vector_store.search(
    query=parsed_messages, vectors=query_embedding, top_k=10, filters=search_filters
)

Phase 2: LLM 提取(单次调用)

输入
输出
设计要点
上下文 + 已有记忆 + 新消息
JSON 格式的记忆操作列表
单次调用
完成全部决策

这是 Mem0 的智能核心。为防幻觉,已有记忆被映射为整数索引(0,1,2...而非 UUID)。

Prompt 自适应:当 filters 中只有 agent_id 而无 user_id 时(即代理级别记忆),系统会自动追加 AGENT_CONTEXT_SUFFIX,要求 LLM 从代理视角提取记忆:

  • 用户陈述的事实 → "Agent was informed that [fact]"
  • 代理行为 → "Agent recommended [X]"
  • 代理配置 → "Agent is configured to [behavior]"
# mem0/memory/main.py:724
is_agent_scoped = bool(filters.get("agent_id")) and not filters.get("user_id")
system_prompt = ADDITIVE_EXTRACTION_PROMPT
if is_agent_scoped:
    system_prompt += AGENT_CONTEXT_SUFFIX

LLM 输出示例:

{
  "memory": [
    {"id": "0", "text": "用户喜欢Python编程", "attributed_to": "user"},
    {"id": "1", "text": "用户用VS Code编辑器", "attributed_to": "user"},
    {"id": "2", "text": "用户正在学习JavaScript", "attributed_to": "user"}
  ]
}

Phase 3: 批量嵌入

输入
输出
容错机制
抽取的记忆文本列表
向量列表
批量失败则回退到单条处理
mem_embeddings_list = self.embedding_model.embed_batch(mem_texts, "add")

Phase 4: 哈希去重

步骤
操作
目的
4a
lemmatize_for_bm25(text)
词形还原,提升关键词搜索效果
4b
hashlib.md5(text.encode()).hexdigest()
计算内容哈希
4c
比对 existing_hashes
与已有记忆去重
4d
比对 seen_hashes
批次内部去重

Phase 5: 批量持久化

目标存储
操作
容错设计
向量存储
vector_store.insert()
逐条 fallback
历史数据库
db.batch_add_history()
逐条 fallback

容错细节:

  • batch_add_history 失败 → 逐条 add_history(),单条失败只记录 error log,不阻断其余记忆
  • vector_store.insert 同理逐条 fallback
  • 整个 Phase 5 被 try/except 包裹,即使全部失败也只影响历史记录,记忆向量仍已写入

Phase 6: 批量实体链接

子阶段
操作
容错设计
6a
全局去重
跨所有记忆收集唯一实体
6b
批量嵌入
为所有唯一实体生成向量
6c
批量搜索
在实体存储中查找已有实体
6d
分离操作
≥0.95 更新链接,<0.95 创建新实体
6e
批量插入
一次性插入所有新实体

容错细节:

  • embed_batch 失败 → 逐条 embed(),失败项返回 None,后续自动过滤
  • 实体链接失败(整个 Phase 6)→ 只打 warning,不抛异常,记忆添加已成功完成

这种非阻塞容错哲学贯穿 Mem0:核心操作(记忆写入)必须成功,增强操作(实体链接、历史记录)允许失败降级。

Phase 7: 保存消息并返回

操作
存储位置
用途
db.save_messages()
SQLite history 表
支持未来 replay / 历史回溯
返回结果
内存
包含 memory_id, event=ADD

Read(搜索记忆)

search() 方法采用 混合搜索策略,结合多种排序信号:

步骤
操作
输入/参数
输出/作用
Step 1
预处理查询
原始查询文本
词形还原文本 + 提取实体列表
Step 2
嵌入查询
原始查询
查询向量
Step 2.5
Metadata Filter 预处理
filters
 字典
检测高级操作符并转换为向量存储兼容格式
Step 3
语义搜索
查询向量
超取 4x 的记忆候选池(≥60条)
Step 4
关键词搜索(BM25)
词形还原文本
关键词匹配结果
Step 5
BM25 分数归一化
原始 BM25 分数
归一化到 [0,1] 区间
Step 6
实体增强计算
查询实体列表
记忆ID → 增强分数映射
Step 7
构建候选集
语义搜索结果
统一格式候选列表
Step 8
评分与排序
多路信号融合
Top-K 排序结果
Step 9
格式化结果
内部结果格式
标准 MemoryItem 格式
(可选)
重排序
Top-K 结果
精排后的最终结果

Step 1: 预处理查询

操作
函数
目的
词形还原
lemmatize_for_bm25(query)
提升关键词搜索召回率
实体提取
extract_entities(query)
用于后续的实体增强步骤

Step 2: 嵌入查询

embeddings = self.embedding_model.embed(query, "search")

Step 2.5: Metadata Filter 预处理

当 filters 中包含 AND/OR/NOT 或比较操作符(gte、in、contains 等)时,search() 会先调用 _process_metadata_filters() 将其转换为向量存储兼容的格式:

# mem0/memory/main.py:1202
if self._has_advanced_operators(effective_filters):
    processed_filters = self._process_metadata_filters(effective_filters)
    # 移除原始操作符键,替换为处理后的格式
    for logical_key in ("AND", "OR", "NOT"):
        effective_filters.pop(logical_key, None)
    effective_filters.update(processed_filters)

处理后的格式使用 $or / $not 作为逻辑组合键,支持嵌套条件深度合并。不同向量存储(Qdrant、Faiss、pgvector)在各自的 adapter 中进一步将其翻译为原生查询语法。

Step 3: 语义搜索

设计要点
说明
超取策略
internal_limit = max(limit * 4, 60)
目的
为后续多路融合提供充足候选池
过滤
支持 user_id/agent_id/run_id 作用域过滤

Step 4: 关键词搜索(BM25)

如果向量存储支持(如 Qdrant、LanceDB),执行 BM25 关键词搜索:

keyword_results = self.vector_store.keyword_search(
    query=query_lemmatized, top_k=internal_limit, filters=filters
)

Step 5: BM25 分数归一化

midpoint, steepness = get_bm25_params(query, lemmatized=query_lemmatized)
bm25_scores[mem_id] = normalize_bm25(raw_score, midpoint, steepness)  # → [0,1]

Step 6: 实体增强(Entity Boosts)

这是 Mem0 的特色功能!

子步骤
操作
技术细节
6a
实体向量搜索
阈值 ≥ 0.5,top_k=500
6b
获取关联记忆
从 linked_memory_ids 读取
6c
计算衰减权重
1.0 / (1.0 + 0.001 * ((n-1)²))
6d
生成增强分数
similarity * 0.5 * weight

设计理念:链接记忆越多的实体越通用,增强效果应衰减。

Step 7-8: 评分与排序

scored_results = score_and_rank(
    semantic_results=candidates,   # 语义相似度
    bm25_scores=bm25_scores,         # 关键词匹配度
    entity_boosts=entity_boosts,     # 实体关联度 [0, 0.5]
    threshold=threshold,
    top_k=limit,
)

评分公式(核心设计):

combined = (semantic + bm25 + entity_boost) / max_possible

其中 max_possible根据可用信号动态计算,确保不同配置(有的向量存储不支持 BM25)的结果分数可比:

可用信号
max_possible
说明
仅语义
1.0
纯向量搜索
语义 + BM25
2.0
混合搜索
语义 + 实体
1.5
无关键词搜索但有实体增强
语义 + BM25 + 实体
2.5
完整三信号融合

Threshold 的守门作用:semantic_score 先与 threshold 比较,低于 threshold 的直接淘汰,即使 BM25 或 entity_boost 再高也不考虑。这避免了语义完全不相关但碰巧命中关键词的噪音项进入 Top-K。

Step 9: 格式化结果

转换为标准 MemoryItem:

  • id, memory, score
  • user_id, agent_id, run_id, actor_id
  • metadata: 其他自定义元数据

可选:重排序(Reranking)

条件
操作
rerank=True
 且配置了 reranker
使用专用模型对 Top-K 精排
失败
降级使用原始结果

Update(更新记忆)

步骤
操作
存储目标
关键细节
1
为新内容生成向量
内存
embed(data, "update")
2
读取现有记忆
向量存储
vector_store.get(memory_id)
3
更新元数据
内存对象
保留 created_at,更新 updated_at;保留 session 标识符
4
覆盖向量存储
向量存储
vector_store.update(vector, payload)
5
记录变更历史
SQLite
db.add_history(..., event="UPDATE")
6
清理旧实体链接
实体存储
_remove_memory_from_entity_store()
7
重建新实体链接
实体存储
_link_entities_for_memory()

update() 的核心是保留不变的元数据(创建时间、session 作用域),同时重建实体关系。


Delete(删除记忆)

步骤
操作
存储目标
关键细节
1
读取现有记忆
向量存储
获取 payload 和 session 标识符
2
从向量存储删除
向量存储
vector_store.delete(memory_id)
3
记录软删除历史
SQLite
db.add_history(..., event="DELETE", is_deleted=1)
4
清理实体存储链接
实体存储
从所有实体中移除 memory_id 引用
5
清理孤立实体
实体存储
无关联记忆的实体自动删除

注意:删除操作采用软删除(记录历史)+ 硬删除(向量存储)的混合策略,便于审计追踪。


异步 API(AsyncMemory)

Mem0 提供完全对等的异步 API AsyncMemory,接口与 Memory 完全一致:

from mem0 import AsyncMemory

memory = AsyncMemory(config=MemoryConfig(...))

# 所有方法均为 async
await memory.add(messages="...", user_id="alice")
results = await memory.search(query="Python", filters={"user_id": "alice"})

内部实现差异:

  • AsyncMemory 复用相同的组件工厂(EmbedderFactory、VectorStoreFactory、LlmFactory)
  • 异步版本同样支持实体存储、reranker、telemetry
  • 适合在 FastAPI / asyncio 应用中避免阻塞事件循环

实体存储:记忆的图结构

Mem0 通过实体存储实现了记忆之间的图关系:

实体结构:

{
  "data": "Python",              # 实体文本
  "entity_type": "technology",   # 实体类型
  "linked_memory_ids": ["m1", "m2"],  # 关联记忆ID
  "user_id": "u123"              # 作用域标识
}

工作原理:

  1. 添加记忆时:提取实体 → 检查是否已存在 → 更新或创建实体 → 链接记忆ID
  2. 搜索时:查询实体 → 获取关联记忆 → 应用增强分数
  3. 更新/删除时:清理旧链接 → 重建/移除链接

这种设计使得搜索能够利用实体关系发现相关记忆,即使语义相似度不高。


中文适配注意事项

Mem0 的 LLM 记忆提取提示词已有中文版本(ADDITIVE_EXTRACTION_PROMPT_ZH),因此 Phase 2(LLM 抽取) 在中文对话下通常表现良好。但系统的 实体抽取(Entity Extraction) 模块默认完全面向英文设计,直接用于中文场景会产生严重退化:

问题根源

实体抽取由 mem0/utils/entity_extraction.py 实现,底层硬编码依赖 spaCy 英文模型 en_core_web_sm(mem0/utils/spacy_models.py):

  • 分词与 POS 标注:en_core_web_sm 对中文不具备分词和词性标注能力,中文文本会被错误切分为无意义的字符片段。
  • 大写检测规则:PROPER 类型实体通过 token.text[0].isupper() 判断,中文无大小写,导致所有中文专有名词(人名、地名、机构名)无法被识别。
  • 硬编码英文停用词表:_GENERIC_HEADS、_NON_SPECIFIC_ADJ、_GENERIC_ENDINGS、_GENERIC_CAPS 等集合全部是英文单词,对中文内容完全不起过滤作用。
  • 依赖英文语法结构:名词复合体(noun_chunks)和依赖关系(compound、amod 等)的解析逻辑基于英文句法,中文的修饰关系和短语边界会被错误分析。

对中文使用者的影响

影响环节
具体表现
Phase 6(实体链接)
中文记忆几乎提取不到有效实体,知识图谱关联网络为空或极稀疏
Read(搜索增强)Step 6: Entity Boosts
 失效,搜索时无法利用实体关系发现相关记忆
BM25 关键词搜索lemmatize_for_bm25
 使用英文词形还原,中文关键词匹配质量下降

缓解方案

  1. 自行替换 spaCy 模型:将 mem0/utils/spacy_models.py 中的 en_core_web_sm 替换为 spaCy 中文模型(如 zh_core_web_sm),并同步修改 entity_extraction.py 中的停用词表和大小写检测逻辑。
  2. 降级使用:若暂时不想改动源码,可确保不安装 spaCy / 不下载英文模型,此时 extract_entities() 会返回空列表,系统退化为纯向量语义搜索,虽失去实体增强但仍可正常工作。
  3. LLM 驱动替代:在 extract_entities() 中接入 LLM-based NER,取代 spaCy 规则抽取,准确率更高但 latency 和成本增加。

结论:Mem0 的中文记忆存储和检索可用,但实体图关系功能在默认配置下对中文基本不可用。生产级中文部署必须对实体抽取模块做本土化改造。


过滤器与作用域隔离

Mem0 的过滤器不仅是查询条件,更是作用域隔离机制的核心。

必需的实体标识符

所有查询必须包含至少一个实体标识符,用于隔离不同用户/代理/会话的记忆:

# 单一作用域
filters={"user_id": "alice"}                    # 用户级别
filters={"agent_id": "agent-123"}               # 代理级别
filters={"run_id": "session-456"}               # 会话级别

# 组合作用域(交集)
filters={"user_id": "alice", "agent_id": "agent-123"}  # alice 使用该代理的记忆

设计原因:防止记忆跨用户/代理泄露,确保多租户隔离。

自定义元数据过滤

在添加记忆时可以附加自定义 metadata,搜索时通过过滤器筛选:

# 添加时附加 metadata
memory.add(
    messages="我需要明天完成项目报告",
    user_id="alice",
    metadata={"category": "work", "priority": "high", "tags": ["urgent"]}
)

# 搜索时使用元数据过滤
memory.search(
    query="项目",
    filters={
        "user_id": "alice",           # 必需:作用域
        "category": "work",           # 可选:精确匹配
        "priority": {"gte": 3}        # 可选:比较操作(gte, gt, lte, lt, eq)
    }
)

过滤器在搜索流程中的作用

在 search() 的 Step 3(语义搜索)和 Step 4(关键词搜索)中,过滤器直接传递给向量存储:

# mem0/memory/main.py:709
existing_results = self.vector_store.search(
    query=parsed_messages,
    vectors=query_embedding,
    top_k=10,
    filters=search_filters,  # 只包含 user_id/agent_id/run_id
)

注意:实体存储(Entity Store)的操作也使用相同的过滤器,确保实体与记忆的作用域一致。


未来展望

结合 Mem0 官方 2026 年关于 token-efficient memory algorithm 的公开研究,以及 LongMemEval、A-Mem、TiMem 和 Elastic 关于混合检索融合的最新材料,可以看到 Mem0 当前路线已经覆盖了“单次抽取 + 多信号检索”的核心框架,但后续仍有几条非常明确的演进方向。

1. 时间应从文本细节升级为检索信号

LongMemEval 将 temporal reasoning 和 knowledge updates 作为长期记忆系统的核心难点;TiMem 也进一步强调,长期对话中的关键问题不只是“记住发生过什么”,而是“记住它们在时间上如何组织”。这意味着 Mem0 后续若要继续提升,不应只把时间写进记忆文本,还应逐步把时间变成可计算的结构化字段,例如区分事件发生时间与记忆写入时间,并在“最近一次”“当前状态”这类查询中显式参与排序或过滤。

2. 记忆组织会从平铺存储走向跨会话归并

Mem0 官方研究在 “What we're building next” 中明确提到 Temporal abstraction 与 Cross-session structure;A-Mem 和 TiMem 也都说明,长期记忆系统如果只有不断追加的扁平条目,最终会面临冗余增长、版本冲突和检索噪声上升的问题。对应到 Mem0,这意味着未来比较自然的方向是:在线写入仍保持轻量和 additive,但在离线阶段逐步做跨会话归并、事件聚合和高层摘要,把“原始观察”“阶段性事实”“稳定 persona”分层组织起来。

3. 检索融合会继续从“可用”走向“更稳健”

Mem0 目前的强项之一是语义、关键词、实体三路融合,这和其 2026 公开研究中的 multi-signal retrieval 方向是一致的。再往前走,值得关注的是 Elastic 在 2025 年持续推进的 Weighted RRF:它的优势不是绝对替代线性加权,而是在多路召回分数分布不稳定时,往往更容易调参与扩展。对 Mem0 而言,这意味着未来可以把当前融合公式保留为默认实现,同时引入基于 rank 的 RRF / Weighted RRF 作为可切换策略,尤其适合后续再接入时间信号或更多检索通道时做 A/…

— 以上为试看内容(约 40%),开通会员后阅读全文 —