From aabab0c7656cafefd6beae27fb4bf2324f376c0a Mon Sep 17 00:00:00 2001
From: lingyuzeng <lingyuzeng@example.com>
Date: Sat, 7 Mar 2026 23:53:28 +0800
Subject: [PATCH] docs: add multi-agent memory best practices and scaffold
 script

---
 README.md                        |  72 +++++++++++++++++
 scripts/scaffold-agent-memory.sh | 130 +++++++++++++++++++++++++++++++
 2 files changed, 202 insertions(+)
 create mode 100755 scripts/scaffold-agent-memory.sh

diff --git a/README.md b/README.md
index 8141e8b..6203825 100644
--- a/README.md
+++ b/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）
diff --git a/scripts/scaffold-agent-memory.sh b/scripts/scaffold-agent-memory.sh
new file mode 100755
index 0000000..c70d54d
--- /dev/null
+++ b/scripts/scaffold-agent-memory.sh
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Create a standard folder scaffold for one agent inside an existing memory git repository.
+# Usage:
+#   ./scripts/scaffold-agent-memory.sh --repo /path/to/memory-repo --agent agent-a
+
+REPO_ROOT=""
+AGENT_ID=""
+DEFAULT_BRANCH="main"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --repo)
+      REPO_ROOT="$2"; shift 2 ;;
+    --agent)
+      AGENT_ID="$2"; shift 2 ;;
+    --default-branch)
+      DEFAULT_BRANCH="$2"; shift 2 ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 1 ;;
+  esac
+done
+
+if [[ -z "${REPO_ROOT}" || -z "${AGENT_ID}" ]]; then
+  echo "Usage: $0 --repo <memory-repo-path> --agent <agent-id> [--default-branch main]" >&2
+  exit 1
+fi
+
+if [[ ! -d "${REPO_ROOT}" ]]; then
+  echo "Repo path does not exist: ${REPO_ROOT}" >&2
+  exit 1
+fi
+
+if [[ ! -d "${REPO_ROOT}/.git" ]]; then
+  echo "Not a git repository: ${REPO_ROOT}" >&2
+  exit 1
+fi
+
+agent_dir="${REPO_ROOT}/agents/${AGENT_ID}"
+shared_dir="${REPO_ROOT}/shared"
+policy_dir="${REPO_ROOT}/policies"
+
+mkdir -p "${agent_dir}/inbox" \
+         "${agent_dir}/working" \
+         "${agent_dir}/handoff" \
+         "${agent_dir}/checkpoints" \
+         "${shared_dir}/announcements" \
+         "${shared_dir}/sop" \
+         "${policy_dir}"
+
+if [[ ! -f "${agent_dir}/AGENT-CARD.md" ]]; then
+cat > "${agent_dir}/AGENT-CARD.md" <<EOF
+# Agent Card: ${AGENT_ID}
+
+## Identity
+- agent_id: ${AGENT_ID}
+- default_branch: ${DEFAULT_BRANCH}
+
+## Writable Paths
+- agents/${AGENT_ID}/**
+- shared/announcements/**
+
+## Read-Only Preferred Paths
+- shared/sop/**
+- policies/**
+
+## Sync Rules
+1. Before write: git pull --rebase origin ${DEFAULT_BRANCH}
+2. After write: git add + git commit (small and atomic)
+3. Push immediately to reduce drift
+4. If conflict: auto-merge once, then manual resolve
+EOF
+fi
+
+if [[ ! -f "${agent_dir}/MEMORY-LOG.md" ]]; then
+cat > "${agent_dir}/MEMORY-LOG.md" <<EOF
+# ${AGENT_ID} Memory Log
+
+Append-only operational memory entries.
+EOF
+fi
+
+if [[ ! -f "${agent_dir}/PROMPT-RULES.md" ]]; then
+cat > "${agent_dir}/PROMPT-RULES.md" <<'EOF'
+# Prompt Rules
+
+- Always `git pull --rebase` before editing memory files.
+- Prefer appending new notes over editing old notes.
+- Commit frequently with narrow scope.
+- If rebase conflict occurs, try one automatic resolution, otherwise stop and ask for manual merge.
+EOF
+fi
+
+if [[ ! -f "${policy_dir}/WRITE-PERMISSIONS.yaml" ]]; then
+cat > "${policy_dir}/WRITE-PERMISSIONS.yaml" <<'EOF'
+version: 1
+rules:
+  - pattern: "agents/*/**"
+    write: ["owner"]
+  - pattern: "shared/announcements/**"
+    write: ["all_agents"]
+  - pattern: "shared/sop/**"
+    write: ["maintainers"]
+EOF
+fi
+
+if [[ ! -f "${REPO_ROOT}/README-memory-layout.md" ]]; then
+cat > "${REPO_ROOT}/README-memory-layout.md" <<'EOF'
+# Memory Repository Layout
+
+- agents/<agent-id>/ : private working memory
+- shared/announcements/ : multi-agent shared updates
+- shared/sop/ : stable SOP and rules
+- policies/ : write permission policy metadata
+EOF
+fi
+
+cd "${REPO_ROOT}"
+if ! git diff --quiet || ! git diff --cached --quiet; then
+  :
+fi
+
+echo "Scaffold created for agent '${AGENT_ID}' at ${agent_dir}"
+
+echo "Next steps:"
+echo "1) Review and adjust ${agent_dir}/AGENT-CARD.md"
+echo "2) git add agents/${AGENT_ID} shared policies README-memory-layout.md"
+echo "3) git commit -m 'chore: scaffold memory space for ${AGENT_ID}'"