joakimp
16915f0e55
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.
207 lines
7.5 KiB
Markdown
207 lines
7.5 KiB
Markdown
# pi ↔ MemPalace MCP bridge
|
|
|
|
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. Installs wake-up context injection, per-tool schema passthrough,
|
|
and a `/mempalace-diary` slash-command.
|
|
|
|
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:**
|
|
- [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)
|
|
|
|
---
|
|
|
|
## What it does
|
|
|
|
1. **Spawns `mempalace-mcp`** as a subprocess and does the MCP stdio
|
|
JSON-RPC handshake (`initialize` + `notifications/initialized` +
|
|
`tools/list`).
|
|
2. **Registers each MCP tool** as a pi tool with its real `inputSchema`
|
|
passed through via `Type.Unsafe(...)` (see gotcha below).
|
|
3. **Wake-up auto-injection** (`before_agent_start`, one-shot per fresh
|
|
session): calls `mempalace_status` + `mempalace_diary_read` and
|
|
injects the result as a `mempalace-wakeup` system message so the
|
|
agent orients itself the way `~/.agents/skills/mempalace/SKILL.md`
|
|
describes. Skipped on resume/fork (context is already in the thread).
|
|
4. **Manual wind-down** via a `/mempalace-diary [topic]` slash command:
|
|
sends a prompt asking the LLM to call `mempalace_diary_write` with
|
|
an AAAK-formatted entry summarizing the session. Not fully auto
|
|
because pi sessions are typically short/tactical and
|
|
`session_shutdown` fires too late to drive another LLM turn.
|
|
|
|
## Fail-soft
|
|
|
|
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.
|
|
|
|
## Identity
|
|
|
|
`agent_name` for diary calls comes from `$MEMPALACE_AGENT_NAME`, defaulting
|
|
to `"pi"`. First diary write against that identity creates `wing_<name>`
|
|
in the palace. Set the env var if you want to run pi under a distinct
|
|
identity on a given machine (e.g. `pi-laptop` vs `pi-server`).
|
|
|
|
## Debugging
|
|
|
|
- `MEMPALACE_EXT_DEBUG=1` — surface `mempalace-mcp` stderr into pi's
|
|
stderr. Without this, stderr is drained silently so a misbehaving
|
|
server doesn't flood the TUI.
|
|
- If a tool call fails with a generic "Internal tool error", spawn
|
|
`mempalace-mcp` manually with raw JSON-RPC on stdin to read the
|
|
server-side error — much faster than guessing.
|
|
|
|
## The `Type.Unsafe` gotcha
|
|
|
|
Earlier versions of this extension registered every MCP tool with
|
|
`parameters: Type.Object({}, { additionalProperties: true })`, which
|
|
discarded each tool's real `inputSchema`. The LLM then saw no parameter
|
|
names and had to guess, leading to bugs like `mempalace_diary_read`
|
|
being called with `agent=` instead of the required `agent_name=` and
|
|
crashing the Python server with `TypeError: missing 1 required
|
|
positional argument`.
|
|
|
|
The fix (≈ lines 160-170) is to wrap the incoming JSON Schema with
|
|
`Type.Unsafe<...>(tool.inputSchema)`. TypeBox schemas are plain JSON
|
|
Schema at runtime plus a `Symbol` marker, so wrapping an
|
|
externally-sourced schema with `Unsafe` is sufficient — no conversion
|
|
to a full TypeBox tree is needed, and the LLM now sees every tool's
|
|
real parameter names.
|
|
|
|
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.
|
|
|
|
---
|
|
|
|
## Deploying pi with mempalace on a new machine
|
|
|
|
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).
|
|
|
|
### 0. Prerequisites
|
|
|
|
- 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.
|
|
|
|
### 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
|
|
git clone <your-dotfiles> ~/src/dotfiles
|
|
cd ~/src/dotfiles
|
|
git-crypt unlock <key>
|
|
./provision.sh --profile <profile> # or your equivalent tool
|
|
```
|
|
|
|
### 2. Install pi upstream
|
|
|
|
```bash
|
|
brew install pi-coding-agent # macOS
|
|
# or see https://github.com/mariozechner/pi-coding-agent for Linux
|
|
pi --help # creates ~/.pi/agent/
|
|
```
|
|
|
|
### 3. Install pi-toolkit (base pi config)
|
|
|
|
```bash
|
|
git clone ssh://git@gitea.jordbo.se:2222/joakimp/pi-toolkit.git ~/pi-toolkit
|
|
cd ~/pi-toolkit && ./install.sh
|
|
```
|
|
|
|
Symlinks `keybindings.json`, copies `pi-env.zsh` into
|
|
`~/.oh-my-zsh/custom/`, and prints the `settings.json` bootstrap command.
|
|
|
|
### 4. Bootstrap pi settings
|
|
|
|
```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
|
|
|
|
```
|
|
mempalace-toolkit/
|
|
└── extensions/
|
|
└── pi/
|
|
├── README.md ← this file
|
|
└── mempalace.ts ← symlinked into ~/.pi/agent/extensions/
|
|
```
|
|
|
|
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.
|