第 0 篇：「Mem0 深度分析与文档系列计划」------ 记忆层基础设施的源码级解读路线图
系列定位 ：对 mem0ai/mem0（GitHub 64.8k stars）开源记忆层框架做源码级深度解读。
代码版本 ：
main分支，最近推送 2026-09-04，Python 包版本mem0ai 2.0.20（pyproject.toml:7）。用户口语中的"master 分支"在 GitHub 上不存在 ------ 该仓库默认分支为main（已通过 GitHub API 确认default_branch=main），本系列所有file:line引用均基于此版本。官方文档 ：docs.mem0.ai，sitemap 共 241 页；本系列篇目以官方文档
core-concepts（7 页）与open-source（13 页）二级章节为骨架，cookbooks（28 篇）作为应用篇素材。篇目来源声明：doc_url 二级章节。阅读本文你将了解： Mem0 在 AI Agent 技术栈中的位置、v3 架构相对 v1 的核心变化（两段式 LLM 决策 → 单次调用 ADD-only 批量管线）、官方文档与源码的对照地图、全系列 9+2 篇的阅读路线。
一、Mem0 是什么：一句话与一张图
Mem0 自我定位是 "The Memory Layer for AI Agents"（README.md / GitHub 仓库描述）。大白话：LLM 会话结束后什么都不会留下，Mem0 在 LLM 和应用之间插了一层------把对话中值得记住的事实提取、去重、存储 到向量库，下次对话时检索出来注入上下文，让 Agent 拥有跨会话的"长期记忆"。
用户消息 ──► 应用层 ──► m.add(messages, user_id="alice") 【写入：提取事实】
│
▼
┌─────────────────────┐
│ LLM 提取（单次调用） │ ADDITIVE_EXTRACTION_PROMPT
│ spaCy 实体抽取 │ mem0/configs/prompts.py:468
│ MD5 去重 │ mem0/utils/entity_extraction.py
└─────────────────────┘
│ │
▼ ▼
向量库(记忆) 向量库(实体) SQLite(历史+消息)
vector_store entity_store SQLiteManager
(三处初始化入口：mem0/memory/main.py 第 496 / 559 / 500 行)
用户提问 ──► m.search("...", filters={"user_id":"alice"}) 【读取：混合检索】
│
▼
语义召回(4x过采样) + BM25 关键词 + 实体链接加分
mem0/memory/main.py:1628 + mem0/utils/scoring.py
│
▼
记忆注入 prompt ──► LLM 回答这张图是全系列的导航图：写入走 add() 八阶段管线（02-03 篇），读取走 search() 三路混合评分（04 篇），存储横跨三套介质（05-06 篇），对外可经 FastAPI 服务化（07 篇）。
二、为什么值得源码级精读：v3 的三个关键转向
关键源码事实：
-
提取策略从"两段式 LLM 决策"转为"单次调用 ADD-only" 。v1 时代（社区广泛引用的旧架构图）
add()要调两次 LLM：先提取事实，再对每条新事实与旧记忆做 ADD/UPDATE/DELETE 决策（旧DEFAULT_UPDATE_MEMORY_PROMPT，mem0/configs/prompts.py:176，现已不再被主管线调用------仅mem0/memory/utils.py:33的get_fact_retrieval_messages保留FACT_RETRIEVAL_PROMPT兼容路径）。v3 改为一次 LLM 调用完成提取（mem0/memory/main.py:940-969），冲突消解下放到读取端与实体链接端。这是成本与延迟上的结构性优化，也是理解新代码的钥匙。 -
图记忆（GraphMemory）被实体库（entity store）取代 。v1 的
mem0/memory/graph_memory.py在 main 分支已不存在；取而代之的是惰性初始化的entity_store（mem0/memory/main.py:559-580）------同一个向量库厂商、独立 collection，存实体及linked_memory_ids关联，检索时按相似度给关联记忆加分（mem0/memory/main.py:1733-1813）。图查询变成了"向量化的实体邻接表"。 -
检索从纯语义升级为三信号加法评分 。
_search_vector_store（mem0/memory/main.py:1628）9 步流水线：语义过采样max(limit*4, 60)+ BM25 关键词 + 实体 boost，score_and_rank（mem0/utils/scoring.py:57）做自适应分母的加法归一。不支持 keyword_search 的向量库会在初始化时收到降级警告（mem0/memory/main.py:543-550）。
另有一个工程细节值得注意：LLM 提取失败从 v1 的静默返回空列表改为显式抛出 LLMError（mem0/memory/main.py:963-969），注释原文说明了理由------"LLM 不可用"与"没提取到事实"不应共享同一个空列表。
三、内核地图：目录结构与三层封装
仓库核心 Python 包（本系列主战场，151 个 .py 文件）：
| 目录 | 职责 | 关键文件 |
|---|---|---|
mem0/memory/ |
记忆内核：add/search/CRUD 管线 | main.py(3868 行)、storage.py(SQLite)、base.py、utils.py |
mem0/configs/ |
配置与提示词 | base.py(MemoryConfig)、prompts.py(1062 行提示词) |
mem0/llms/ |
19 家 LLM 适配 | factory 经 mem0/utils/factory.py:44 注册表 |
mem0/embeddings/ |
15 家嵌入模型适配 | 同上 |
mem0/vector_stores/ |
26 家向量库适配 | mem0/vector_stores/qdrant.py:454 的 keyword_search 是混合检索关键 |
mem0/reranker/ |
5 种重排序器 | cohere / huggingface / llm / sentence_transformer / zero_entropy |
mem0/utils/ |
实体抽取、评分、工厂 | entity_extraction.py(spaCy)、scoring.py、factory.py |
mem0/client/ |
Platform 托管版客户端 | main.py --- MemoryClient 走 REST API |
server/ |
自托管 FastAPI 服务 | main.py(560 行) + routers/(auth/api_keys/entities) |
mem0-ts/ |
TypeScript SDK（另 243 文件） | 本系列仅对照，不展开 |
三层封装设计：配置层 （MemoryConfig，mem0/configs/base.py:28-62，pydantic，默认 version="v1.1"）→ 工厂层 （LlmFactory.create 等按 provider 字符串 + 注册表反射创建，mem0/utils/factory.py:64）→ 内核层 （Memory/AsyncMemory，mem0/memory/main.py:487/2172）。所有外部依赖（LLM、嵌入、向量库）都通过工厂可替换，这正是"drop-in memory infrastructure"的工程含义。
四、环境与版本基线
- 语言/依赖：Python ≥3.10（
pyproject.toml:9），核心依赖 qdrant-client / pydantic / openai / httpx - 默认历史库路径：
~/.mem0/history.db，可用MEM0_DIR环境变量重定向（mem0/configs/base.py:7-8） - 复现引用：
git clone https://github.com/mem0ai/mem0（main 分支，2026-09-04 快照）；本系列源码镜像存于 Vaultassets/raw-src/mem0/ - 快速验证：
m = Memory()需OPENAI_API_KEY（默认 provider 是 openai）；自定义 provider 见 01 篇配置解析
五、系列篇目与三列索引（文档概念 ↔ 源码位置 ↔ 篇目）
| 官方文档章节 | 核心源码入口 | 篇目 |
|---|---|---|
| open-source/overview + configuration | mem0/memory/main.py:488，mem0/configs/base.py:28，mem0/utils/factory.py:64 |
01 架构鸟瞰与 Memory 初始化 |
| core-concepts/memory-operations/add | mem0/memory/main.py:879-1206（八阶段管线） |
02 add() 深读：V3 批量提取管线 |
| core-concepts/memory-operations/add（提示词）+ custom-instructions | mem0/configs/prompts.py:468-946 |
03 提取大脑：ADDITIVE_EXTRACTION_PROMPT 解剖 |
| core-concepts/memory-operations/search + reranker-search | mem0/memory/main.py:1379-1813，mem0/utils/scoring.py |
04 search() 深读：三信号混合检索 |
| core-concepts/memory-types + graph 相关 | mem0/utils/entity_extraction.py，mem0/memory/main.py:559-730 |
05 实体库：取代 GraphMemory 的图式记忆 |
| memory-operations/update、delete | mem0/memory/main.py:1815-1960，mem0/memory/storage.py |
06 CRUD 与审计：SQLite 双表设计 |
| open-source/setup + features/rest-api + async-memory | server/main.py，mem0/memory/main.py:2172-3868 |
07 自托管服务化：FastAPI 与 AsyncMemory |
| cookbooks/overview + essentials | 应用层编排（无单点源码） | 08 Cookbook 实战地图 |
| 全系列收束 | --- | 99 收尾总结与设计思想提炼 |
| 源码线（逐文件拆解） | mem0/memory/main.py 全文 |
fp01 main.py 逐段拆解 |
| 源码线（逐文件拆解） | mem0/configs/prompts.py 全文 |
fp02 prompts.py 逐段拆解 |
覆盖率口径：官方文档 core-concepts 全部 7 页 + open-source 全部 13 页映射进 01-07 篇；platform/（托管版专属：v2 filters、Dream、webhooks 等）与 api-reference/（47 页 REST 手册）不属于 OSS 仓库范畴，仅作对照引用；integrations/（36 页）为第三方胶水，不设独立篇目。
六、阅读顺序建议
- 想快速建立心智模型：00 → 01 → 02 → 04，其余按需。
- 想抄管线设计：02（写入）与 04（检索）是本仓库最有含金量的两篇，提示词工程看 03。
- 要自托管部署：01 → 07 → 08。
- 游戏策划视角彩蛋：Mem0 的"提取什么/忘掉什么"本质是 NPC 记忆系统的通用解，99 篇会单独展开这层类比。