记忆系统：搜索/读取/回退/注入上限

这一章关注“记忆怎么落地才不会拖垮主对话”：可用、可回退、可观测，并控制注入成本。

入口：

• 记忆
• 工具组：group:memory

源码入口（可选）

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

系统结构（两层管理器 + 一层工具）

1. 配置解析：决定 backend（qmd/builtin）、limits、citations 等运行态参数
2. 管理器选择：优先 qmd，失败自动切 builtin（并可在线自愈）
3. 工具暴露：memory_search 先定位，memory_get 再按需读取片段

关键机制 1：FallbackManager + 缓存驱逐（在线自愈）

你需要的行为：

• primary（qmd）失败后切换到 fallback（builtin）
• 失败后主动驱逐缓存条目，让下次有机会重新创建 primary
• 工具层在 manager 不可用时返回“disabled/不可用”，而不是把主对话打崩

关键机制 2：scope guard（该不该搜）

要点：

• 对不允许的会话范围，返回空结果而非报错
• 这属于“权限边界”，不是“后端故障”

关键机制 3：注入上限（控制成本与窗口）

建议做法：

• 对搜索结果做总注入字符上限（例如 maxInjectedChars）
• 让 memory_get 只读取片段（from/lines），避免整文件注入

关键机制 4：启动预热（把故障前置）

如果 backend 需要外部依赖（向量索引/服务），建议在网关启动阶段探测可用性并输出明确日志。

失败场景与排障入口（至少记住一个）

• memory_search 返回 disabled/不可用：通常是 backend 初始化失败或依赖缺失；先从 日志 与 Doctor 定位原因，再确认是否需要回退到 builtin。
• 结果“挤爆上下文”或回复变慢：优先检查注入上限是否生效，以及是否用 memory_get 只读取必要片段（参见 记忆 与 压缩）。
• 群聊/频道意外召回记忆：优先检查 scope guard 的策略边界；不要把“权限边界问题”当作“后端故障”。

验收清单

1. primary 失败后能自动切 fallback，且不影响主对话完成。
2. 缓存驱逐后，下次可以重试 primary 的创建。
3. scope 不匹配时返回 []，不报错。
4. 注入上限生效，避免记忆挤爆上下文。