the-librarian-pi-extension

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

It is the Pi sibling of the Claude Code plugin and the Hermes plugin: same session model, same /lib-session-* contract, native to each harness.

What it does

Capability	How
Memory tools for the model (recall, remember, verify_memory, …)	Registered as native Pi tools by the extension — no mcp.json, no separate adapter
/lib-session-* commands	Real Pi commands (deterministic — no LLM round-trip)
Automatic session lifecycle	A TypeScript extension hooks Pi's events to start/checkpoint/pause sessions and gate privacy before the agent runs

Pi's core has no built-in MCP support (the mcp.json/mcpServers feature lives in third-party adapter extensions, not the runtime). So rather than make you install an adapter and hand-place a config file, this extension talks to the remote Librarian itself and exposes the memory tools to the model via registerTool. One pi install, zero config.

Unlike the hook-based harnesses (Claude Code, Codex), a Pi extension runs in-process in a long-lived TUI. So the Librarian calls here are fully async — the event loop is never blocked on network I/O — and privacy is enforced at the input event, before the model sees the prompt.

Install

Requires a reachable Librarian MCP server.

export LIBRARIAN_MCP_URL="https://your-librarian/mcp"
export LIBRARIAN_AGENT_TOKEN="<your agent token>"

Install the package (pick one):

# From a git checkout
pi install git:github.com/JimJafar/the-librarian-pi-extension

# From a local clone
pi install /path/to/the-librarian-pi-extension

That's it — the memory tools and the session lifecycle are both live. Nothing else to copy or configure.

Without LIBRARIAN_MCP_URL + LIBRARIAN_AGENT_TOKEN the extension is dormant: the commands are still registered but only report the missing configuration, and no automatic calls are made.

Configuration (environment)

Variable	Purpose
LIBRARIAN_MCP_URL	Remote Librarian MCP endpoint (required)
LIBRARIAN_AGENT_TOKEN	Per-agent bearer token (required)
LIBRARIAN_PROJECT / LIBRARIAN_PROJECT_KEY	Override the project key. Optional — defaults to the git repo name (else the folder name) of the working directory
LIBRARIAN_CAPTURE_MODE	summary (default) or off. log is never auto-selected
LIBRARIAN_TIMEOUT_MS	Per-call network timeout
PI_DEVICE_ID	Optional device id, used in source_ref

Commands

• /lib-session-start [title] [--private]
• /lib-session-list [--include-ended]
• /lib-session-resume [<number|session_id>]
• /lib-session-checkpoint [summary]
• /lib-session-pause [summary]
• /lib-session-end [summary]
• /lib-session-search <query>
• /lib-toggle-private

See the bundled use-the-librarian skill for the full memory + session discipline (states, visibility, verify-after-recall).

Automatic lifecycle

Pi event	Action
input (non-command prompts)	Privacy gate + idempotent auto start/resume
agent_end	Activity checkpoint (rate-limited gate)
session_compact	Checkpoint (high-value boundary)
session_shutdown	Pause (never end)

Privacy: typing /lib-toggle-private, or natural-language markers like "off the record" / "don't remember this", switches off-record mode. Going off-record ends the attached session with a neutral reason and suppresses all automatic recording until you toggle back. Local state I/O failures fail closed — no automatic Librarian call is made.

Architecture

• extensions/librarian/index.ts — the extension factory: event wiring + commands + tools.
• orchestrator.ts — async session-lifecycle engine (an in-process port of @librarian/lifecycle's session.ts decisions: idempotent start/resume, checkpoint gating, fail-closed privacy).
• session-client.ts — async wrapper over the Librarian MCP server (tool arg shapes pinned to @librarian/mcp-server).
• memory-tools.ts — registers the memory tools (recall/remember/…) as native Pi tools that proxy to the shared MCP client.
• config.ts, source-ref.ts — environment + identity derivation (incl. project-key inference from the git repo / folder name).
• extensions/librarian/vendor/ — three dependency-light leaf modules (mcp-client, privacy, state) vendored from @librarian/lifecycle. They are regenerated by npm run vendor:sync and drift-checked by npm run validate against vendor/PROVENANCE.json.

Development

npm install
npm run typecheck     # tsc --noEmit
npm test              # vitest
npm run validate      # vendored-code drift check
npm run check-imports # guard: no runtime imports a git-installed package can't resolve
npm run smoke         # load the extension under jiti (Pi's loader) with a mock API
npm run vendor:sync   # re-vendor from a sibling the-librarian checkout

License

Apache-2.0