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

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

1. 文档目标

1. 在 3 天内交付一个“可演示、可讲清楚、可继续演进”的记忆系统 MVP。
2. 兼容当前单体工程，不引入高风险拆分，不破坏现有聊天主链路。
3. 复用现有 Outbox 异步基础设施，避免重复造轮子。
4. 形成可直接用于面试讲述的架构故事线、指标体系与演示脚本。

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. 读取链路：硬约束优先 -> 语义召回补充 -> 重排 -> 门控 -> 注入上下文。

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. 新增 Outbox 事件：
   • memory.extract.requested（v1）
4. 在聊天后置持久化环节发布事件：
   • 仅传轻量字段，避免超大 payload。
5. 新增消费处理器：
   • 只做任务入库，不做重型 LLM 调用。
6. 启动期接线：
   • 在 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. 新增最小管理接口：
   • GET /api/v1/memory/items
   • DELETE /api/v1/memory/items/:id
   • POST /api/v1/memory/settings（开关）
5. 完成首版日志埋点：
   • 检索命中数、注入条数、门控丢弃原因。

Day 2 验收标准

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

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

目标

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

任务清单

1. 实现/预留向量接口：
   • VectorStore.Upsert()
   • VectorStore.Search()
   • VectorStore.Delete()
2. 对接 Milvus（可选）：
   • collection 初始化。
   • 向量 + 元数据过滤检索。
3. 指标体系落地：
   • 记忆命中率（retrieved/useful）
   • 错误提及率（wrong mention）
   • 用户纠正率（user correction）
   • 回复延迟影响（P50/P95）
4. 准备演示脚本与面试问答稿：
   • 5 分钟架构说明。
   • 3 个典型失败案例及兜底策略。
   • 未来迭代路线。

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. memory_type varchar(32)
   • preference（偏好）
   • constraint（硬约束）
   • fact（事实）
   • todo_hint（近期提醒线索）
5. title varchar(128)
6. content text
7. normalized_content text（去噪后）
8. confidence decimal(5,4)（0~1）
9. importance decimal(5,4)（0~1）
10. sensitivity_level tinyint
    • 0 普通
    • 1 中敏
    • 2 高敏
11. source_message_id bigint
12. source_event_id varchar(64)
13. is_explicit tinyint(1)（是否用户明确要求记住）
14. status varchar(16)
    • active
    • archived
    • deleted
15. ttl_at datetime（到期时间）
16. last_access_at datetime
17. created_at datetime
18. updated_at datetime

索引建议：

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.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. payload_json longtext
8. status varchar(16)
   • pending
   • processing
   • success
   • failed
   • dead
9. retry_count int
10. max_retry int
11. next_retry_at datetime
12. last_error varchar(2000)
13. created_at datetime
14. updated_at datetime

索引建议：

1. (status, next_retry_at, id)
2. (user_id, created_at desc)
3. (source_event_id)（幂等与追踪）

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. source_message_id
4. source_role
5. source_text
6. occurred_at
7. trace_id

设计约束：

1. Payload 只放执行需要的最小字段。
2. 大文本允许截断并保留摘要，防止消息膨胀。
3. 必须包含幂等标识（如 source_message_id + user_id）。

7. 写入流程详细设计

7.1 主流程

1. 聊天主链路完成并落历史消息。
2. 发布 memory.extract.requested 到 Outbox。
3. Outbox 消费处理器验证 payload。
4. 处理器创建或幂等更新 memory_jobs（仅任务入库）。
5. memory/worker 扫描 pending 任务并抢占为 processing。
6. Worker 调用 LLM 执行“候选记忆抽取”。
7. 执行标准化（时间归一化、实体归一化、噪声去除）。
8. 执行冲突消解（同类偏好最新优先、互斥约束降权）。
9. 计算分值（置信度、重要度、时效度）。
10. 写入 memory_items 与审计日志。
11. 触发向量化（同步或异步二选一）。
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 重试导致的重复消费必须无副作用。

8. 读取流程详细设计

8.1 主流程

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

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

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. 幂等去重函数。

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. “我们用命中率、误提率、纠正率三项核心指标验证记忆是否真的有价值。”

15. DoD（完成定义）

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

16. 本轮执行顺序建议

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

---

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