Skip to content

Commit ae517fb

Browse files
phernandezphernandez
committed
feat(integrations): add Pi memory package
Signed-off-by: phernandez <paul@basicmachines.co>
1 parent cf54013 commit ae517fb

29 files changed

Lines changed: 6326 additions & 7 deletions

‎.github/workflows/consolidated-packages.yml‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,24 @@ jobs:
9797
- name: Validate manifest and run unit tests
9898
run: just check
9999

100+
pi:
101+
name: Pi package
102+
permissions:
103+
contents: read
104+
runs-on: ubuntu-latest
105+
steps:
106+
- uses: actions/checkout@v4
107+
108+
- uses: extractions/setup-just@v4
109+
110+
- uses: actions/setup-node@v4
111+
with:
112+
node-version: "24"
113+
registry-url: "https://registry.npmjs.org"
114+
115+
- name: Validate extension, bundled skills, tests, and package
116+
run: just package-check-pi
117+
100118
openclaw:
101119
name: OpenClaw package
102120
permissions:

‎docs/PI_MEMORY_E2E_RESULTS.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Pi memory end-to-end results
2+
3+
## Environment
4+
5+
- Pi: 0.85.1
6+
- Basic Memory CLI: 0.23.2 from `/Users/phernandez/dev/basicmachines/basic-memory/.venv/bin/bm`
7+
- Model-backed Pi RPC runs: `openai-codex/gpt-5.5`
8+
- All Basic Memory data/config used isolated temp directories via `BASIC_MEMORY_HOME` and `BASIC_MEMORY_CONFIG_DIR`.
9+
- Project config used per-temp-workspace `.pi/basic-memory.json`; no live Pi config was modified.
10+
11+
## CLI capture → fresh CLI recall
12+
13+
Temp project: `pi-e2e-cli` in `/tmp/pi-bm-e2e-cli.B41VJy`.
14+
15+
Flow:
16+
17+
1. Created isolated local Basic Memory project with `bm project add pi-e2e-cli ... --default --local --no-wait`.
18+
2. Started Pi RPC with the local Basic Memory Pi package in CLI mode.
19+
3. Sent a working-thread prompt containing:
20+
- decision: support CLI and MCP modes with shared Basic Memory notes;
21+
- rationale: transport is secondary to never starting over;
22+
- blocker: MCP adapter mode still needs an isolated run;
23+
- next step: run fresh-session recall.
24+
4. Ran `/bm-capture Pi E2E CLI continuity checkpoint`.
25+
5. Verified note through `bm tool search-notes`.
26+
6. Started a separate fresh Pi RPC session and ran `/bm-recall transport is secondary`.
27+
28+
Result:
29+
30+
- Created note: `pi-e2e-cli/pi/sessions/pi-e2-e-cli-continuity-checkpoint`
31+
- Fresh-session recall injected a `basic-memory-pi` custom message containing the note permalink, decision, rationale, blocker, and next step.
32+
33+
## CLI-written note → MCP adapter recall
34+
35+
Same isolated `pi-e2e-cli` project.
36+
37+
Flow:
38+
39+
1. Switched `.pi/basic-memory.json` to `transport: "mcp"` and `mcpServerName: "basic-memory-e2e"`.
40+
2. Started Pi RPC with both `npm:pi-mcp-adapter@2.32.1` and the local Basic Memory Pi package.
41+
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`.
42+
43+
Result:
44+
45+
- The model connected the runtime-registered Basic Memory MCP server, discovered `basic-memory-e2e_search_notes`, called it, and answered with:
46+
- permalink: `pi-e2e-cli/pi/sessions/pi-e2-e-cli-continuity-checkpoint`
47+
- decision: Pi integration must support CLI and MCP modes with shared Basic Memory notes;
48+
- rationale: transport is secondary to never starting over;
49+
- blocker: MCP adapter mode still needs an isolated run;
50+
- next step: run fresh-session recall.
51+
52+
## MCP adapter write → CLI recall
53+
54+
Temp project: `pi-e2e-mcp` in `/tmp/pi-bm-e2e-mcp.Lt83CA`.
55+
56+
Flow:
57+
58+
1. Created isolated local Basic Memory project with `bm project add pi-e2e-mcp ... --default --local --no-wait`.
59+
2. Started Pi RPC with `npm:pi-mcp-adapter@2.32.1` and the local Basic Memory Pi package in MCP mode.
60+
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`.
61+
4. Verified the MCP-written note through the CLI with `bm tool search-notes`.
62+
63+
Result:
64+
65+
- Created note: `pi-e2e-mcp/pi/sessions/pi-e2-e-mcp-continuity-checkpoint`
66+
- CLI search found the MCP-written note with:
67+
- decision: MCP adapter writes use the same portable Basic Memory notes;
68+
- rationale: CLI and MCP should interoperate without migration;
69+
- blocker: automation defaults remain unsettled;
70+
- next step: verify CLI recall of this MCP-written note.
71+
72+
## Issues observed
73+
74+
- 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.
75+
- In MCP mode the model first listed the server before connecting, then called `mcp({ connect })`. This is expected adapter behavior for lazy runtime servers.
76+
- 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‎

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

‎docs/PI_MEMORY_PLAN.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
# Pi memory integration: you are never starting over
2+
3+
## Goal
4+
5+
A fresh Pi session recovers the relevant decisions, working state, blockers, and next
6+
steps without the user repeating the previous conversation. Knowledge belongs to the
7+
user and remains usable across agents, projects, and local/cloud deployments.
8+
9+
Ship one Pi package with two user-selectable access modes: Basic Memory CLI and an
10+
existing Pi MCP adapter. Share memory behavior and skills, not two independent memory
11+
implementations. Switching transport must not require migrating notes.
12+
13+
## Confirmed direction
14+
15+
- Implement under `integrations/pi/` in the Basic Memory monorepo.
16+
- Reuse canonical top-level memory skills and Basic Memory routing/authentication.
17+
- Support CLI access and MCP through an existing extension; do not build a generic MCP host.
18+
- Preserve Pi's native session history and compaction.
19+
- Distinguish lifecycle metadata, raw transcripts, and synthesized durable knowledge.
20+
- Keep project selection explicit; never change the user's global default implicitly.
21+
- Surface capture/recall failures without blocking ordinary work or claiming a save succeeded.
22+
23+
## Phase 1 — investigate and prove transport contracts
24+
25+
- [x] Inspect `pi-mcp-adapter` and alternatives: current Pi compatibility, tool naming,
26+
discovery, cancellation, shutdown/reload, stdio and remote support, licensing.
27+
- [x] Determine whether lifecycle hooks can invoke the adapter through a supported API.
28+
If not, document the limitation before choosing how automated recall/capture runs;
29+
do not depend on private adapter internals.
30+
- [x] Verify installed `bm` CLI flags, structured output, write error/overwrite semantics,
31+
stdin support, project UUID routing, and local/cloud behavior against real calls.
32+
- [x] Inspect existing `bm hook` recall/checkpoint implementation for reusable core logic.
33+
Its documented harnesses are Claude and Codex, not Pi.
34+
- [x] Record a short architecture decision with version requirements and initial defaults.
35+
See `docs/PI_MEMORY_TRANSPORT_DECISION.md`.
36+
37+
## Phase 2 — smallest end-to-end continuity slice
38+
39+
- [x] Add Pi package metadata, TypeScript extension entrypoint, config validation,
40+
and hermetic test setup.
41+
- [x] Support explicit CLI/MCP mode and project selection with visible status.
42+
- [x] Bundle a focused set of shared skills: notes, capture, continue, and tasks.
43+
- [ ] Verify bundled skill tool/CLI instructions work in both modes without duplicate discovery.
44+
- [x] Capture one coherent working-thread note with goal, decisions and rationale,
45+
current state, blockers, next steps, and source/session provenance.
46+
- [x] Start a separate fresh Pi process and recover that thread through Basic Memory.
47+
- [x] Repeat the identical scenario through the other access mode.
48+
See `docs/PI_MEMORY_E2E_RESULTS.md`.
49+
50+
## Phase 3 — lifecycle continuity
51+
52+
- [ ] Bounded recall at session entry / first relevant prompt, including note identifiers
53+
and source provenance; avoid repeatedly injecting the same context.
54+
- [ ] Capture important decisions during work; support explicit remember/recall commands.
55+
- [ ] Add compaction-aware durable checkpoints without replacing native compaction.
56+
Settle checkpoint timing using Pi lifecycle tests, not assumptions about reentrant turns.
57+
- [ ] Restore state on reload/resume and track forks/tree navigation without merging
58+
contradictory branches or duplicating captures.
59+
- [ ] Choose and document automatic capture defaults and destinations. Raw transcript
60+
capture is a separate opt-in decision, not an implied prerequisite for continuity.
61+
- [ ] Treat recalled notes as source material, not privileged instructions. Respect project
62+
trust and never route private session traces into shared projects implicitly.
63+
- [ ] Bound subprocess/request duration, propagate cancellation, and clean up owned resources.
64+
Never blindly retry non-idempotent writes after an ambiguous transport failure.
65+
66+
## Phase 4 — compare CLI and MCP
67+
68+
Run both modes with the same Basic Memory version, seeded notes, model, task prompts,
69+
retrieval budgets, and capture policy. Use independent sessions and equivalent isolated
70+
projects so one trial cannot benefit from another trial's captures.
71+
72+
Measure separately:
73+
74+
- cold startup, first operation, warm read/search/write latency;
75+
- tool discovery and prompt overhead, tokens and provider usage;
76+
- successful writes and recovery of their actual identifiers;
77+
- recall correctness: decision, rationale, blocker, next action, source citation;
78+
- duplication, routing isolation, and behavior after errors/reload/compaction.
79+
80+
Test local routing first. Cloud tests are opt-in against a dedicated test project;
81+
never mutate existing personal/team projects as fixtures. Report model-backed quality
82+
results separately from deterministic transport assertions. Recommend a default from
83+
observed results while keeping both modes supported.
84+
85+
## Acceptance scenarios
86+
87+
1. Session A records a decision and unfinished next step. Fresh session B receives only
88+
the topic and recovers the decision, rationale, and next step with a real note reference.
89+
2. CLI captures are recalled over MCP and vice versa without migration.
90+
3. Reload, resume, compaction, and forks preserve usable context without duplicate writes
91+
or attributing another branch's state to the current branch.
92+
4. Two projects with conflicting decisions remain isolated, including ambiguous names.
93+
5. Missing CLI, unavailable MCP server, auth failure, cancellation, and failed writes are
94+
visible; Pi remains usable and never falsely confirms persistence.
95+
6. Opted-out capture writes nothing; retrieved note instructions cannot change capture
96+
settings or destination routing.
97+
98+
## Phase 5 — distribution and documentation
99+
100+
- [x] Root `just package-check-pi` target and integration into consolidated package checks.
101+
- [x] Package install/pack validation and isolated Pi subprocess smoke tests.
102+
See `docs/PI_MEMORY_E2E_RESULTS.md`.
103+
- [x] README with CLI and MCP installation, explicit mode switching, project routing,
104+
privacy defaults, failure recovery, and supported version matrix.
105+
- [ ] Add the Pi integration page to `docs.basicmemory.com` in a separate docs change.
106+
- [ ] Wire release metadata/publishing consistently with existing integration packages.
107+
Version bump wiring is in place; npm publishing workflow is still open.
108+
See `docs/PI_MEMORY_SHIPPING.md`.
109+
110+
## Development workflow
111+
112+
Worktree: `../basic-memory-pi`; branch: `feat/pi-memory` (created from local `origin/main`).
113+
Use separate Pi print/JSON/RPC processes for end-to-end verification and isolated Basic
114+
Memory config/data. Model-backed tests require available provider access and incur usage.
115+
Use `/reload` for interactive development once the extension is configured; a full restart
116+
is not normally required. Do not install extensions into the user's live config implicitly.
117+
118+
## References
119+
120+
Live website index: https://docs.basicmemory.com/llms.txt
121+
122+
Live Markdown read during planning:
123+
- https://docs.basicmemory.com/raw/reference/ai-assistant-guide.md
124+
- https://docs.basicmemory.com/raw/integrations/harness-capture.md
125+
126+
Additional documentation reviewed from the sibling website source checkout:
127+
- https://docs.basicmemory.com/raw/reference/cli-reference.md
128+
- https://docs.basicmemory.com/raw/cloud/cloud-cli.md
129+
- https://docs.basicmemory.com/raw/cloud/routing.md
130+
- https://docs.basicmemory.com/raw/integrations/hermes.md
131+
- https://docs.basicmemory.com/raw/integrations/openclaw.md
132+
133+
Implementation references: `integrations/openclaw/`, `integrations/hermes/`, `skills/`.
134+
MCP adapter: https://github.com/nicobailon/pi-mcp-adapter (`2.32.1` compatibility verified for the initial runtime-registration scenario).
135+
Pi: installed README, extension/package/skill/compaction documentation and examples.

0 commit comments

Comments
 (0)