junlin https://www.junlin-233.top/ 保持思考 Sun, 19 Apr 2026 06:04:43 GMT https://validator.w3.org/feed/docs/rss2.html https://github.com/jpmonette/feed zh-CN All rights reserved 2026, junlin <![CDATA[agent那些事：一文带你入门agent]]> https://www.junlin-233.top/article/agent-analysis https://www.junlin-233.top/article/agent-analysis Tue, 14 Apr 2026 00:00:00 GMT

agent 那些事

Agent 这两年很热，但很多讨论还停留在“会调用工具的大模型”这个层面。真到工程落地时，问题很快就会变成另一类：到底什么时候该用 Agent，什么时候只需要 Workflow？所谓记忆到底是不是核心能力？多 Agent 是不是天然比单 Agent 更高级？
这篇文章试着从工程实现的角度，结合我自己用oh my opencode/openagent 开发的经历，把这些问题重新梳理一遍。

一、什么时候该用 Agent？

💡
核心原则：越简单越好，避免过度设计。
对于依赖传统规则、结构稳定、输入输出边界清晰的系统，一般不需要引入 Agent，直接使用 Workflow 往往更稳、更省成本，也更容易维护。
Agent 更适合以下场景：
  • 多轮动态决策 — 任务路径无法预先固定，需要根据中间结果灵活调整
  • 多工具 / 多数据源交互 — 需要在多个外部系统之间协调操作
  • 用户意图模糊 — 需要系统先理解、澄清、拆解任务，再决定执行路径
  • 结果带有开放性 — 例如调研、分析、生成方案、制定计划等，本身就不是纯规则问题
Workflow 与 Agent 并不完全对立。很多生产系统的最佳解法，往往是 用 Workflow 承接确定性流程，用 Agent 处理不确定性环节。

二、先判断任务类型，再设计系统

设计 Agent 系统之前，一个很重要但经常被忽略的问题是：当前任务到底是自由探索型，还是可枚举状态转换型（通常有几个稳定状态）？

自由探索型任务

这类任务的特点是：路径事先很难完全写死，中间需要边做边判断下一步。
典型例子：
  • 调研某个技术方向
  • 分析一个产品问题
  • 阅读资料后形成观点
  • 基于模糊目标提出方案
这种任务更依赖模型的理解、归纳、搜索、判断和动态规划能力。

可枚举状态转换型任务

这类任务虽然也可能复杂，但整体流程通常可以拆成若干稳定状态，并且每一步从哪个状态走向哪个状态，大体是清楚的。
典型例子：
  • 工单处理：新建 → 分类 → 分派 → 处理 → 关闭
  • 审批流程：提交 → 校验 → 审核 → 批准 / 驳回
  • 代码交付：生成方案 → 编写代码 → 跑测试 → 修复 → 提交
这种任务更适合用 状态机（State Machine） 或 工作流引擎（Workflow Engine） 去实现，LLM 只需要作为某些节点的能力模块。
🧭
很多看起来像“Agent 架构”的系统，落到工程实现上，本质更接近带大模型节点的状态机。真正决定系统稳定性的，往往不是“有几个 Agent”，而是：状态如何流转、失败如何恢复、人工如何介入、工具结果如何落盘。
因此，设计架构时可以多问几个更现实的问题：
  • 当前任务能不能画成几个比较稳定的状态？
  • 出错后是让模型“继续想”，还是回到某个明确节点重试？
  • 多个模块之间传递的是自然语言，还是结构化状态？
  • 人工审批插在哪一步，审批结果如何写回系统？

三、搭建Agent流程

一般来说，设计一个 Agent 系统可以遵循下面这条主线：
这条线索背后的重点不是“让模型更聪明”，而是把系统里真正影响稳定性的部分都显式设计出来。

四、常见的 Agent 架构模式

在“设计架构”这一步，常见模式有下面几类：
模式
说明
适用场景
单 Agent（ReAct / Tool-use）
一个 Agent 负责理解任务、调用工具、汇总结果
任务相对单一、工具数量可控、链路较短
多 Agent 协作
多个 Agent 分工合作，例如规划、执行、审查分别由不同角色承担
复杂任务需要多角色、多专长或多层校验
层级式（Orchestrator + Workers）
一个编排 Agent 负责任务拆解与调度，Workers 可以是工具、函数，或具备一定自主能力的子 Agent（subagent）
任务可拆解，子任务之间相对独立
Workflow + LLM 节点
整体流程由工作流控制，LLM 只在个别节点负责分类、抽取、生成、判断
流程稳定但局部需要智能决策的业务系统
先把单 Agent + 工具调用 + 状态流转做好，再考虑多 Agent，通常更稳。

五、Prompt 工程

系统指令（System Prompt）仍然是 Agent 行为的重要驱动力，但在生产环境中，重点已经不再只是“怎么写一个更厉害的 Prompt”，而是如何让模型在一个受控框架里工作。
常见关注点包括：
  • 角色设定 — 明确 Agent 的身份、能力边界和行为风格
  • Few-shot 示例 — 提供典型输入输出样例，引导模型理解预期格式
  • 输出格式约束 — 指定 JSON、Markdown 等结构化输出格式
  • 边界条件处理 — 明确当信息不足或遇到异常时的行为（如拒答、追问、降级）
  • 工具使用规则 — 明确哪些工具能用、何时能用、参数格式是什么、调用失败如何处理

什么是推理过程控制？

很多早期做法会强调让模型显式输出长篇 Chain-of-Thought，似乎只要“想得够多”，复杂任务就会更可靠。但工程上更常见的结论是：稳定性更多来自任务拆解、状态管理和工具约束，而不是来自更长的自然语言思维过程。
更推荐的做法通常包括：
  • 任务拆解：把大任务拆成一系列目标明确的小步骤
  • 结构化中间结果：让模型输出机器可读的中间结果，而不是大段随意文本
  • 工具调用约束：限制可调用工具、调用顺序和参数格式
  • 可检查的计划：让计划本身可被系统校验、人工修改、失败恢复
生产环境通常更关注三件事：
  • 结果可验证：不是“看起来像对的”，而是能通过规则、测试或工具结果验证
  • 步骤可回放：系统知道每一步做了什么，便于调试、审计和优化
  • 失败可恢复：某一步出错时，可以回到节点重试，而不是整条链路全部重来

六、记忆与上下文管理：不是记得越多越好，而是拿到对的上下文

很多早期文章会把 Agent 的“记忆”理解为把信息长期存起来，但在当前主流实践中，更重要的往往不是“记住更多”，而是在合适的时机，把合适的信息放进当前上下文。
因此，与其单独强调记忆，不如把这一层理解为：
上下文工程（Context Engineering）+ 状态管理（State Management）+ 检索增强（Retrieval）。
更贴近实际落地的划分通常是：
  • 会话上下文（Session Context） — 当前轮对话、系统指令、最近几步工具调用结果，以及当前任务约束
  • 任务状态（Task State） — 当前任务的显式状态，例如计划、待办、子任务结果、失败记录、审批状态
  • 外部知识（External Knowledge） — 文档、知识库、工单、代码、网页等，通过检索系统按需取回
  • 用户偏好 / 档案（Profile / Preferences） — 少量稳定、结构化、可编辑的长期信息
目前主流 Agent 更常见的是下面几种做法：
  1. 滑动窗口 + 摘要压缩：保留最近关键交互，对更早内容做摘要，但摘要要可回溯，否则容易累积偏差
  1. RAG / 按需检索：把“知道什么”交给检索系统，而不是全部塞进长期记忆
  1. 显式状态存储：把任务进度、中间结果、工具输出、审批节点存到结构化状态中
  1. 事件日志与可观测性：记录每一步决策、工具调用和失败原因，便于调试、审计和恢复
  1. 记忆写入门控：长期记忆不是越多越好，需要去重、打分、时效控制和人工可编辑能力
因此，所谓“长期记忆”在很多生产系统里并不是默认核心能力。真正关键的是：让 Agent 在当前步骤拿到完成任务所需的最小充分上下文，并用结构化状态保证流程稳定。

七、多 Agent，不一定比单 Agent 更高级

多 Agent 是一个很容易被高估的方向。它适合某些复杂场景，但并不天然优于单 Agent。
适合引入多 Agent 的情况通常包括：
  • 任务天然可分治，不同子任务需要不同工具或专业能力
  • 需要明确的“规划—执行—校验”分层
  • 不同角色之间需要相互制衡，例如生成、审查、审批
但多 Agent 也会引入新的成本：
  • 上下文传递成本：如果 Agent 之间主要依赖自然语言传递信息，容易造成信息漂移
  • 状态同步成本：多个 Agent 同时读写共享状态时，更容易出现冲突和重复执行
  • 调试复杂度：问题可能来自提示词、路由逻辑、工具调用、协作协议中的任意一层
所以一个更实用的经验是：能用单 Agent + 明确工作流解决的问题，不必急着拆成多 Agent。
很多“多 Agent 系统”最后稳定运行的关键，并不是 agent 数量，而是共享状态定义清楚、交接协议简单、失败路径可控。

八、安全与护栏

Agent 的风险通常不只来自“说错话”，更来自它能不能访问系统、能不能调用工具、会不会把错误决策放大成真实操作。
因此，安全与护栏至少要覆盖下面几个层面：

1. 输入安全

  • Prompt Injection 防护：防止外部文本诱导模型忽略系统规则
  • 恶意内容识别：识别越权请求、社会工程、敏感数据提取等风险输入
  • 上下文隔离：避免不可信内容与高权限系统指令混在同一层级生效

2. 输出安全

  • 敏感信息过滤：避免输出隐私数据、密钥、内部配置、商业机密
  • 合规检查：对特定业务场景做内容审查，例如金融、医疗、法律等
  • 高风险操作前确认：在给出执行建议和实际执行动作之间加一道确认或审批

3. 工具调用安全

  • 最小权限原则：Agent 只拿到完成任务所需的最低权限
  • 工具白名单：限制可调用工具范围，而不是默认全开
  • 参数校验：对工具调用参数做格式和范围检查
  • 写操作分级：读、写、删除、发布、转账等操作应该有不同等级的保护

4. 执行过程护栏

  • 最大轮次 / 最大预算限制：防止无限循环与成本失控
  • 速率限制与熔断：避免工具风暴、异常重试和外部系统被打爆
  • 人工介入点：在关键节点支持人工审核、驳回或接管
  • 审计日志：记录关键决策、工具调用、参数和结果，满足调试与追责需要

5. 记忆与数据安全

  • 长期记忆可编辑、可删除、可追踪来源
  • 避免把未清洗的原始对话直接长期保存并参与后续决策
  • 区分用户数据、系统数据和检索到的外部数据的信任等级

九、评估与测试

Agent 系统的难点在于，它不是一个只有固定输入输出的函数。你不仅要看最终结果，还要看过程是否稳定、工具调用是否正确、在异常情况下是否还能工作。
因此，评估与测试至少要分成几个层次来看：

1. 能力评测

这部分关注 Agent“会不会做”。
常见方式包括：
  • 基于 Benchmark 的自动评测 — 用标准数据集或内部题集量化分类、抽取、规划、工具使用等能力
  • 任务集评测 — 基于真实业务样本构造评测集，比通用 benchmark 更有价值
  • 人工评审 — 对开放性任务的质量、可用性、表达方式做主观打分

2. 流程正确性测试

这部分关注 Agent“是不是按预期流程工作”。
需要重点看：
  • 是否调用了不该调用的工具
  • 是否遗漏关键步骤
  • 是否在错误节点重复循环
  • 是否正确遵守输出格式与约束
  • 是否在需要审批时停下来
这类测试往往比单纯看最终答案更重要，因为很多系统是“结果偶尔看着还行，但过程完全不可控”。

3. 端到端回归测试

每次修改 Prompt、模型版本、工具定义、上下文拼接逻辑后，都可能引入新问题。
所以需要有一套端到端回归用例，用来验证：
  • 老问题有没有复发
  • 原本能完成的任务有没有退化
  • 工具链路有没有被新的改动破坏
  • 输出格式和系统接口是否仍兼容

4. 异常与对抗测试

很多问题并不会在正常样例里暴露出来，所以还需要专门测：
  • 工具超时 / 返回错误
  • 检索不到结果
  • 用户输入含歧义或恶意注入
  • 上下文过长导致截断
  • 中间状态损坏或部分缺失
一个真正可上线的 Agent，不只是“正常情况能做对”，还要在异常情况下可降级、可恢复、可解释。

5. 线上观测与持续评估

上线之后，测试并没有结束。
还需要持续关注：
  • 成功率、失败率、平均轮次、工具调用次数
  • 成本、耗时、重试次数、人工接管比例
  • 常见失败模式，例如规划错误、检索错误、工具参数错误、状态丢失
  • 用户反馈中的高频抱怨点

十、总结精华

如果把这篇文章压缩成几句最重要的话，大概是这样：
  • 不是所有问题都需要 Agent，很多时候 Workflow 更好
  • 设计之前，先判断任务是自由探索型还是可枚举状态转换型
  • 很多所谓 Agent 系统，本质上是带 LLM 节点的状态机
  • 复杂任务的稳定性，更多来自状态、约束、检索和流程，而不是更长的 Chain-of-Thought
  • 记忆不是越多越好，很多系统真正需要的是把对的信息放进对的上下文
  • 多 Agent 不天然更高级，能不用就别滥用
很多人说AI时代学得慢就可以不用学，对于普通人来说或许是对的，面向他们的AI应用一定是足够简单且不需要复杂的知识和操作。但对于程序员来说，即便不从事agent开发的工作，了解一些基本概念也是必要的，尽管很多东西都像是受限于模型能力而不得不暂时使用的“中间态”。
 
]]> <![CDATA[NotionNext：重新定义写博客这件事]]> https://www.junlin-233.top/article/notionnext https://www.junlin-233.top/article/notionnext Sat, 18 Apr 2026 00:00:00 GMT
💡
如果你厌倦了传统的md文件写博客，想要一种更简便更高效的办法，那么我强烈推荐使用这套NotionNext部署博客，在notion里写的文章无感同步到你的网站，即便不懂代码也能快速上手。
 

什么是 NotionNext

NotionNext 是一个基于 Next.js 的开源 Notion 建站工具，它会把你的 Notion 笔记实时渲染成一个静态博客站点。
核心特点：
  • 写作在 Notion：所有文章都在 Notion 数据库里编辑，发布即同步。
  • 免费开源：源码托管在 GitHub，可自行fork后修改。
  • 无需服务器：通常部署到 Vercel，免费额度足够个人博客使用。
  • 多主题可选：内置数十款主题，覆盖博客、文档、导航站、落地页、相册等场景。
  • SEO 友好：基于 Next.js 服务端渲染，有利于被搜索引擎收录。

搭建博客的大致流程

由于官方的教程文档写的足够详细，所以本文就简要带过。
整体流程可以概括为下面这张图：
简要说明：
  1. 准备账号：Notion、GitHub、Vercel，最好再加一个自己的域名。
  1. 复制模板 + 部署：复制官方 Notion 模板拿到 Page ID，Fork NotionNext 仓库后在 Vercel 里导入，填入 NOTION_PAGE_ID，点 Deploy 即可拿到一个 xxx.vercel.app 的站点。
  1. 配置 + 域名：在 Notion 的 Config 页和代码里的 blog.config.js 改站点名、主题、菜单等；建议在 Vercel 里绑定自己的域名。
  1. 开始写作：在 Notion 文章数据库里新建页面，把 type 设为 Post、status 设为 Published，保存后站点会自动同步。

进阶方向

在过去，折腾博客主题基本是技术爱好者的专利——普通人想在模板上改点东西不仅费时费力，还可能直接把站点改崩。但在 LLM 时代，这些都不是问题。

个性化你的博客

步骤其实很简单：你只需要把fork的项目存到本地，无论用codex桌面版（对无代码基础的同学更友好，强烈推荐），claude code还是opencode，只需告诉AI你的需求（相信我，现在的LLM水平足够创建出你想要的博客），等它工作完再推送到github仓库，就这么简单，唯一比较烧脑的部分是你需要让AI明白你的需求（你在提示词花费的时间绝对物超所值）。

让 AI 帮你写文章

此外如果你像我一样连文章都懒得全部手打了，无论是用notion内置的LLM还是用notion mcp（codex桌面版完美适配）都可以帮助你快速构建文章，当然，核心部分还是需要你打，不然就没有意义了，不是吗？

小结

回过头看，NotionNext 做的事情其实只有一件：把 Notion 变成你博客的后台，把发布、渲染、部署这些脏活累活全部抽象掉。你要做的，只是打开 Notion，写下今天想说的话。
对我来说，它的价值不在于"又多了一个博客系统"，而在于大幅降低了持续写作的门槛：
  • 不用切换编辑器，想到什么随手就能写；
  • 不用操心构建和部署，保存即发布；
  • 配合 AI 工具，连主题魔改和选题灵感都能被加速。
但是工具再顺手，也只是放大器。真正决定这个博客能走多远的，是你愿不愿意持续地写下去。NotionNext 帮你把路铺平了，剩下的那一步，只能靠你自己了。

📎 参考链接

 
]]> <![CDATA[一文讲透 mem0：结合官方文档与核心源码]]> https://www.junlin-233.top/article/mem0-analysis https://www.junlin-233.top/article/mem0-analysis Thu, 16 Apr 2026 00:00:00 GMT
在agent领域，特别是针对agent的应用，memory是不可或缺的一环，有些时候memory带给用户的体验甚至大于llm本身，下面就让我们来了解一下mem0这个项目：

1. 整体架构

分析mem0的源码，可以得出以下架构：
这个分层最重要的理解是：
  • configs/ 负责说明“怎么配”
  • utils/factory.py 负责“按配置造对象”
  • memory/main.py 负责“把对象串成 add/search 的业务流水线”
  • llms/embeddings/vector_stores/reranker 只是被插拔的能力模块

2. 顶层目录怎么理解

notion image

2.1 embeddings/

本质上就是把不同厂商的 embedding 能力统一成一套标准接口。
你可以把它理解成一个“统一插座”——上层不关心底层是 OpenAI、Gemini、HuggingFace 还是 Ollama，只关心有没有 embed()。

2.2 llms/

和 embeddings/ 是同样的思路，只不过负责的是模型推理。
在 mem0 里，LLM 不是可有可无的装饰，它直接参与：
  • fact extraction
  • memory update decision
  • graph relation extraction
所以 llms/ 的地位其实很高。

2.3 vector_stores/

负责统一不同向量库的 CRUD 与 search 接口。对上层来说，Qdrant、PgVector、Chroma、Pinecone 的区别应该被尽量屏蔽。

2.4 reranker/

只负责检索后的精排，不负责写入。
rerank 主要不在 add() 里，而在正式 search() 里。

2.5 utils/

这个目录最容易被低估。
它其实有两类职责：

第一类：装配工

最关键的是 factory.py。它根据配置创建：
  • LLM
  • embedder
  • vector store
  • reranker
如果 configs/ 是说明书，那 factory.py 就是总装车间。

第二类：算法和共享工具

比如：
  • entity_extraction.py
  • lemmatization.py
  • scoring.py
  • spacy_models.py
这些东西不属于某一个 provider，但会被主链路反复调用。

2.6 client/

它不是 memory engine 本体，而是平台 API 的 SDK。
  • Memory：本地发动机
  • MemoryClient：远程遥控器

3. memory/ 目录：真正的精华

如果只允许挑一个目录深入分析，那一定是 memory/。
notion image

3.1 文件职责

main.py

核心 orchestrator（协调者）
负责：
  • 初始化 LLM / embedding / vector store / SQLite / reranker / graph
  • 对外暴露 add / search / get / update / delete / history / reset
  • 串联 vector memory 和 graph memory 两条链

storage.py

SQLite 本地状态层。
负责两张表：
  • history：memory 的增删改轨迹
  • messages：某个 scope 最近的消息缓存
这意味着 mem0 不是只有长期记忆，还显式维护了短期上下文和审计轨迹。

base.py

抽象接口层。

utils.py

注意这是 memory/ 内部的 utils，不是顶层 utils/。
主要负责：
  • prompt 组装
  • message 解析
  • JSON 清洗
  • fact normalization

telemetry.py

埋点。

setup.py

本地初始化脚手架。

graph_memory.py / kuzu_memory.py / memgraph_memory.py / apache_age_memory.py

不同图后端的实现。

4. Memory ：整个系统的大脑

最值得看的是 memory/main.py 里的 Memory。
原因很简单：它不是一个数据类，而是一个 runtime orchestrator。
初始化的时候，它会把：
  • embedding model
  • vector store
  • llm
  • SQLiteManager
  • 可选 reranker
  • 可选 graph store
都装进同一个对象里。
这意味着 mem0 的 memory 不是某一张表，也不是某一个集合，而是一条由多个组件共同驱动的流水线。

5. 关键源码：_add_to_vector_store()

_add_to_vector_store()，基本就是 mem0 的灵魂所在。

5.1 总流程图

6. 第一条分支：infer=False 是“原样写入模式”

我们先看源码第一段：
这一段非常直白：
  • 消息必须是合法 dict
  • 跳过 system 消息
  • 把 role、actor_id 写进 metadata
  • 对原始 content 做 embedding
  • 然后直接 _create_memory()
它的本质是：
不做理解，只做存储。
适合这几类场景：
  • 审计日志
  • 原始转录保存
  • 法务/医疗等不希望被 LLM 改写的高风险文本
缺点也很明显：
  • 冗余高
  • 容易重复
  • 不会自动处理冲突
所以 infer=False 更像 raw ingest。

7. 第二条分支：infer=True 才是 mem0 的真正价值

7.1 第一阶段：先从消息里抽 facts

源码这一段是：
这段代码有三个关键点。

关键点 1：custom_instructions ：抽取规则覆盖层

一旦配置了 custom_instructions，默认的 get_fact_retrieval_messages(...) 就不会再走。
也就是说：
custom_instructions 本质上是在定义“哪些内容值得被记住”。
这正是业务定制最重要的抓手。
例如：
  • 客服：只抽订单、地址、售后诉求
  • IDE Agent：只抽 repo 约定、工具偏好、失败经验
  • 医疗：只抽过敏史、既往病史、诊疗偏好

关键点 2：agent memory 和 user memory 的分流发生在“抽取阶段”

如果没有 custom_instructions，源码会先判断：
这意味着 agent memory 与 user memory 的区别，首先不是底层存储，而是：
  • 抽取 prompt 不同
  • 抽取视角不同

关键点 3：这里是第一轮 LLM，不是最终写入决策

这次 generate_response() 的目标只有一个：
从当前对话里抽取 facts
不是直接返回增删改动作。

7.2 清洗 LLM 输出：这一步体现了很强的工程意识

接下来是解析响应：
这里可以看出 mem0 处理 LLM 输出的三个策略：
  1. 先去掉代码块
  1. 先尝试直接解析 JSON
  1. 失败后再做 JSON 提取
  1. 最后统一做 facts 归一化
这说明作者非常清楚：
LLM 即使被要求输出 JSON，也并不总是干净可靠。
所以这段代码不是“锦上添花”，而是 LLM 系统工程里非常必要的一层容错。

7.3 如果没抽出 facts，后面还会继续吗？

源码这里有一句很关键：
这句话意味着：
  • 整个函数不会报错退出
  • 但第二轮 memory update LLM 会被跳过
  • 最终大概率不会产生新的 memory action
所以更准确地说：
如果 custom_instructions 或默认抽取规则判断“这段内容没有值得记住的 facts”，那后续的 memory lifecycle 决策基本不会发生。
这正是 mem0 的实用价值之一：
把“不相关内容”挡在长期记忆之外。

8. 最关键的一步：不是抽完就存，而是先搜旧 memory

这部分是 mem0 和“普通向量库存文本”的根本分界线。
源码如下：
这段代码说明了三件事。

8.1 memory write 不是 append-only，而是 retrieval-assisted

新的 fact 不是抽出来就写，而是先去搜旧 memories。
这个设计特别重要，因为现实里的长期记忆一定会遇到：
  • 偏好变化
  • 地址更新
  • 以前的说法被推翻
  • 同一事实被不同表达重复提到
所以 mem0 的设计思路是：
先检索旧记忆，再决定这条新信息到底是新增、覆盖、删除还是忽略。

8.2 作用域控制靠 user_id / agent_id / run_id

这里的 search_filters 明确把：
  • user_id
  • agent_id
  • run_id
都作为检索范围条件。
这说明 mem0 不是两套独立的 user memory / agent memory 系统，而是：
同一个 memory engine，用 metadata 和 filters 做多维 scope 管理。

8.3 user memory 和 agent memory

底层存储几乎一样：
  • 同一个 vector store
  • 同一个 SQLite history/messages
  • 同一套 create/update/delete 逻辑
真正的区别主要体现在：
  • 写入时 metadata 不同
  • 检索时 filters 不同
  • 抽取时 prompt 视角不同
一句话概括：
user memory 是“记住这个人”，agent memory 是“记住这个 agent”，run memory 是“记住这次任务”。

9. 一个特别好的工程细节：为什么要把 UUID 映射成整数

源码这一段我非常喜欢：
作者在注释里已经把原因写出来了：
为了处理 UUID hallucination。
意思非常直接：
  • 如果把真实 UUID 给 LLM
  • LLM 很容易记错、拼错、瞎编
  • 所以先给旧 memories 编成 0/1/2/...
  • LLM 返回动作时只引用这些短编号
  • 最后再映射回真实 id
这件事虽然小，但特别能体现系统工程意识：
不要让 LLM 直接处理长而脆弱的主键。
这是很典型的“不是算法多先进，而是工程经验很到位”。

10. 第二轮 LLM：真正的 memory lifecycle

在拿到：
  • 新 facts
  • 旧 memories
  • 可选的 custom update memory prompt
之后，代码会再次调用 LLM：
这一轮和第一轮的区别一定要讲清楚：
  • 第一轮：抽 facts
  • 第二轮：决定动作
也就是说，mem0 把“理解内容”和“更新状态”拆成了两次 LLM 调用。
这是个很聪明的设计，因为：
  • 先抽事实，更容易控制 recall
  • 再做动作，更容易处理冲突和覆盖
  • 两步拆开后，prompt 更清晰，可调性也更强

11. ADD / UPDATE / DELETE / NONE 四种动作到底意味着什么

源码里对四种动作分别做了处理。

11.1 ADD

含义很简单：
这是一条新的长期记忆，应该新增。

11.2 UPDATE

这里不是 delete+add，而是显式 update。
这个设计特别适合：
  • 地址变更
  • 偏好变化
  • 配置覆盖
  • 用户画像更新

11.3 DELETE

说明 mem0 接受这样一种事实：
新信息可能让旧记忆失效。
这也是长期记忆和聊天日志最大的不同之一。

11.4 NONE

这一支最有意思。
如果内容不需要更新，但有新的 agent_id 或 run_id，源码仍然会更新 metadata，而不改文本和 embedding。
这意味着：
在 mem0 的设计里，“记忆内容”和“记忆归属范围”是两个独立维度。

12. 代码到底体现了哪些设计思想

基于 _add_to_vector_store()，可以把 mem0 的 memory write 设计总结成 5 个关键词。

12.1 Retrieval-assisted writing

不是抽出来就存，而是：
  • 先抽 facts
  • 再搜旧 memories
  • 再决定动作

12.2 Stateful memory

记忆不是一条条孤立文本，而是有状态、有冲突、有演化的对象。

12.3 Scope-aware

旧 memory 检索总是带着：
  • user_id
  • agent_id
  • run_id
这使得 mem0 天然支持多用户、多 agent、多任务隔离。

12.4 Prompt-driven

custom_instructions 和 custom_update_memory_prompt 让“记什么”“怎么更新”都变成可配置规则，而不是硬编码。

12.5 LLM-aware engineering

像 UUID 映射成整数这种细节，说明源码非常了解 LLM 的脆弱点，并且为此做了工程优化。

13. Graph memory：和 vector memory 是什么关系

这一节不只停留在 main.py 的 _add_to_graph() 包装层，而是要继续下钻到 graph_memory.py。因为真正的 graph 逻辑，不是在 orchestrator 里，而是在 graph backend 的 add() 里。

13.1 直接看 graph_memory.py：add() 怎么做 graph 写入

官方仓库里，graph_memory.py 的 add() 主体调用链可以概括成下面这段：
这段代码非常关键，因为它直接暴露了 graph memory 的完整写入流程。它不是“收到一段文本就落图”，而是分成了五步：
  1. _retrieve_nodes_from_data(...)：先从文本里抽实体，并建立 entity_type_map
  1. _establish_nodes_relations_from_data(...)：再基于实体去抽关系，形成待新增关系集合
  1. _search_graph_db(...)：去现有图里搜索这些实体相关的旧关系
  1. _get_delete_entities_from_search_output(...)：判断旧关系里哪些应该被删除
  1. _delete_entities(...) + _add_entities(...)：最后真正执行图里的删除和新增
所以从这段 add() 本身就能看出来：
graph memory 不是简单存储，而是一个“抽实体 → 抽关系 → 对齐旧图 → 删除旧关系 → 新增新关系”的图生命周期管理流程。

13.2 graph 里 LLM 到底参与在什么地方

答案就在 graph_memory.py 的内部函数里。

1. 抽实体：_retrieve_nodes_from_data() 里直接调用了 LLM

源码里，实体抽取函数会直接调用：
这一步的目标不是聊天，而是：
  • 从原始文本里抽取实体
  • 给每个实体分配类型
  • 最后形成 entity_type_map
后面它还会解析 tool call，把实体结果整理成映射表。也就是说：
graph memory 的第一步不是存文本，而是先让 LLM 把文本理解成“实体集合”。

2. 抽关系：_establish_nodes_relations_from_data() 再调用一次 LLM

接下来 graph 不是直接把实体写成节点就结束了，而是还要继续抽关系。对应逻辑会再次调用：
这一步不是抽实体，而是：
  • 基于已经抽出来的实体集合
  • 再结合原始文本
  • 让模型建立实体之间的关系
  • 最后形成待写入图数据库的关系三元组
所以 graph memory 的写入至少包含两轮语义抽取：
  • 第一轮：抽实体
  • 第二轮：抽关系

3. 删除旧关系：graph 里连“删什么”都交给 LLM 决策

还有一个特别容易被忽略的点：graph memory 不只是抽实体和关系，它连“哪些旧关系该删”也会让 LLM 参与决策。
对应函数 _get_delete_entities_from_search_output(...) 里也会调用：
这一步的目标是：
  • 先拿到旧图里的关系
  • 再结合当前输入文本
  • 让模型判断哪些旧关系已经过时或冲突
  • 然后再执行删除
所以 graph memory 的完整生命周期其实很清晰：
  • 抽实体
  • 抽关系
  • 查旧图
  • 判定删除
  • 新增新关系
换句话说：
graph memory 不是 append-only，而是一个由 LLM 驱动的关系图重写流程。

13.3 所以 graph memory 和 vector memory 到底哪里像，哪里不像

相似点：都不是“原文直接入库”

不管是 vector memory 还是 graph memory，它们都不是简单把原始文本塞进存储层。
  • vector memory：抽 facts，再做 ADD / UPDATE / DELETE / NONE
  • graph memory：抽 entities，再抽 relations，再决定删什么、加什么
从系统设计角度看，这两者都属于“语义先行，再持久化”的 memory pipeline。

不同点：两者处理的对象完全不同

vector memory 处理的是 fact / memory item
vector 更关心的是：
  • 这句话里有什么事实值得记住
  • 这条事实是新增、覆盖、删除还是忽略
graph memory 处理的是 entity / relation / node / edge
graph 更关心的是：
  • 这段文本里出现了哪些实体
  • 实体之间是什么关系
  • 旧关系哪些需要失效
  • 新关系哪些需要写入
所以一句话概括：
vector memory 更像“记住一句有用的话”，graph memory 更像“把这句话拆成实体和关系网络”。

13.4 graph 的 CRUD 怎么理解

从 graph_memory.py 这套实现来看，graph memory 至少有比较清晰的生命周期：
  • Create：_add_entities(...) 新增 node / edge
  • Read：search() 返回 relations 相关结果
  • Delete：_delete_entities(...) 删除或失效旧关系
  • Update：更像通过一次新的 add() 流程触发“旧关系删除 + 新关系新增”来完成重写，而不是暴露一个单独的 graph.update() 公共接口
这一点和 vector memory 的区别也很明显：
  • vector memory 强调单条 fact 的生命周期管理
  • graph memory 更强调关系网络的维护与重构
也就是说，vector 更像“对象级记忆”，graph 更像“关系级记忆”。

14. Rerank 与业务设计：mem0 真正值钱的地方是什么

很多人会把 mem0 的价值理解成“能记住用户偏好”，但这其实只看到了表面。真正有业务价值的是，它把“长期记忆”拆成了几层可运营、可调规则的策略。

14.1 rerank 体现在哪里，为什么不放在 add 阶段

这个问题很容易被问到。
结论是：
rerank 主要体现在 search()，而不是 add() 的旧 memory 搜索阶段。
原因并不复杂。

add 阶段搜旧 memories，目标是“判断状态”

在 _add_to_vector_store() 里，旧 memory 搜索的目的是：
  • 判断是否重复
  • 判断是否冲突
  • 判断应该 ADD / UPDATE / DELETE / NONE
这一步要求的是：
  • 足够快
  • 足够稳
  • 能提供大致相关的旧 memory 即可
所以这里通常不需要再加一层昂贵的 rerank。

search 阶段面向的是“对外召回质量”

而正式的 search() 则完全不同。它的目标是：
  • 给 agent 注入更高质量上下文
  • 给用户返回更准确的 memory
  • 把 semantic search、keyword search、entity boost 之后的结果再精排
所以 rerank 更适合放在这里。
这其实是个很合理的分层：
  • add()：偏写入决策，关注状态判断
  • search()：偏对外召回，关注结果质量

14.2 业务上真正值钱的是四层策略

如果站在业务设计视角看，mem0 真正有价值的不是“支持很多模型和很多库”，而是把长期记忆拆成了四层可运营策略。

第一层：写入策略——什么值得记

通过 custom_instructions 定义。
这决定了：
  • 什么内容允许进入长期记忆
  • 什么内容必须被过滤掉
这对真实业务特别重要。因为业务通常不需要“尽可能多地记忆”，而是需要“只记高价值信息”。
例如：
  • 客服：只记订单、地址、售后诉求
  • 医疗：只记过敏史、既往病史、诊疗偏好
  • IDE Agent：只记 repo 约定、工具偏好、失败经验

第二层：更新策略——新旧事实冲突时怎么办

通过 custom_update_memory_prompt 定义。
这决定了：
  • 什么情况应该新增
  • 什么情况应该覆盖
  • 什么情况应该删除
  • 什么情况应该保持 NONE
这一步直接决定 memory system 是“日志堆积”，还是“有状态、可演化的长期记忆”。

第三层：作用域策略——这条 memory 属于谁

通过：
  • user_id
  • agent_id
  • run_id
定义。
这意味着你可以把记忆清晰地分成：
  • 属于某个用户的长期偏好
  • 属于某个 agent 的经验或专属上下文
  • 属于某次 run 的短期任务信息
这也是 mem0 可以支撑多用户、多 agent、多任务系统的核心原因。

第四层：检索质量策略——怎么把相关 memory 找准

这一层由多个模块共同决定：
  • vector search
  • keyword search
  • entity boost
  • rerank
  • graph relations
从系统角度看，mem0 并不是简单的 ANN 检索，而是在逐步把 search 做成一套多路增强的召回与精排系统。

14.3 所以 mem0 真正值钱的地方到底是什么

如果只从“它能记住用户偏好”来看 mem0，其实低估它了。
我更倾向于把它总结成一句话：
mem0 的真正价值，不是“它支持很多向量库”，而是“它把 memory 变成了一套可运营的业务系统”。
也就是说，mem0 最有价值的地方，不是某一个 provider，也不是某一个 graph backend，而是它把长期记忆拆成了：
  • 可以控制写什么
  • 可以控制怎么改
  • 可以控制记给谁
  • 可以控制怎么找
这四层策略。
这才是它和“自己手搓一个向量库 + embedding + search”最大的差别。

参考资料

mem0ai/mem0: Universal memory layer for AI Agents
Mem0 源码解析系列（一）：记忆是如何被添加的 - 肥肥旭手记 - 博客园
 
]]>