diff --git a/rootfs/usr/local/share/pi-devbox/pi-global-AGENTS.append.md b/rootfs/usr/local/share/pi-devbox/pi-global-AGENTS.append.md index 48929fe..10cc839 100644 --- a/rootfs/usr/local/share/pi-devbox/pi-global-AGENTS.append.md +++ b/rootfs/usr/local/share/pi-devbox/pi-global-AGENTS.append.md @@ -41,3 +41,32 @@ especially load-bearing here — a pi-devbox container is frequently recreated, the palace is your only memory across recreates. Without the habit it is just storage, not memory. (The skill is the consumer side; feeding the palace is the separate `opencode-mempalace-bridge` skill, if present.) + +### If the palace is central, it is shared — three rules + +If `MEMPALACE_REMOTE_URL` is set, the MCP tools write to a **central palace +shared with other machines**, not to a local one. Your drawers are not the only +ones in there, and most drawers' `source_file` paths do not exist on this host. +The skill covers the orientation side (provenance, chronology, whose diary is +whose); these three are here instead because getting them wrong does *damage* +rather than merely confusing you: + +- **Never run `mempalace sync` / `mempalace_sync` against a shared palace.** It + prunes drawers whose source files look gitignored, deleted, or moved — and on + a shared palace that describes most of the content, including every other + machine's. Compounding it (RFC-001 §7.2): feeders now stage *inside* the + palace root, so a scoped sync can delete the very drawers it just filed. + `mempalace_delete_by_source` is exact-match rather than existence-based, but + its blast radius is now the whole fleet's palace — leave it on its default + `dry_run=true` and confirm the match count before committing. +- **A timeout is not a failure.** The palace is single-writer, and one large + mine can block every client for minutes, so a write or mine that exceeds the + client's deadline has usually *completed* server-side. Verify with + `mempalace_get_drawer` or `mempalace_search` before retrying — a blind retry + files a duplicate. `[mempalace ext] feed (tick) failed: mine timed out after + 30000ms` is the common benign instance: the transcript is already in the + server's inbox and the mine is idempotent, so nothing is lost either way. +- **The `mempalace` CLI is not remote-aware.** It always opens a palace on + local disk, so `mempalace search` can return older and different results than + the MCP tools while both look correct. Use the MCP tools for the central + palace; the CLI only for a local one.