The Librarian — Pi extension

A Pi package that gives the Pi coding agent durable memory and cross-harness handoffs, backed by a remote Librarian MCP server.

Pi's core has no MCP support, so this extension does the wiring itself: it registers the Librarian's 7 agent verbs as native Pi tools (each one a thin, fail-soft proxy over the server's stateless /mcp endpoint) and injects the Librarian primer into the system prompt. One install, zero config files.

What you get

• 8 tools, identical to every other harness — recall, remember, flag_memory, store_handoff, list_handoffs, claim_handoff, search_references, journal. Descriptions and schemas mirror the server's (a drift-guard test pins them), so the model is taught the same protocol in Pi as in Claude Code, Codex, OpenCode, and Hermes. flag_memory asks the curator to review a wrong or outdated memory: it may correct it in place, propose a correction, or leave the flag for a person. The response reports queue status, not completion.
• Primer injection — the primer (the shipped default plus the server's optional addendum, ≤2KB in all) is fetched once per process from GET <server>/primer.md and appended to the system prompt via before_agent_start.
• The journal at session start — the recent window of the journal (GET <server>/journal.md?max_chars=9500) follows the primer in the system prompt, fetched once per Pi session and then reused so the prompt stays the same every turn. Captured turns are labelled with their project (the git repository name, else the folder name) once /healthz shows the server accepts it.
• Automatic per-turn capture — after every completed turn Pi fires agent_end with the turn's messages in-payload, and the adapter ships the non-private prose as a delta to the server's POST /transcript door for the curator to mine for durable memories. Default-on; opt out with LIBRARIAN_AUTO_SAVE=false. Forward-only private mode is honoured (a [librarian:private=on] turn and every turn until [librarian:private=off] is never shipped, and never retroactively sent), the conversation is keyed by Pi's own session id (getSessionId() — concurrent sessions never collide, never $USER/cwd), the seq advances only on a server 2xx ack, the bearer token travels in the header only (redirect:"error"), and it is fully fail-soft — a Librarian outage never blocks a turn or leaks a stack trace. Private mode is an in-conversation instruction; the server cannot verify its marker. A curator review queued by a flag from public context may still correct that memory after switching private; the toggle does not cancel queued work.
• Three slash commands (optional sugar): /handoff, /takeover, /toggle-private — thin prompt templates that drive the corresponding tool flows. See docs/slash-commands.md.
• Fail-soft everywhere — if the Librarian is down, tools return a short error string (never a thrown harness error), the primer is skipped, and the user's turn is never blocked.

Install

The easy way — the Librarian CLI (recommended)

npx @the-librarian/cli install      # choose Pi; paste your MCP URL + token
npx @the-librarian/cli update       # later: pull the latest extension

install runs Pi's native pi install for you and persists your server URL + token. Run it with npx, or npm i -g @the-librarian/cli once and call librarian install / librarian update directly. Prefer to wire it by hand? See below.

Manual setup

From npm (once published — see "Publishing" below):

pi install npm:@the-librarian/pi-extension

From source (works today):

git clone https://github.com/code-ministry-ltd/the-librarian
pi install /path/to/the-librarian/integrations/pi

(pi install git:… of the monorepo root won't work — the package lives in the integrations/pi subdirectory, so install from a local clone path.)

Configure

Set two environment variables in the shell that launches pi:

Without both required variables the extension stays dormant: no tools, no network calls — only the three slash commands register, and they explain what's missing.

Security posture (inherited from the security-reviewed clients in this family): the bearer token travels only in the Authorization header, redirects are refused so a 3xx can't carry the token cross-origin, the endpoint scheme is allowlisted to http(s), and response bodies are size-capped.

Develop

This package is part of the the-librarian pnpm workspace:

pnpm install
pnpm --filter @the-librarian/pi-extension test        # vitest
pnpm --filter @the-librarian/pi-extension typecheck   # tsc --noEmit

The schema-parity suite imports the compiled @librarian/mcp-server, which is built automatically on pnpm install (its prepare script).

Publishing

The package is publishable ("private": false) and carries the pi-package keyword, so npm publish from integrations/pi/ both releases it and lists it in Pi's gallery at pi.dev/packages. Publishing is a repo-owner action — it is deliberately not part of any automated flow here. Until it's published, use the "from source" install above.