memind/docs/regression-guards/memory-v2-candidate-and-lifecycle.md

Memory V2 候选表与生命周期灰度守卫

已知故障

生产曾出现 h5_memory_v2_candidates 不存在：候选记忆写入和后台查询报错， 但 Agent 召回仍在 shadow 模式执行，因此表现为“有召回事件、回答未注入、个人记忆状态降级”。

同时，生命周期 worker 只检查了 worker 开关；expire() 没有检查 rollout 作用域。若忘却开关开启，即使 MEMORY_LIFECYCLE_ROLLOUT_MODE=off，定时器也可能 归档全量用户的过期记忆。

灰度还曾出现 MySQL 已成功保存新记忆，但 pgvector 仍只包含旧数据：runtime 从全局 updated_at=0 游标开始做有限批次 backfill，新写入行可能长期排在批次之外。结果是 agent_memory_resolved 显示已注入，但回答只拿到旧的无关记忆。

首次修复同步后，灰度又发现 remember-recent 读取的是 Agent 编排后的会话文本，其中 包含已注入的 [Memory Context]。提取器因此可能把旧记忆再次沉淀，而忽略用户本轮明确 要求保存的内容，形成旧记忆自我复制。

提取器返回 {"memories":[]} 时，旧逻辑仍会触发规则回退，可能把“……是什么”一类 问句误存为事实。空数组必须视为成功的“无需保存”判断；只有提取不可用并返回 null 时才允许规则回退。

当前生产使用的本地 hash embedding 只有 3 维，且连续中文可能被视为单个 token。即使正确 记忆已进入 pgvector，它也可能排在向量 Top-K 之外。因此 pgvector 读取必须合并有界的 向量候选与最近候选，再以中文字符 n-gram 查询覆盖率重排；无词法重合时保持向量排序。

必须保留的行为

1. MEMORY_CANDIDATE_PERSISTENCE_ENABLED=1 且 MySQL 可用时，Portal 必须先执行 ensurePersonalMemoryCandidateSchema()，再创建候选记忆 store。
2. 候选表 DDL 失败不能阻塞 Portal 聊天启动；Portal 应记录告警并退回 bounded-memory。
3. memind_adm 必须在创建候选 store 前完成同一幂等建表；初始化失败时后台启动失败， 不允许以“页面可用但候选接口持续报错”的半初始化状态运行。
4. 生命周期 rollout 语义必须严格一致：
   • off：不得执行任何写操作，也不得启动 worker 定时器。
   • canary：只允许 MEMORY_LIFECYCLE_ROLLOUT_USER_IDS 中的用户。
   • active：才允许无 user scope 的全局任务。
5. forgetMemory() 和 expire() 都必须同时满足功能开关与 rollout 作用域。
6. 用户记忆 write/compact 成功后，必须在返回前按 userId + sessionId 将本次活跃记忆 幂等 upsert 到 pgvector；候选晋升成功后也必须按实际晋升用户同步。不得依赖从零开始 的全局有限批次 backfill 来保证新记忆可立即召回。
7. 显式记忆提取必须优先使用同一用户、同一会话中已成功 h5_agent_runs.user_message_json 保存的原始用户消息。不得把 Agent 编排提示或 [Memory Context] 当作用户的新记忆； 原始消息查询失败时必须 fail-open 到现有可见会话，不能阻塞保存接口。
8. pgvector 召回必须同时覆盖有界向量候选和有界最近候选，去重后只返回请求的 limit； 中文词法重排用于弥补低维本地 hash 的排序缺陷，且候选池上限不得超过 100。
9. LLM 提取明确返回空数组时不得再走规则回退；提取提示必须明确排除没有提供答案的 问题、请求、指令和待办，避免把问句本身沉淀为长期记忆。

回归检查

node --test conversation-memory.test.mjs conversation-repair.test.mjs memory-v2-personal-store.test.mjs memory-v2-lifecycle.test.mjs \
  memory-v2-pgvector-backfill.test.mjs memory-v2-runtime.test.mjs
npm test

memind_adm 同时执行：

node --test server/personal-memory-candidate-store.test.mjs
npm test

灰度上线后还必须验证：候选表存在、候选写入成功、后台可查询，以及一个测试用户完成 “保存 → 候选 → 晋升 → 新会话召回 → 回答注入”的闭环。未通过前不得切换全量 active。

回滚

代码可以按标准 runtime/release 回滚；候选表是加法结构，回滚时保留空表或已有数据， 不得为了代码回滚直接删除表。先把候选、生命周期和 Agent 注入模式切回 shadow/off。