mempalace-toolkit/extensions/pi

pi ↔ MemPalace extension

The canonical source of ~/.pi/agent/extensions/mempalace.ts — the bridge that wires the MemPalace MCP server into the pi coding-agent harness.

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).

---

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.

Keybindings (mosh/tmux newline fix)

keybindings.json is symlinked so edits flow through git. Default:

{
  "tui.input.newLine": ["shift+enter", "ctrl+j", "alt+j"]
}

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.

Settings template (start pi without --model)

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:

cp /path/to/mempalace-toolkit/extensions/pi/settings.example.json \
   ~/.pi/agent/settings.json
$EDITOR ~/.pi/agent/settings.json

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.

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  ← set -a; source ~/.config/pi/.env; set +a

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.

File layout

mempalace-toolkit/
└── extensions/
    └── pi/
        ├── README.md               ← this file
        ├── mempalace.ts            ← symlinked into ~/.pi/agent/extensions/
        ├── keybindings.json        ← symlinked into ~/.pi/agent/
        └── settings.example.json   ← template; copy + edit into ~/.pi/agent/

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).