feat(bootstrap): add shared session bootstrap and machine-alias resolver

policies/MACHINE-ALIASES.yaml

@@ -0,0 +1,14 @@
+version: 1
+machines:
+  - hostname: mac-5
+    aliases: mac5,control,openclaw-control
+    default_agent_suffix: mac5
+  - hostname: lingyuzeng-X99-TI-D4-PLUS
+    aliases: rtx2080ti,gpu-gateway,group
+    default_agent_suffix: rtx2080ti
+  - hostname: mac-6
+    aliases: mac6,executor,node-exec
+    default_agent_suffix: mac6
+  - hostname: mac-7
+    aliases: mac7,browser,node-browser
+    default_agent_suffix: mac7

policies/SESSION-BOOTSTRAP.md

@@ -0,0 +1,48 @@
+# SESSION BOOTSTRAP (Shared Memory)
+
+## 目标
+- 所有客户端（OpenClaw / Claude / Codex / Cursor）共享同一记忆系统。
+- Durable memory authority 是 `collective-memory-repo`。
+- 群体权威召回只认远程 `memory-gateway`。
+
+## 统一架构
+- Memory repo: `/Users/lingyuzeng/project/collective-memory-repo`
+- Gateway URL: `http://100.64.0.45:8787`
+- Gateway MCP URL: `http://100.64.0.45:8787/mcp`
+- 记忆层规则：
+  - 共享长期事实：`shared/long-term/`
+  - 每日记录：`daily/`
+  - 任务协作：`tasks/<task-id>/`
+  - Agent 私域：`agents/<agent-id>/`
+
+## 分支规则
+- 长期协作默认：`branch=main`
+- 并发任务协作：`branch=task/<task-id>`
+- 群体查询必须带：`require_latest=true`
+
+## 读写规则
+- Runtime 文件（persona/tools/heartbeat）留在各自本机 runtime 目录。
+- Durable facts 只能写入 `collective-memory-repo` 的对应 lane。
+- `vaults/memory/*` 是兼容区，不是长期真相源。
+
+## 会话初始化必填上下文
+在新会话第一条消息中提供：
+- `machine_hostname`
+- `machine_alias`
+- `agent_id`
+- `memory_branch`（默认 `main`）
+- `task_id`（如有）
+
+## 示例（首条消息）
+```text
+@/Users/lingyuzeng/project/collective-memory-repo/policies/SESSION-BOOTSTRAP.md
+machine_hostname=mac-5
+machine_alias=mac5
+agent_id=codex-mac5
+memory_branch=main
+```
+
+## MCP 接入要求
+- 先在客户端注册 MCP server（URL 指向 `...:8787/mcp`）。
+- 再通过 `@SESSION-BOOTSTRAP.md` 注入架构与规则。
+- 客户端本地检索可保留，但群体结论以 gateway 结果为准。

scripts/print-session-bootstrap.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/print-session-bootstrap.sh [--tool <tool>] [--branch <branch>] [--task-id <id>] [--gateway-url <url>] [--hostname <name>]
+
+Prints a ready-to-paste first message for Claude/Codex/Cursor/OpenClaw sessions.
+USAGE
+}
+
+TOOL="codex"
+BRANCH="main"
+TASK_ID=""
+GATEWAY_URL="http://100.64.0.45:8787"
+HOSTNAME_INPUT=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --tool)
+      TOOL="${2:-}"
+      shift 2
+      ;;
+    --branch)
+      BRANCH="${2:-}"
+      shift 2
+      ;;
+    --task-id)
+      TASK_ID="${2:-}"
+      shift 2
+      ;;
+    --gateway-url)
+      GATEWAY_URL="${2:-}"
+      shift 2
+      ;;
+    --hostname)
+      HOSTNAME_INPUT="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "ERROR: unknown arg: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+ARGS=(--field all --tool "$TOOL")
+if [[ -n "$HOSTNAME_INPUT" ]]; then
+  ARGS+=(--hostname "$HOSTNAME_INPUT")
+fi
+INFO="$($REPO_ROOT/scripts/resolve-machine-alias.sh "${ARGS[@]}")"
+
+hostname_v="$(printf '%s\n' "$INFO" | awk -F= '$1=="hostname"{print $2}')"
+alias_v="$(printf '%s\n' "$INFO" | awk -F= '$1=="alias"{print $2}')"
+agent_id_v="$(printf '%s\n' "$INFO" | awk -F= '$1=="agent_id"{print $2}')"
+
+cat <<OUT
+@/Users/lingyuzeng/project/collective-memory-repo/policies/SESSION-BOOTSTRAP.md
+machine_hostname=${hostname_v}
+machine_alias=${alias_v}
+agent_id=${agent_id_v}
+memory_branch=${BRANCH}
+memory_gateway=${GATEWAY_URL}
+OUT
+
+if [[ -n "$TASK_ID" ]]; then
+  echo "task_id=${TASK_ID}"
+fi

scripts/resolve-machine-alias.sh

@@ -0,0 +1,177 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/resolve-machine-alias.sh [--hostname <name>] [--field alias|suffix|agent-id|all] [--tool <tool>]
+
+Defaults:
+  --hostname: current host shortname (hostname -s)
+  --field: all
+  --tool: openclaw
+
+Reads mapping from policies/MACHINE-ALIASES.yaml.
+USAGE
+}
+
+HOSTNAME_INPUT="$(hostname -s 2>/dev/null || hostname)"
+FIELD="all"
+TOOL="openclaw"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --hostname)
+      HOSTNAME_INPUT="${2:-}"
+      shift 2
+      ;;
+    --field)
+      FIELD="${2:-}"
+      shift 2
+      ;;
+    --tool)
+      TOOL="${2:-}"
+      shift 2
+      ;;
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "ERROR: unknown arg: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+case "$FIELD" in
+  alias|suffix|agent-id|all) ;;
+  *)
+    echo "ERROR: --field must be one of alias|suffix|agent-id|all" >&2
+    exit 1
+    ;;
+esac
+
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+if [[ -z "$REPO_ROOT" ]]; then
+  echo "ERROR: run inside collective-memory-repo" >&2
+  exit 2
+fi
+
+MAP_FILE="$REPO_ROOT/policies/MACHINE-ALIASES.yaml"
+if [[ ! -f "$MAP_FILE" ]]; then
+  echo "ERROR: mapping file not found: $MAP_FILE" >&2
+  exit 2
+fi
+
+trim() {
+  local s="$1"
+  s="${s#${s%%[![:space:]]*}}"
+  s="${s%${s##*[![:space:]]}}"
+  printf '%s' "$s"
+}
+
+contains_csv_value() {
+  local csv="$1"
+  local needle="$2"
+  IFS=',' read -r -a parts <<< "$csv"
+  for p in "${parts[@]}"; do
+    if [[ "$(trim "$p")" == "$needle" ]]; then
+      return 0
+    fi
+  done
+  return 1
+}
+
+record_hostname=""
+record_aliases=""
+record_suffix=""
+matched_alias=""
+matched_suffix=""
+matched_hostname=""
+found="false"
+
+finalize_record() {
+  if [[ "$found" == "true" || -z "$record_hostname" ]]; then
+    return
+  fi
+
+  if [[ "$HOSTNAME_INPUT" == "$record_hostname" ]]; then
+    found="true"
+  elif contains_csv_value "$record_aliases" "$HOSTNAME_INPUT"; then
+    found="true"
+  fi
+
+  if [[ "$found" == "true" ]]; then
+    matched_hostname="$record_hostname"
+    matched_suffix="$record_suffix"
+
+    if contains_csv_value "$record_aliases" "$HOSTNAME_INPUT"; then
+      matched_alias="$HOSTNAME_INPUT"
+    else
+      IFS=',' read -r first_alias _ <<< "$record_aliases"
+      matched_alias="$(trim "$first_alias")"
+    fi
+  fi
+}
+
+while IFS= read -r raw_line || [[ -n "$raw_line" ]]; do
+  line="${raw_line%%#*}"
+  line="$(trim "$line")"
+  [[ -z "$line" ]] && continue
+
+  if [[ "$line" =~ ^-[[:space:]]hostname:[[:space:]]*(.+)$ ]]; then
+    finalize_record
+    record_hostname="$(trim "${BASH_REMATCH[1]}")"
+    record_aliases=""
+    record_suffix=""
+    continue
+  fi
+
+  if [[ "$line" =~ ^aliases:[[:space:]]*(.+)$ ]]; then
+    record_aliases="$(trim "${BASH_REMATCH[1]}")"
+    continue
+  fi
+
+  if [[ "$line" =~ ^default_agent_suffix:[[:space:]]*(.+)$ ]]; then
+    record_suffix="$(trim "${BASH_REMATCH[1]}")"
+    continue
+  fi
+done < "$MAP_FILE"
+
+finalize_record
+
+if [[ "$found" != "true" ]]; then
+  # fallback: use normalized hostname directly
+  fallback_suffix="$(printf '%s' "$HOSTNAME_INPUT" | tr '[:upper:]' '[:lower:]' | tr -cs 'a-z0-9-' '-')"
+  fallback_suffix="${fallback_suffix#-}"
+  fallback_suffix="${fallback_suffix%-}"
+  [[ -z "$fallback_suffix" ]] && fallback_suffix="host"
+
+  matched_hostname="$HOSTNAME_INPUT"
+  matched_alias="$fallback_suffix"
+  matched_suffix="$fallback_suffix"
+fi
+
+agent_id="${TOOL}-${matched_suffix}"
+
+case "$FIELD" in
+  alias)
+    printf '%s\n' "$matched_alias"
+    ;;
+  suffix)
+    printf '%s\n' "$matched_suffix"
+    ;;
+  agent-id)
+    printf '%s\n' "$agent_id"
+    ;;
+  all)
+    cat <<OUT
+hostname=$matched_hostname
+alias=$matched_alias
+suffix=$matched_suffix
+agent_id=$agent_id
+OUT
+    ;;
+esac

templates/AGENT-ONBOARDING.md

@@ -1,5 +1,16 @@
 # New Agent Onboarding Template
 
+## 0) Register MCP once per client
+
+- Codex:
+
+```bash
+codex mcp add memory-gateway --url http://100.64.0.45:8787/mcp
+```
+
+- Claude/Cursor: 在对应客户端 MCP 配置中添加同一 URL：
+  - `http://100.64.0.45:8787/mcp`
+
 ## 1) Create agent lane
 
 ```bash
@@ -19,7 +30,20 @@ scripts/add-agent.sh kimi-helper
 scripts/add-agent.sh <agent-id> --openclaw-config ~/.openclaw/openclaw.json
 ```
 
-## 3) Commit and push
+## 3) Session first message (recommended)
+
+```bash
+cd /Users/lingyuzeng/project/collective-memory-repo
+scripts/print-session-bootstrap.sh --tool codex --branch main
+```
+
+任务会话示例：
+
+```bash
+scripts/print-session-bootstrap.sh --tool codex --branch task/openclawd-migration-2026-03 --task-id openclawd-migration-2026-03
+```
+
+## 4) Commit and push
 
 ```bash
 git add agents/<agent-id>
@@ -27,7 +51,7 @@ git commit -m "feat(agent): add <agent-id> memory lane"
 git push
 ```
 
-## 4) Verify memory-gateway visibility
+## 5) Verify memory-gateway visibility
 
 ```bash
 curl -fsS http://100.64.0.45:8787/health
@@ -36,7 +60,7 @@ printf '{"branch":"main","require_latest":true}' \
   http://100.64.0.45:8787/memory/status
 ```
 
-## 5) Query smoke test
+## 6) Query smoke test
 
 ```bash
 printf '{"query":"<agent-id>","branch":"main","require_latest":true,"top_k":3}' \