docs: add multi-agent memory best practices and scaffold script

README.md

@@ -274,3 +274,75 @@ gateway 已对本地 `GIT_REMOTE_URL` 自动添加 `safe.directory`。
 - Git 管理：[gateway/app/git_manager.py](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/gateway/app/git_manager.py)
 - QMD 调用：[gateway/app/qmd_client.py](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/gateway/app/qmd_client.py)
 - Compose 编排：[docker-compose.yml](/home/lingyuzeng/project/qmd-local/qmd-docker-http-mcp/docker-compose.yml)
+
+## 14. 多 Agent 记忆仓库最佳实践
+
+### 14.1 子记忆仓库怎么放
+
+建议把“记忆系统仓库”单独管理，并在本项目中通过 `.gitignore` 忽略运行态 clone/mirror/workspace。
+
+- 推荐：独立 memory repo（独立 push/pull 生命周期）
+- 不推荐主方案：submodule（多 agent 高频写入时维护成本高、冲突处理复杂）
+
+### 14.2 推荐目录结构（memory repo 内）
+
+```text
+memory-repo/
+├─ shared/
+│  ├─ announcements/
+│  └─ sop/
+├─ agents/
+│  ├─ agent-a/
+│  │  ├─ AGENT-CARD.md
+│  │  ├─ MEMORY-LOG.md
+│  │  ├─ PROMPT-RULES.md
+│  │  ├─ inbox/
+│  │  ├─ working/
+│  │  ├─ handoff/
+│  │  └─ checkpoints/
+├─ tasks/
+│  └─ TASK-001/
+└─ policies/
+   └─ WRITE-PERMISSIONS.yaml
+```
+
+### 14.3 每个子 Agent 的脚手架
+
+本仓库提供脚手架脚本：`scripts/scaffold-agent-memory.sh`
+
+示例：
+
+```bash
+./scripts/scaffold-agent-memory.sh \
+  --repo /path/to/memory-repo \
+  --agent agent-a \
+  --default-branch main
+```
+
+作用：
+
+- 生成 `agents/<agent-id>/` 标准目录
+- 生成 `AGENT-CARD.md`（身份与可写路径声明）
+- 生成 `PROMPT-RULES.md`（写前 pull、冲突处理规则）
+- 生成 `policies/WRITE-PERMISSIONS.yaml`
+
+### 14.4 多 Agent 同步与冲突最小化策略
+
+1. 写入前固定执行：`git pull --rebase origin <branch>`
+2. 尽量 append-only，减少多人改同一行
+3. 原子小提交（按一次记忆动作提交）
+4. 推送失败先 rebase，再自动合并一次；仍冲突则人工解决
+5. 共享目录写权限建议通过 gateway 或服务端 hook 校验，避免越权路径写入
+
+### 14.5 与 QMD/gateway 的关系
+
+- Git 仓库负责“真相源”和版本历史
+- gateway 负责查询前同步和分支/工作区隔离
+- qmd 负责本地索引与检索
+
+这样可以同时满足：
+
+- 多 agent 共享记忆
+- 查询一致性
+- 冲突可控
+- 结果可追溯（branch + commit）