docs(memory): document and harden hybrid gateway setup

app-instance/backend/README.md

@@ -27,3 +27,38 @@
 ## 说明
 
 后端已切到 Beaver 主线，不再保留旧实现、vendored 第三方 runtime 或迁移期旧命名兼容入口。所有 agent 运行都复用 `beaver.engine`，多 agent 协调通过 Beaver 自有 coordinator 和 `ExecutionGraph` 表达。
+
+## Memory Gateway
+
+Curated memory 始终启用：每轮仍会冻结并注入 `MEMORY.md` / `USER.md`，原有
+`memory` 工具也保持可用。`hybrid` 模式会额外启用独立的 Memory Gateway 层，
+每轮先调用 `/memories/search`，正常完成后调用一次 `/memories/add`，成功后再调用
+一次 `/memories/flush`。两套存储不会互相同步、覆盖或去重。
+
+完整配置示例：
+
+```json
+{
+  "memory": {
+    "mode": "hybrid",
+    "gateway": {
+      "baseUrl": "http://127.0.0.1:8010",
+      "userId": "gateway_test_user",
+      "userKey": "uk_xxx",
+      "appId": "default",
+      "projectId": "default",
+      "scope": ["current_chat", "resources"],
+      "topK": 8,
+      "timeoutSeconds": 10
+    }
+  }
+}
+```
+
+- `memory` 整段缺失时，默认采用隐式 `hybrid`；Gateway 凭证不完整会告警并只运行 curated memory。
+- 显式配置 `"mode": "hybrid"` 时，`baseUrl`、`userId` 和 `userKey` 缺失会导致启动失败。
+- 配置 `"mode": "curated"` 可关闭 Gateway，curated memory 行为不变。
+- `userKey` 是密钥，不应写入日志、状态响应或提交到版本库。
+- 容器访问宿主机 Gateway 时不能使用容器内的 `127.0.0.1`。应让 Gateway 监听
+  `0.0.0.0`，并把 `baseUrl` 配成该 Docker 网络的宿主机网关地址。
+- 修改 memory 配置后需要重启 runtime，因为 Gateway 服务在 `EngineLoader` 启动时创建。