pi-automem-bridge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vaniteav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+<div align="center">
+
+# 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.
+
+```bash
+pi install npm:pi-automem-bridge
+```
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/L2J320X82M)
+
+</div>
+
+---
+
+## Before you begin
+
+This package does not include pi or AutoMem — it connects them. You need both running independently first:
+
+1. **[pi](https://github.com/earendil-works/pi)** — the agent this extension runs inside
+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.
+
+---
+
+## What it does
+
+- **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
+
+---
+
+## Getting started
+
+**1. Add your AutoMem server to `~/.pi/agent/mcp.json`:**
+
+```json
+{
+  "mcpServers": {
+    "automem": {
+      "url": "https://your-automem-server.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${AUTOMEM_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Use `${ENV_VAR}` interpolation for secrets. Never hardcode credentials.
+
+**2. Create `~/.pi/agent/automem.json`:**
+
+```json
+{
+  "mcpServerName": "automem",
+  "startupRecall": {
+    "queries": [
+      "user preferences working style",
+      "current environment setup",
+      "active projects and recent decisions"
+    ]
+  },
+  "behavior": {
+    "displayRecall": "summary"
+  }
+}
+```
+
+**3. Start or reload pi.** Recall is now automatic.
+
+---
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `/automem-status` | Health check — shows memory count and active config |
+| `/automem-recall <query>` | Manual recall query for debugging |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `automem_propose_memory` | Preview a memory candidate — validates, scans for secrets, checks for duplicates. Does not write. |
+| `automem_commit_memory` | Store a policy-approved memory. Returns `DUPLICATE_DETECTED` if a similar memory exists. |
+| `automem_update_memory` | Update an existing memory by ID. |
+| `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). |
+
+---
+
+## Write policy
+
+Every write goes through: normalize → secret scan → policy check → dedupe → confirm/auto → store. Nothing bypasses this pipeline.
+
+```json
+{
+  "writePolicy": {
+    "mode": "safe-auto",
+    "autoWriteCategories": ["technical-decision", "agent-pattern", "bug-fix", "tooling-lesson"],
+    "confirmCategories": ["personal", "financial", "private", "identity"],
+    "blockedCategories": ["secret", "credential", "api-key", "raw-transcript"],
+    "minImportanceToWrite": 0.7,
+    "dedupeBeforeWrite": true
+  }
+}
+```
+
+| Mode | Behavior |
+|---|---|
+| `safe-auto` | Auto-write configured low-risk categories; confirm everything else. **Default.** |
+| `propose` | Propose all candidates; require explicit approval to commit. |
+| `confirm-all` | Confirm every write individually. |
+| `off` | Block all writes. |
+
+### Duplicate handling
+
+When a commit finds a close match, `automem_commit_memory` returns `DUPLICATE_DETECTED` with the existing memory's ID. Options:
+1. Update it — re-call with `updateMemoryId` set to the returned ID
+2. Force a new store — set `dedupeQuery: ""` to skip the check
+3. Cancel — do nothing if the existing memory already covers it
+
+---
+
+## 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`)
+
+| 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 |
+| `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).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/vaniteav/pi-automem-bridge.git
+cd pi-automem-bridge
+npm install
+npm test               # offline tests
+npm run test:smoke     # live smoke test (requires AutoMem)
+npm run test:live      # full round-trip write test (requires AutoMem)
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for architecture notes, test descriptions, and release process.
+
+---
+
+## Credits
+
+This package builds on two excellent open-source projects:
+
+- **[pi](https://github.com/earendil-works/pi)** by [Earendil Works](https://github.com/earendil-works) — the extensible AI agent toolkit this package runs on
+- **[AutoMem](https://github.com/verygoodplugins/automem)** by [Very Good Plugins](https://github.com/verygoodplugins) — the graph-vector memory service powering recall and storage
+- **[mcp-automem](https://github.com/verygoodplugins/mcp-automem)** by [Very Good Plugins](https://github.com/verygoodplugins) — the MCP bridge this extension communicates through
+
+---
+
+## License
+
+MIT — [vaniteav](https://github.com/vaniteav)
+
+---

package/examples/config.advanced.json

@@ -0,0 +1,59 @@
+{
+  "mcpServerName": "automem",
+  "startupRecall": {
+    "queries": [
+      "user preferences working style",
+      "agent operating guidelines",
+      "local development environment",
+      "active projects recent decisions"
+    ],
+    "tags": ["source:pi"],
+    "tagMode": "any",
+    "limit": 6,
+    "maxBytes": 5000
+  },
+  "turnRecall": {
+    "enabled": true,
+    "limit": 5,
+    "maxBytes": 3000,
+    "contextTypes": ["Preference", "Decision", "Pattern", "Insight", "Context"],
+    "expandRelations": true,
+    "expandEntities": true
+  },
+  "projectDetection": {
+    "tagPrefix": "project:",
+    "folderTags": {
+      "projects": ["project"],
+      "areas": ["area"],
+      "resources": ["resource"]
+    },
+    "gitRepoToTag": {
+      "my-project": "project:my-project"
+    }
+  },
+  "writePolicy": {
+    "mode": "safe-auto",
+    "autoWriteCategories": ["technical-decision", "agent-pattern", "bug-fix", "tooling-lesson"],
+    "confirmCategories": ["personal", "financial", "private", "identity"],
+    "blockedCategories": ["secret", "credential", "api-key", "raw-transcript"],
+    "alwaysTag": ["source:pi"],
+    "minImportanceToWrite": 0.7,
+    "dedupeBeforeWrite": true,
+    "dedupeLimit": 3
+  },
+  "behavior": {
+    "displayRecall": "hidden",
+    "maxContentLength": 2000,
+    "preferredContentLength": 500
+  },
+  "projectOverrides": {
+    "project:my-large-project": {
+      "limit": 10,
+      "maxBytes": 6000
+    },
+    "project:quick-scripts": {
+      "limit": 2,
+      "maxBytes": 1000
+    }
+  }
+}

package/examples/config.minimal.json

@@ -0,0 +1,10 @@
+{
+  "mcpServerName": "automem",
+  "startupRecall": {
+    "queries": ["my preferences and working style"],
+    "limit": 5
+  },
+  "writePolicy": {
+    "alwaysTag": ["source:pi"]
+  }
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "pi-automem-bridge",
+  "version": "0.2.0",
+  "description": "Automatic long-term memory recall and policy-gated writes for pi agents via AutoMem MCP",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "automem",
+    "mcp",
+    "memory",
+    "long-term-memory",
+    "semantic-memory",
+    "memory-write-policy",
+    "agent-memory"
+  ],
+  "license": "MIT",
+  "author": "vaniteav",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vaniteav/pi-automem-bridge.git"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.78.0",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "tsx tests/unit.ts && tsx tests/write-policy.ts",
+    "test:smoke": "tsx tests/smoke.ts",
+    "test:live": "tsx tests/live-write.ts"
+  },
+  "devDependencies": {
+    "tsx": "^4.20.6"
+  },
+  "dependencies": {},
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "bugs": {
+    "url": "https://github.com/vaniteav/pi-automem-bridge/issues"
+  },
+  "homepage": "https://github.com/vaniteav/pi-automem-bridge#readme",
+  "files": [
+    "src",
+    "skills",
+    "prompts",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/prompts/automem-guidelines.md

@@ -0,0 +1,42 @@
+# AutoMem Behavioral Guidelines
+
+AutoMem is pi's long-term semantic memory, available automatically in this session.
+
+## What's already done for you
+
+- **Startup recall** ran at session start — relevant memories about preferences, environment, and operating style are already loaded.
+- **Turn-level recall** runs before every agent turn — memories related to the current project and prompt are automatically injected.
+- The `/automem-status` command shows health and memory count.
+- The `/automem-recall <query>` command does manual recall for debugging.
+
+## Recall behavior
+
+- Startup recall runs at session start and turn-level recall runs before each agent turn.
+- Use `/automem-recall <query>` for manual recall/debugging.
+- If AutoMem is unreachable, pi works normally — the footer status indicator shows "AutoMem (offline)".
+
+## Write behavior
+
+- Do **not** write raw session transcripts, long summaries, or incidental chatter.
+- Use `automem_propose_memory` first for durable candidates. It validates type/tags/importance, scans for secrets, and checks for similar memories.
+- Use `automem_commit_memory` only after explicit user approval, unless the category is in the safe-auto list (technical-decision, agent-pattern, bug-fix, tooling-lesson) — those auto-write by default.
+- Good memory candidates are compact, intentional, and useful across sessions: decisions, preferences, repeated patterns, key insights, durable bug-fix lessons, and important project context.
+
+## Relationship tools
+
+- `automem_link_memories` — create a typed relationship between two existing memories by ID. Requires both IDs and a `RelationshipType`. Use after recognizing that two stored memories are causally or semantically linked.
+- `automem_correct_memory` — store a corrected version of an existing memory and link the old memory to the new one (EVOLVED_INTO or CONTRADICTS). Use when the original memory was wrong or outdated and you want to preserve the history. For simple in-place edits, use `automem_update_memory` instead.
+
+## Memory types
+
+AutoMem uses 7 typed memories: Decision, Pattern, Preference, Style, Habit, Insight, Context.
+
+## Relationship types
+
+The 11 relationship types are: RELATES_TO, LEADS_TO, OCCURRED_BEFORE, PREFERS_OVER, EXEMPLIFIES, CONTRADICTS, REINFORCES, INVALIDATED_BY, EVOLVED_INTO, DERIVED_FROM, PART_OF.
+
+## What NOT to do
+
+- Never store secrets, API keys, credentials, or raw conversation transcripts in AutoMem.
+- Never store unverified guesses as facts.
+- If AutoMem content conflicts with live files or known current state, trust live state first.

package/skills/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: automem-bridge
+description: Long-term semantic memory for pi via AutoMem MCP. Provides startup recall, turn-level recall, project detection, and memory health status. Use when the session starts, when recalling context, or when checking AutoMem health.
+---
+
+# AutoMem Core Extension
+
+Long-term semantic memory for pi via AutoMem MCP.
+
+## Commands
+
+- `/automem-status` — Show AutoMem health, memory count, and config summary
+- `/automem-recall <query>` — Manually query AutoMem (debugging)
+- `automem_propose_memory` — Validate/preview a durable memory candidate without writing
+- `automem_commit_memory` — Store a policy-approved memory after confirmation or safe-auto policy
+- `automem_link_memories` — Create a typed relationship between two existing memories
+- `automem_correct_memory` — Store a correction and link old → new with provenance (EVOLVED_INTO/CONTRADICTS)
+
+## Config
+
+Config lives at `~/.pi/agent/automem.json`. See the README for the full schema.
+
+Key settings:
+- `startupRecall.enabled` — Run recall at session start (default: true)
+- `startupRecall.queries` — Queries to run at startup
+- `turnRecall.enabled` — Run recall before each agent turn (default: true)
+- `projectDetection.enabled` — Auto-detect project from git/cwd (default: true)
+
+## Status indicator
+
+The footer shows:
+- `● AutoMem (42)` — healthy, 42 memories
+- `● AutoMem (offline)` — unreachable
+
+## Write policy
+
+Default mode is safe-auto for the four low-risk categories (technical-decision, agent-pattern, bug-fix, tooling-lesson); all other writes require explicit approval. Store only compact durable knowledge: decisions, preferences, patterns, insights, and important context. Never store secrets, credentials, raw transcripts, or incidental chatter.
+
+Use `automem_propose_memory` before committing. Use `automem_commit_memory` only after explicit user approval unless config enables safe-auto for the exact low-risk category.
+
+If AutoMem is down, pi works normally with a warning.

package/src/commands/recall.ts

@@ -0,0 +1,44 @@
+/**
+ * /automem-recall - Manual recall for debugging.
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { automemRecall, setAutoMemMcpServerName } from "../mcp-client";
+import { loadConfig } from "../config";
+
+export function registerRecallCommand(pi: {
+  registerCommand: (name: string, opts: {
+    description: string;
+    handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+  }) => void;
+}) {
+  pi.registerCommand("automem-recall", {
+    description: "Manually query AutoMem: /automem-recall <query>",
+    handler: async function(args: string, ctx: ExtensionCommandContext) {
+      const query = args.trim();
+      if (!query) {
+        ctx.ui.notify("Usage: /automem-recall <query>", "warning");
+        return;
+      }
+
+      const config = loadConfig();
+      setAutoMemMcpServerName(config.mcpServerName);
+
+      try {
+        const result = await automemRecall(query, {
+          limit: config.startupRecall.limit,
+          tags: config.startupRecall.tags,
+          tagMode: config.startupRecall.tagMode,
+        });
+
+        const text = (result.content && result.content[0] && result.content[0].text)
+          ? result.content[0].text
+          : "(no results)";
+        const preview = text.length > 500 ? text.slice(0, 500) + "..." : text;
+        ctx.ui.notify('Results for "' + query + '":\n' + preview, "info");
+      } catch (err) {
+        ctx.ui.notify("Recall failed: " + err, "error");
+      }
+    },
+  });
+}

package/src/commands/status.ts

@@ -0,0 +1,40 @@
+/**
+ * /automem-status - Show AutoMem health, memory count, and config summary.
+ */
+
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { automemHealth, setAutoMemMcpServerName } from "../mcp-client";
+import { loadConfig } from "../config";
+
+export function registerStatusCommand(pi: {
+  registerCommand: (name: string, opts: {
+    description: string;
+    handler: (args: string, ctx: ExtensionCommandContext) => Promise<void>;
+  }) => void;
+}) {
+  pi.registerCommand("automem-status", {
+    description: "Show AutoMem health and memory count",
+    handler: async function(_args: string, ctx: ExtensionCommandContext) {
+      const config = loadConfig();
+      setAutoMemMcpServerName(config.mcpServerName);
+
+      ctx.ui.notify("Checking AutoMem...", "info");
+
+      const health = await automemHealth();
+
+      if (health.healthy) {
+        const count = health.memoryCount != null ? " (" + health.memoryCount + " memories)" : "";
+        ctx.ui.notify("AutoMem: healthy" + count, "success");
+      } else {
+        ctx.ui.notify("AutoMem: unhealthy - " + (health.error || "unknown error"), "error");
+      }
+
+      ctx.ui.notify(
+        "Config: startup=" + (config.startupRecall.enabled ? "on" : "off") +
+        " turn=" + (config.turnRecall.enabled ? "on" : "off") +
+        " project=" + (config.projectDetection.enabled ? "on" : "off"),
+        "info",
+      );
+    },
+  });
+}