joakimp/mempalace-toolkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: reconcile the RFC-001 docs with what is actually deployed

Browse Source 
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:
Joakim Persson
2026-08-14 22:57:22 +02:00
parent 2293f1c89b
commit ec436ed3ad
7 changed files with 443 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
contrib/README.md
+76 -2
View File
@@ -1,11 +1,18 @@
# contrib/ — automation recipes for `mempalace-session` and `mempalace-pi-session`
Manual invocation of the session-mining wrappers is fine on a machine you actively drive. For long-running devboxes, a weekly automated mine keeps the palace fresh without thinking about it. This directory ships ready-to-use templates for two common scheduling mechanisms, for each wrapper.
Manual invocation of the session-mining wrappers is fine on a machine you actively drive. For long-running devboxes, a weekly automated mine keeps the palace fresh without thinking about it. This directory ships ready-to-use templates for two common scheduling mechanisms, for each wrapper — plus `systemd/mempalace-serve.service`, which is not a mining job at all but the **shared-palace server** ([its own section below](#mempalace-serveservice--the-shared-palace-server)).
> **pi machines: check whether you need this at all.** If the pi bridge
> extension (`extensions/pi/mempalace.ts`) is installed, it already feeds the
> extension (`extensions/pi/mempalace.ts`) is installed **and is ≥ `29e660e`
> (2026-08-12)**, it already feeds the
> palace by itself on `session_shutdown` and a debounced `agent_settled` —
> see [`extensions/pi/README.md` § Automatic transcript feeding](../extensions/pi/README.md#automatic-transcript-feeding).
> ⚠️ **"Installed" is not enough** — the pre-`29e660e` extension has no feed
> path at all, and a container image baked before that date ships exactly that
> copy. Check the *deployed* file, not the repo clone:
> `grep -c MEMPALACE_FEED "$(readlink -f ~/.pi/agent/extensions/mempalace.ts)"`
> — zero means the templates below are **not** optional on that machine. As of
> 2026-08-14 the entire pi-devbox fleet returns zero.
> The templates below were written when scheduling was the *only* path for
> both harnesses; that's still true for **opencode** (no such extension
> exists), but for pi they're now a fallback — useful for a bare pi install
@@ -29,11 +36,78 @@ Pick **one scheduler** (systemd *or* launchd *or* cron). The opencode and pi job
| `cron/mempalace-session.cron` | opencode → palace | Mon 03:00 |
| `cron/mempalace-pi-session.cron` | pi → palace | Tue 03:00 |
| `cron/mempalace-session-devbox.cron` | opencode (devbox) → palace | Mon 03:00 |
| `systemd/mempalace-serve.service` | **not a mining job** — runs the shared palace *server* | always-on |
The pi variants are drop-in copies of the opencode variants with script name and schedule updated; the install recipes below apply equally — just swap `mempalace-session` for `mempalace-pi-session` and the schedule day.
---
## `mempalace-serve.service` — the shared palace server
The odd one out in this directory: every other template *feeds* a palace on a schedule, this one
**serves** a palace over HTTP so several machines can share it (RFC-001). **This unit currently runs
the fleet primary on `synlig`** — serving since 2026-08-12, seeded 2026-08-14, and the palace behind
it is the only copy. Read [`docs/rfc-001-global-palace.md`](../docs/rfc-001-global-palace.md) and
[`docs/phase-1-exposure-runbook.md`](../docs/phase-1-exposure-runbook.md) before installing a second one.
It is a **user** unit (`systemctl --user`), so it dies with your login session unless lingering is
enabled — that is the one `sudo` this recipe needs:
```sh
# Install
mkdir -p ~/.config/systemd/user
cp contrib/systemd/mempalace-serve.service ~/.config/systemd/user/
sudo loginctl enable-linger "$USER" # else the server stops when you log out
systemctl --user daemon-reload
systemctl --user enable --now mempalace-serve
# Verify — both lines matter
curl -s 172.17.0.1:8765/healthz # -> ok
curl -s localhost:8765/healthz # -> connection refused (exit 7), and that is CORRECT
# Logs
journalctl --user -u mempalace-serve -f
```
The unit refuses to start if `~/.mempalace/palace` does not exist (`ConditionPathExists`) — better a
clear failure than a server quietly creating an empty palace somewhere unexpected.
**Why it binds `172.17.0.1` and not loopback**, since this looks backwards and is the single most
load-bearing line in the file: mempalace pins the HTTP `Host` header to loopback literals *only on a
loopback bind*, so a `127.0.0.1` server behind a reverse proxy 403s every proxied request — **and**
token auto-minting is gated on the bind being non-loopback, so the "safe-looking" loopback bind starts
with **no authentication at all and no warning**. `172.17.0.1` is the docker0 gateway: non-loopback
(so the pin relaxes and a token is minted), reachable from this host and its containers, not from the
LAN. Point the tunnel/proxy at **`http://172.17.0.1:8765`** — not `https://` — because there is no
`--tls-cert` here; TLS belongs at the proxy. Targeting `https://` yields 502 from outside while local
curl still says `ok`.
**The token.** There is deliberately no `--token` in the unit (units are world-readable). `serve`
mints or reuses a `0600` token at `~/.mempalace/server/<sha256-prefix-of-palace-path>/token`, stable
across restarts. Read it from there to configure clients.
> ⚠️ **Uninstall is where this unit differs from every other template here.** Stopping it is safe;
> deleting its data is not.
>
> ```sh
> systemctl --user disable --now mempalace-serve
> rm ~/.config/systemd/user/mempalace-serve.service && systemctl --user daemon-reload
> ```
>
> **Do not `rm -rf ~/.mempalace` on a host that has served the fleet.** That tree holds the shared
> palace *and* the only copy of the bearer token every client authenticates with. For the same reason,
> **never `rsync --delete` into `~/.mempalace`** — the token lives inside the tree you would be
> syncing. And note palace directories cannot simply be moved: the directory name is a sha256 prefix
> of its own path.
>
> Clients **fail closed** when this unit is down — they lose their palace tools entirely rather than
> falling back to a local palace — so stopping it is visible, reversible, and loses no data.
Operational note: the server serializes every request behind one lock, so a wedged process is a
fleet-wide outage. Hence `Restart=on-failure` with `TimeoutStopSec=30` — fail fast and let systemd
recover it.
## systemd user timer (recommended on modern Linux)
**Why:** runs without the user logged in (with `loginctl enable-linger`), survives reboots, logs to `journalctl`, Persistent=true catches missed runs after the machine was off. No root required — it's a *user* unit.