@plur-ai/mcp 0.5.3 → 0.7.0

package/README.md

@@ -50,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

@@ -4,12 +4,12 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-var VERSION = "0.5.3";
+var VERSION = "0.7.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         Set up PLUR: storage + MCP config + Claude Code hooks
+  plur-mcp init         Set up PLUR: storage + MCP config + hooks + CLAUDE.md
   plur-mcp --help       Show this help message
   plur-mcp --version    Show version
 
@@ -25,15 +25,93 @@ var MCP_SERVER_CONFIG = {
   command: "npx",
   args: ["-y", "@plur-ai/mcp@latest"]
 };
+var CLI = "npx @plur-ai/cli";
 var PLUR_HOOKS = {
+  // --- Session lifecycle ---
   UserPromptSubmit: [{
-    hooks: [{ type: "command", command: "npx @plur-ai/cli hook-inject", timeout: 15 }]
+    hooks: [{ type: "command", command: `${CLI} hook-inject`, timeout: 15 }]
   }],
   PostCompact: [{
     matcher: "auto|manual",
-    hooks: [{ type: "command", command: "npx @plur-ai/cli hook-inject --rehydrate", timeout: 15 }]
-  }]
+    hooks: [{ type: "command", command: `${CLI} hook-inject --rehydrate`, timeout: 15 }]
+  }],
+  // --- Contextual injection ---
+  PreToolUse: [
+    { matcher: "EnterPlanMode", hooks: [{ type: "command", command: `${CLI} hook-inject --event plan_mode`, timeout: 10 }] },
+    { matcher: "Skill", hooks: [{ type: "command", command: `${CLI} hook-inject --event skill`, timeout: 10 }] },
+    { matcher: "Agent", hooks: [{ type: "command", command: `${CLI} hook-inject --event agent`, timeout: 10 }] },
+    { matcher: "Bash|Edit|Write|Agent", hooks: [{ type: "command", command: `${CLI} hook-observe`, timeout: 3 }] }
+  ],
+  PostToolUse: [
+    { matcher: "Bash|Edit|Write|Agent", hooks: [{ type: "command", command: `${CLI} hook-observe --post`, timeout: 3 }] }
+  ],
+  SubagentStart: [
+    { matcher: ".*", hooks: [{ type: "command", command: `${CLI} hook-inject --event subagent`, timeout: 10 }] }
+  ]
 };
+var CLAUDE_MD_SECTION = `## PLUR Memory
+
+You have persistent memory via PLUR. Corrections, preferences, and conventions persist across sessions as engrams.
+
+### Session Workflow
+
+1. **Start**: Call \`plur_session_start\` with task description \u2014 injects relevant engrams
+2. **Learn**: When corrected or discovering something new, call \`plur_learn\` immediately
+3. **Recall**: Before answering factual questions, call \`plur_recall_hybrid\` \u2014 check memory first
+4. **Feedback**: Rate injected engrams with \`plur_feedback\` (positive/negative) \u2014 trains relevance
+5. **End**: Call \`plur_session_end\` with summary + engram_suggestions
+
+Do not ask permission to use these tools \u2014 they are your memory system.
+
+### When to check memory
+
+Before reaching for web search, file reads, or guessing \u2014 apply this priority:
+1. Is the answer already in engrams? \u2192 \`plur_recall_hybrid\`
+2. Is the answer in the local filesystem? \u2192 Read/Grep/Glob
+3. Is the answer derivable from context already loaded? \u2192 Just answer
+4. Only if 1-3 fail \u2192 Use external tools
+
+| Domain | When to recall |
+|--------|----------------|
+| Decisions | Past design choices, architecture rationale |
+| Corrections | API quirks, bugs, wrong assumptions |
+| Preferences | Formatting, tone, workflow, tool choices |
+| Conventions | Tag formats, file routing, naming rules |
+| Infrastructure | Server IPs, SSH configs, deployment targets |
+
+### When corrected
+
+When the user corrects you ("no, use X not Y", "that's wrong"):
+1. Call \`plur_learn\` immediately \u2014 before continuing the task
+2. Call \`plur_feedback\` with negative signal on the wrong engram if one was injected
+3. Then continue with the corrected approach
+
+### Verification
+
+When recalling facts that will drive actions:
+1. State the recalled fact explicitly before acting on it
+2. Include the engram ID or search that produced it
+3. If no engram matches, say so and verify from the filesystem
+4. Never interpolate between two engrams to produce a "probably correct" composite
+`;
+function installClaudeMd() {
+  const marker = "## PLUR Memory";
+  const projectClaudeMd = join(process.cwd(), "CLAUDE.md");
+  const globalClaudeMd = join(homedir(), "CLAUDE.md");
+  const claudeMdPath = existsSync(projectClaudeMd) ? projectClaudeMd : existsSync(globalClaudeMd) ? globalClaudeMd : projectClaudeMd;
+  if (existsSync(claudeMdPath)) {
+    const content = readFileSync(claudeMdPath, "utf8");
+    if (content.includes(marker)) {
+      return `already in ${claudeMdPath}`;
+    }
+    writeFileSync(claudeMdPath, content.trimEnd() + "\n\n" + CLAUDE_MD_SECTION);
+    return `added to ${claudeMdPath}`;
+  }
+  writeFileSync(claudeMdPath, `# CLAUDE.md
+
+${CLAUDE_MD_SECTION}`);
+  return `created ${claudeMdPath}`;
+}
 function findMcpConfig() {
   const projectMcp = join(process.cwd(), ".mcp.json");
   if (existsSync(projectMcp)) return projectMcp;
@@ -113,6 +191,8 @@ async function runInit() {
   results.push(`MCP:      ${mcpStatus}`);
   const hooksStatus = installHooks();
   results.push(`Hooks:    ${hooksStatus}`);
+  const claudeMdStatus = installClaudeMd();
+  results.push(`CLAUDE.md: ${claudeMdStatus}`);
   process.stdout.write(`PLUR initialized.
 
   ${results.join("\n  ")}
@@ -143,7 +223,7 @@ if (arg === "init") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-VFKTDY7O.js");
+  const { runStdio } = await import("./server-2UMO2VDB.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-VFKTDY7O.js → server-2UMO2VDB.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;
+        }
       }
     },
     {
@@ -439,7 +446,7 @@ function getToolDefinitions() {
     },
     {
       name: "plur_packs_install",
-      description: "Install an engram pack from a directory path \u2014 adds curated engrams to the store",
+      description: "Install an engram pack from a directory path \u2014 adds curated engrams to the store. Reports conflicts with existing engrams.",
       annotations: { title: "Install pack", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -450,12 +457,32 @@ function getToolDefinitions() {
       },
       handler: async (args, plur) => {
         const result = plur.installPack(args.source);
-        return { installed: result.installed, name: result.name, success: true };
+        return {
+          installed: result.installed,
+          name: result.name,
+          conflicts: result.conflicts,
+          success: true
+        };
+      }
+    },
+    {
+      name: "plur_packs_uninstall",
+      description: "Uninstall an engram pack by name \u2014 removes the pack and all its engrams",
+      annotations: { title: "Uninstall pack", destructiveHint: true, idempotentHint: false },
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Pack name to uninstall (use plur_packs_list to see names)" }
+        },
+        required: ["name"]
+      },
+      handler: async (args, plur) => {
+        return plur.uninstallPack(args.name);
       }
     },
     {
       name: "plur_packs_list",
-      description: "List all installed engram packs",
+      description: "List all installed engram packs with integrity hashes",
       annotations: { title: "List packs", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -466,14 +493,35 @@ function getToolDefinitions() {
         return {
           packs: packs.map((p) => ({
             name: p.name,
-            version: p.version,
-            description: p.description,
-            engram_count: p.engram_count
+            version: p.manifest?.version,
+            description: p.manifest?.description,
+            engram_count: p.engram_count,
+            integrity: p.integrity
           })),
           count: packs.length
         };
       }
     },
+    {
+      name: "plur_packs_discover",
+      description: "Browse available engram packs from the registry \u2014 discover curated expertise packs to install",
+      annotations: { title: "Discover packs", readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Search query to filter packs by name or description" },
+          tags: { type: "array", items: { type: "string" }, description: "Filter by tags" },
+          category: { type: "string", description: "Filter by category (e.g., devops, trading, writing)" }
+        }
+      },
+      handler: async (args, plur) => {
+        return {
+          packs: [],
+          count: 0,
+          message: "Pack discovery coming soon. For now, install packs from local paths via plur_packs_install."
+        };
+      }
+    },
     {
       name: "plur_sync",
       description: "Sync engrams via git \u2014 initializes repo on first call, commits and pushes/pulls on subsequent calls. Provide a remote URL on first call to enable cross-device sync.",
@@ -742,27 +790,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;
@@ -862,33 +918,56 @@ You have ${store_stats.engram_count} engrams but none matched this task. Call pl
     },
     {
       name: "plur_packs_export",
-      description: "Export personal engrams as a shareable pack",
+      description: "Export engrams as a shareable thematic pack with privacy scanning and integrity hash. Filters out private and secret-containing engrams automatically. Output goes to ~/plur-packs/<name> by default.",
       annotations: { title: "Export pack", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
-          name: { type: "string", description: "Pack name" },
+          name: { type: "string", description: 'Pack name (e.g. "react-patterns", "mcp-design")' },
           description: { type: "string", description: "Pack description" },
-          filter_domain: { type: "string", description: "Filter engrams by domain prefix" },
-          filter_scope: { type: "string", description: "Filter engrams by scope" },
-          output_dir: { type: "string", description: "Output directory for the pack (default: ~/.plur/exports/)" }
+          filter_domain: { type: "string", description: 'Filter engrams by domain prefix (e.g. "mcp", "trading")' },
+          filter_scope: { type: "string", description: 'Filter engrams by scope (e.g. "global", "project:myapp")' },
+          filter_tags: { type: "array", items: { type: "string" }, description: "Filter by tags" },
+          filter_type: { type: "string", enum: ["behavioral", "procedural", "architectural", "terminological"], description: "Filter by engram type" },
+          output_dir: { type: "string", description: "Output directory (default: ~/plur-packs/<name>)" },
+          creator: { type: "string", description: "Creator name" }
         },
         required: ["name"]
       },
       handler: async (args, plur) => {
         const name = args.name;
-        const engrams = plur.list({
+        let engrams = plur.list({
           domain: args.filter_domain,
           scope: args.filter_scope
-        }).filter((e) => e.visibility !== "private" || !args.filter_domain);
-        const outputDir = args.output_dir || `${plur.status().storage_root}/exports`;
+        });
+        const filterTags = args.filter_tags;
+        if (filterTags) {
+          engrams = engrams.filter(
+            (e) => e.tags && filterTags.some((t) => e.tags.includes(t))
+          );
+        }
+        const filterType = args.filter_type;
+        if (filterType) {
+          engrams = engrams.filter((e) => e.type === filterType);
+        }
+        const { homedir } = await import("os");
+        const { join } = await import("path");
+        const outputDir = args.output_dir || join(homedir(), "plur-packs", name);
         const result = plur.exportPack(engrams, outputDir, {
           name,
           version: "1.0.0",
           description: args.description,
-          creator: "plur-mcp"
+          creator: args.creator || void 0
         });
-        return { path: result.path, engram_count: result.engram_count, name };
+        return {
+          path: result.path,
+          engram_count: result.engram_count,
+          integrity: result.integrity,
+          match_terms: result.match_terms,
+          privacy_clean: result.privacy.clean,
+          privacy_issues: result.privacy.issues.length,
+          name
+        };
       }
     }
   ];
@@ -896,7 +975,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.3";
+var VERSION = "0.7.0";
 var INSTRUCTIONS = `PLUR is your persistent memory. Corrections, preferences, and conventions persist across sessions as engrams.
 
 REQUIRED at session boundaries:
@@ -912,6 +991,8 @@ OPTIONAL but improves quality:
 - Call plur_feedback to rate which injected engrams helped (positive/negative)
 - Call plur_recall_hybrid before answering factual questions \u2014 the answer may be in memory
 
+For combined search (engrams + files): call plur_recall_hybrid for memories, then datacore.search for journal/knowledge files.
+
 Do not ask permission to use these tools \u2014 they are your memory system.
 
 Setup: If this is a fresh install, suggest the user run: npx @plur-ai/cli init

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.5.3",
+  "version": "0.7.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.7.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"