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

refactor: split pi-generic config into pi-toolkit repo

Browse Source 
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.
This commit is contained in:
Joakim Persson
2026-05-05 17:26:53 +02:00
parent 3d3a0fb125
commit 16915f0e55
7 changed files with 178 additions and 454 deletions
Download Patch File Download Diff File Expand all files Collapse all files
extensions/pi/README.md
+112 -216
View File
@@ -1,163 +1,23 @@
# pi ↔ MemPalace extension
# pi ↔ MemPalace MCP bridge
The canonical source of `~/.pi/agent/extensions/mempalace.ts` — the bridge
that wires the [MemPalace](https://github.com/MemPalace/mempalace) MCP
The canonical source of `~/.pi/agent/extensions/mempalace.ts` — the TypeScript
extension that wires [MemPalace](https://github.com/MemPalace/mempalace)'s MCP
server into the [pi coding-agent](https://github.com/mariozechner/pi-coding-agent)
harness.
harness. Installs wake-up context injection, per-tool schema passthrough,
and a `/mempalace-diary` slash-command.
`install.sh` at the repo root symlinks `mempalace.ts` from this directory
into `~/.pi/agent/extensions/` so the live file on every machine tracks
version control. Works on macOS and Linux (the extension itself is plain
Node / TypeScript; the symlink is a POSIX `ln -s`).
This directory **only** holds the bridge. Pi's own base config (keybindings,
environment loader, settings template) lives in the sibling
[`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit) repo — split out
2026-05-05 so [`opencode-devbox`](https://gitea.jordbo.se/joakimp/opencode-devbox)
can build slim containers that include pi without dragging in mempalace's
dependencies (~300 MB).
**Jump to:**
- [Deploying pi on a new machine](#deploying-pi-on-a-new-machine) — step-by-step recipe.
- [Keybindings (mosh/tmux newline fix)](#keybindings-moshtmux-newline-fix)
- [Settings template](#settings-template-start-pi-without---model)
- [Environment setup](#environment-setup)
---
## Deploying pi on a new machine
Full recipe from a clean macOS or Linux box to a working pi+MemPalace
install with all modifications shipped by this repo and by
[`myconfigs`](https://gitea.jordbo.se/joakimp/myconfigs). Follow in order.
### 0. Prerequisites
- Shell: **zsh + oh-my-zsh** (the env loader is `~/.oh-my-zsh/custom/pi-env.zsh`).
On bash-only hosts, adapt by sourcing `~/.config/pi/.env` from `~/.bashrc`.
- `git`, `node` ≥ 20, `uv` (for installing mempalace), `tmux` ≥ 3.2.
- AWS credentials reachable via `AWS_PROFILE` (either `aws configure sso`
cache or static keys in `~/.aws/credentials`) — **only if** you'll use
`amazon-bedrock` as pi's provider.
### 1. Clone your dotfiles repo and provision
Brings `~/.tmux.conf` with CSI-u extended keys, `~/.config/pi/.env`
(git-crypt encrypted), and `~/.oh-my-zsh/custom/pi-env.zsh`:
```bash
git clone ssh://git@gitea.jordbo.se:2222/joakimp/myconfigs.git ~/src/src_local/myconfigs
cd ~/src/src_local/myconfigs
# Unlock git-crypt so ~/.config/pi/.env decrypts (skip on a box that has
# never held your git-crypt key; see myconfigs/GIT-CRYPT.md to set up).
git-crypt unlock ~/path/to/git-crypt-key
# Provision — choose the profile matching the box (homelab, work-macos, ...).
./provision.sh --dry-run --profile homelab # preview
./provision.sh --profile homelab # apply
```
### 2. Install pi (upstream)
```bash
brew install pi-coding-agent # macOS
# or: follow https://github.com/mariozechner/pi-coding-agent for Linux
```
First run creates `~/.pi/agent/`.
### 3. Install mempalace + the toolkit
```bash
# MemPalace CLI (isolated venv via uv, shim in ~/.local/bin)
uv tool install mempalace
# mempalace-toolkit (this repo) — the bin/ wrappers, the pi extension,
# keybindings, settings template, and install probes.
git clone ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git ~/mempalace-toolkit
cd ~/mempalace-toolkit
./install.sh
```
`install.sh` detects pi, symlinks `mempalace.ts` + `keybindings.json` into
`~/.pi/agent/`, installs the companion skill, and runs five probes. The
AWS probe stays quiet until step 4 selects `amazon-bedrock`.
### 4. Bootstrap pi settings (start pi without `--model`)
```bash
cp ~/mempalace-toolkit/extensions/pi/settings.example.json \
~/.pi/agent/settings.json
$EDITOR ~/.pi/agent/settings.json
```
Adjust the inference-profile prefix to match your AWS region:
| Region | Prefix | Example model ID |
|---|---|---|
| eu-west-1 | `eu.` | `eu.anthropic.claude-sonnet-4-6` |
| us-east-1 | `us.` | `us.anthropic.claude-sonnet-4-6` |
| non-Bedrock | (none) | `anthropic:claude-sonnet-4-6` |
Run `pi --list-models` to confirm what your credentials can actually invoke.
### 5. Ensure AWS env vars are live in your shell
**On zsh + oh-my-zsh hosts:** step 3's `install.sh` already copied
`pi-env.zsh` into `~/.oh-my-zsh/custom/`, so every new shell sources
`~/.config/pi/.env` automatically. Verify:
```bash
exec zsh
echo "$AWS_PROFILE $AWS_REGION" # should print your values
```
**On bash or plain zsh (no oh-my-zsh):** `install.sh` printed a
`source <repo>/extensions/pi/pi-env.zsh` snippet — add that one line to
`~/.bashrc` or `~/.zshrc`, open a fresh shell, verify as above.
If vars are empty, check that `~/.config/pi/.env` decrypted
(`head ~/.config/pi/.env` should show plain text, not binary).
`git-crypt unlock` in step 1 is the usual culprit when this is empty.
### 6. Register mempalace MCP with opencode (if using opencode too)
Skip if this box is pi-only. Otherwise:
- Install [`opencode-toolkit`](https://gitea.jordbo.se/joakimp/opencode-toolkit) so `~/.config/opencode/.env` is sourced into every shell (GitHub / Gitea / other MCP server tokens).
- Register the mempalace MCP server in `~/.config/opencode/opencode.json` — see [root README § Registering mempalace with opencode](../../README.md#registering-mempalace-with-opencode-or-other-mcp-clients).
### 7. First run
```bash
pi # should start with the default model, no --model needed
```
Inside pi, the wake-up auto-injection should print a `mempalace-wakeup`
system message with palace status and recent diary entries. If it doesn't,
run `MEMPALACE_EXT_DEBUG=1 pi` to surface `mempalace-mcp` stderr.
### Verification checklist
```bash
# Symlinks in place
ls -la ~/.pi/agent/mempalace.ts ~/.pi/agent/keybindings.json # → repo
ls -la ~/.agents/skills/opencode-mempalace-bridge/SKILL.md # → repo
# Env loaded
zsh -ic 'echo $AWS_PROFILE $AWS_REGION'
# tmux extended keys
tmux show-options -g | grep extended-keys # csi-u
# Palace reachable
mempalace status
# Installer re-run is idempotent
cd ~/mempalace-toolkit && ./install.sh --yes # all rows should say "already linked"
```
### Uninstall
```bash
cd ~/mempalace-toolkit && ./install.sh --uninstall --yes
# Leaves mempalace CLI, pi binary, and ~/.config/pi/.env alone —
# only removes symlinks this repo created.
```
- [What it does](#what-it-does)
- [The `Type.Unsafe` gotcha](#the-typeunsafe-gotcha)
- [Deploying pi with mempalace on a new machine](#deploying-pi-with-mempalace-on-a-new-machine)
- [Fail-soft, identity, debugging](#fail-soft)
---
@@ -222,74 +82,113 @@ If you ever need to re-loosen the schema for debugging, fall back to
the `Type.Object({}, { additionalProperties: true })` default only for
that specific tool, not globally.
## Keybindings (mosh/tmux newline fix)
---
`keybindings.json` is symlinked so edits flow through git. Default:
## Deploying pi with mempalace on a new machine
```json
{
"tui.input.newLine": ["shift+enter", "ctrl+j", "alt+j"]
}
```
This is the "pi + memory" recipe. For pi without mempalace, see
[`pi-toolkit`'s README](https://gitea.jordbo.se/joakimp/pi-toolkit/src/branch/main/README.md#deploying-pi-on-a-new-machine).
Rationale: when pi runs over `kitty → mosh → tmux`, shift+enter doesn't
forward cleanly (mosh uses vt220-ish emulation, no kitty-keyboard-protocol
or csi-u extended keys). `ctrl+j` and `alt+j` pass through as plain
control/meta bytes and give you reliable newline insertion.
### 0. Prerequisites
## Settings template (start pi without `--model`)
- Shell: zsh + oh-my-zsh recommended (both toolkits install loaders into
`~/.oh-my-zsh/custom/`; bash works too, installers print the manual
`source` snippet).
- `git`, `node` ≥ 20, `uv`, `tmux` ≥ 3.2, pi installed upstream.
- AWS credentials reachable via `AWS_PROFILE` — only if using
`amazon-bedrock` as pi's provider.
`settings.example.json` is a template — **not symlinked**. pi rewrites
its `settings.json` at runtime (`lastChangelogVersion` bumps on upgrade),
which would dirty a symlinked repo file. Instead, bootstrap with:
### 1. Dotfiles (if you keep one)
Brings `~/.config/pi/.env` (AWS creds, git-crypt encrypted), tmux CSI-u
extended keys, and other machine state:
```bash
cp /path/to/mempalace-toolkit/extensions/pi/settings.example.json \
~/.pi/agent/settings.json
$EDITOR ~/.pi/agent/settings.json
git clone <your-dotfiles> ~/src/dotfiles
cd ~/src/dotfiles
git-crypt unlock <key>
./provision.sh --profile <profile> # or your equivalent tool
```
The Bedrock inference-profile prefix on model IDs (`eu.`, `us.`) is
**region-specific** and must match `AWS_REGION` in `~/.config/pi/.env`.
For a bare Anthropic provider (non-Bedrock) drop the prefix entirely
and use `anthropic:claude-...`. Run `pi --list-models` to confirm what
your credentials can actually invoke.
### 2. Install pi upstream
`install.sh` warns (non-fatal) if `settings.json` is missing.
## Environment setup
pi with `defaultProvider=amazon-bedrock` needs `AWS_PROFILE` and
`AWS_REGION` exported into the shell that launches it. Recommended
layout (matches the tor-ms22 dotfiles pattern):
```
~/.config/pi/.env ← AWS_PROFILE=..., AWS_REGION=...
(git-crypt encrypted in dotfiles repo)
~/.oh-my-zsh/custom/pi-env.zsh ← installed by mempalace-toolkit install.sh
(sources the .env into every shell)
```bash
brew install pi-coding-agent # macOS
# or see https://github.com/mariozechner/pi-coding-agent for Linux
pi --help # creates ~/.pi/agent/
```
The loader file `pi-env.zsh` is canonical here in `extensions/pi/` and
installed by `install.sh` in one of two ways:
### 3. Install pi-toolkit (base pi config)
| Detected | Action |
|---|---|
| `~/.oh-my-zsh/custom/` exists | `cp` (not symlink) into that directory — auto-loaded by omz on every new shell. cp not symlink because that directory is part of the dotfiles backup, and a symlink into mempalace-toolkit would break when the backup is restored on another host. |
| No oh-my-zsh | Prints a shell-specific `source <repo>/extensions/pi/pi-env.zsh` snippet for `~/.zshrc` or `~/.bashrc`. Installer does not auto-edit rc files. |
```bash
git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git ~/pi-toolkit
cd ~/pi-toolkit && ./install.sh
```
The loader itself is POSIX-compatible (`set -a` / `source` / `set +a`),
so bash users can source it directly — no zsh dependency in the file.
Symlinks `keybindings.json`, copies `pi-env.zsh` into
`~/.oh-my-zsh/custom/`, and prints the `settings.json` bootstrap command.
Re-runs are idempotent: if the installed copy matches the repo, prints
"already installed". If it differs, leaves your edits alone and points
at `diff` for comparison. Uninstall only removes the file if it still
matches the repo copy; local edits are preserved.
### 4. Bootstrap pi settings
Historical note: these vars used to live under a `# Environment variables
for pi` block inside `~/.config/opencode/.env`. Split out 2026-05-05 so
each tool owns its own env file. `install.sh` runs a `check_aws_env`
probe that warns if the vars are missing and points back here.
```bash
cp ~/pi-toolkit/settings.example.json ~/.pi/agent/settings.json
$EDITOR ~/.pi/agent/settings.json # eu./us./anthropic: prefix
```
### 5. Install mempalace CLI + this toolkit
```bash
uv tool install mempalace
git clone ssh://git@gitea.jordbo.se:2222/joakimp/mempalace-toolkit.git ~/mempalace-toolkit
cd ~/mempalace-toolkit && ./install.sh
```
Detects pi, symlinks `mempalace.ts` into `~/.pi/agent/extensions/`.
Also detects pi-toolkit artifacts and prints a green check (or a warning
telling you to install pi-toolkit first if you skipped step 3).
### 6. Register mempalace MCP with opencode (if applicable)
Skip if this box is pi-only. Otherwise:
- Install [`opencode-toolkit`](https://gitea.jordbo.se/joakimp/opencode-toolkit) so `~/.config/opencode/.env` is sourced into every shell (GitHub / Gitea / other MCP server tokens).
- Register the mempalace MCP server in `~/.config/opencode/opencode.json` — see [root README § Registering mempalace with opencode](../../README.md#registering-mempalace-with-opencode-or-other-mcp-clients).
### 7. First run
```bash
exec zsh
pi # should start with defaults; wake-up injection shows palace status
```
If the wake-up doesn't print, run `MEMPALACE_EXT_DEBUG=1 pi` to surface
`mempalace-mcp` stderr.
### Verification checklist
```bash
# MCP bridge in place
ls -la ~/.pi/agent/extensions/mempalace.ts # → this repo
# pi-toolkit artifacts also in place
ls -la ~/.pi/agent/keybindings.json # → pi-toolkit
ls -la ~/.oh-my-zsh/custom/pi-env.zsh # cp from pi-toolkit
# Env loaded
zsh -ic 'echo $AWS_PROFILE $AWS_REGION'
# Palace reachable
mempalace status
```
### Uninstall
```bash
cd ~/mempalace-toolkit && ./install.sh --uninstall --yes # bridge only
cd ~/pi-toolkit && ./install.sh --uninstall --yes # pi base config
# Leaves pi itself, mempalace CLI, and ~/.config/pi/.env alone.
```
---
## File layout
@@ -297,14 +196,11 @@ probe that warns if the vars are missing and points back here.
mempalace-toolkit/
└── extensions/
└── pi/
├── README.md ← this file
├── mempalace.ts ← symlinked into ~/.pi/agent/extensions/
├── keybindings.json ← symlinked into ~/.pi/agent/
├── pi-env.zsh ← cp'd into ~/.oh-my-zsh/custom/ (or source'd manually for bash)
└── settings.example.json ← template; copy + edit into ~/.pi/agent/
├── README.md ← this file
└── mempalace.ts ← symlinked into ~/.pi/agent/extensions/
```
`install.sh` detects pi by probing for `~/.pi/agent/extensions/` and
only creates symlinks when that directory exists. On machines without
pi the files stay dormant in the repo. Re-runs are idempotent (same
pattern as `bin/` and `SKILL.md`).
Pi base config (keybindings, env loader, settings template) lives in
[`pi-toolkit`](https://gitea.jordbo.se/joakimp/pi-toolkit). `install.sh`
detects pi via `~/.pi/agent/extensions/` and runs a `check_pi_toolkit`
probe that warns if pi-toolkit's artifacts are missing.