Two small doc updates consolidating the session's architectural arc:
1. README.md gets a new 'Ecosystem' section (after the contents list,
before 'Why this exists') showing the five-repo composition:
myconfigs -> opencode-toolkit + pi-toolkit -> mempalace-toolkit
Plus an ownership table clarifying which scope lives where. The
diagram makes the opt-out pattern visible \u2014 opencode-devbox's slim
container path skips mempalace-toolkit and still gets a functional
stack.
2. AGENTS.md 'Adding a new harness extension' section was still written
for the pre-split extensions/pi/ which had keybindings.json +
settings.example.json + pi-env.zsh. Rewrote to reflect:
- Bridge-only scope (harness-generic config goes in <harness>-toolkit).
- 'Probe for the sibling toolkit' step replaces the old symlink-keybindings
and template-settings steps.
- Worked example now points at install_pi_extension + check_pi_toolkit
rather than the four functions that moved out.
- Explicitly names the pattern: opencode-toolkit + pi-toolkit as
the two existing examples of the sibling-toolkit convention.
Parallel to the opencode-toolkit split earlier today. Pi's own config
(keybindings, shell env loader, settings template) moves to a new
sibling repo so opencode-devbox's mempalace opt-out can build slim
containers that include pi without dragging in chromadb + embedding
models (~300 MB).
What moved to pi-toolkit (https://gitea.jordbo.se/joakimp/pi-toolkit):
- extensions/pi/keybindings.json (mosh/tmux newline fix)
- extensions/pi/pi-env.zsh (sources ~/.config/pi/.env)
- extensions/pi/settings.example.json (Bedrock template)
- install.sh::install_pi_keybindings (symlink step)
- install.sh::install_pi_env_loader (cp step + bash fallback)
- install.sh::check_pi_settings (probe)
- install.sh::check_aws_env (probe)
What stays here (this is the pi\u2194mempalace bridge, mempalace-side):
- extensions/pi/mempalace.ts (the MCP extension)
- install.sh::install_pi_extension (symlink step)
- NEW: install.sh::check_pi_toolkit (probe: warns if pi is
installed but pi-toolkit's
artifacts are missing, with
git-clone pointer)
install.sh shrank from 520 to 403 lines. Uninstall mirror correctly
does NOT touch pi-toolkit-owned files (explicit comment).
Docs updated:
- extensions/pi/README.md: rewritten as 'pi\u2194MemPalace MCP bridge',
recipe becomes 'Deploying pi with mempalace' (pi-toolkit step 3,
this repo step 5).
- AGENTS.md: Structure block + 'What install.sh does' section reflect
the narrower scope and list the four things that moved out.
- README.md: repo-contents line + Setup section's deploy summary.
Verified on tor-ms22: full install\u2192uninstall\u2192reinstall lifecycle clean.
After mempalace-toolkit uninstall, pi-toolkit artifacts
(~/.pi/agent/keybindings.json, ~/.oh-my-zsh/custom/pi-env.zsh) remain
intact \u2014 correctly untouched. check_pi_toolkit probe fires green when
both exist.
The loader that sources ~/.config/pi/.env into every shell was only
living in the myconfigs tor-ms22 backup \u2014 a fresh machine had nowhere
to get it from except copying by hand. Now canonical here.
- extensions/pi/pi-env.zsh: 20-line POSIX-compatible loader
(set -a; source ~/.config/pi/.env; set +a). Works in bash and zsh.
- install.sh install_pi_env_loader:
* oh-my-zsh detected (~/.oh-my-zsh/custom/ exists)
\u2192 cp into that dir (NOT symlink \u2014 that dir is typically part of
a dotfiles backup, and a symlink to mempalace-toolkit would
break when restored on another host).
\u2192 Idempotent: if target content matches repo, says 'already
installed'. If it differs, leaves user edits alone and points
at diff for manual reconcile.
* No oh-my-zsh \u2192 prints source-this-line snippet for ~/.zshrc or
~/.bashrc (derived from $SHELL). Does NOT auto-edit rc files.
- install.sh uninstall: only removes the copy if content still matches
repo. Local edits preserved.
- Docs:
* extensions/pi/README.md Environment setup section rewritten with
both install paths, step 5 of deploy recipe updated.
* AGENTS.md Structure block lists pi-env.zsh.
* Root README repo-contents line mentions it.
Verified on tor-ms22: install fresh \u2192 uninstall (content match \u2192 remove)
\u2192 reinstall \u2192 zsh -ic loads AWS vars correctly. Also tested bash fallback
path via HOME=/tmp/fake-home SHELL=/bin/bash \u2014 prints right .bashrc snippet.
Two stale lines from the 2-wrapper era (we have three now), plus a
missing convention doc for future harness extensions:
- 'What this is': two wrappers \u2192 three + extensions/ tree
- 'Adding a new wrapper': drop the 'third wrapper triggers helper lib'
claim since three coexist fine as standalone scripts; keep the
threshold at four, re-evaluate then.
- New 'Adding a new harness extension' section codifies the extensions/
pattern so a future claude-code or kiro bridge follows the same shape
(per-harness dir, symlink-vs-template rules, gated install steps,
probe-don't-halt, uninstall mirror, README + Structure updates).
AGENTS.md Structure block was stale (listed only 2 bin/ wrappers, no
extensions/, no contrib/). Added full tree + a new 'What install.sh does'
section enumerating all steps, gates, and probes so maintainers see at a
glance what the installer touches.
ARCHITECTURE.md is scoped to the producer side (feeding the palace);
pi extension is consumer side, so out of scope for the main body. Added
a pointer in the See also section so readers can find extensions/pi/README.md.
The three feeder wrappers (mempalace-docs, mempalace-pi-session,
mempalace-session) unconditionally ran 'mempalace repair --yes' after
mining, controllable only via --no-repair opt-out. The contrib launchd
and systemd templates did not pass --no-repair, so every scheduled tick
invoked the destructive in-place HNSW rebuild.
This has bitten us twice:
- 2026-05-04 09:08: a kickstart triggered repair while an MCP
subprocess held the DB open; the live collection was wiped (0
drawers) and had to be restored from the palace.backup snapshot.
- 2026-05-05 10:00: post-mine repair crashed mid-rebuild with
'NotFoundError: Collection [<uuid>] does not exist' - chromadb's
rebuild recreated the collection under a new UUID while the code
still held the old handle. Live DB survived only by luck (crash
hit before the swap).
Fix: flip the default.
- New flag: --repair (opt-in). Prints a warning and sleeps 3s before
invoking 'mempalace repair --yes'.
- --no-repair is retained as a deprecated no-op alias for backward
compatibility with any scripts/units still passing it.
- Default behavior: no repair. Routine ChromaDB add() keeps HNSW
consistent; repair is a recovery op, not a maintenance tick.
Docs updated to match: README, SKILL, ARCHITECTURE, AGENTS,
contrib/README. Scheduling guidance now explicitly warns against
enabling --repair on cron/launchd/systemd-timer runs.
The skill directory at ~/.agents/skills/opencode-mempalace-bridge/ is a
real dir containing a single SKILL.md symlink back into this repo — the
'colocated skill' pattern. Sibling reconcilers (skillset's
deploy-skills.sh, cli_utils's agents-sync.zsh) already handle external
dirs correctly via their existing 'leave real dirs alone' policies, but
a machine-readable marker makes ownership explicit:
# skill-source: mempalace-toolkit
# repo: <absolute path>
# url: ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git
The marker is the convention for any external repo that wants to ship a
colocated skill. The name is generic (.skill-source, not
.managed-by-mempalace-toolkit) so a second colocated skill from a
different repo can reuse the same file name; the first line identifies
the owner.
--uninstall now also removes the marker (only if it still says
mempalace-toolkit) and the now-empty skill dir.
AGENTS.md + README.md describe the pattern and point at sibling docs in
cli_utils/AGENTS-SYNC.md and skillset/README.md that mirror the
convention.
Producer-side MemPalace tooling: two bash wrappers that bridge opencode
session history and project documentation into the palace. Originally
developed in cli_utils (2026-04-28); split into its own repo on
2026-04-30 because the conceptual fit was weak — cli_utils is
interactive shell tooling, while this is agent memory infrastructure
with its own architecture, dependency surface, and growth trajectory.
Contents:
- bin/mempalace-docs — docs-only mining wrapper (originally a2ddcc9 in
cli_utils), bridges the gap until MemPalace PR #1213 (exclude_patterns)
merges upstream.
- bin/mempalace-session — opencode → palace session bridge (originally
dacca0e in cli_utils). Reads ~/.local/share/opencode/opencode.db,
exports each session to Claude Code JSONL, mines via
'mempalace mine --mode convos'. Bridges the gap until opencode
session-stopping hooks + an opencode harness in hooks_cli.py land
upstream.
- ARCHITECTURE.md — canonical spec: architecture diagram, component
details, setup recipe, operational notes, upstream-retirement
roadmap. Originally a4cf314 in cli_utils.
- SKILL.md — companion agent skill (producer side). Pairs with the
consumer-side mempalace skill. Symlinked into
~/.agents/skills/opencode-mempalace-bridge/ by install.sh.
- install.sh — idempotent installer, also handles --uninstall.
- AGENTS.md — repo conventions.
History of the individual files is not preserved in this split; see
cli_utils (gitea.jordbo.se/joakimp/cli_utils) commits a2ddcc9, dacca0e,
and a4cf314 for the original authorship context.
joakimp
Joakim Persson