feat(integrations): add Pi memory package

.github/workflows/consolidated-packages.yml

@@ -107,6 +107,24 @@ jobs:
       - name: Verify Tau extension
         run: just package-check-tau
 
+  pi:
+    name: Pi package
+    permissions:
+      contents: read
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: extractions/setup-just@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Validate extension, bundled skills, tests, and package
+        run: just package-check-pi
+
   openclaw:
     name: OpenClaw package
     permissions:

docs/PI_MEMORY_E2E_RESULTS.md

@@ -0,0 +1,76 @@
+# Pi memory end-to-end results
+
+## Environment
+
+- Pi: 0.85.1
+- Basic Memory CLI: 0.23.2 from `/Users/phernandez/dev/basicmachines/basic-memory/.venv/bin/bm`
+- Model-backed Pi RPC runs: `openai-codex/gpt-5.5`
+- All Basic Memory data/config used isolated temp directories via `BASIC_MEMORY_HOME` and `BASIC_MEMORY_CONFIG_DIR`.
+- Project config used per-temp-workspace `.pi/basic-memory.json`; no live Pi config was modified.
+
+## CLI capture → fresh CLI recall
+
+Temp project: `pi-e2e-cli` in `/tmp/pi-bm-e2e-cli.B41VJy`.
+
+Flow:
+
+1. Created isolated local Basic Memory project with `bm project add pi-e2e-cli ... --default --local --no-wait`.
+2. Started Pi RPC with the local Basic Memory Pi package in CLI mode.
+3. Sent a working-thread prompt containing:
+   - decision: support CLI and MCP modes with shared Basic Memory notes;
+   - rationale: transport is secondary to never starting over;
+   - blocker: MCP adapter mode still needs an isolated run;
+   - next step: run fresh-session recall.
+4. Ran `/bm-capture Pi E2E CLI continuity checkpoint`.
+5. Verified note through `bm tool search-notes`.
+6. Started a separate fresh Pi RPC session and ran `/bm-recall transport is secondary`.
+
+Result:
+
+- Created note: `pi-e2e-cli/pi/sessions/pi-e2-e-cli-continuity-checkpoint`
+- Fresh-session recall injected a `basic-memory-pi` custom message containing the note permalink, decision, rationale, blocker, and next step.
+
+## CLI-written note → MCP adapter recall
+
+Same isolated `pi-e2e-cli` project.
+
+Flow:
+
+1. Switched `.pi/basic-memory.json` to `transport: "mcp"` and `mcpServerName: "basic-memory-e2e"`.
+2. Started Pi RPC with both `npm:pi-mcp-adapter@2.32.1` and the local Basic Memory Pi package.
+3. Asked the model to use the `mcp` proxy tool to search server `basic-memory-e2e` for `transport is secondary` in project `pi-e2e-cli`.
+
+Result:
+
+- The model connected the runtime-registered Basic Memory MCP server, discovered `basic-memory-e2e_search_notes`, called it, and answered with:
+  - permalink: `pi-e2e-cli/pi/sessions/pi-e2-e-cli-continuity-checkpoint`
+  - decision: Pi integration must support CLI and MCP modes with shared Basic Memory notes;
+  - rationale: transport is secondary to never starting over;
+  - blocker: MCP adapter mode still needs an isolated run;
+  - next step: run fresh-session recall.
+
+## MCP adapter write → CLI recall
+
+Temp project: `pi-e2e-mcp` in `/tmp/pi-bm-e2e-mcp.Lt83CA`.
+
+Flow:
+
+1. Created isolated local Basic Memory project with `bm project add pi-e2e-mcp ... --default --local --no-wait`.
+2. Started Pi RPC with `npm:pi-mcp-adapter@2.32.1` and the local Basic Memory Pi package in MCP mode.
+3. Asked the model to use the `mcp` proxy tool and server `basic-memory-e2e-mcp` to call `write_note` in project `pi-e2e-mcp`.
+4. Verified the MCP-written note through the CLI with `bm tool search-notes`.
+
+Result:
+
+- Created note: `pi-e2e-mcp/pi/sessions/pi-e2-e-mcp-continuity-checkpoint`
+- CLI search found the MCP-written note with:
+  - decision: MCP adapter writes use the same portable Basic Memory notes;
+  - rationale: CLI and MCP should interoperate without migration;
+  - blocker: automation defaults remain unsettled;
+  - next step: verify CLI recall of this MCP-written note.
+
+## Issues observed
+
+- The first CLI capture driver timed out waiting for Pi RPC idle, but the `/bm-capture` command had already succeeded. The later fresh recall and direct CLI search confirmed the note was durable.
+- In MCP mode the model first listed the server before connecting, then called `mcp({ connect })`. This is expected adapter behavior for lazy runtime servers.
+- The current `/bm-capture` and `/bm-recall` extension commands are CLI-backed even when `transport: "mcp"`; MCP mode currently exposes Basic Memory to the model through `pi-mcp-adapter`. A future iteration can decide whether commands should also invoke MCP through a supported adapter call surface if one becomes available.

docs/PI_MEMORY_HANDOFF.md

@@ -0,0 +1,103 @@
+---
+title: Pi Memory Plugin — You Are Never Starting Over
+type: note
+thread_id: 01a074b5-e8f2-706d-8aad-84cbcff0e060
+tags: [pi, basic-memory, integrations, continuity]
+---
+
+# Pi Memory Plugin — You Are Never Starting Over
+
+## Context
+
+Paul welcomed this Pi agent into Basic Memory and asked us to build a memory plugin.
+The harness reports model `gpt-6-astra`, provider `openai-codex`; this is configured
+identity, not independent verification of the underlying model. Our product goal is
+**you are never starting over**: recover decisions, rationale, working state, blockers,
+and next steps without asking Paul to explain the previous session again.
+
+## Settled direction
+
+Ship one Pi package with both CLI and MCP access modes. Users choose; notes and memory
+behavior stay portable between modes. Pi favors CLI tools plus skills, but existing
+MCP adapters mean we need not build another MCP host. Compare both empirically rather
+than selecting transport on philosophy alone.
+
+Basic Memory owns storage, search, graph operations, project routing, and authentication.
+The Pi integration should be thin: shared skills plus lifecycle continuity. Durable
+knowledge, transcripts, and lifecycle envelopes are distinct. Automatic capture defaults
+and destinations still need a deliberate decision. Do not equate logging every turn
+with useful memory, or silently send private traces into a team project.
+
+## Where to work
+
+- Worktree: `/Users/phernandez/dev/basicmachines/basic-memory-pi`
+- Branch: `feat/pi-memory`, created from local `origin/main` (not freshly fetched).
+- Main working directory remains on unrelated `feat/locked-notes`; leave it alone.
+- Plan: `docs/PI_MEMORY_PLAN.md` in the Pi worktree.
+- GitHub issue: https://github.com/basicmachines-co/basic-memory/issues/1488
+- Intended package: `integrations/pi/`.
+- No plugin implementation or end-to-end tests have been completed yet.
+- Plan and this handoff are not committed yet.
+
+## Evidence and references
+
+Existing host integrations live at `integrations/openclaw/` and `integrations/hermes/`,
+not `plugins/`. OpenClaw has a TypeScript MCP client and context engine. Hermes carries
+sync/async thread bridging and host compatibility workarounds that Pi should not need.
+Canonical shared skills live in top-level `skills/`.
+
+Read the installed Pi README and full extension, package, skill, and compaction docs.
+Pi supports async hooks, commands, context injection, session persistence, and reload.
+Resource-owning extensions must handle session shutdown and replacement explicitly.
+
+Candidate MCP adapter: https://github.com/nicobailon/pi-mcp-adapter
+Npm search found version 2.32.1. README fetched to `/tmp/pi-mcp-adapter-readme.md`,
+but not yet read or compatibility-verified. No extension has been installed.
+
+Paul explicitly pointed out that the documentation website serves Markdown. Initially
+we read source files in `../docs.basicmemory.com`; subsequently fetched live:
+- https://docs.basicmemory.com/llms.txt
+- https://docs.basicmemory.com/raw/reference/ai-assistant-guide.md
+- https://docs.basicmemory.com/raw/integrations/harness-capture.md
+
+The live assistant guide emphasizes search-before-answer, capture during work, editing
+rather than duplicating, and graph context on follow-ups. `bm hook` currently documents
+Claude and Codex lifecycle support, not Pi. Inspect core reuse before adding new logic.
+
+## Immediate next steps
+
+1. Read the MCP adapter README/source; verify installed Pi compatibility and whether
+   lifecycle extensions can call it through a supported API, without private internals.
+2. Verify actual CLI contracts: structured outputs, write failures, stdin, overwrite,
+   routing, cancellation, and latency. Do not infer these solely from documentation.
+3. Implement a minimal capture → fresh Pi session → recall scenario in both modes.
+4. Extend to reload, resume, forks, compaction, project isolation, and failure handling.
+5. Compare equivalent isolated fixtures with the same model and memory policies.
+
+Separate Pi subprocesses can run end-to-end tests without restarting Paul's live Pi.
+Model-backed tests use provider access and incur usage. Use temporary Basic Memory
+config/data and dedicated opt-in cloud projects, not existing user projects. `/reload`
+can refresh a configured extension interactively. Do not alter live Pi config implicitly.
+
+## Current blocker discovered during this capture
+
+`bm project list --json` returned:
+
+```text
+Error listing projects: Can't locate revision identified by 't3q4r5s6x7y8'
+```
+
+`bm tool write-note --help` works. The root cause of the migration mismatch has not
+been investigated. No database repair or reset was attempted. This note is saved as a
+local Markdown handoff only, not confirmed indexed in Basic Memory. Same-thread graph
+lookup could not proceed after project discovery failed. When indexing becomes available,
+search by `thread_id` above and synthesize into the existing note if one exists.
+
+## Observations
+
+- [decision] Support CLI and existing MCP-adapter access, with shared continuity semantics.
+- [requirement] A fresh session must recover the decision, rationale, and next action with a real note reference.
+- [principle] Transport is secondary to continuity across sessions and agents.
+- [constraint] Switching modes must not require migrating knowledge.
+- [status] Issue and plan exist; implementation has not started.
+- [blocker] Installed CLI project listing fails on an unavailable database migration revision.

docs/PI_MEMORY_PLAN.md

@@ -0,0 +1,136 @@
+# Pi memory integration: you are never starting over
+
+## Goal
+
+A fresh Pi session recovers the relevant decisions, working state, blockers, and next
+steps without the user repeating the previous conversation. Knowledge belongs to the
+user and remains usable across agents, projects, and local/cloud deployments.
+
+Ship one Pi package with two user-selectable access modes: Basic Memory CLI and an
+existing Pi MCP adapter. Share memory behavior and skills, not two independent memory
+implementations. Switching transport must not require migrating notes.
+
+## Confirmed direction
+
+- Implement under `integrations/pi/` in the Basic Memory monorepo.
+- Reuse canonical top-level memory skills and Basic Memory routing/authentication.
+- Support CLI access and MCP through an existing extension; do not build a generic MCP host.
+- Preserve Pi's native session history and compaction.
+- Distinguish lifecycle metadata, raw transcripts, and synthesized durable knowledge.
+- Keep project selection explicit; never change the user's global default implicitly.
+- Surface capture/recall failures without blocking ordinary work or claiming a save succeeded.
+
+## Phase 1 — investigate and prove transport contracts
+
+- [x] Inspect `pi-mcp-adapter` and alternatives: current Pi compatibility, tool naming,
+      discovery, cancellation, shutdown/reload, stdio and remote support, licensing.
+- [x] Determine whether lifecycle hooks can invoke the adapter through a supported API.
+      If not, document the limitation before choosing how automated recall/capture runs;
+      do not depend on private adapter internals.
+- [x] Verify installed `bm` CLI flags, structured output, write error/overwrite semantics,
+      stdin support, project UUID routing, and local/cloud behavior against real calls.
+- [x] Inspect existing `bm hook` recall/checkpoint implementation for reusable core logic.
+      Its documented harnesses are Claude and Codex, not Pi.
+- [x] Record a short architecture decision with version requirements and initial defaults.
+      See `docs/PI_MEMORY_TRANSPORT_DECISION.md`.
+
+## Phase 2 — smallest end-to-end continuity slice
+
+- [x] Add Pi package metadata, TypeScript extension entrypoint, config validation,
+      and hermetic test setup.
+- [x] Support explicit CLI/MCP mode and project selection with visible status.
+- [x] Bundle a focused set of shared skills: notes, capture, continue, and tasks.
+- [x] Verify bundled skill tool/CLI instructions work in both modes without duplicate discovery.
+- [x] Capture one coherent working-thread note with goal, decisions and rationale,
+      current state, blockers, next steps, and source/session provenance.
+- [x] Start a separate fresh Pi process and recover that thread through Basic Memory.
+- [x] Repeat the identical scenario through the other access mode.
+      See `docs/PI_MEMORY_E2E_RESULTS.md`.
+
+## Phase 3 — lifecycle continuity
+
+- [x] Bounded recall at session entry / first relevant prompt, including note identifiers
+      and source provenance; avoid repeatedly injecting the same context.
+- [x] Capture important decisions during work; support explicit remember/recall commands.
+- [ ] Add compaction-aware durable checkpoints without replacing native compaction.
+      Settle checkpoint timing using Pi lifecycle tests, not assumptions about reentrant turns.
+- [x] Restore state on reload/resume and track forks/tree navigation without merging
+      contradictory branches or duplicating captures.
+- [x] Choose and document automatic capture defaults and destinations. Raw transcript
+      capture is a separate opt-in decision, not an implied prerequisite for continuity.
+- [x] Treat recalled notes as source material, not privileged instructions. Respect project
+      trust and never route private session traces into shared projects implicitly.
+- [x] Bound subprocess/request duration, propagate cancellation, and clean up owned resources.
+      Never blindly retry non-idempotent writes after an ambiguous transport failure.
+
+## Phase 4 — compare CLI and MCP
+
+Run both modes with the same Basic Memory version, seeded notes, model, task prompts,
+retrieval budgets, and capture policy. Use independent sessions and equivalent isolated
+projects so one trial cannot benefit from another trial's captures.
+
+Measure separately:
+
+- cold startup, first operation, warm read/search/write latency;
+- tool discovery and prompt overhead, tokens and provider usage;
+- successful writes and recovery of their actual identifiers;
+- recall correctness: decision, rationale, blocker, next action, source citation;
+- duplication, routing isolation, and behavior after errors/reload/compaction.
+
+Test local routing first. Cloud tests are opt-in against a dedicated test project;
+never mutate existing personal/team projects as fixtures. Report model-backed quality
+results separately from deterministic transport assertions. Recommend a default from
+observed results while keeping both modes supported.
+
+## Acceptance scenarios
+
+1. Session A records a decision and unfinished next step. Fresh session B receives only
+   the topic and recovers the decision, rationale, and next step with a real note reference.
+2. CLI captures are recalled over MCP and vice versa without migration.
+3. Reload, resume, compaction, and forks preserve usable context without duplicate writes
+   or attributing another branch's state to the current branch.
+4. Two projects with conflicting decisions remain isolated, including ambiguous names.
+5. Missing CLI, unavailable MCP server, auth failure, cancellation, and failed writes are
+   visible; Pi remains usable and never falsely confirms persistence.
+6. Opted-out capture writes nothing; retrieved note instructions cannot change capture
+   settings or destination routing.
+
+## Phase 5 — distribution and documentation
+
+- [x] Root `just package-check-pi` target and integration into consolidated package checks.
+- [x] Package install/pack validation and isolated Pi subprocess smoke tests.
+      See `docs/PI_MEMORY_E2E_RESULTS.md`.
+- [x] README with CLI and MCP installation, explicit mode switching, project routing,
+      privacy defaults, failure recovery, and supported version matrix.
+- [ ] Add the Pi integration page to `docs.basicmemory.com` in a separate docs change.
+- [x] Wire release metadata consistently with existing integration packages.
+      Version bump wiring is in place; see `docs/PI_MEMORY_SHIPPING.md`.
+- [ ] Add npm publishing workflow wiring for the Pi package.
+      Publishing remains open until the release workflow includes `integrations/pi`.
+
+## Development workflow
+
+Worktree: `../basic-memory-pi`; branch: `feat/pi-memory` (created from local `origin/main`).
+Use separate Pi print/JSON/RPC processes for end-to-end verification and isolated Basic
+Memory config/data. Model-backed tests require available provider access and incur usage.
+Use `/reload` for interactive development once the extension is configured; a full restart
+is not normally required. Do not install extensions into the user's live config implicitly.
+
+## References
+
+Live website index: https://docs.basicmemory.com/llms.txt
+
+Live Markdown read during planning:
+- https://docs.basicmemory.com/raw/reference/ai-assistant-guide.md
+- https://docs.basicmemory.com/raw/integrations/harness-capture.md
+
+Additional documentation reviewed from the sibling website source checkout:
+- https://docs.basicmemory.com/raw/reference/cli-reference.md
+- https://docs.basicmemory.com/raw/cloud/cloud-cli.md
+- https://docs.basicmemory.com/raw/cloud/routing.md
+- https://docs.basicmemory.com/raw/integrations/hermes.md
+- https://docs.basicmemory.com/raw/integrations/openclaw.md
+
+Implementation references: `integrations/openclaw/`, `integrations/hermes/`, `skills/`.
+MCP adapter: https://github.com/nicobailon/pi-mcp-adapter (`2.32.1` compatibility verified for the initial runtime-registration scenario).
+Pi: installed README, extension/package/skill/compaction documentation and examples.