@codemem/pi-extension

Pi coding-agent extension for codemem: session ingest and turn-local memory injection.

Install

Requires Pi 1.1.0 or newer, below 2.0. Upgrade an older host with pi update (pi update --extensions reconciles installed packages, not the host).

npm i -g codemem
codemem setup --pi-only

Update the CLI and Pi extension together, then rerun setup and restart Pi. The extension's CLI fallback uses the grouped memory and session commands. An older CLI may not support those paths if the extension is upgraded separately.

Restart Pi after setup. codemem setup --pi-only configures only Pi. A fresh setup adds npm:@codemem/pi-extension@<version> to settings.json packages (PI_CODING_AGENT_DIR when set, otherwise ~/.pi/agent); an existing configured dev path may be retained. Useful flags:

Dev / local-path install (equivalent to --pi-extension-path):

{
  "packages": ["/absolute/path/to/codemem/packages/pi-extension"]
}

Build first so dist/index.js exists (pnpm --filter @codemem/pi-extension build).

Uninstall: remove the @codemem/pi-extension packages entry and restart pi. The shared memory store is left intact.

What it does

• Ingest — ordinary session events (session_start, user/assistant messages, tool calls/results) prefer POST /api/pi-hooks (source: "pi"), with codemem pi-hook-ingest CLI fallback (spool on failure). Boundary events (session_before_compact, session_shutdown) always attempt the CLI path so a flush can run; failure is fail-open.
• Injection — on pi's context event, appends a ## codemem memories block to the latest user message of the request copy (never the system prompt, never the saved session). Older user messages replay the exact bytes already injected for them, and a new pack is fetched only for the latest undecided message, so the provider's prefix cache stays stable. Already-shown items are cut from new packs when the pack response carries renderer spans. A contract-valid HTTP or memory pack --json response, including a zero-item pack, ends that fetch; {} and error-shaped bodies fall through. Those span-bearing successes log inject.pack.ok source=pi to the plugin log, the same line pi-hook-inject writes when it is the fallback. Decisions live in memory: a restart fetches again.
• File context — after a successful built-in read, related memories may be appended to that tool result. Failed reads and other tools are skipped.
• Tools — registers the 15 memory_* tools natively (HTTP preferred, CLI fallback), including memory_session_search over stored Pi session text. Every HTTP operation first proves the viewer is target-aware (GET /api/prompt-pack-profile must report this process's db_path + identity_target) and re-sends the target on the query, so a foreign or stale older viewer on the port is never trusted (409 or unproven → targeted CLI path). Non-idempotent memory_remember does NOT CLI-replay on ambiguous HTTP failures (timeout/5xx/reset after send). No pi-mcp-adapter needed. Skipped when pi.tools_mode is mcp-adapter.
• Compaction — session_before_compact attempts a flush only and never returns a custom summary. session_compact skips one new fetch only when willRetry is set and reason is not manual. Failed compaction, agent_settled, manual compaction, and a later user message clear that skip. A threshold compact skips only if that same guard matches.
• Fork/resume — re-keys stream identity on every session_start. Ingest cursor metadata persists via pi.appendEntry (codemem.cursor). Recall decisions stay in memory and are cleared on session_start; a restart refetches.
• Cross-agent — one shared, project-scoped store. Memories from OpenCode/Claude/Codex inject into pi and the reverse.
• Dashboard — pi rows appear in the source-agnostic feed/sessions/projects tabs with no extra setup.

Tool purposes and troubleshooting: Pi extension.

Observer derivation (v1)

Setup can fill unset observer_* keys from pi's API-key providers (cheap-model-first). Credentials stay in memory only and are never written to codemem config. unconfigured (oauth-only) is an auto-derivation status when only OAuth credentials are available, not the state of every observer connection. Configure observer credentials or the connection separately, with provider or model overrides as needed (observer auth). Explicit observer_* config/env always wins.

Configuration

Read from CODEMEM_CONFIG when set, otherwise $XDG_CONFIG_HOME/codemem or ~/.config/codemem, using an existing config.json then config.jsonc. Pi keys live under the pi object, with CODEMEM_PI_* env overrides.

Shared viewer / inject knobs (same as other clients):

Example config:

{
  "pi": {
    "tools_mode": "native",
    "inject_prompts": true,
    "file_context": true
  }
}

Lifecycle

Per pi extension rules: the factory only wires handlers. Viewer auto-start and other session resources begin on session_start and clean up idempotently on session_shutdown. Session state is re-keyed from ctx.sessionManager.getSessionId() on every session_start; durable ingest cursors persist via pi.appendEntry (codemem.cursor). Recall decisions are not session entries.

Peer dependencies

• @earendil-works/pi-coding-agent >=1.1.0 <2 (declared host peer)
• typebox (tool parameter schemas)

No @codemem/core or native modules load inside the pi process.