Mem0 Memory Pipeline 源码深潜：ADD-only 提取、混合检索与多存储一致性

0.1 最关键的版本纠正：V3 是 ADD-only#

代码库中仍能找到旧的 DEFAULT_UPDATE_MEMORY_PROMPT，它让 LLM 输出 ADD / UPDATE / DELETE / NONE。[M4]

但固定版本的 V3 主写路径 _add_to_vector_store(..., infer=True) 使用的是：

1
ADDITIVE_EXTRACTION_PROMPT
2
→ only ADD
3
→ Prompt requests optional links
4
→ this commit does not persist those links

官方迁移文档也明确说明：V3 从“两次 LLM 调用 + 写时合并”转为“一次 ADD-only 提取”，历史 Memory 不在 Extraction 阶段被覆盖或删除。[M2]

这不代表系统没有 Update/Delete：显式 API 仍提供 update() 与 delete()。准确说法是：

自动推断写路径改为 ADD-only；显式管理 API 仍能 Update/Delete。

0.2 本文要回答的十二个问题#

1. 为什么 user_id / agent_id / run_id 是隔离约束，不是普通 Metadata？
2. infer=False 与 infer=True 的数据语义有何区别？
3. 为什么 V3 在 Extraction 前先取最近消息与 Existing Memory？
4. 为什么源码构造了 UUID → Integer 映射，却没有把它接回持久化路径？
5. ADD-only 如何表达偏好变化与历史关系？
6. Provider Failure 与“没有可提取 Memory”如何区分？
7. Batch Embedding 和单条 Fallback 会制造什么部分成功窗口？
8. Hash、BM25、Vector 与 Entity 分别解决什么问题？
9. 为什么 Keyword Search 不扩大当前实现的 Candidate Pool？
10. Vector、History、Entity 三套存储如何发生不一致？
11. Expiration 与 Delete 的语义为什么不同？
12. Benchmark 分数如何在相同 Token、TopK 和模型约束下解释？

1.1 Scope 是 Authorization Predicate#

1
Memory Identity
2
= content
3
+ user_id
4
+ agent_id
5
+ run_id
6
+ actor / role
7
+ timestamps
8
+ expiration

如果写入带 user_id=alice，搜索却只做全局 Vector TopK，再在应用层过滤，Alice 的候选内容已经进入错误租户的检索与日志路径。

所以 Scope 应尽量下推到 Store：

1
Query
2
→ build authorized filters
3
→ vector / keyword / entity retrieval under same scope
4
→ rank

1.2 三种 ID 不是互斥的“任选标签”#

固定版本还用 Metadata 判断是否采用 Agent Memory Extraction：同时存在 agent_id 且消息中包含 Assistant Role 时，才进入 Agent-oriented Extraction。[M5]

1.3 attributed_to 与 role#

V3 Prompt 要求每条提取结果带 attributed_to=user|assistant。Raw Path 则把原始 Role 和可选 Actor Name 写入 Payload。[M4][M6]

这两个字段解决不同问题：

1
role
2
→ transport-level message role
3

4
attributed_to
5
→ extracted fact is about / originates from whom

“Assistant 建议用户迁移到 Postgres”不应被错误抽取成“用户偏好 Postgres”。

2.1 Raw Path 的契约#

它适合：

• 已由上游完成结构化提取；
• 法规要求保留原始事件；
• 测试需要绕过 LLM 不确定性；
• 业务自己拥有 Write Policy。

它不自动提供：

• 事实压缩；
• 语义去重；
• 冲突判断；
• 重要性筛选；
• 跨消息归因修正。

所以 infer=False 不是“更低质量模式”，而是：

调用方接管 Semantic ETL，Mem0 只负责持久化与检索基础设施。

2.2 System Message 为什么跳过#

Raw Path 明确跳过 role=system。这是合理的默认边界：System Prompt 通常是应用 Policy，不应被当成用户长期事实写回 Memory。

如果需要持久化 Agent Policy，应进入配置、版本控制或专用 Policy Store，而不是让它和观察到的 Memory 共享召回路径。

3.1 Phase 0：最近消息为 Extraction 提供局部连续性#

1
session_scope = user / agent / run filters
2
last_messages = db.get_last_messages(scope, limit=10)
3
parsed_messages = parse_messages(current_input)

仅看当前消息会把：

1
“是的，就按上次那个方案”

错误提取成缺少指代对象的 Memory。最近消息不是为了把 Full History 全塞给模型，而是给 Extraction 一个受控窗口。

3.2 Phase 1：Read-before-Write#

系统用当前 Parsed Messages 做 Query，在相同 Scope 下搜索 Top 10 Existing Memories。[M6]

Read-before-Write 在 V3 中不再用于决定原地 Update/Delete。按 Extraction Prompt 的设计，它承担两件事：

• 让模型跳过与 Existing Memory 语义等价的新输出；
• 让新事实通过 linked_memory_ids 指向相关旧事实。

但固定版本只完整兑现了第一件事：Existing Memories 确实进入 Prompt，模型可以据此不输出重复事实；linked_memory_ids 却没有进入后续 Record Metadata。因而“保留偏好变化的历史链”在这个 Commit 中仍是 Prompt 意图，不是已落盘的数据结构保证。[M4][M6]

3.3 UUID → Integer：正确的接口思想，未闭合的实现#

Vector Store 返回 UUID，但 Prompt 中映射为：

1
0 → 9d1f...
2
1 → 3c82...
3
2 → a06b...

这种短句柄本来可以降低模型抄写高熵 UUID 的错误率。但固定版本存在明确的实现断点：

1
uuid_mapping[str(idx)] = mem.id
2
existing_memories.append({"id": str(idx), "text": ...})
3

4
# 后续持久化只消费这两个模型字段
5
text = mem.get("text")
6
attributed_to = mem.get("attributed_to")

uuid_mapping 在同步和异步 V3 路径中都没有再次被读取；模型输出的 linked_memory_ids 也没有写入 Vector Payload、History 或独立关系存储。[M6]

所以这个 Commit 的准确结论不是“Runtime 再映射回真实 UUID”，而是：Runtime 为短 ID 映射做了准备，但关联字段尚未接入持久化路径。 这是源码审计必须区分“Prompt Schema”“局部变量”和“最终可观察状态”的典型案例。

这是通用的 Tool Interface 原则：

不要让模型复制高熵内部标识符；给它一个受限、短小、可验证的句柄。

3.4 Phase 2：Single-pass ADD-only Extraction#

V3 Prompt 强调：

• 只输出值得记忆的自包含事实；
• 每条输出只执行 ADD；
• Prompt 要求可链接 Existing Memory，但固定版本不会持久化该关联；
• 必须标注 attributed_to；
• 新输出使用顺序 ID；Existing Memory 在 Prompt 中同样显示为短 Integer ID，尽管 Prompt 文案仍称其为 UUID。[M4][M6]

这把 Write-time Conflict Resolution 推迟到 Retrieval：新旧事实共同存在，由时间、关系和排序决定当前查询看到什么。

3.5 ADD-only 的收益与成本#

收益：

• 不在一次 LLM 判断中破坏历史；
• 避免错误 DELETE 导致不可恢复的 Recall Ceiling；
• 偏好变化可以保留演进轨迹；
• 单次 LLM 调用降低 Extraction Latency。

成本：

• Memory 数量持续增长；
• Retrieval 必须处理近重复和冲突；
• Expiration / Cleanup 变得重要；
• 如果 Temporal Metadata 不足，“保留历史”可能退化成“召回矛盾”。

4.1 三类结果#

1
SUCCESS_WITH_MEMORIES
2
→ extracted list non-empty
3

4
SUCCESS_NO_MEMORY
5
→ valid response, no memorable fact
6

7
FAILED_PROVIDER / FAILED_PARSE
8
→ extraction did not complete reliably

如果把后两者都编码为 []：

• Retry Policy 无法判断；
• SLA 把失败算成正常空结果；
• Memory Write Recall 会被悄悄拉低；
• 上游无法切换 Provider。

4.2 Parse Failure 当前仍有降级风险#

固定版本会先去 Code Fence、直接 JSON Parse，再尝试提取 JSON；最终 Parse Exception 会记录日志并把结果置空。[M6]

这意味着 Provider Exception 与部分 Parse Error 的外部语义并不完全一致。生产化建议：

1
provider_error
2
schema_error
3
empty_valid_result

分别计数，并将 Schema Error 纳入有限重试或 Dead-letter Queue。

4.3 即使无 Memory 也保存 Message#

当没有提取结果时，当前 Messages 仍写入 Session DB。这样未来 Extraction 的 Last-k Context 不会因为本轮无长期事实而断裂。[M6]

这是一个很好的职责拆分：

1
Conversation continuity
2
≠
3
Long-term memory creation

5.1 Batch First，Individual Fallback#

全部提取文本先调用 embed_batch。失败后逐条调用 embed；单条失败只记录 Warning，该条不会进入后续 Record。[M6]

1
N memories
2
→ 1 batch request
3
→ on failure, up to N individual requests

收益是正常路径减少网络往返；代价是 Fallback 可能造成长尾延迟和部分 Memory 丢失。

5.2 Exact Hash Dedup#

每条 Text 计算 MD5：

1
hash(text)

并同时对：

• Existing Results 中已有 Hash；
• 当前 Batch 已见 Hash；

做去重。[M6]

它解决的是 Exact Duplicate，不解决：

1
User lives in Beijing
2
用户目前住在北京

这类 Semantic Duplicate。

Hash 还不是安全完整性证明：MD5 在这里承担快速内容键，而不是抗攻击签名。

5.3 text_lemmatized#

写入时生成 Lemmatized Text，为 Keyword / BM25 Retrieval 提供稳定投影。[M6]

一个 Record 因而至少有：

1
data
2
embedding
3
text_lemmatized
4
hash
5
created_at
6
updated_at
7
scope metadata
8
attributed_to
9
expiration_date?

这是典型的 Canonical Text + Derived Projections 模型。问题在于固定实现把多种投影共同塞入 Vector Store Payload；如果各投影更新不一致，需要 Reconciliation 才能修复。

6.1 可能状态#

1
Vector ✓  History ✓  Entity ✓
2
→ complete
3

4
Vector ✓  History ✗  Entity ✓/✗
5
→ searchable but audit incomplete
6

7
Vector ✓  History ✓  Entity ✗
8
→ searchable but entity boost incomplete
9

10
Vector partial
11
→ only subset of extracted memories visible

6.2 为什么 Fallback 不等于事务#

Fallback 提高 Availability：批接口不支持或偶发失败时，单条仍可能成功。

但它没有提供：

• All-or-nothing；
• 已成功项 Rollback；
• 全局 Commit Marker；
• Exactly-once History；
• Entity Projection 与 Vector Version 对齐。

6.3 Production Reliability Envelope#

更稳妥的设计：

1
Canonical Memory DB transaction
2
→ write records + outbox
3
→ asynchronous projectors
4
   ├── vector index
5
   ├── BM25 index
6
   ├── entity index
7
   └── history / audit
8
→ projector checkpoint
9
→ reconciliation scans

Vector / Keyword / Entity 都应被视为可重建 Projection，而不是彼此独立的真相源。

7.1 Entity Store 表达什么#

它不是完整 Temporal Knowledge Graph，更接近：

1
Entity Node
2
→ set of linked memory IDs

它能帮助：

• Proper Noun；
• 产品名、人名、地点；
• 同一 Entity 相关 Memory 聚合；
• Query Entity 对相关 Memory 提升排序。

它不能天然表达：

• 关系有效时间；
• 事实边的 Provenance；
• 多跳逻辑约束；
• 互相矛盾的状态区间。

7.2 High-degree Entity 降权#

查询 Entity 命中后，Boost 会结合相似度与 Linked Memory 数量。源码对链接很多的 Entity 施加衰减，避免“高频超级节点”把大量 Memory 全部抬高。[M7]

这类似图检索中的 Hub Penalty：

1
boost = similarity × weight × degree_penalty

8.1 Over-fetch#

内部候选数：

1
internal_limit = max(limit * 4, 60)

最终 TopK=10 时仍取至少 60 个 Semantic Candidates，给 BM25 与 Entity Signal 留出重排空间。

8.2 一个非常重要的实现细节#

Keyword Search 会生成 memory_id → normalized_bm25_score，但 Candidate List 仍由 Semantic Results 构建。[M7]

所以当前路径更准确是：

1
Semantic retrieval defines candidate recall
2
BM25 and Entity enrich candidate ranking

而不是严格意义上的：

1
Vector candidates ∪ Keyword candidates

这意味着一个 Vector 完全漏掉、但 Keyword 精确命中的 Memory，可能没有机会进入最终排名。

8.3 真正的 Hybrid Candidate Fusion#

生产化可改为：

1
semantic_candidates
2
∪ keyword_candidates
3
∪ entity_linked_candidates
4
→ dedup by memory_id
5
→ feature enrichment
6
→ rank / rerank

并分别记录：

1
candidate_source = vector|keyword|entity
2
raw_rank
3
raw_score
4
normalized_score
5
final_score

8.4 Explainability#

固定版本支持 explain，将 score_details 放入结果。这是调优 Multi-signal Retrieval 的基础：没有每个 Signal 的贡献，只能看到一个无法行动的 Final Score。

9.1 Expiration 是 Read-time Visibility#

expiration_date 被规范化后写入 Payload。Search / Get All 默认隐藏 Expired Memory，除非 show_expired=True。[M5][M7]

1
Expired
2
≠ physically deleted

这适合：

• 临时旅行计划；
• 有效期内优惠；
• 短期项目偏好；
• 待过期授权状态。

但如果合规要求删除，Read-time Hide 不足以证明 Vector、History、Entity 和 Backup 都不可恢复。

9.2 显式 Update#

_update_memory() 会：[M8]

1. 读取 Existing Record；
2. 保留 created_at；
3. 更新 updated_at、Hash、Lemmatized Text 与 Embedding；
4. actor_id 创建后保持不可变；
5. 写 Vector Store；
6. 追加 UPDATE History；
7. Text 变化时清理旧 Entity Links，再链接新 Text Entity。

Vector Update 成功、History 或 Entity Cleanup 失败时仍有投影不一致风险。

9.3 显式 Delete#

_delete_memory() 的顺序是：[M8]

1
get existing
2
→ vector delete
3
→ append DELETE history
4
→ remove memory id from entity records (non-fatal)

这不是跨存储原子删除。需要 Tombstone / Reconciliation 才能向用户证明所有读路径已不可见。

9.4 Procedural Memory#

当 memory_type=procedural_memory 且存在 agent_id，系统调用 LLM 把对话整理成 Procedure，再走普通 Create Path。[M8]

它保存的是：

1
Goal
2
→ ordered actions
3
→ tool use
4
→ observations
5
→ outcome / lesson

Procedure 如果没有版本、适用条件和失败边界，很容易把一次偶然成功固化成错误 SOP。生产系统应附加：

1
environment fingerprint
2
source run ids
3
success evidence
4
last validated at
5
applicability constraints

10.1 诊断事件#

1
{
2
  "query_id": "...",
3
  "memory_id": "...",
4
  "scope_match": true,
5
  "candidate_sources": ["vector", "keyword"],
6
  "semantic_rank": 17,
7
  "bm25_score": 0.74,
8
  "entity_boost": 0.18,
9
  "final_rank": 4,
10
  "packed": true,
11
  "used_by_answer": true
12
}

10.2 Candidate Recall 与 Ranking Quality 分开#

如果 Gold Memory 不在 Candidate Pool，调 Reranker 没用；如果它在 Pool 但排第 80，才是 Ranking Problem。

1
Candidate Recall@N
2
MRR / NDCG@K
3
Context Precision@K
4
Answer Attribution

必须分开计算。

11.1 Token Efficiency#

官方 Evaluation 强调在 LoCoMo、LongMemEval、BEAM 上同时观察 Accuracy、Context Token 和 Latency，并指出小 Benchmark 可以通过大 Context 与 Frontier Model 被激进检索“做高”。[M3]

这是正确的工程方向：

$Utility = f(accuracy, token\ cost, latency, harm)$

只比较 Accuracy 会鼓励把 TopK 拉到 200、把大量近重复 Memory 塞进 Context。

11.2 Equal Constraints#

公平比较至少要求：

• 相同 Answer Model；
• 相同 Judge；
• 相同 Retrieval Budget；
• 相同 Context Token 上限；
• 相同时间切分；
• 相同是否允许 Full History；
• 相同是否使用 Reranker。

12.1 Scope Bypass#

所有 Vector、Keyword、Entity、History 操作必须共享同一 Scope。任何一个 Projection 忘记 Filter 都可能形成跨租户泄漏。

12.2 Memory Poisoning#

V3 会把 User 与 Assistant 内容提取为持久事实。外部网页中的 Prompt Injection 如果被 Assistant 复述，可能被错误标记为 Assistant Memory。

Write Path 应保留：

1
source_message_ids
2
source_role
3
source_trust
4
extractor_model
5
extractor_version
6
extraction_prompt_hash

12.3 Sensitive Metadata#

固定版本有 Sensitive Field 识别与 Config Safe Copy，但这不等于完整 DLP。[M5] 生产系统仍需要：

• PII Classification；
• Secret Redaction；
• Tenant-specific Encryption Key；
• Retention / Legal Hold；
• Derived Index Delete Verification；
• Access Audit。

13.1 Canonical Store#

1
MemoryRecord
2
├── id / version
3
├── scope
4
├── canonical text
5
├── provenance
6
├── valid / expiration time
7
├── status
8
└── tombstone

13.2 Outbox + Projectors#

1
Canonical transaction
2
→ Outbox
3
→ Vector Projector
4
→ Keyword Projector
5
→ Entity Projector
6
→ History / Audit Projector

每个 Projector 维护 Watermark，失败可重放；读结果带 memory_id + version，Context Builder 注入前回查 Canonical Status。

13.3 Reconciliation#

周期检查：

1
canonical ids - vector ids
2
vector ids - canonical ids
3
history latest version vs canonical version
4
entity linked ids not found
5
expired / deleted ids still searchable

13.4 Idempotency#

API 应接受：

1
event_id
2
extraction_job_id
3
mutation_id

Exact Text Hash 不能替代请求幂等键，因为同一事实可能合法地在不同 Scope 或时间重复出现。

14.1 优势#

• Scope、Extraction、Embedding、History、Entity 与 Retrieval 集成完整；
• Raw 与 Inferred Write Path 清晰分离；
• V3 单次 ADD-only Extraction 降低写时破坏与 LLM Latency；
• Batch-first / Item-fallback 提高 Provider 兼容性；
• Hash、Lexical 与 Entity 提供多信号；
• Expiration、Explicit Update/Delete、Procedural Memory 覆盖常用生命周期；
• Explain Score 为检索调优提供基础。

14.2 边界#

• 自动提取质量依赖 LLM；
• ADD-only 会持续增长 Memory 数量；
• Keyword 当前主要重排 Semantic Candidates，Candidate Recall 仍受 Vector 限制；
• 多 Store 顺序写入存在部分成功；
• Hash 只做 Exact Dedup；
• Entity Link 不是完整 Temporal Graph；
• Expiration Hide 不等于可验证删除；
• 论文与产品 Benchmark 必须在同等约束下解释。

14.3 最准确的架构定义#

Mem0 不是：

1
LLM + Vector DB

而是：

1
Scoped Semantic Extraction Pipeline
2
+ ADD-only Historical Accumulation
3
+ Batch Embedding / Persistence
4
+ Hash + Lexical + Entity Projections
5
+ Multi-signal Ranking
6
+ Mutation History
7
+ Expiration and Explicit Lifecycle APIs

它最值得学习的结论是：

Memory 的工业化关键不在某一种存储，而在把 Extraction、Scope、Projection、检索信号、错误语义和维护任务做成可观测的数据管线。

[M1] Mem0 OSS 固定版本#

• Repository：mem0ai/mem0 @ ccbe586
• 核心实现：mem0/memory/main.py

[M2] V3 Migration#

• Platform: Migrating to the New Memory Algorithm
• Markdown 原文
• 核对内容：Single-pass ADD-only、Built-in Entity Graph、Hybrid Retrieval、API 变化、Latency 与迁移边界。

[M3] Memory Evaluation#

• Memory Evaluation
• Markdown 原文
• Open Evaluation Repository
• 核对内容：LoCoMo、LongMemEval、BEAM、Top-200 Budget、Context Token、Judge 不确定性与 Equal Constraints。

[M4] Extraction Prompts#

• prompts.py
• 核对内容：Legacy Update Prompt、ADDITIVE_EXTRACTION_PROMPT、attributed_to、Existing Link 与 Prompt Builder。

[M5] Scope 与 Public Add Contract#

• _build_filters_and_metadata
• Memory.add

[M6] V3 Write Pipeline#

• _add_to_vector_store
• 核对内容：Raw Path、Context Gathering、Existing Retrieval、ID Mapping、Error Semantics、Batch Embed、Hash、Vector / History / Entity Persist。

[M7] Hybrid Search 与 Entity Boost#

• _search_vector_store
• _compute_entity_boosts

[M8] Explicit Lifecycle APIs#

• _create_memory
• _create_procedural_memory
• _update_memory
• _delete_memory

[M9] Mem0 Paper#

• Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory
• 核对内容：系统动机、Evaluation 设计与早期算法背景；当前 V3 产品实现以最新官方文档和固定源码为准。

[M10] OWASP Agent Memory Security#

• OWASP Agent Memory Guard

上一篇：Hermes Memory 源码深潜 · 下一篇：Letta / MemGPT Memory 深潜