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.
check_aws_env was warning about missing AWS_PROFILE/AWS_REGION even on
fresh machines with no settings.json yet \u2014 but at that point we don't
know which provider the user will pick, so the warning is noise.
check_pi_settings already tells the user to bootstrap settings.json;
the AWS probe now stays quiet until it has evidence (amazon-bedrock in
settings.json) that AWS creds are actually needed.
Round out the pi bring-up story so a fresh machine can reach a working
pi+mempalace install with just `git clone && ./install.sh`:
- extensions/pi/keybindings.json: generic mosh/tmux newline fix
(shift+enter, ctrl+j, alt+j). Safe on any machine — not
region/account-specific. Symlinked into ~/.pi/agent/.
- extensions/pi/settings.example.json: template for `settings.json`
so pi can start without --provider/--model. NOT symlinked — pi
rewrites settings.json at runtime (lastChangelogVersion bumps),
which would dirty the repo. Installer prints the cp + edit hint.
- install.sh: new install_pi_keybindings + uninstall mirror; new
check_pi_settings probe (warns if settings.json missing); new
check_aws_env probe (warns if AWS_PROFILE/AWS_REGION unset and
settings.json selects amazon-bedrock). All new steps gated on
pi being installed (~/.pi/agent/extensions/ exists).
- extensions/pi/README.md: documents keybindings rationale,
settings bootstrap, and the recommended ~/.config/pi/.env +
~/.oh-my-zsh/custom/pi-env.zsh env layout (paired with the
myconfigs commit 884e329 that split AWS vars out of
~/.config/opencode/.env).
Verified on tor-ms22: full install → uninstall → reinstall cycle,
new shell loads AWS_PROFILE/AWS_REGION from the new pi-env.zsh hook.
Works on macOS and Linux (plain ln -s, POSIX bash).
The pi coding-agent extension at ~/.pi/agent/extensions/mempalace.ts was
living only on tor-ms22, including hand-edited fixes (Type.Unsafe
schema-passthrough for MCP tool parameters). One disk wipe away from
losing it, and no way to reproduce the install on a new machine.
- extensions/pi/mempalace.ts: canonical copy (matches tor-ms22 byte-for-byte)
- extensions/pi/README.md: what it does, the schema-passthrough gotcha,
debugging knobs
- install.sh: new install_pi_extension step — gated on ~/.pi/agent/extensions/
existing, backs up any real file in the way, idempotent re-runs, mirror
block in uninstall. Works on macOS and Linux (plain ln -s, readlink -f).
- README.md: mention extensions/pi/ in the repo-contents list and in the
Setup section
Verified on tor-ms22: install (backs up existing real file) → uninstall
(removes symlink) → reinstall (clean symlink). Re-runs are no-ops.
Two missing pieces bundled here:
1. The README described the MCP server wrapper (mempalace-mcp-server,
a 3-line shell script that exec's the venv's python) as the
canonical answer on a uv-tool install. That is over-engineered and
out of step with the live reference box: opencode.json there uses
['mempalace-mcp'] directly, which is the shim uv tool install
already creates. Rewrote the section to put the simple canonical
answer first and demote the wrapper to a legacy-fallback sidebar.
New 'Registering mempalace with opencode' section covers:
- The one-entry JSON stanza to paste into the mcp object.
- A full minimal opencode.json for someone starting fresh (with
the 'instructions' array pointing at the wake-up protocol).
- Custom palace path variant.
- Claude Code one-liner (claude mcp add mempalace -- mempalace-mcp).
- Pointer at 'mempalace mcp' subcommand which prints the currently-
recommended snippets — useful when upstream updates conventions.
- Troubleshooting table (tools absent / server unavailable /
ModuleNotFoundError) with per-symptom fixes.
The legacy-fallback subsection explains what the wrapper script
was for (the pip-install → uv-tool-install transition era), shows
its 3-line implementation for completeness, and is explicit about
not using it for new installs.
Verification checklist updated: now runs 'which mempalace-mcp' and
'mempalace-mcp --help' against the shim, not the wrapper.
2. install.sh gains a matching probe: after the existing wake-up
protocol check, it grep-checks ~/.config/opencode/opencode.json
for 'mempalace' + 'mempalace-mcp' substrings. Present → clean
success line. Missing → actionable warning that prints the exact
JSON stanza to add plus a pointer to the README anchor and the
'mempalace mcp' CLI helper. Skipped when opencode.json doesn't
exist (non-opencode hosts).
Textual grep rather than strict JSON parse: we don't want to
hard-depend on python/jq at install time, and the two substrings
together are specific enough to avoid false positives.
Prerequisites list gets a 5th bullet flagging MCP registration as
required and pointing at the new section + the installer probe.
Smoke-tested both scenarios on the reference box — config with
mempalace entry present (all ticks green), config with entry removed
(actionable warning, correct snippet shown), config restored to
original state.
The mempalace skill is only useful if an agent loads its wake-up
protocol at session start. Without ~/.config/opencode/instructions/
mempalace.md, the skill is reachable but never auto-runs — agents
forget to search before answering and to write a diary at wind-down.
The failure mode is silent: no error, no warning, just gradual
memory degradation.
install.sh now probes for the file after its regular installation
steps and prints an actionable warning if missing:
! Wake-up protocol NOT installed at /path/to/.../mempalace.md
Without it, the mempalace skill is loadable but never auto-
runs at session start. Install via the skillset repo:
git clone .../skillset.git ~/skillset
cd ~/skillset && ./deploy-skills.sh --bootstrap
(if skillset is already cloned, just run the --bootstrap step)
If the file is present: prints a matching success line. If the host
doesn't even have ~/.config/opencode/, the check is skipped entirely
(non-opencode machine → no warning to display).
README Prerequisites gains a 4th bullet pointing at skillset's
--bootstrap as the canonical source for the wake-up protocol, so
anyone reading the docs without running install.sh also learns
about the dependency.
The wake-up file is shipped by skillset, not this toolkit. Rationale:
the file bootstraps the 'mempalace' skill (which lives in skillset)
and applies to any harness, not just opencode-plus-toolkit machines.
Cross-referenced via the skillset gitea URL in both the installer
message and the README.
Smoke-tested present + missing scenarios on the reference box —
cleanly detects both, does not hard-fail on missing.
1. 'mempalace init --yes' without a dir argument fails — 'dir' is
required. The semantics were wrong too: 'mempalace init' is
per-project (sets up mempalace.yaml + entity detection in a specific
directory), not a one-time global init. The palace itself is
created lazily on first write, so neither mempalace-session nor
mempalace-docs requires any init step.
Removed the misleading 'One-time palace init' block from README.md,
ARCHITECTURE.md, and SKILL.md. Added a clarifying note:
'mempalace init <dir>' is per-project and optional (needed only to
customize the wing name or entity detection before mempalace-docs).
2. install.sh's 'Skipping <name>: <dest> exists and is not our symlink'
warning gave no actionable guidance. On the Mac, a leftover
~/.local/bin/mempalace-docs (likely from the pre-split cli_utils
days) was blocking the new install and the user had no easy way
to know what to do about it.
Expanded the warning to:
- Show whether the blocker is a symlink (and what it points at) or
a real file.
- Print the exact 'rm && ./install.sh' fix line.
- Track skipped count separately and flag it in the closing
summary so a scrolling user doesn't miss it.
Added matching troubleshooting paragraph to the README 'Install
mempalace-toolkit' section explaining the skip behaviour and
pointing at the installer's own message for the fix.
Smoke-tested the new skip-warning code path by temporarily replacing
~/.local/bin/mempalace-docs with a foreign symlink and re-running
install.sh — output is clear, specific, and restores cleanly.
The initial commit created install.sh with mode 0644, so a fresh clone
(e.g. on tor-ms22) hit 'permission denied: ./install.sh' and needed a
manual chmod +x or 'bash install.sh' workaround before first run.
This is a pure permission change (same content hash); git tracks the
execute bit in the tree, so this fixes it for every future clone.
bin/mempalace-docs and bin/mempalace-session were already 0755 because
they carried over from their original cli_utils commits — install.sh
was new in the split-out commit and missed the +x that the write-path
doesn't apply by default.
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