docs: reconcile the RFC-001 docs with what is actually deployed
Audit of every doc touching the global-palace rollout against the running
fleet. Each correction below was verified against the filesystem or the host,
not against another doc:
- synlig-primary-runbook: the decommission `rm -rf ~/.mempalace` now carries a
STOP block. That tree holds the fleet palace *and* the only copy of the
bearer token every client authenticates with; the old "empty today" comment
stopped being true when the palace was seeded on 2026-08-14. Adds an ordered
safe decommission, and drops count-based join verification.
- phase-1-exposure-runbook: new S3.8, how to verify a flip actually took --
the procedure that until now existed only in an untracked handover file.
Three claims that fail independently (env var / curl / the palace-path
discriminator) plus an explicit list of checks that produce FALSE POSITIVES:
drawer counts (both sides were seeded from the same palace, and `status`
counts chunks not drawers), write-then-read through the same transport, and
the `mempalace` CLI -- which has no remote support at all, so post-flip it
reads the dead local archive and reports success.
- rfc-001: status Draft -> Phases 0-1 implemented. Records that the join was a
file-level copy, which SIDESTEPPED the S7.6 diary-dedup question rather than
answering it -- so S7.6 remains a hard blocker for the second machine, which
is the one that will actually exercise merge semantics.
- ARCHITECTURE, SKILL, contrib/README, extensions/pi/README all claimed pi
feeds the palace automatically, unconditionally. That is gated on
mempalace-toolkit >= 29e660e and every deployed image predates it, so the
claim is currently false fleet-wide. Each site now states the gate plus a
check that inspects the *deployed* file rather than repo HEAD.
- extensions/pi/README: plaintext http://mempalace.lan example -> https
endpoint; the two transports are either/or (no dual-write, no local mirror);
the bridge fails CLOSED, so "the agent has no mempalace_* tools" is the
expected symptom of a server/token/DNS fault, not of a broken install.
- contrib/README: documents mempalace-serve.service, which this directory has
shipped since day one without explaining it (linger, the load-bearing
172.17.0.1 bind and why loopback is the unsafe-looking-safe option, the
token path, and an uninstall warning).
- Fixes a pre-existing stray ```sh fence that was swallowing S3.2's heading and
the token command into a code block.
Docs only; no behaviour change.
This commit is contained in:
+61
-5
@@ -40,7 +40,10 @@ dependencies (~300 MB).
|
||||
describes. Skipped on resume/fork (context is already in the thread).
|
||||
4. **Automatic transcript feeding** (`session_shutdown`, and a debounced
|
||||
`agent_settled`): stages + mines this pi installation's own session
|
||||
transcripts into the palace with no user action needed. Unlike the diary
|
||||
transcripts into the palace with no user action needed — **as of
|
||||
mempalace-toolkit `29e660e` (2026-08-12); see the version gate below,
|
||||
because "the extension is installed" does not imply "this copy can feed"**.
|
||||
Unlike the diary
|
||||
below, this needs no LLM turn — it's a subprocess + a tool call — so it
|
||||
*can* run on `session_shutdown` where the diary cannot. See
|
||||
[Automatic transcript feeding](#automatic-transcript-feeding).
|
||||
@@ -53,6 +56,26 @@ dependencies (~300 MB).
|
||||
|
||||
## Automatic transcript feeding
|
||||
|
||||
> **⚠️ Version gate — requires mempalace-toolkit ≥ `29e660e` (2026-08-12), and "installed" is not
|
||||
> the same question as "capable".** Feeding was added to this extension on 2026-08-12. A copy baked
|
||||
> into a container image built before that date has *no* feed path at all — its entire
|
||||
> `session_shutdown` handler is `client.stop()` — and it fails the only way a memory system must not:
|
||||
> silently, looking exactly like a healthy run with nothing to do.
|
||||
>
|
||||
> **Check the deployed artifact, never the repo.** `/opt/*` in an image is baked at build time and can
|
||||
> be days behind a bind-mounted clone, and `~/.pi/agent/extensions/mempalace.ts` is usually a symlink
|
||||
> *into* that baked copy:
|
||||
>
|
||||
> ```sh
|
||||
> grep -c MEMPALACE_FEED "$(readlink -f ~/.pi/agent/extensions/mempalace.ts)" # 0 = cannot feed
|
||||
> ```
|
||||
>
|
||||
> Zero hits means this machine needs the fallback recipes in
|
||||
> [`contrib/`](../../contrib/README.md) until it is rebuilt, regardless of what the toolkit repo's HEAD
|
||||
> looks like. Date the deployed copy with `stat` plus that content probe — not `git log`, which fails
|
||||
> with *"detected dubious ownership"* inside a root-owned `/opt` tree. As of 2026-08-14 the whole
|
||||
> pi-devbox fleet fails this check.
|
||||
|
||||
The bridge feeds this pi installation's own session transcripts into the
|
||||
palace by itself — no scheduler, no cron, no manual invocation. It fires on
|
||||
`session_shutdown` (covers quit, `/new`, `/resume`, `/fork`) and on a
|
||||
@@ -117,10 +140,27 @@ chosen at load time:
|
||||
lives wherever that process opens it (default `~/.mempalace`). This is the
|
||||
hardened path with per-request timeouts and respawn/self-heal (below).
|
||||
- **External** — set `MEMPALACE_REMOTE_URL` to a MemPalace HTTP endpoint (e.g.
|
||||
`http://mempalace.lan:8765/mcp`) and the bridge connects over HTTP instead,
|
||||
spawning no local process. Use this to share **one** palace across several
|
||||
harnesses/containers (pi + opencode + native). `MEMPALACE_REMOTE_TOKEN`, if
|
||||
set, is sent as `Authorization: Bearer <token>`.
|
||||
`https://mempalace.jordbo.se/mcp`, the live fleet primary — full path
|
||||
including `/mcp`, no trailing slash) and the bridge connects over HTTP
|
||||
instead, spawning no local process. Use this to share **one** palace across
|
||||
several harnesses/containers (pi + opencode + native).
|
||||
`MEMPALACE_REMOTE_TOKEN`, if set, is sent as `Authorization: Bearer <token>`.
|
||||
Use `https://` for anything crossing a network — the plaintext `http://`
|
||||
example that stood here until 2026-08-14 predated the reverse proxy.
|
||||
|
||||
The two transports are **either/or**, decided once at load time: with the URL
|
||||
set, writes go **only** to the remote palace. There is no dual-write, no
|
||||
local mirror, and no local `mempalace-mcp` process at all.
|
||||
|
||||
⚠️ **Consequence: once `MEMPALACE_REMOTE_URL` is set, the `mempalace` CLI on
|
||||
that machine is no longer a valid way to inspect or feed the palace the agent
|
||||
is using.** The CLI has no remote support whatsoever — its only selector is
|
||||
`--palace <path>` — so it reads and writes the LOCAL on-disk archive. After a
|
||||
flip that archive is frozen, yet `mempalace status` / `mempalace search`
|
||||
still report a plausible drawer count and look exactly like success: a
|
||||
false-positive machine. Memories filed with the CLI post-flip land in the
|
||||
dead archive, not in the shared palace. Use the agent's own palace tools
|
||||
(which go over HTTP), and mine backfills **on the palace host**.
|
||||
|
||||
Serve such an endpoint with `mempalace serve --host 172.17.0.1 --port 8765`
|
||||
(the `pi-devbox` / `opencode-devbox` repos ship a
|
||||
@@ -155,6 +195,22 @@ If `mempalace-mcp` can't be spawned (PATH missing, binary crashes at
|
||||
startup, …) the extension logs to stderr and returns early. pi keeps
|
||||
working without palace tools rather than refusing to start.
|
||||
|
||||
**In remote mode the triggers differ but the outcome is identical.** An
|
||||
unreachable server, a DNS failure, or an HTTP 401 from a wrong/expired token
|
||||
all end the same way: after bounded retries the extension prints
|
||||
`mempalace-mcp unavailable after retries; continuing without palace tools` and
|
||||
**does not register the palace tools**.
|
||||
|
||||
It is **fail-closed, not fail-local**: it does *not* quietly fall back to the
|
||||
local palace, so a remote outage can never scatter memories into a local copy
|
||||
nobody will look at again. The practical corollary, worth knowing before you
|
||||
debug the wrong layer: **"the agent has no `mempalace_*` tools" is the
|
||||
expected symptom of a server, token, or DNS fault**, not of a broken install.
|
||||
Diagnose it with a direct `curl` to `MEMPALACE_REMOTE_URL` — see
|
||||
[`docs/phase-1-exposure-runbook.md`](../../docs/phase-1-exposure-runbook.md)
|
||||
§3.8. The design rationale for de-registering rather than degrading is in
|
||||
[`docs/rfc-001-global-palace.md`](../../docs/rfc-001-global-palace.md) §2 and §4.1.
|
||||
|
||||
## Identity
|
||||
|
||||
`agent_name` for diary calls comes from `$MEMPALACE_AGENT_NAME`, defaulting
|
||||
|
||||
Reference in New Issue
Block a user