# 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` 显示已注入，但回答只拿到旧的无关记忆。

## 必须保留的行为

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 来保证新记忆可立即召回。

## 回归检查

```bash
node --test 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 同时执行：

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

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

## 回滚

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