pi-automem-bridge 0.2.1 → 0.2.3

package/README.md

@@ -1,16 +1,16 @@
 <div align="center">
 
-![Pi Automem Bridge](assets/banner.png)
+![pi-automem-bridge](assets/banner.png)
 
 # pi-automem-bridge
 
-The missing link between [pi](https://github.com/earendil-works/pi) and [AutoMem](https://github.com/verygoodplugins/automem). If you already have both set up, this package connects them — giving pi automatic long-term memory: startup recall, turn-level recall, policy-gated writes, and relationship tools.
+> **AutoMem is the memory. This bridge ensures pi actually uses it.**
 
 ```bash
 pi install npm:pi-automem-bridge
 ```
 
-[![npm version](https://badge.fury.io/js/pi-automem-bridge.svg)](https://badge.fury.io/js/pi-automem-bridge)
+[![npm version](https://img.shields.io/npm/v/pi-automem-bridge)](https://www.npmjs.com/package/pi-automem-bridge)
 [![npm downloads](https://img.shields.io/npm/dw/pi-automem-bridge)](https://www.npmjs.com/package/pi-automem-bridge)
 
 [![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L2J320X82M)
@@ -19,6 +19,30 @@ pi install npm:pi-automem-bridge
 
 ---
 
+## Why pi-automem-bridge
+
+Plenty of agents can store a memory. Far fewer reach for it when it counts — or check what they're scribbling down. pi-automem-bridge makes pi do both, automatically: startup + per-turn recall injected straight into the prompt, and a secret-scanning, policy-gated write pipeline guarding the door to AutoMem.
+
+- **Per-project scoping** — recall limits and filters tuned to the repo or folder you're working in.
+- **Bring your own AutoMem** — talks to your existing instance over MCP. No duplicate credentials or storage to manage.
+
+> The storage and the recall/similarity intelligence are [AutoMem](https://github.com/verygoodplugins/automem)'s. This package is the guardrail-and-automation layer that makes them automatic inside pi.
+
+---
+
+## How it works
+
+Once installed, the bridge hooks into pi's session lifecycle:
+
+- **At session start** it runs your startup recall queries against AutoMem and injects the results — your preferences, working style, and environment — into the system prompt.
+- **Before each turn** it recalls memories relevant to the current task and the detected project, again injected silently.
+- **When the agent writes a memory** the candidate passes through the write pipeline — normalize → secret-scan → policy check → dedupe → confirm or auto-store — so nothing unvetted reaches AutoMem.
+- **Relationship tools** let the agent link memories or record corrections with provenance, building a connected graph over time.
+
+Recall display, write policy, and per-project scoping are all configurable — see the [Configuration reference](#configuration-reference).
+
+---
+
 ## Before you begin
 
 This package does not include pi or AutoMem — it connects them. You need both running independently first:
@@ -27,24 +51,25 @@ This package does not include pi or AutoMem — it connects them. You need both
 2. **[AutoMem](https://github.com/verygoodplugins/automem)** — the graph-vector memory service (self-hosted or Railway)
 3. **[mcp-automem](https://github.com/verygoodplugins/mcp-automem)** — the MCP bridge that exposes AutoMem's tools over the MCP protocol
 
-Once those three are in place, add `mcp-automem` to pi's MCP config and install this package. That's all the wiring this package needs.
+Once those three are in place, follow the setup below.
 
 ---
 
-## What it does
+## Setup
 
-- **Startup recall** — at session start, queries AutoMem for your preferences, working style, and environment
-- **Turn-level recall** — before each agent prompt, retrieves memories relevant to the current task and detected project
-- **Silent injection** — memory context is injected into the system prompt, not the chat window
-- **Policy-gated writes** — every memory write is validated, secret-scanned, deduplicated, and confirmed before storage
-- **Relationship tools** — link memories to each other or record corrections with provenance history
-- **Per-project tuning** — configure different recall limits and filters per detected project
+Three steps to a working install, then optional tuning. The package install is automatic — the **only** thing you must configure by hand is the connection to your own AutoMem server, because that carries your private server URL and token, and no package can (or should) write those for you.
 
----
+### 1. Install the package
+
+```bash
+pi install npm:pi-automem-bridge
+```
 
-## Getting started
+This registers the extension's tools, commands, and recall hooks with pi automatically. Nothing runs yet — it has no server to talk to.
 
-**1. Add your AutoMem server to `~/.pi/agent/mcp.json`:**
+### 2. Connect it to your AutoMem server — *required*
+
+Add an MCP server entry named `automem` to `~/.pi/agent/mcp.json`, pointing at the AutoMem instance from [Before you begin](#before-you-begin):
 
 ```json
 {
@@ -59,9 +84,17 @@ Once those three are in place, add `mcp-automem` to pi's MCP config and install
 }
 ```
 
-Use `${ENV_VAR}` interpolation for secrets. Never hardcode credentials.
+This is the one step that can't be automated: the package has no way to know your server's address or auth token, and writing credentials on your behalf would be unsafe. Use `${ENV_VAR}` interpolation for the token — never hardcode secrets. The entry must be named `automem` (the name the extension looks for by default), or set a different name via `mcpServerName` in step 4.
+
+**Don't want to hand-edit JSON?** pi is a coding agent — tell it to do it: *"add an `automem` MCP server to my `mcp.json` at `https://my-server.example.com/mcp`, using `${AUTOMEM_TOKEN}` for auth."* Keep the real token in your environment so it never touches the file or the chat.
+
+### 3. Reload pi
+
+Start a new session or run `/reload`. **That's it — recall is now automatic and the bridge runs on sensible defaults** (`safe-auto` writes, `summary` recall display). From here, just work: pi recalls on its own and saves routine decisions automatically — tell it *"remember this"* anytime you want something kept. Confirm everything's live with `/automem-status`.
+
+### 4. Tune behavior — *optional*
 
-**2. Create `~/.pi/agent/automem.json`:**
+The bridge works fully without this file. To customize recall queries, write policy, per-project scoping, or display mode, create `~/.pi/agent/automem.json` — any value you leave out falls back to its default. (Or just tell pi what you want — *"only auto-save bug fixes and technical decisions, and hide the recall block"* — and have it write the file for you.)
 
 ```json
 {
@@ -79,7 +112,7 @@ Use `${ENV_VAR}` interpolation for secrets. Never hardcode credentials.
 }
 ```
 
-**3. Start or reload pi.** Recall is now automatic.
+Every option — with real values you can copy — is in the [Configuration reference](#configuration-reference) below.
 
 ---
 
@@ -92,6 +125,8 @@ Use `${ENV_VAR}` interpolation for secrets. Never hardcode credentials.
 
 ## Tools
 
+You don't type these — pi does, in plain conversation. Tell it *"remember that I prefer Vitest over Jest"* and it runs the thought through the write pipeline before storing; say *"actually, we moved off Railway"* and it records a correction with provenance. In `safe-auto` mode it also captures routine decisions on its own, no prompting needed.
+
 | Tool | What it does |
 |---|---|
 | `automem_propose_memory` | Preview a memory candidate — validates, scans for secrets, checks for duplicates. Does not write. |
@@ -100,6 +135,8 @@ Use `${ENV_VAR}` interpolation for secrets. Never hardcode credentials.
 | `automem_link_memories` | Create a typed relationship between two existing memories. |
 | `automem_correct_memory` | Store a correction and link old → new with a provenance relationship (EVOLVED_INTO or CONTRADICTS). |
 
+Policy blocks, missing approval in non-interactive contexts, and invalid update requests surface as pi tool errors. User-cancelled confirmations and duplicate detection are normal control-flow results, so the agent can stop or choose the next write path deliberately.
+
 ---
 
 ## Write policy
@@ -135,16 +172,6 @@ When a commit finds a close match, `automem_commit_memory` returns `DUPLICATE_DE
 
 ---
 
-## Recall display modes
-
-| Mode | Behavior |
-|---|---|
-| `hidden` | Inject into system prompt only. Nothing shown in chat. |
-| `summary` | Inject into system prompt + show a compact notification. |
-| `full` | Show the full recall block. Useful for debugging. |
-
----
-
 ## Configuration reference
 
 Config file: `~/.pi/agent/automem.json` (or `AUTOMEM_CONFIG_PATH`)
@@ -152,14 +179,31 @@ Config file: `~/.pi/agent/automem.json` (or `AUTOMEM_CONFIG_PATH`)
 | Section | Purpose |
 |---|---|
 | `mcpServerName` | Which server in `mcp.json` to use |
-| `startupRecall` | Queries, tags, limits, byte budget for session-start recall |
-| `turnRecall` | Per-prompt recall: limits, memory types, relation/entity expansion |
+| `startupRecall` | Queries, tags, limits, byte budget, and timeout for session-start recall |
+| `turnRecall` | Per-prompt recall: limits, memory types, relation/entity expansion, and timeout |
 | `projectDetection` | Map git repos and folder names to project tags for scoped recall |
 | `projectOverrides` | Per-project overrides for turn recall limits and filters |
 | `writePolicy` | Write mode, categories, importance threshold, dedupe settings |
 | `behavior` | Display mode and content-length preferences |
 
-See [`examples/config.minimal.json`](examples/config.minimal.json) and [`examples/config.advanced.json`](examples/config.advanced.json).
+Set only the keys you want to change — everything else uses its default. Two ready-to-edit starting points ship with the package:
+
+- **[`config.minimal.json`](https://github.com/vaniteav/pi-automem-bridge/blob/main/examples/config.minimal.json)** — the smallest useful config.
+- **[`config.advanced.json`](https://github.com/vaniteav/pi-automem-bridge/blob/main/examples/config.advanced.json)** — every option above, filled in with real values and sensible defaults. Copy it, trim what you don't need.
+
+### Recall display (`behavior.displayRecall`)
+
+Controls how much of the recalled context shows in chat. Injection into the system prompt happens regardless.
+
+| Mode | Behavior |
+|---|---|
+| `hidden` | Inject into system prompt only. Nothing shown in chat. |
+| `summary` | Inject into system prompt + show a compact notification. |
+| `full` | Show the full recall block. Useful for debugging. |
+
+### Recall timeouts
+
+Recall is best-effort context enrichment, so it runs on a short, bounded timeout instead of the full MCP request timeout — a slow or unreachable AutoMem server degrades gracefully to no injection rather than blocking your prompt. Tune with `turnRecall.timeoutMs` (default `8000`) and `startupRecall.timeoutMs` (default `15000`).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-automem-bridge",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Automatic long-term memory recall and policy-gated writes for pi agents via AutoMem MCP",
   "keywords": [
     "pi-package",
@@ -27,7 +27,9 @@
   "scripts": {
     "test": "tsx tests/unit.ts && tsx tests/phase2-policy.ts && tsx tests/review-fixes.ts",
     "test:smoke": "tsx tests/phase1-smoke.ts",
-    "test:live": "tsx tests/phase2-live-write.ts"
+    "test:live": "tsx tests/phase2-live-write.ts",
+    "preflight": "node scripts/preflight.mjs",
+    "prepublishOnly": "node scripts/preflight.mjs"
   },
   "devDependencies": {
     "tsx": "^4.20.6"

package/src/tools/memory-tools.ts

@@ -68,11 +68,10 @@ export function registerMemoryTools(pi: ExtensionAPI) {
         config,
       ).catch(() => ({ text: "Similar recall failed.", matches: [] }));
 
-      return {
-        content: [{ type: "text" as const, text: formatProposal(decision.action, decision.reasons, decision.normalized, similarText, similarMatches) }],
-        details: { action: decision.action, reasons: decision.reasons, findings: decision.findings, candidate: decision.normalized, similarMatches },
-        isError: decision.action === "block",
-      };
+      return {
+        content: [{ type: "text" as const, text: formatProposal(decision.action, decision.reasons, decision.normalized, similarText, similarMatches) }],
+        details: { action: decision.action, reasons: decision.reasons, findings: decision.findings, candidate: decision.normalized, similarMatches },
+      };
     },
   });
 
@@ -87,15 +86,11 @@ export function registerMemoryTools(pi: ExtensionAPI) {
       const config = loadConfig();
       setAutoMemMcpServerName(config.mcpServerName);
       const candidate = toCandidate(params);
-      const decision = evaluateWritePolicy(candidate, config);
-
-      if (decision.action === "block") {
-        return {
-          content: [{ type: "text" as const, text: "Blocked by AutoMem write policy.\n" + decision.reasons.map((r: string) => "- " + r).join("\n") }],
-          details: { action: decision.action, reasons: decision.reasons, findings: decision.findings },
-          isError: true,
-        };
-      }
+      const decision = evaluateWritePolicy(candidate, config);
+
+      if (decision.action === "block") {
+        throw new Error("Blocked by AutoMem write policy.\n" + decision.reasons.map((r: string) => "- " + r).join("\n"));
+      }
 
       const needsConfirmation = decision.action !== "auto";
       if (needsConfirmation && !params.approvedByUser) {
@@ -104,14 +99,10 @@ export function registerMemoryTools(pi: ExtensionAPI) {
           if (!ok) {
             return { content: [{ type: "text" as const, text: "AutoMem memory write cancelled." }], details: { cancelled: true } };
           }
-        } else {
-          return {
-            content: [{ type: "text" as const, text: "Confirmation required before storing this memory. Re-run with approvedByUser=true only after explicit user approval." }],
-            details: { action: decision.action, reasons: decision.reasons, candidate: decision.normalized },
-            isError: true,
-          };
-        }
-      }
+        } else {
+          throw new Error("Confirmation required before storing this memory. Re-run with approvedByUser=true only after explicit user approval.");
+        }
+      }
 
       // ── UPDATE path ──────────────────────────────────────────────────────
       if (params.updateMemoryId) {
@@ -158,11 +149,10 @@ export function registerMemoryTools(pi: ExtensionAPI) {
               "  2. Store anyway (new memory): call automem_commit_memory with dedupeQuery=\"\" to skip dedupe",
               "  3. Cancel: do nothing if this is not worth storing separately",
             ].join("\n"),
-          }],
-          details: { duplicateDetected: true, existingMemoryId: top.id, existingContent: top.content, candidate: decision.normalized, allSimilar: similarMatches },
-          isError: false,
-        };
-      }
+          }],
+          details: { duplicateDetected: true, existingMemoryId: top.id, existingContent: top.content, candidate: decision.normalized, allSimilar: similarMatches },
+        };
+      }
 
       // ── STORE path ───────────────────────────────────────────────────────
       const result = await automemStore(
@@ -193,12 +183,9 @@ export function registerMemoryTools(pi: ExtensionAPI) {
     promptSnippet: "Use after automem_commit_memory returns DUPLICATE_DETECTED, or when correcting a known memory. Requires the existing memory ID.",
     parameters: UpdateParams,
     async execute(_toolCallId, params, _signal, _onUpdate, ctx: any) {
-      if (!params.memoryId) {
-        return {
-          content: [{ type: "text" as const, text: "memoryId is required for automem_update_memory." }],
-          isError: true,
-        };
-      }
+      if (!params.memoryId) {
+        throw new Error("memoryId is required for automem_update_memory.");
+      }
 
       if (!params.approvedByUser) {
         if (ctx && ctx.ui && typeof ctx.ui.confirm === "function") {
@@ -212,13 +199,10 @@ export function registerMemoryTools(pi: ExtensionAPI) {
           if (!ok) {
             return { content: [{ type: "text" as const, text: "AutoMem memory update cancelled." }], details: { cancelled: true } };
           }
-        } else {
-          return {
-            content: [{ type: "text" as const, text: "Confirmation required before updating this memory. Re-run with approvedByUser=true only after explicit user approval." }],
-            isError: true,
-          };
-        }
-      }
+        } else {
+          throw new Error("Confirmation required before updating this memory. Re-run with approvedByUser=true only after explicit user approval.");
+        }
+      }
 
       const result = await automemUpdate(params.memoryId, {
         content: params.content,

package/src/tools/relationship-tools.ts

@@ -31,14 +31,11 @@ export function registerRelationshipTools(pi: ExtensionAPI) {
     parameters: LinkParams,
     async execute(_toolCallId: string, params: any) {
       const config = loadConfig();
-      setAutoMemMcpServerName(config.mcpServerName);
-
-      if (!params.approvedByUser) {
-        return {
-          content: [{ type: "text" as const, text: "Confirmation required before linking memories. Re-run with approvedByUser=true only after explicit user approval.\n\nWould link:\n  " + params.memoryId1 + " → " + params.relationship + " → " + params.memoryId2 }],
-          isError: true,
-        };
-      }
+      setAutoMemMcpServerName(config.mcpServerName);
+
+      if (!params.approvedByUser) {
+        throw new Error("Confirmation required before linking memories. Re-run with approvedByUser=true only after explicit user approval.\n\nWould link:\n  " + params.memoryId1 + " -> " + params.relationship + " -> " + params.memoryId2);
+      }
 
       const strength = typeof params.strength === "number" ? params.strength : 0.5;
       const result = await automemAssociate(params.memoryId1, params.memoryId2, params.relationship, strength);
@@ -66,21 +63,14 @@ export function registerRelationshipTools(pi: ExtensionAPI) {
         tags: Array.isArray(params.tags) ? params.tags : [],
         importance: params.importance,
       };
-      const decision = evaluateWritePolicy(candidate, config);
-      if (decision.action === "block") {
-        return {
-          content: [{ type: "text" as const, text: "Blocked by AutoMem write policy.\n" + decision.reasons.map((r: string) => "- " + r).join("\n") }],
-          details: { action: decision.action, reasons: decision.reasons, findings: decision.findings },
-          isError: true,
-        };
-      }
-
-      if (!params.approvedByUser) {
-        return {
-          content: [{ type: "text" as const, text: "Confirmation required before correcting memory. Re-run with approvedByUser=true only after explicit user approval.\n\nWould correct memory " + params.memoryId + " with:\n  " + params.correction }],
-          isError: true,
-        };
-      }
+      const decision = evaluateWritePolicy(candidate, config);
+      if (decision.action === "block") {
+        throw new Error("Blocked by AutoMem write policy.\n" + decision.reasons.map((r: string) => "- " + r).join("\n"));
+      }
+
+      if (!params.approvedByUser) {
+        throw new Error("Confirmation required before correcting memory. Re-run with approvedByUser=true only after explicit user approval.\n\nWould correct memory " + params.memoryId + " with:\n  " + params.correction);
+      }
 
       const rel = params.relationship === "CONTRADICTS" ? "CONTRADICTS" : "EVOLVED_INTO";
       // Store the normalized candidate so corrections get the same alwaysTag,