smartmate/backend/services/memory/docs/legacy/HANDOFF_Memory向Mem0靠拢三步冲刺计划.md

Memory 向 Mem0 靠拢三步冲刺计划（newAgent）

1. 一句话结论

当前 memory 已经具备了“可异步写入、可基础抽取、可基础检索、可注入 newAgent”的骨架，但距离真正有 Mem0 味道的记忆系统，还差三块核心能力：

1. 写入侧没有“先召回旧记忆，再做 ADD/UPDATE/DELETE/NONE 决策”的治理层。
2. 读侧没有把“硬约束优先、语义召回补充、结果去重、注入预算”做成稳定链路。
3. 系统层没有形成“可灰度、可解释、可清理、可回滚”的治理闭环。

因此建议按三步走推进，并严格遵守一个原则：

1. 每一轮只处理一个能力域。
2. 第一步只动写入决策层。
3. 第二步只动读链路与注入质量。
4. 第三步只动治理、清理、指标与切流收口。

---

2. 本文档给谁看

本文档面向三类读者：

1. 需要继续实现 memory/newAgent 的 agent。
2. 需要拆任务、排优先级的人。
3. 需要快速判断“本轮该改什么、不该改什么”的维护者。

本文档不是背景介绍文档，而是“可直接拿去拆工单和接力开发”的冲刺说明。

---

3. 当前现状与目标差距

3.1 当前已完成的部分

当前已经有的能力：

1. 聊天消息可通过 outbox -> memory.extract.requested -> memory_jobs -> worker 进入异步记忆链路。
2. Worker 可调用 LLM 做事实抽取，并通过 NormalizeFacts 做批内标准化和批内去重。
3. memory_items / memory_jobs / memory_audit_logs / memory_user_settings 四张核心表已经建立并接线。
4. ReadService 已可做基础查询与轻量排序。
5. newAgent 已通过 injectMemoryContext 把记忆写入 pinned block。
6. 用户设置、删除、审计已经具备基础治理能力。

3.2 当前离 Mem0 还差什么

最关键的差距如下：

能力	当前状态	与 Mem0 的差距
异步入队	已完成	基本到位
抽取候选事实	已完成	缺少更强的抽取后治理
批内去重	已完成	仅限单批，不处理历史记忆
历史去重	未完成	需要按旧记忆召回后做决策
ADD/UPDATE/DELETE/NONE 决策	未完成	这是最关键差距
语义召回	部分完成	接口有了，质量与稳定性未形成闭环
读侧去重	未完成	现在更多是展示层弱去重
Prompt 注入	基础版已接	还没有类型分层与预算控制
管理治理	部分完成	还缺更新、恢复、历史清理、指标闭环
灰度/回滚	较弱	需要细粒度 feature flag 与分阶段切流

3.3 本次冲刺的目标定义

本轮不是要把项目做成完整 Mem0，也不是做图记忆或多 Provider 平台，而是要做到一个“Mem0-lite 可自信上线”的状态。满足以下条件，就可以认为基本靠近目标：

1. 相同或同义记忆不会无脑越写越多。
2. 用户纠正一条旧记忆时，系统更倾向于更新旧值，而不是新增一条冲突值。
3. 读侧能优先拿到“硬约束 + 偏好 + 当前话题相关事实”，而不是仅按最近更新时间胡乱注入。
4. Prompt 注入是稳定、可控、可解释的，而不是纯拼接。
5. 出问题时可以快速关掉某一层能力，而不是整条 memory 链路一起陪葬。

---

4. 设计原则与边界

4.1 每轮只处理一个能力域

为避免回归问题无法定位，本计划明确规定：

1. 第一步只处理“写入决策层”。
2. 第二步只处理“读取与注入层”。
3. 第三步只处理“治理、清理与切流层”。

禁止在同一轮里同时大改：

1. memory 写入逻辑。
2. newAgent 图节点结构。
3. WebSearch / 其他 RAG 语料。
4. 多个 prompt 体系。

4.2 保留旧实现，走并行迁移

整个冲刺必须遵守并行迁移策略：

1. 旧的“抽取后直接 Create”路径先保留。
2. 新的“决策后 ApplyAction”路径并行落地。
3. 用 feature flag 灰度切流。
4. 验证通过后，再决定是否删除旧路径。

4.3 不新增“memory 工具化”这条支线

本轮不建议把 memory 改成一个显式工具让 newAgent 主动调用，原因如下：

1. 当前 pinned block 已经接入主链路，切点稳定。
2. 本轮目标是让记忆“更准”，不是让图结构更复杂。
3. 若同时引入工具化调用，会把“写入决策层”和“图编排层”耦到一起。

因此本轮默认继续沿用：

1. backend/memory/service/read_service.go
2. backend/service/agentsvc/agent_memory.go
3. pinned block 注入

---

5. 三步走总览

步骤	只处理的能力域	核心目标	旧实现是否保留
第一步	写入决策层	把“抽取即新增”升级为“召回旧记忆 + 决策动作”	保留
第二步	读链路与注入层	把“查到就拼”升级为“硬约束优先 + 语义补充 + 注入预算”	保留
第三步	治理与切流层	把“能跑”升级为“可灰度、可观测、可清理、可回滚”	收口

---

6. 第一步：先把写入侧做成 Mem0-lite

6.1 这一步解决什么问题

当前写入链路本质上还是：

抽取 -> 标准化 -> 直接写 memory_items

这会带来三个直接问题：

1. 历史同义记忆不会合并。
2. 用户纠正旧记忆时，系统更可能新增一条相反记忆。
3. content_hash 现在更多只是存了个字段，没有真正承担“历史治理”的职责。

第一步的目标是把写入链路升级为：

抽取 -> 召回旧记忆候选 -> 临时 ID 映射 -> LLM 决策 -> ApplyAction

6.2 本轮要落的能力

第一步必须落地以下能力：

1. 为每条新候选 fact 召回有限个旧记忆候选。
2. 用临时整数 ID 或候选序号喂给决策模型，避免模型直接编造真实 memory_id。
3. 让模型只输出结构化 JSON 决策：ADD/UPDATE/DELETE/NONE。
4. 后端严格校验决策合法性，再执行数据库动作。
5. UPDATE/DELETE 也必须补齐审计日志，而不是只有 create/delete。

6.3 推荐的文件落点

建议新增文件：

1. backend/memory/model/decision.go
   • 定义决策 DTO、候选旧记忆 DTO、ApplyAction DTO。
2. backend/memory/orchestrator/llm_decision_orchestrator.go
   • 负责“给定新 fact + 旧候选 -> 输出结构化动作决策”。
3. backend/memory/utils/decision_id_map.go
   • 负责“真实 memory_id <-> 临时决策 ID”的映射。
4. backend/memory/utils/decision_validate.go
   • 负责校验动作是否合法、目标 ID 是否存在、动作字段是否完整。
5. backend/memory/worker/decision_flow.go
   • 负责 worker 内的“候选召回 -> 决策 -> 动作执行编排”。
6. backend/memory/worker/apply_actions.go
   • 负责把 ADD/UPDATE/DELETE/NONE 落为数据库动作与审计。

建议修改文件：

1. backend/memory/model/config.go
2. backend/memory/service/config_loader.go
3. backend/memory/repo/item_repo.go
4. backend/memory/worker/runner.go
5. backend/memory/utils/audit.go

6.4 推荐新增配置

建议新增配置项，全部走 memory 命名空间：

1. memory.decision.enabled
   • 是否启用决策层。
2. memory.decision.candidateTopK
   • 每个新 fact 召回多少个旧记忆候选。
3. memory.decision.fallbackMode
   • 建议支持 legacy_add / drop 两种模式。
4. memory.write.mode
   • 建议支持 legacy / decision 两种模式。

建议默认值：

1. memory.decision.enabled=false
2. memory.write.mode=legacy
3. memory.decision.candidateTopK=5
4. memory.decision.fallbackMode=legacy_add

6.5 ItemRepo 需要补的能力

当前 ItemRepo 只有“查、建、删状态、刷访问时间、刷向量状态”，还不够支撑决策动作。第一步至少要补以下能力：

1. FindDecisionCandidates(...)
   • 按 user_id + assistant_id + conversation_id + run_id + memory_type 查候选。
   • 当 RAG 可用时，可优先用向量召回补候选。
2. UpdateContentByID(...)
   • 用于 UPDATE。
   • 至少要更新：title/content/normalized_content/content_hash/confidence/importance/sensitivity_level/is_explicit/updated_at。
3. SoftDeleteByID(...)
   • 用于决策型 DELETE。
4. FindActiveByHash(...)
   • 给兜底幂等或低成本重复检测预留接口。

注意：

1. 不要把这些逻辑继续堆进 UpsertItems。
2. UpsertItems 可以暂时保留给 legacy 路径使用。
3. 新路径应尽量使用显式动作函数，而不是一个“万能 Upsert”。

6.6 Worker 内推荐的执行顺序

对每个 job，建议执行以下顺序：

1. 先抽取新事实。
2. 对抽取结果做 NormalizeFacts。
3. 按用户设置过滤。
4. 若 memory.decision.enabled=false，直接走旧路径并返回。
5. 对每条新 fact 召回旧候选：
   • 先查强约束域内候选。
   • 若 memory.rag.enabled=true，再用 RAG 补充语义候选。
6. 对候选做临时 ID 映射。
7. 调 LLMDecisionOrchestrator 输出动作。
8. 后端校验动作合法性。
9. 执行动作：
   • ADD：创建 item + create audit
   • UPDATE：更新旧 item + update audit
   • DELETE：软删除旧 item + delete audit
   • NONE：只记日志，不动表
10. 根据动作决定是否做向量同步：
    • ADD：新增向量
    • UPDATE：重写向量
    • DELETE：删向量或打 pending 删除标记

6.7 决策 Prompt 的建议约束

决策 prompt 需要非常收敛，建议只允许模型做一件事：

1. 给定一条新 fact。
2. 给定少量旧候选。
3. 在 ADD/UPDATE/DELETE/NONE 中选一个动作。

不建议第一版就让模型：

1. 一次同时处理多条新 fact 与多条旧事实的复杂批量决策。
2. 自己生成复杂的替代文案策略。
3. 自己修改 scope 或元数据。

推荐第一版输出结构大致为：

{
  "decisions": [
    {
      "candidate_index": 0,
      "action": "UPDATE",
      "target_temp_id": 2,
      "title": "更新后的标题",
      "content": "更新后的内容",
      "reason": "新事实是在纠正旧事实"
    }
  ]
}

6.8 这一步的验收标准

满足以下条件，可认为第一步完成：

1. 重复表达同一偏好，不会连续生成多条 active 记忆。
2. 用户显式纠正旧偏好时，会更倾向触发 UPDATE，而不是再新增一条冲突记忆。
3. memory_audit_logs 能明确区分 create/update/delete。
4. 决策层失败时，不会阻断原有 legacy 链路。
5. 关闭 memory.decision.enabled 后，系统行为可完全回到当前实现。

6.9 这一步的回滚点

第一步必须保留明确回滚点：

1. 关闭 memory.decision.enabled
2. memory.write.mode 切回 legacy

回滚后仍然使用：

1. LLMWriteOrchestrator.ExtractFacts
2. NormalizeFacts
3. buildMemoryItems
4. ItemRepo.UpsertItems

6.10 这一步明确不做什么

第一步不要顺手做以下事情：

1. 不重构 newAgent 图节点。
2. 不引入 memory 工具调用。
3. 不做图记忆。
4. 不做用户侧“编辑记忆内容”的管理 API。
5. 不同时改 WebSearch 的 RAG 链路。

---

7. 第二步：把读取与注入做成真正可用的记忆链路

7.1 这一步解决什么问题

写入侧即使更聪明，如果读出来的还是“按分数凑五条，再平铺给 prompt”，整体体验依然不会像 Mem0。

第二步要解决的问题是：

1. 硬约束和偏好不能被普通事实挤掉。
2. 历史重复项不能继续在读侧污染 TopK。
3. 注入给模型的文本需要可控，而不是简单平铺。
4. RAG 可用时要真正成为加分项，不可用时要稳定降级。

7.2 本轮要落的能力

第二步必须落地以下能力：

1. 读侧合并“结构化强约束召回”和“语义候选召回”。
2. 读侧在服务层做真正的去重，而不是只在渲染字符串时弱去重。
3. 注入文本按类型分组，而不是所有内容同一层级平铺。
4. 给每一类记忆设置注入预算，避免事实类把 prompt 撑爆。

7.3 推荐的文件落点

建议优先修改文件：

1. backend/memory/service/read_service.go
2. backend/memory/repo/item_repo.go
3. backend/service/agentsvc/agent_memory.go

如需补辅助文件，建议新增：

1. backend/memory/service/retrieve_merge.go
   • 负责多路召回的结果合并、去重、预算裁剪。
2. backend/memory/service/retrieve_rank.go
   • 负责重排与门控。
3. backend/service/agentsvc/agent_memory_render.go
   • 负责把 memory DTO 渲染成稳定的注入 block。

说明：

1. 当前 agent_memory.go 已经不算小。
2. 第二步不要继续往单文件里堆“召回策略 + 去重 + 渲染模板”。
3. 这一轮拆开渲染层是合理的职责拆分，不属于跨能力域大重构。

7.4 读取侧推荐的新流程

建议读侧升级为以下顺序：

1. 先从 MySQL 拉“必守约束”：
   • constraint
   • 高置信度 preference
2. 再按当前 query 做相关召回：
   • 若 memory.rag.enabled=true，优先走 RAG
   • 否则走 legacy DB 排序
3. 合并两路结果。
4. 先按 memory_id 去重。
5. 再按 content_hash 去重。
6. 最后才按渲染文本兜底去重。
7. 对结果做类型预算：
   • constraint：优先保留
   • preference：次优先
   • todo_hint：控制数量
   • fact：最容易膨胀，要严格限额

7.5 注入层推荐的渲染方式

当前渲染方式更像“扁平清单”。第二步建议升级成“分段注入”，例如：

1. 必守约束
2. 用户偏好
3. 当前话题相关事实
4. 近期线索

推荐生成类似文本：

以下是与当前对话相关的用户记忆，仅在确实有帮助时参考，不要机械复述。

【必守约束】
- 用户点外卖不要香菜。

【用户偏好】
- 用户偏爱黑咖啡。

【当前话题相关事实】
- 用户最近在准备周四的程序设计作业。

这样做的好处：

1. 模型更容易区分“必须遵守”和“仅可参考”。
2. 日后更容易按类型做 budget。
3. 若发生错误注入，也更容易解释是哪一层出错。

7.6 第二步建议新增配置

建议新增：

1. memory.read.mode
   • 建议支持 legacy / hybrid
2. memory.read.factLimit
3. memory.read.preferenceLimit
4. memory.read.constraintLimit
5. memory.inject.renderMode
   • 建议支持 flat / typed_v2

建议默认值：

1. memory.read.mode=legacy
2. memory.inject.renderMode=flat

灰度时再逐步切到：

1. memory.read.mode=hybrid
2. memory.inject.renderMode=typed_v2

7.7 这一步的验收标准

满足以下条件，可认为第二步完成：

1. 同一条重复记忆即使数据库里有多条，最终注入给 prompt 也只保留一条。
2. constraint 类记忆不会轻易被 fact 类挤出注入集合。
3. RAG 异常时，系统仍能稳定退回 legacy 读取逻辑。
4. 注入文本结构清晰，且总长度稳定，不会一轮长一轮短。
5. newAgent 的 pinned block 内容更可读、更可解释。

7.8 这一步的回滚点

第二步必须支持快速回滚：

1. memory.read.mode=legacy
2. memory.inject.renderMode=flat
3. memory.rag.enabled=false

回滚后保留：

1. 旧的 ReadService.retrieveByLegacy
2. 当前 agent_memory.go 扁平渲染逻辑

7.9 这一步明确不做什么

第二步不要顺手做以下事情：

1. 不把 memory 改造成工具调用。
2. 不改 newAgent 的图路由结构。
3. 不把 WebSearch 一起并进统一召回。
4. 不在这一轮清理历史重复脏数据。

---

8. 第三步：做治理、清理、指标与切流收口

8.1 这一步解决什么问题

前两步做完后，系统可能“效果已经不错”，但仍缺三个上线必须项：

1. 出问题时怎么知道错在哪一层。
2. 历史已经写进去的重复脏数据怎么治理。
3. 什么时候能把 legacy 路径关掉。

第三步就是收口这一层。

8.2 本轮要落的能力

第三步建议至少做以下能力：

1. 为写入决策、读取召回、注入渲染补齐结构化日志和指标。
2. 增加历史重复清理能力。
3. 补齐“我的记忆”增删改查语义，以及必要的最小变更留痕。
4. 明确 feature flag 切流策略与回滚手册。
5. 更新文档，避免后续维护者只看到旧 README。

8.3 推荐的文件落点

建议修改文件：

1. backend/memory/utils/audit.go
2. backend/memory/service/manage_service.go
3. backend/memory/repo/item_repo.go
4. backend/memory/README.md
5. backend/memory/记忆模块实施计划.md

建议新增文件：

1. backend/memory/cleanup/dedup_runner.go
   • 用于历史重复治理。
2. backend/memory/cleanup/dedup_policy.go
   • 负责定义“保留哪条、归档哪条”。
3. backend/memory/observe/log_fields.go
   • 统一日志字段，避免不同文件各写各的。

8.4 历史数据清理建议

建议不要直接写危险 SQL 一把梭清表，而是通过可留痕的治理流程清理历史脏数据：

1. 按 user_id + memory_type + content_hash + status=active 扫描重复组。
2. 为每组挑一个保留主记录：
   • 优先保留最近更新
   • 或优先保留置信度更高
3. 其余重复项改为 archived 或 deleted。
4. 对每次治理动作写最小变更留痕。

建议第一版优先做“离线治理工具”或“手动触发 job”，不要直接绑到主 worker 周期任务里。

8.5 建议补的指标

第三步建议至少打这些指标：

1. memory_job_success_rate
2. memory_job_retry_rate
3. memory_decision_distribution
4. memory_decision_fallback_rate
5. memory_retrieve_hit_count
6. memory_retrieve_dedup_drop_count
7. memory_inject_item_count
8. memory_rag_fallback_rate
9. memory_wrong_mention_rate
10. memory_user_correction_rate

其中前八项可以本轮先落，后两项可通过后续用户纠正入口接入。

8.6 建议的切流顺序

第三步不要“一刀切”。建议按以下顺序灰度：

1. 阶段 A：决策层 shadow 模式
   • 真正写库仍走 legacy
   • 新决策层只做日志，不生效
2. 阶段 B：决策层仅对显式记忆生效
3. 阶段 C：决策层对全部写入生效
4. 阶段 D：读侧切到 hybrid
5. 阶段 E：注入切到 typed_v2
6. 阶段 F：历史清理跑完，再考虑关闭 legacy 默认路径

8.7 这一步的验收标准

满足以下条件，可认为第三步完成：

1. 能从日志看清某条记忆为何被 ADD/UPDATE/DELETE/NONE。
2. 能从指标看清读侧命中、去重、降级、回滚情况。
3. 能对历史重复数据做可留痕清理。
4. 出现异常时可在分钟级通过开关退回 legacy。
5. 文档与代码现状一致，不再依赖口头传递。

8.8 这一步的回滚点

第三步的回滚不应影响前两步代码保留，只需回切开关：

1. 决策层回到 legacy
2. 读侧回到 legacy
3. 注入渲染回到 flat
4. 停掉清理任务

8.9 这一步明确不做什么

第三步仍然不建议同时做以下事情：

1. 不做图记忆。
2. 不做多 Provider 工厂化。
3. 不拆独立 memory 服务。
4. 不把 WebSearch 与 Memory 强行合并到同一轮上线。

---

9. 推荐的三轮交付顺序

如果资源有限，建议严格按下面顺序推进：

1. 先做第一步。
   • 原因：写侧如果还是“抽取即新增”，读侧再怎么优化也会越来越脏。
2. 再做第二步。
   • 原因：写侧稳定后，读侧才能真正体现效果。
3. 最后做第三步。
   • 原因：治理、指标、清理要建立在前两步能力已经基本成形的前提下。

一句话总结：

1. 先让系统“会整理记忆”。
2. 再让系统“会正确读记忆”。
3. 最后让系统“可稳定上线和维护”。

---

10. 建议的任务拆分方式

如果后续要多人并行，建议按职责边界拆，而不是按文件随意拆：

10.1 第一步可拆为两块

1. 决策模型与编排
   • decision.go
   • llm_decision_orchestrator.go
   • decision_validate.go
2. Repo 与动作执行
   • item_repo.go
   • apply_actions.go
   • audit.go

10.2 第二步可拆为两块

1. 读侧召回与合并
   • read_service.go
   • retrieve_merge.go
   • retrieve_rank.go
2. newAgent 注入渲染
   • agent_memory.go
   • agent_memory_render.go

10.3 第三步可拆为两块

1. 治理与清理
   • dedup_runner.go
   • manage_service.go
2. 观测与文档
   • 指标日志
   • README / 计划文档更新

---

11. 如果只看一个结论，请看这里

要让当前 memory 真正靠近 Mem0，不是再加一张表，也不是再加一个 prompt，而是要完成以下收敛：

1. 写入侧从“抽到就加”升级为“先回看旧记忆，再决定加改删不做”。
2. 读侧从“查到就拼”升级为“硬约束优先、语义补充、结果去重、预算注入”。
3. 系统侧从“能跑”升级为“有灰度、有指标、有清理、有回滚”。

只要三步按这个顺序推进，最终得到的就不是一个“会不断积灰的记忆表”，而是一套真正能为 newAgent 服务的记忆系统。