@plur-ai/mcp 0.5.2 → 0.6.0

package/README.md

@@ -8,16 +8,14 @@ Part of [PLUR](https://plur.ai) — where **Haiku with memory outperforms Opus w
 
 ### Claude Code
 
-Add to `.claude/mcp.json`:
+One command — sets up storage, MCP config, and hooks:
 
-```json
-{
-  "mcpServers": {
-    "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp"] }
-  }
-}
+```bash
+npx @plur-ai/mcp init
 ```
 
+Restart Claude Code. Done. Your agent now has persistent memory with automatic injection.
+
 ### Cursor
 
 Add to `.cursor/mcp.json`:
@@ -52,31 +50,32 @@ Your agent gets these tools automatically:
 
 | Tool | What it does |
 |------|-------------|
-| `plur.learn` | Store a memory — correction, preference, convention, or decision |
-| `plur.recall` | Keyword search (BM25, instant) |
-| `plur.recall.hybrid` | **Best default** — BM25 + embeddings merged via RRF. Zero cost. |
-| `plur.inject` | Load relevant memories for the current task |
-| `plur.feedback` | Rate a memory — trains relevance over time |
-| `plur.forget` | Retire a memory (history preserved) |
-| `plur.sync` | Sync memory across machines via git |
-| `plur.sync.status` | Check sync state |
-| `plur.capture` | Record a session event |
-| `plur.timeline` | Query session history |
-| `plur.ingest` | Extract learnings from text |
-| `plur.packs.install` | Install a shareable memory pack |
-| `plur.packs.list` | List installed packs |
-| `plur.status` | System health |
+| `plur_session_start` | Start a session — injects relevant engrams for your task |
+| `plur_learn` | Store a memory — correction, preference, convention, or decision |
+| `plur_recall_hybrid` | **Best default** — BM25 + embeddings merged via RRF. Zero cost. |
+| `plur_recall` | Keyword search (BM25 only, instant) |
+| `plur_inject_hybrid` | Load relevant memories for the current task |
+| `plur_feedback` | Rate a memory — trains relevance over time |
+| `plur_forget` | Retire a memory (history preserved) |
+| `plur_session_end` | End a session — captures summary and new learnings |
+| `plur_capture` | Record a session event |
+| `plur_timeline` | Query session history |
+| `plur_ingest` | Extract learnings from text |
+| `plur_sync` | Sync memory across machines via git |
+| `plur_packs_install` | Install a shareable memory pack |
+| `plur_packs_list` | List installed packs |
+| `plur_status` | System health |
 
 ## Sync across machines
 
 Your agent can sync memory to any git remote:
 
 ```
-Agent: plur.sync({ remote: "git@github.com:you/plur-memory.git" })
+Agent: plur_sync({ remote: "git@github.com:you/plur-memory.git" })
 → "Initialized and pushed."
 
 # On another machine, same remote:
-Agent: plur.sync()
+Agent: plur_sync()
 → "Synced. Pulled 12 remote commits."
 ```
 

package/dist/index.js

@@ -1,81 +1,149 @@
 #!/usr/bin/env node
 
 // src/index.ts
-var VERSION = "0.5.2";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var VERSION = "0.6.0";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
   plur-mcp              Start the MCP server (stdio transport)
-  plur-mcp init         Initialize storage and print setup instructions
+  plur-mcp init         Set up PLUR: storage + MCP config + Claude Code hooks
   plur-mcp --help       Show this help message
   plur-mcp --version    Show version
 
 Environment:
   PLUR_PATH             Storage location (default: ~/.plur/)
 
-Setup:
-  Add to .claude/mcp.json (Claude Code) or .cursor/mcp.json (Cursor):
-
-  {
-    "mcpServers": {
-      "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp@latest"] }
-    }
-  }
+Quick start:
+  npx @plur-ai/mcp init
 
 Docs: https://plur.ai \xB7 https://github.com/plur-ai/plur
 `;
-var arg = process.argv[2];
-if (arg === "--help" || arg === "-h") {
-  process.stdout.write(HELP);
-  process.exit(0);
+var MCP_SERVER_CONFIG = {
+  command: "npx",
+  args: ["-y", "@plur-ai/mcp@latest"]
+};
+var PLUR_HOOKS = {
+  UserPromptSubmit: [{
+    hooks: [{ type: "command", command: "npx @plur-ai/cli hook-inject", timeout: 15 }]
+  }],
+  PostCompact: [{
+    matcher: "auto|manual",
+    hooks: [{ type: "command", command: "npx @plur-ai/cli hook-inject --rehydrate", timeout: 15 }]
+  }]
+};
+function findMcpConfig() {
+  const projectMcp = join(process.cwd(), ".mcp.json");
+  if (existsSync(projectMcp)) return projectMcp;
+  const globalMcp = join(homedir(), ".claude", "mcp.json");
+  if (existsSync(globalMcp)) return globalMcp;
+  return projectMcp;
 }
-if (arg === "--version" || arg === "-v") {
-  process.stdout.write(`${VERSION}
-`);
-  process.exit(0);
+function writeMcpConfig(configPath) {
+  let config = {};
+  if (existsSync(configPath)) {
+    try {
+      config = JSON.parse(readFileSync(configPath, "utf8"));
+    } catch {
+    }
+  }
+  const servers = config.mcpServers ?? {};
+  if (servers.plur) {
+    return `already configured in ${configPath}`;
+  }
+  servers.plur = MCP_SERVER_CONFIG;
+  config.mcpServers = servers;
+  const dir = join(configPath, "..");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+  return `added to ${configPath}`;
 }
-if (arg === "init") {
+function installHooks() {
+  const projectSettings = join(process.cwd(), ".claude", "settings.json");
+  const globalSettings = join(homedir(), ".claude", "settings.json");
+  const settingsPath = existsSync(join(process.cwd(), ".claude")) ? projectSettings : globalSettings;
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch {
+    }
+  }
+  const hooks = settings.hooks ?? {};
+  for (const entries of Object.values(hooks)) {
+    for (const entry of entries) {
+      for (const h of entry.hooks ?? []) {
+        if (h.command.includes("@plur-ai/cli")) {
+          return `already installed in ${settingsPath}`;
+        }
+      }
+    }
+  }
+  const existing = settings.hooks ?? {};
+  const merged = { ...existing };
+  for (const [event, newEntries] of Object.entries(PLUR_HOOKS)) {
+    merged[event] = [...merged[event] ?? [], ...newEntries];
+  }
+  settings.hooks = merged;
+  const dir = join(settingsPath, "..");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+  return `installed in ${settingsPath}`;
+}
+async function runInit() {
+  const results = [];
   const { detectPlurStorage } = await import("@plur-ai/core");
   const paths = detectPlurStorage();
-  let embeddingsAvailable = false;
+  results.push(`Storage:  ${paths.root}`);
+  let searchMode = "BM25 keyword search";
   try {
     const mod = "@huggingface/transformers";
     await import(
       /* @vite-ignore */
       mod
     );
-    embeddingsAvailable = true;
+    searchMode = "hybrid (BM25 + embeddings)";
   } catch {
   }
-  const searchMode = embeddingsAvailable ? "hybrid (BM25 + embeddings)" : "BM25 keyword search (embeddings not installed \u2014 install @huggingface/transformers for hybrid search)";
+  results.push(`Search:   ${searchMode}`);
+  const mcpConfigPath = findMcpConfig();
+  const mcpStatus = writeMcpConfig(mcpConfigPath);
+  results.push(`MCP:      ${mcpStatus}`);
+  const hooksStatus = installHooks();
+  results.push(`Hooks:    ${hooksStatus}`);
   process.stdout.write(`PLUR initialized.
 
-  Storage: ${paths.root}
-  Search:  ${searchMode}
+  ${results.join("\n  ")}
 
-  Next step \u2014 add to your MCP config:
+`);
+  if (mcpStatus.includes("added") || hooksStatus.includes("installed")) {
+    process.stdout.write(`  Restart Claude Code to activate.
 
-  Claude Code (.claude/mcp.json):
-  {
-    "mcpServers": {
-      "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp@latest"] }
-    }
-  }
+`);
+  } else {
+    process.stdout.write(`  Everything is set up. Start a new conversation to use PLUR.
 
-  Cursor (.cursor/mcp.json):
-  {
-    "mcpServers": {
-      "plur": { "command": "npx", "args": ["-y", "@plur-ai/mcp@latest"] }
-    }
+`);
   }
-
-  Then restart your editor. Your agent now has persistent memory.
-  Learn more: https://plur.ai
+}
+var arg = process.argv[2];
+if (arg === "--help" || arg === "-h") {
+  process.stdout.write(HELP);
+  process.exit(0);
+}
+if (arg === "--version" || arg === "-v") {
+  process.stdout.write(`${VERSION}
 `);
   process.exit(0);
 }
+if (arg === "init") {
+  await runInit();
+  process.exit(0);
+}
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-4WAIYC37.js");
+  const { runStdio } = await import("./server-5BXYBMHX.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-4WAIYC37.js → server-5BXYBMHX.js}

@@ -297,8 +297,15 @@ function getToolDefinitions() {
           }
           return { mode: "batch", results, summary };
         }
-        plur.feedback(args.id, args.signal);
-        return { success: true, id: args.id, signal: args.signal };
+        try {
+          plur.feedback(args.id, args.signal);
+          return { success: true, id: args.id, signal: args.signal };
+        } catch (err) {
+          if (err.message?.includes("readonly store")) {
+            return { success: false, id: args.id, signal: args.signal, note: "Engram is in a readonly store. Feedback noted for this session but not persisted." };
+          }
+          throw err;
+        }
       }
     },
     {
@@ -742,27 +749,35 @@ You have ${store_stats.engram_count} engrams but none matched this task. Call pl
     },
     {
       name: "plur_session_end",
-      description: "End a session \u2014 captures an episode and creates engrams from suggestions. Call before the conversation ends.",
+      description: `End a session. BEFORE calling this tool, review the conversation and extract learnings:
+
+1. Corrections the user made ("no, use X not Y") \u2192 type: behavioral
+2. Preferences stated ("always X", "never Y") \u2192 type: behavioral
+3. Codebase patterns discovered (naming, structure, conventions) \u2192 type: architectural
+4. Technical facts learned (API quirks, config, gotchas) \u2192 type: procedural
+5. Terminology defined or clarified \u2192 type: terminological
+
+Include at least one engram_suggestion if ANYTHING was learned. An empty suggestions array means nothing worth remembering happened \u2014 this should be rare.`,
       annotations: { title: "Session End", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
-          summary: { type: "string", description: "What happened in this session" },
+          summary: { type: "string", description: "What happened in this session (1-3 sentences)" },
           session_id: { type: "string", description: "Session ID from plur_session_start" },
           engram_suggestions: {
             type: "array",
             items: {
               type: "object",
               properties: {
-                statement: { type: "string", description: "The knowledge assertion" },
+                statement: { type: "string", description: "A concise, reusable assertion. Write it as advice to your future self." },
                 type: { type: "string", enum: ["behavioral", "terminological", "procedural", "architectural"] }
               },
               required: ["statement"]
             },
-            description: "New learnings to capture as engrams"
+            description: "Learnings from this session. Review the conversation for corrections, preferences, patterns, and technical facts before calling."
           }
         },
-        required: ["summary"]
+        required: ["summary", "engram_suggestions"]
       },
       handler: async (args, plur) => {
         const summary = args.summary;
@@ -896,7 +911,7 @@ You have ${store_stats.engram_count} engrams but none matched this task. Call pl
 
 // src/server.ts
 import { z } from "zod";
-var VERSION = "0.5.2";
+var VERSION = "0.6.0";
 var INSTRUCTIONS = `PLUR is your persistent memory. Corrections, preferences, and conventions persist across sessions as engrams.
 
 REQUIRED at session boundaries:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "type": "module",
   "bin": {
     "plur-mcp": "dist/index.js"
@@ -12,7 +12,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
     "zod": "^3.23.0",
-    "@plur-ai/core": "0.5.2"
+    "@plur-ai/core": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"