smartmate/backend/services/memory/docs/legacy/记忆模块实施计划.md

记忆模块实施计划（面试优先版 -> 产品可用版）

1. 文档目标

1. 在 3 天内交付一个“可演示、可讲清楚、可继续演进”的记忆系统 MVP。
2. 兼容当前单体工程，不引入高风险拆分，不破坏现有聊天主链路。
3. 复用现有 Outbox 异步基础设施，避免重复造轮子。
4. 形成可直接用于面试讲述的架构故事线、指标体系与演示脚本。
5. 在不增加过度复杂度的前提下，吸收 Mem0 中已被验证的关键机制（抽取、决策、检索、降级、防幻觉）。

2. 背景与约束

1. 当前系统是单体 Go 项目，已有稳定的 Outbox + Kafka + 消费事务 通路。
2. 当前项目定位先是日程助手，长期演进为陪伴型助手。
3. 短期目标是快速做出“真的可用”的记忆能力，不追求一次做成完整通用平台。
4. 风险约束：
   • 不能让重型 LLM 处理阻塞聊天实时响应。
   • 不能在 Outbox 消费主循环里堆重计算，避免拖垮其他事件消费。
   • 不能牺牲数据一致性与可审计性。

3. 总体方案

3.1 核心思路

采用“同步快路径 + 异步慢路径”：

1. 同步快路径：回复前快速读取可用记忆（以 MySQL 结构化事实为主），保证“下一轮能用”。
2. 异步慢路径：通过 Outbox 触发记忆抽取任务，执行去重、冲突消解、打分、向量化等重操作。
3. 读写解耦：写路径确保可靠入队，读路径优先稳定可控，再做语义增强。

3.2 存储职责分层

1. MySQL：事实主库（偏好、约束、任务上下文、TTL、置信度、敏感级别、来源）。
2. Milvus：语义召回（同义表达匹配、模糊语义联想）。
3. Redis（可选）：热数据缓存（后续优化，不作为 MVP 必选项）。

3.3 编排层职责

Memory Orchestrator 负责两条链路：

1. 写入链路：候选抽取 -> 去重/冲突 -> 打分 -> 分流落库（MySQL/Milvus）。
2. 读取链路：硬约束优先 -> 语义召回补充 -> 重排 -> 门控 -> 注入上下文。

3.4 借鉴 Mem0 的关键机制（已裁剪版）

1. 双阶段去重决策：先向量召回候选旧记忆，再由 LLM 决策 ADD/UPDATE/DELETE/NONE，而不是只靠相似度阈值硬判。
2. UUID 映射防幻觉：把真实 memory_id 映射成临时整数给 LLM，回收结果时再反查，防止模型编造不存在 ID。
3. 结构化输出刚性约束：抽取与决策都用 JSON 结构，失败时走 extract_json -> normalize_facts 容错链，不让解析失败直接污染主流程。
4. 动作分型嵌入：嵌入接口显式传入 memory_action（add/search/update），为后续差异化 embedding 策略预留接口。
5. 检索后处理标准化：threshold 过滤 -> 可选 reranker -> 统一降级，当重排器异常时保留向量原始排序并打告警日志。
6. 多维隔离语义：统一采用 user_id + agent_id + run_id 三维过滤；在本项目映射为 user_id + assistant_id + conversation_id。

3.5 本项目明确不做（本轮）

1. 不做图记忆（Graph Memory）落地实现，仅预留扩展点，避免 3 天范围失控。
2. 不做多 Provider 工厂体系，只保留单 Provider 可替换接口，后续再扩展。
3. 不做独立 server 化记忆服务，先在单体内完成闭环与指标验证。

4. 3 天执行计划（可直接照着做）

Day 1：把“可写入”打通（可靠入队 + 可追踪）

目标

1. 记忆任务能稳定从聊天主链路发出。
2. 能看到任务从 pending 到 success/failed 的状态流转。
3. 保证失败可重试、可追踪、可补偿。

任务清单

1. 新增文档与目录占位：
   • backend/memory/README.md（模块说明）
   • backend/memory/service/（门面）
   • backend/memory/model/（DTO 与状态）
   • backend/memory/repo/（数据访问）
   • backend/memory/orchestrator/（编排）
   • backend/memory/worker/（异步执行）
2. 新增 MySQL 表（建议先手写 SQL + DAO）：
   • memory_items
   • memory_jobs
   • memory_audit_logs
   • memory_user_settings
3. 新增配置对象（memory config）：
   • 抽取 prompt、更新决策 prompt、阈值、是否启用 reranker、LLM 温度参数。
   • 默认采用低随机参数（temperature/top_p 低值）提高可复现性。
4. 新增 Outbox 事件：
   • memory.extract.requested（v1）
5. 在聊天后置持久化环节发布事件：
   • 仅传轻量字段，避免超大 payload。
6. 新增消费处理器：
   • 只做任务入库，不做重型 LLM 调用。
7. 新增解析与标准化工具：
   • extract_json()：从模型输出中抽取 JSON（兼容代码块包裹）。
   • normalize_facts()：去重、去空、长度校验、非法项过滤。
8. 新增决策状态机定义：
   • ADD/UPDATE/DELETE/NONE 的合法状态与动作映射。
9. 启动期接线：
   • 在 backend/cmd/start.go 注册记忆事件处理器。

Day 1 验收标准

1. 一次聊天后，Outbox 中能看到 memory.extract.requested 事件。
2. 事件消费后，memory_jobs 生成记录。
3. 人工触发 worker 可完成一次任务状态推进（哪怕先是 mock 抽取）。

Day 2：把“可读取可注入”打通（先 MySQL 后向量）

目标

1. 记忆可在回复前被检索并注入上下文。
2. 能避免明显的“尬提”与无关提及。
3. 提供最小用户可控能力（查看/删除/关闭）。

任务清单

1. 实现 MemoryReadService：
   • 按用户与会话上下文读取记忆。
   • 优先结构化硬约束（时间偏好、排程禁忌、显式偏好）。
2. 实现 MemoryInjector：
   • Top-K 记忆选择。
   • token 预算截断。
   • 注入模板统一化。
3. 实现门控逻辑：
   • 相关性阈值。
   • 置信度阈值。
   • 时间衰减权重。
   • 敏感级别检查。
4. 增加“阈值 + 可选重排 + 降级”链路：
   • 阈值过滤作为第一道过滤。
   • reranker 失败时自动降级为原排序并记录原因码。
5. 新增最小管理接口：
   • GET /api/v1/memory/items
   • DELETE /api/v1/memory/items/:id
   • POST /api/v1/memory/settings（开关）
6. 完成首版日志埋点：
   • 检索命中数、注入条数、门控丢弃原因。
   • 决策分布（ADD/UPDATE/DELETE/NONE 占比）。

Day 2 验收标准

1. 给出偏好后，下一轮排程请求能利用该偏好。
2. 无关话题不会频繁硬提旧记忆。
3. 用户可删除指定记忆，删除后不再注入。

Day 3：把“可讲清楚”与“可评估”补齐（面试可答）

目标

1. 输出完整可讲架构，说明设计取舍。
2. 增加可量化指标，证明记忆“有用”而不是“看起来有”。
3. 可选接入 Milvus（若环境未就绪，先保留接口 + mock）。

任务清单

1. 实现/预留向量接口：
   • VectorStore.Upsert()
   • VectorStore.Search()
   • VectorStore.Delete()
   • VectorStore.Get()（为 UPDATE/DELETE 决策回查旧值）
2. 对接 Milvus（可选）：
   • collection 初始化。
   • 向量 + 元数据过滤检索。
3. 指标体系落地：
   • 记忆命中率（retrieved/useful）
   • 错误提及率（wrong mention）
   • 用户纠正率（user correction）
   • 回复延迟影响（P50/P95）
4. 准备演示脚本与面试问答稿：
   • 5 分钟架构说明。
   • 3 个典型失败案例及兜底策略。
   • 未来迭代路线。
5. 输出“借鉴 Mem0 但本地化裁剪”的对比说明：
   • 借鉴了什么。
   • 为什么暂时不做图记忆与多 Provider 工厂。

Day 3 验收标准

1. 能现场演示“记住偏好 -> 下轮生效 -> 删除后失效”。
2. 能答清楚“为什么不是纯同步/纯异步”。
3. 能答清楚“为什么 MySQL + Milvus 双存储”。

5. 数据模型设计（首版）

5.1 memory_items（长期事实记忆）

用途：保存对业务有约束价值的可注入记忆。

关键字段建议：

1. id bigint PK
2. user_id bigint（必填）
3. conversation_id varchar(64)（可空，表示全局用户记忆）
4. assistant_id varchar(64)（可空，区分不同助手人格/技能域）
5. run_id varchar(64)（可空，会话级隔离）
6. memory_type varchar(32)
   • preference（偏好）
   • constraint（硬约束）
   • fact（事实）
   • todo_hint（近期提醒线索）
7. title varchar(128)
8. content text
9. normalized_content text（去噪后）
10. content_hash varchar(64)（幂等去重）
11. confidence decimal(5,4)（0~1）
12. importance decimal(5,4)（0~1）
13. sensitivity_level tinyint
    • 0 普通
    • 1 中敏
    • 2 高敏
14. source_message_id bigint
15. source_event_id varchar(64)
16. is_explicit tinyint(1)（是否用户明确要求记住）
17. status varchar(16)
    • active
    • archived
    • deleted
18. ttl_at datetime（到期时间）
19. last_access_at datetime
20. created_at datetime
21. updated_at datetime
22. vector_status varchar(16)（pending/synced/failed）
23. vector_id varchar(128)（向量库主键映射）

索引建议：

1. (user_id, status, memory_type, updated_at desc)
2. (user_id, conversation_id, status, updated_at desc)
3. (source_message_id)（排查链路）
4. (ttl_at)（过期清理）
5. (user_id, assistant_id, run_id, status, updated_at desc)
6. (user_id, memory_type, content_hash)（幂等去重）

5.2 memory_jobs（异步任务队列表）

用途：承接 Outbox 消费后的待处理任务，解耦重计算。

关键字段建议：

1. id bigint PK
2. user_id bigint
3. conversation_id varchar(64)
4. source_message_id bigint
5. source_event_id varchar(64)
6. job_type varchar(32)
   • extract
   • embed
   • reconcile
7. idempotency_key varchar(128)
8. payload_json longtext
9. status varchar(16)
   • pending
   • processing
   • success
   • failed
   • dead
10. retry_count int
11. max_retry int
12. next_retry_at datetime
13. last_error varchar(2000)
14. created_at datetime
15. updated_at datetime

索引建议：

1. (status, next_retry_at, id)
2. (user_id, created_at desc)
3. (source_event_id)（幂等与追踪）
4. (idempotency_key)（消费防重）

5.3 memory_audit_logs（审计日志）

用途：回答“这条记忆是谁在什么条件下写的/改的/删的”。

关键字段建议：

1. id bigint PK
2. memory_id bigint
3. user_id bigint
4. operation varchar(32)
   • create
   • update
   • archive
   • delete
   • restore
5. operator_type varchar(16)
   • system
   • user
6. reason varchar(255)
7. before_json longtext
8. after_json longtext
9. created_at datetime

5.4 memory_user_settings（用户记忆开关）

用途：实现用户可控能力。

关键字段建议：

1. user_id bigint PK
2. memory_enabled tinyint(1)
3. implicit_memory_enabled tinyint(1)
4. sensitive_memory_enabled tinyint(1)
5. updated_at datetime

6. 事件与协议设计

6.1 事件类型

1. memory.extract.requested（v1）
2. 预留：
   • memory.embed.requested
   • memory.cleanup.requested

6.2 载荷字段（v1）

1. user_id
2. conversation_id
3. assistant_id
4. run_id
5. source_message_id
6. source_role
7. source_text
8. occurred_at
9. trace_id
10. idempotency_key

设计约束：

1. Payload 只放执行需要的最小字段。
2. 大文本允许截断并保留摘要，防止消息膨胀。
3. 必须包含幂等标识（如 source_message_id + user_id）。
4. 过滤维度必须完整（user_id + assistant_id + run_id），避免跨会话串记忆。

7. 写入流程详细设计

7.1 主流程

1. 聊天主链路完成并落历史消息。
2. 发布 memory.extract.requested 到 Outbox。
3. Outbox 消费处理器验证 payload。
4. 处理器创建或幂等更新 memory_jobs（仅任务入库）。
5. memory/worker 扫描 pending 任务并抢占为 processing。
6. Worker 调用 LLM 执行“候选事实抽取”（JSON 输出）。
7. 执行 extract_json -> normalize_facts 容错标准化链路。
8. 对每条候选事实做向量检索，召回 Top-K 旧记忆候选。
9. 对召回结果执行“临时整数 ID 映射”，再交给 LLM 决策 ADD/UPDATE/DELETE/NONE。
10. 根据决策执行写入动作：
    • ADD：新增 memory_items + 审计日志。
    • UPDATE：更新记录并保留历史旧值。
    • DELETE：软删除并记录删除原因。
    • NONE：不写入，仅记调试日志。
11. 按决策动作触发向量同步（支持 vector_pending）。
12. 成功后任务标记 success，失败按重试策略推进。

7.2 失败处理策略

1. Payload 非法：直接标记 dead，不重试。
2. LLM 短时失败：指数退避重试。
3. DB 写失败：重试，超过上限 dead。
4. 向量写失败：
   • MVP 策略：不阻塞事实写入，记录 vector_pending 状态。
   • 后续策略：补偿任务重建向量索引。

7.3 幂等策略

1. 幂等键：user_id + source_message_id + memory_type + normalized_content_hash
2. 同幂等键重复写入：更新 updated_at、提升访问热度，不新增重复条目。
3. 由 Outbox 重试导致的重复消费必须无副作用。
4. 对 UPDATE/DELETE 必须先校验目标 memory_id 是否存在且属于当前过滤域。

8. 读取流程详细设计

8.1 主流程

1. 接收用户新问题，先做意图分类（排程/闲聊/混合）。
2. 从 memory_items 拉取硬约束记忆（高优先级）。
3. 若 Milvus 可用，执行语义召回补充记忆候选。
4. 对候选执行重排：
   • 相关性分
   • 置信度分
   • 时间衰减分
   • 显式记忆加权
5. 执行门控：
   • 低相关丢弃
   • 高敏过滤
   • 过期过滤
6. 执行阈值过滤后可选 reranker；若 reranker 异常则自动降级使用原排序。
7. 按 token budget 选择最终注入条目。
8. 组装统一注入上下文，传给主模型生成回复。

8.2 重排评分（建议公式）

final_score = 0.45 * relevance + 0.25 * confidence + 0.20 * recency + 0.10 * explicit_bonus

说明：

1. 排程类场景可增加硬约束权重。
2. 闲聊类场景可提高语义相关权重。
3. 该公式为 MVP 默认值，后续可通过线上数据调参。

8.3 门控规则（MVP）

1. final_score < 0.55 不注入。
2. sensitivity_level >= 2 且用户未开启敏感记忆时不注入。
3. ttl_at < now 不注入。
4. 同主题最多注入 1~2 条，防止重复轰炸。

9. 对外接口（MVP）

9.1 用户接口

1. GET /api/v1/memory/items
   • 支持按类型、时间、状态过滤。
2. DELETE /api/v1/memory/items/:id
   • 软删除并写审计日志。
3. POST /api/v1/memory/settings
   • 修改记忆总开关、隐式记忆开关。

9.2 内部接口

1. MemoryService.EnqueueExtractJob(ctx, payload)
2. MemoryService.RetrieveForPrompt(ctx, req)
3. MemoryService.UpsertMemoryItems(ctx, items)
4. MemoryService.DeleteMemory(ctx, userID, memoryID)

10. 可观测性与指标

10.1 指标定义

1. memory_job_success_rate
2. memory_job_retry_rate
3. memory_retrieval_hit_rate
4. memory_injection_count_avg
5. memory_wrong_mention_rate
6. memory_user_correction_rate
7. chat_p95_latency_delta_with_memory
8. memory_json_parse_fail_rate
9. memory_decision_distribution（ADD/UPDATE/DELETE/NONE）
10. reranker_fallback_rate

10.2 日志与追踪

1. 每个任务写 trace_id，贯穿聊天请求 -> outbox -> memory_job -> memory_item。
2. 对门控丢弃记录原因码：
   • LOW_SCORE
   • EXPIRED
   • SENSITIVE_BLOCKED
   • DUP_TOPIC
3. 保证可以反查“为什么这次没有提某条记忆”。

11. 安全与隐私约束

1. 敏感信息默认不做隐式记忆（如健康、财务、证件等）。
2. 用户必须可删除历史记忆，删除后不再用于注入。
3. 记忆开关关闭后，仅保留必要系统数据，不再新增记忆条目。
4. 审计日志保留系统写入行为，便于风控与合规排查。

12. 测试策略

12.1 单元测试范围（实现阶段）

1. 候选抽取结果解析函数。
2. 冲突消解函数。
3. 重排评分函数。
4. 门控函数。
5. 幂等去重函数。
6. extract_json 容错解析函数。
7. normalize_facts 标准化函数。
8. UUID 映射与反查函数。
9. ADD/UPDATE/DELETE/NONE 决策结果校验函数。

12.2 集成测试范围（实现阶段）

1. 聊天后事件成功入 outbox。
2. Outbox 消费后任务成功入 memory_jobs。
3. Worker 成功写 memory_items。
4. 读取链路能在回复中注入预期记忆。

12.3 注意事项（遵循项目约束）

1. 若编写 Go 测试文件（*_test.go）做验证，任务完成后按项目约定移除测试文件。
2. 每次执行本地 go test 后清理项目根目录 .gocache。

13. 风险与回滚

13.1 主要风险

1. 记忆误提影响体验。
2. LLM 抽取不稳定导致脏记忆。
3. 向量检索误召回导致不相关注入。
4. 任务积压影响时效。

13.2 应对策略

1. 先严门控，宁可少提，不要乱提。
2. 保留“用户纠正”入口，纠正后提高冲突更新优先级。
3. 对召回做 metadata 过滤（近 30 天、类型限定）。
4. 监控任务积压长度，超阈值降级（停向量，仅结构化记忆）。

13.3 回滚方案

1. 配置开关 memory.enabled=false 可一键关闭记忆注入。
2. 保留写入链路但停读取链路，避免历史数据丢失。
3. 极端情况下停 worker，仅保留主链路聊天功能。

14. 面试表达模板（可直接复述）

1. “我们做的是同步快路径 + 异步慢路径。同步保证下轮可用，异步负责治理和质量。”
2. “结构化事实放 MySQL 保证可控可审计，语义联想放 Milvus 提高召回覆盖。”
3. “Outbox 保证事件可靠入队，Worker 解耦重计算，避免阻塞主链路。”
4. “借鉴 Mem0 的双阶段策略：先向量召回旧记忆，再让 LLM 决策 ADD/UPDATE/DELETE/NONE，兼顾召回率与准确率。”
5. “我们用 UUID 映射防止模型伪造 ID，并且用 JSON 容错链保证抽取稳定性。”
6. “我们用命中率、误提率、纠正率和 reranker 降级率验证记忆是否真的有价值。”

15. DoD（完成定义）

1. 代码层：
   • 记忆事件可发布、可消费、可重试。
   • 记忆可检索、可注入、可删除、可关闭。
2. 质量层：
   • 有基础指标与日志，支持问题排查。
   • 有失败兜底与降级路径。
3. 叙事层：
   • 3 分钟能讲清架构。
   • 5 分钟能演示端到端效果。
   • 能回答核心取舍与后续演进。

16. 本轮执行顺序建议

1. 先做 Day 1 的表结构与事件接线，不进入复杂抽取细节。
2. 再做 Day 2 的读取注入，优先 MySQL 结构化记忆。
3. 最后补 Day 3 的 Milvus 与指标，确保面试讲述闭环。

17. Mem0 借鉴清单与取舍结论（本轮新增）

17.1 直接借鉴

1. ADD/UPDATE/DELETE/NONE 统一决策状态机。
2. threshold -> reranker(可选) -> fallback 的检索后处理套路。
3. 三维过滤隔离（user_id/agent_id/run_id）的语义边界设计。
4. 历史追踪思路（本项目落在 memory_audit_logs）。
5. 低随机参数 + JSON 输出约束，提升可复现性。

17.2 延后借鉴

1. 图记忆（关系三元组与软删除）延后到 V2/V3。
2. 多 Provider 工厂体系延后到“需要跨云/跨模型”时再上。
3. 托管 API 平台化能力延后到单体稳定后再拆。

17.3 不照搬的原因

1. 当前目标是 3 天可演示 MVP，优先“稳定可讲”而非“能力最全”。
2. 项目已有 Outbox 可靠链路，先最大化复用，避免架构重复。
3. 日程助手是强约束场景，结构化事实主库优先级高于图谱表达能力。

---

本文件定位为“落地执行蓝图”。后续每完成一块能力，建议在本文件追加“已落地清单 + 待办差距”，持续收敛为真实实施记录。