记忆系统状态机实战：backend 选择、fallback、自愈与 scope guard

这一章是实现手册，补齐 记忆系统 中“怎么写代码”的部分。

对应源码入口（可选）

• src/memory/backend-config.ts
• src/memory/search-manager.ts
• src/memory/qmd-manager.ts
• src/agents/tools/memory-tool.ts
• src/gateway/server-startup-memory.ts

状态机拆解（建议按这三层写）

1. 配置解析层：把配置解析成运行时结构（backend/citations/limits/scope）。
2. manager 获取层：尝试 primary（qmd），失败回落 fallback（builtin）。
3. 工具层：memory_search / memory_get 暴露给智能体；失败要“安全降级”，不能打崩主对话。

最关键的自愈点：失败后驱逐缓存条目

如果 primary manager 初始化失败或 search 出错，应该：

• 标记 primaryFailed
• 关闭 primary
• 驱逐缓存条目（下次允许重新创建 primary）

否则系统会“永久复用一个已坏的实例”，线上很难自愈。

scope guard：权限边界不是后端故障

scope 不允许时返回空结果（或 disabled），不要抛错误把主链路打崩。

失败场景与排障入口

• qmd 依赖缺失/命令不可用：应自动回退到 builtin，并在 日志 中留下可读原因。
• 记忆泄漏到群聊/频道：优先检查 scope 规则与 sessionKey 的匹配方式（参见 会话管理）。

验收清单

1. primary 失败会自动切 fallback，且主对话可继续完成。
2. 驱逐缓存后，下次请求会重试创建 primary。
3. scope 不匹配时返回空结果，不报错。
4. 工具层在 manager 不可用时返回 disabled，而不是 throw。