@codemem/pi-extension

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

Install

npm i -g codemem
codemem setup

codemem setup auto-detects pi and appends npm:@codemem/pi-extension@<version> to ~/.pi/agent/settings.json packages. 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 — captures pi session events (session_start/session_shutdown, user/assistant messages, tool calls/results) into codemem with source: "pi" via POST /api/pi-hooks (compat alias over the canonical ingest envelope), falling back to codemem pi-hook-ingest (spool when offline).
• 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 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.
• Tools — registers the 14 memory_* tools natively (HTTP preferred, CLI fallback). 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 still only flushes extraction and never returns a custom summary. The next context skips a new pack fetch only after session_compact with willRetry, which is Pi's automatic overflow resume. Manual, threshold, cancelled, and failed compactions do not skip that fetch, and a later user message clears a skip that was not the immediate resume.
• Fork/resume — re-keys stream identity on every session_start; durable cursors via pi.appendEntry.
• 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.

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. OAuth-only installs get an explicit unconfigured (oauth-only) status — never a silent failure. Set observer_provider / observer_model explicitly when needed. Explicit observer_* config/env always wins.

Configuration

Read from ~/.config/codemem/config.json 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.

Peer dependencies

• @earendil-works/pi-coding-agent (extension host)
• typebox (tool parameter schemas)

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