Skip to content

feat(integrations): Pi memory plugin using native lifecycle and Basic Memory CLI #1488

Open
Open
feat(integrations): Pi memory plugin using native lifecycle and Basic Memory CLI#1488
Labels
enhancementNew feature or request

Description

@phernandez
phernandez
opened on Sep 6, 2026

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

  • Inspect pi-mcp-adapter and alternatives: current Pi compatibility, tool naming,
    discovery, cancellation, shutdown/reload, stdio and remote support, licensing.
  • 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.
  • Verify installed bm CLI flags, structured output, write error/overwrite semantics,
    stdin support, project UUID routing, and local/cloud behavior against real calls.
  • Inspect existing bm hook recall/checkpoint implementation for reusable core logic.
    Its documented harnesses are Claude and Codex, not Pi.
  • Record a short architecture decision with version requirements and initial defaults.

Phase 2 — smallest end-to-end continuity slice

  • Add Pi package metadata, TypeScript extension entrypoint, config validation,
    and hermetic test setup.
  • Support explicit CLI/MCP mode and project selection with visible status.
  • Bundle a focused set of shared skills: notes, capture, continue, and tasks.
    Verify their tool/CLI instructions work in both modes without duplicate discovery.
  • Capture one coherent working-thread note with goal, decisions and rationale,
    current state, blockers, next steps, and source/session provenance.
  • Start a separate fresh Pi process and recover that thread through Basic Memory.
  • Repeat the identical scenario through the other access mode.

Phase 3 — lifecycle continuity

  • Bounded recall at session entry / first relevant prompt, including note identifiers
    and source provenance; avoid repeatedly injecting the same context.
  • 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.
  • Restore state on reload/resume and track forks/tree navigation without merging
    contradictory branches or duplicating captures.
  • Choose and document automatic capture defaults and destinations. Raw transcript
    capture is a separate opt-in decision, not an implied prerequisite for continuity.
  • Treat recalled notes as source material, not privileged instructions. Respect project
    trust and never route private session traces into shared projects implicitly.
  • 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

  • Root just package-check-pi target and integration into consolidated package checks.
  • Package install/pack validation and isolated Pi subprocess smoke tests.
  • 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.
  • Wire release metadata/publishing consistently with existing integration packages.

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:

Additional documentation reviewed from the sibling website source checkout:

Implementation references: integrations/openclaw/, integrations/hermes/, skills/.
MCP candidate: https://github.com/nicobailon/pi-mcp-adapter (not yet compatibility-verified).
Pi: installed README, extension/package/skill/compaction documentation and examples.

Activity

  1. claude commented on Sep 6, 2026

    @claude
    claudebot
    on Sep 6, 2026 – with Claude
    Contributor

    Claude finished @phernandez's task in 27s —— View job

    Triage

    Type: Feature request (enhancement) — new integration package (integrations/pi/), no existing code affected.

    Component: integrations (Pi plugin, CLI + MCP transport modes). Not a Cloud-specific issue — routing/auth reuse existing Basic Memory mechanisms, so no cloud label applied.

    Priority: Medium. High strategic value (extends the OpenClaw/Hermes integration pattern to a new host), but it's net-new, additive scope with no user-facing regression or broken functionality today.

    Complexity: Complex. This is a multi-phase effort (investigation of an unverified third-party MCP adapter, a new package with CLI/MCP dual-mode support, lifecycle/compaction-aware capture, cross-mode comparison benchmarking, and distribution/docs) spanning a dedicated worktree and branch already scoped in the issue.

    Duplicate check: No existing open or closed issues found referencing Pi integration, pi-mcp-adapter, or this plugin work.

    Notes for follow-up: Phase 1 explicitly calls out an unverified dependency (pi-mcp-adapter compatibility/licensing not yet confirmed) — worth confirming that spike happens before committing to the MCP-mode design, since Phase 2+ scope depends on its outcome.

  2. claude
    added
    enhancementNew feature or request
    on Sep 6, 2026
  3. phernandez
    added this to the v0.24.0 milestone on Sep 14, 2026

  4. phernandez commented on Sep 14, 2026

    @phernandez
    phernandez
    on Sep 14, 2026
    MemberAuthor

    v0.24.0 delivery audit: needs maintainer decision on MCP lifecycle contract

    Inspected the complete issue and discussion, merged #1492 and #1509, preserved feat/pi-memory / ../basic-memory-pi, and started fresh branch codex/1488-pi-completion in the requested reusable ../basic-memory-pr1540 worktree from current origin/main (756f183617a8aae0ce7c503b88e9fb5c8180b1de). No product changes, new PR, or merge in this audit.

    Existing work is reusable, but does not close this issue

    #1492 already landed the package, CLI installer/wheel resources, shared skill references, CLI hook integration, and cross-transport manual evidence. #1509 corrected effective automation status. The old prototype's Pi implementation is already represented on main; it should not be reimplemented.

    Current integrations/pi/extensions/index.ts routes buildRecall, captureSession, and runHook through runBm regardless of transport. MCP mode registers a model-facing server only. refreshConfig explicitly rejects MCP projectId. docs/PI_MEMORY_E2E_RESULTS.md already acknowledges the CLI-backed command limitation. These are incomplete acceptance coverage, not evidence that equivalent CLI/MCP lifecycle modes have shipped.

    Released external API gap

    Verified installed Pi 0.85.1, installed bm 0.23.2, and downloaded the actual npm tarball for pi-mcp-adapter 2.33.0 (npm SHA-1 bb623263f34de7f6fc5927952118ba7caf4330e8). The adapter is MIT licensed and supports stdio/remote servers, discovery, cancellation and owned connection cleanup internally. Those capabilities do not imply a public call API for another extension.

    • Released adapter entrypoint: McpServerRegistration exposes only dispose(): Promise<void>. Public runtime events register a server or read its snapshot; there is no public cross-extension tool invocation operation.
    • Released adapter README, “Runtime registration from other extensions”: registered servers expose tools through the model proxy. Registration is not a callable client. The standalone CLI is setup/configuration, not a tool-call bridge.
    • Released Pi API: ExtensionAPI.getAllTools() returns ToolInfo metadata, not executable tool handles. There is no executeTool/callTool method. sendUserMessage starts/queues a model turn; it is not a bounded tool-result API that a pre-compaction callback can await.
    • Alternative inspected: @nklisch/pi-mcp-adapter 2.21.0-nklisch.4 public contract. McpProgrammaticRuntime supports capabilities, validation, replace/remove/inspect source operations; its public interface excludes the internal runtime's callTool method.
    • Alternative inspected: pi-mcp-extension 1.5.0. It bridges tools to the model but documents no cooperating-extension invocation API; its peer contracts also still use the older @mariozechner host package names. Importing its internal manager would not satisfy the issue's supported-API constraint.

    Decision needed before completing scope

    The missing API blocks awaitable MCP-backed recall/capture in lifecycle callbacks using the supported installed-adapter contract. It does not block ordinary model-initiated MCP calls. I am not claiming all Pi integration is blocked or that the existing CLI work is unusable.

    Choose one explicit delivery contract:

    1. Accept the existing hybrid boundary for v0.24: CLI owns lifecycle recall/checkpoint operations in both modes, while MCP is model-driven access. Update the issue's same-mode lifecycle comparison/acceptance wording accordingly. The issue anticipated documenting this limitation before choosing automation; this choice must be explicit, not concealed behind transport: "mcp".
    2. Retain full transport parity and obtain a released public adapter invocation API (server/tool/arguments, cancellation, bounded completion, result/error, cleanup ownership, no blind retry of ambiguous writes) before completing the MCP lifecycle slice.

    Queuing model instructions for a later turn changes checkpoint timing and persistence guarantees. Deep-importing private managers or implementing a new MCP host conflicts with the confirmed scope. I have not chosen either workaround implicitly.

    Other remaining work, not separate external blockers

    After the transport decision, reuse the current package and finish synthesized capture versus raw-turn opt-in semantics (current Pi checkpoints copy user/assistant turn text), lifecycle/branch/deduplication host tests, explicit project isolation in both modes, equivalent fresh-process comparisons, and the remaining distribution/docs work. These remain implementation tasks; the API gap does not excuse marking them complete.

    just package-check-pi passed on the audited head: TypeScript, 15 tests, four canonical reference drift checks, npm pack dry run. The current tests cover config, capture construction, fencing and status; they do not prove the full lifecycle acceptance matrix. No model-backed quality benchmark or cloud fixture run is claimed.

    Per the requested stop condition, marking this issue needs review and stopping delivery work here. #1488 remains open. Existing #1492 and #1509 remain merged; no new PR is awaiting CI/Codex/merge. Main and all worktree registrations were left untouched; only the requested reusable worktree was switched to the fresh branch.

    Additional real CLI probe (isolated BASIC_MEMORY_HOME and BASIC_MEMORY_CONFIG_DIR, forced local, throwaway pi-contract project): stdin write returned JSON action: created with pi-contract/pi/sessions/pi-contract; repeating without overwrite exited 1 with NOTE_ALREADY_EXISTS; --overwrite returned action: updated; a separate search process returned that real reference and the decision/rationale/next-step text. This proves local CLI transport behavior only, not MCP lifecycle parity or cloud UUID isolation. Evidence is retained locally in /tmp/bm-pi-1488-contract/cli-results.json.

  5. phernandez
    added
    needs reviewA human maintainer needs to look at this issue
    on Sep 14, 2026

  6. phernandez commented on Sep 14, 2026

    @phernandez
    phernandez
    on Sep 14, 2026
    MemberAuthor

    Milestone status (2026-09-14): the Pi package is shipped; full MCP lifecycle parity remains decision-blocked.

    Merged #1492 and #1509 provide the integration package, installer/wheel resources, shared skills, CLI lifecycle flow, MCP registration, and truthful automation status. just package-check-pi previously passed. The released contracts are still Pi 0.85.1 and pi-mcp-adapter 2.33.0; neither exposes a supported awaitable cross-extension MCP tool-call API for pre-compaction recall/capture.

    Next step requires one maintainer decision:

    1. accept the current hybrid contract for v0.24—CLI owns automatic lifecycle work while MCP remains model-facing; or
    2. retain full transport parity and wait for a released adapter API that supports bounded invocation, cancellation, results/errors, and lifecycle ownership.

    After that decision, remaining work is synthesized-vs-raw capture semantics, lifecycle/deduplication and project-isolation tests, fresh-process mode comparison, and final distribution docs. No PR is pending.

  7. phernandez
    removed
    needs reviewA human maintainer needs to look at this issue
    on Sep 14, 2026

  8. phernandez commented on Sep 14, 2026

    @phernandez
    phernandez
    on Sep 14, 2026
    MemberAuthor

    Maintainer decision for v0.24: accept the CLI-owned lifecycle contract.

    Pi is intentionally CLI-first for automatic memory behavior. The Basic Memory CLI owns lifecycle recall, capture/checkpoint persistence, project routing, and bounded completion. MCP registration remains available for model-initiated tools, but transport: "mcp" does not promise that Pi lifecycle callbacks invoke MCP tools or provide transport parity.

    This resolves the decision blocker identified above. Do not wait for or build a cross-extension MCP invocation API, deep-import adapter internals, queue a model turn to simulate lifecycle persistence, or add another MCP host.

    Remaining delivery work for this issue:

    • make configuration/status/docs describe the hybrid boundary plainly;
    • finish synthesized durable capture versus explicit raw-turn opt-in semantics;
    • add lifecycle, branch/deduplication, failure-surfacing, and explicit project-isolation tests;
    • verify the CLI flow from a fresh Pi process;
    • finish distribution documentation and package checks.

    Removing needs review; the issue remains in v0.24.0 and is ready for this bounded CLI-flow completion.

  9. phernandez commented on Sep 14, 2026

    @phernandez
    phernandez
    on Sep 14, 2026
    MemberAuthor

    Correction to the decision above: “CLI-first” describes the transport, not lifecycle ownership.

    Pi owns the integration shape:

    • Pi's native session, branch, compaction, and extension lifecycle events decide when recall and capture happen.
    • The Basic Memory extension translates those native events into the smallest appropriate Basic Memory operations.
    • The bm CLI provides structured, bounded storage/search/read/write primitives and explicit project routing.
    • Basic Memory must adapt to Pi's event payloads and timing; Pi should not be made to emulate Basic Memory's hook protocol or lifecycle model.

    So the target is Basic Memory working naturally inside Pi, not a generic bm hook --harness pi flow that makes Pi behave like another harness. Reuse shared logic where it genuinely fits, but do not make shared lifecycle uniformity an acceptance criterion.

    Implementation implication: evaluate the current runHook path as replaceable scaffolding. Prefer direct adapter code driven by Pi-native events and backed by structured CLI commands. Preserve Pi's compaction/history behavior, make capture synthesis fit the information Pi actually exposes, and surface failures through Pi's normal extension UX.

    MCP remains model-facing and optional. No cross-extension MCP invocation parity is required for automatic lifecycle behavior.

    Updated remaining work:

    1. map Pi-native lifecycle events and guarantees;
    2. implement recall/capture at those native boundaries using structured CLI operations;
    3. test branching, compaction, deduplication, project isolation, and failure behavior in Pi terms;
    4. document the behavior as a Pi integration, with Basic Memory configuration limited to storage/routing concerns.
  10. phernandez
    changed the title [-]feat(integrations): Pi memory plugin with CLI and MCP modes — never start over[/-] [+]feat(integrations): Pi memory plugin using native lifecycle and Basic Memory CLI[/+] on Sep 14, 2026

  11. phernandez commented on Sep 14, 2026

    @phernandez
    phernandez
    on Sep 14, 2026
    MemberAuthor

    Final maintainer clarification: Pi integration is CLI-only. There is no MCP mode.

    The architectural contract for #1488 is:

    • Pi owns session, branching, compaction, lifecycle timing, and extension UX.
    • The Basic Memory Pi extension adapts to Pi's native events.
    • The extension invokes structured bm CLI operations for project routing, recall, reads, searches, and durable writes.
    • Basic Memory does not ask Pi to emulate a shared Basic Memory harness lifecycle.
    • Basic Memory does not register or invoke an MCP server for this integration.
    • There is no CLI/MCP parity matrix, transport switch, MCP adapter dependency, or model-facing MCP fallback in scope.

    Existing MCP-oriented implementation and acceptance text in this issue is superseded by this decision. Reuse useful CLI/package work from #1492 and #1509, but remove or simplify MCP-specific configuration and code where it exists.

    The remaining acceptance target is a host-native Pi integration, backed by the Basic Memory CLI, with tests expressed in Pi's own lifecycle terms.

  12. phernandez
    removed this from the v0.24.0 milestone on Sep 14, 2026

  13. phernandez commented on Sep 14, 2026

    @phernandez
    phernandez
    on Sep 14, 2026
    MemberAuthor

    Milestone decision: removing this from v0.24.0. The issue remains open under the clarified architecture: Pi-native lifecycle with structured Basic Memory CLI operations and no MCP mode. This integration can proceed independently without blocking the v0.24 release.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions