@plur-ai/mcp 0.4.1 → 0.5.0

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-var VERSION = "0.4.1";
+var VERSION = "0.5.0";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
@@ -75,7 +75,7 @@ if (arg === "init") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-4QXMVGOV.js");
+  const { runStdio } = await import("./server-3QMSEZUP.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-4QXMVGOV.js → server-3QMSEZUP.js}

@@ -36,6 +36,20 @@ function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
     return data.choices?.[0]?.message?.content ?? "";
   };
 }
+var PLUR_GUIDE = `## PLUR Quick Start
+
+Persistent memory for AI agents. Corrections, preferences, and conventions stored as engrams.
+
+### Session Workflow
+1. **plur_session_start** (you just called this) \u2014 get context
+2. Work on your task
+3. **plur_feedback** \u2014 rate which injected engrams helped
+4. **plur_session_end** \u2014 capture summary + suggest new engrams
+
+### Core Tools
+- **plur_learn** \u2014 record patterns, preferences, insights
+- **plur_recall_hybrid** \u2014 search engrams
+- **plur_forget** \u2014 retire an outdated engram`;
 function getToolDefinitions() {
   return [
     {
@@ -53,7 +67,33 @@ function getToolDefinitions() {
           },
           scope: { type: "string", description: "Namespace, e.g. global, project:myapp" },
           domain: { type: "string", description: "Domain tag, e.g. software.deployment" },
-          source: { type: "string", description: "Origin of this knowledge" }
+          source: { type: "string", description: "Origin of this knowledge" },
+          tags: { type: "array", items: { type: "string" }, description: "Searchable keyword tags" },
+          rationale: { type: "string", description: "Why this knowledge matters" },
+          visibility: { type: "string", enum: ["private", "public", "template"], description: "Visibility level" },
+          knowledge_anchors: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                path: { type: "string", description: "Path to related document" },
+                relevance: { type: "string", enum: ["primary", "supporting", "example"] },
+                snippet: { type: "string", description: "Short snippet (max 200 chars)" }
+              },
+              required: ["path"]
+            },
+            description: "Links to related knowledge documents"
+          },
+          dual_coding: {
+            type: "object",
+            properties: {
+              example: { type: "string", description: "Concrete example" },
+              analogy: { type: "string", description: "Analogy to aid understanding" }
+            },
+            description: "Dual coding for richer encoding"
+          },
+          abstract: { type: "string", description: "Abstract engram ID this was derived from" },
+          derived_from: { type: "string", description: "Source engram ID this was derived from" }
         },
         required: ["statement"]
       },
@@ -62,7 +102,14 @@ function getToolDefinitions() {
           type: args.type,
           scope: args.scope,
           domain: args.domain,
-          source: args.source
+          source: args.source,
+          tags: args.tags,
+          rationale: args.rationale,
+          visibility: args.visibility,
+          knowledge_anchors: args.knowledge_anchors,
+          dual_coding: args.dual_coding,
+          abstract: args.abstract,
+          derived_from: args.derived_from
         });
         return { id: engram.id, statement: engram.statement, scope: engram.scope, type: engram.type };
       }
@@ -160,7 +207,8 @@ function getToolDefinitions() {
           directives: result.directives,
           consider: result.consider,
           count: result.count,
-          tokens_used: result.tokens_used
+          tokens_used: result.tokens_used,
+          injected_ids: result.injected_ids
         };
       }
     },
@@ -187,46 +235,91 @@ function getToolDefinitions() {
           consider: result.consider,
           count: result.count,
           tokens_used: result.tokens_used,
+          injected_ids: result.injected_ids,
           mode: "hybrid"
         };
       }
     },
     {
       name: "plur_feedback",
-      description: "Rate an engram's usefulness \u2014 trains injection relevance over time",
+      description: "Rate an engram's usefulness \u2014 trains injection relevance over time. Supports single or batch mode.",
       annotations: { title: "Feedback", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
-          id: { type: "string", description: "Engram ID (e.g. ENG-001)" },
+          id: { type: "string", description: "Engram ID (single mode)" },
           signal: {
             type: "string",
             enum: ["positive", "negative", "neutral"],
-            description: "Feedback signal to apply"
+            description: "Feedback signal (single mode)"
+          },
+          signals: {
+            type: "array",
+            items: {
+              type: "object",
+              properties: {
+                id: { type: "string", description: "Engram ID" },
+                signal: { type: "string", enum: ["positive", "negative", "neutral"] }
+              },
+              required: ["id", "signal"]
+            },
+            description: "Batch feedback signals"
           }
-        },
-        required: ["id", "signal"]
+        }
       },
       handler: async (args, plur) => {
+        if (args.signals && Array.isArray(args.signals)) {
+          const results = [];
+          const summary = { positive: 0, negative: 0, neutral: 0 };
+          for (const { id, signal } of args.signals) {
+            try {
+              plur.feedback(id, signal);
+              results.push({ id, signal, success: true });
+              summary[signal]++;
+            } catch (err) {
+              results.push({ id, signal, success: false, error: err.message });
+            }
+          }
+          return { mode: "batch", results, summary };
+        }
         plur.feedback(args.id, args.signal);
         return { success: true, id: args.id, signal: args.signal };
       }
     },
     {
       name: "plur_forget",
-      description: "Retire an engram \u2014 marks it as no longer active without deleting history",
+      description: "Retire an engram by ID or search term \u2014 marks it as no longer active without deleting history",
       annotations: { title: "Forget", destructiveHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
-          id: { type: "string", description: "Engram ID to retire" },
-          reason: { type: "string", description: "Optional reason for retiring this engram" }
-        },
-        required: ["id"]
+          id: { type: "string", description: "Exact engram ID to retire" },
+          search: { type: "string", description: "Search term to find engram to retire" }
+        }
       },
       handler: async (args, plur) => {
-        plur.forget(args.id, args.reason);
-        return { success: true, id: args.id, status: "retired" };
+        if (args.id) {
+          const engram = plur.getById(args.id);
+          if (!engram) throw new Error(`Engram not found: ${args.id}`);
+          if (engram.status === "retired") return { success: false, error: `Already retired: ${args.id}` };
+          plur.forget(args.id);
+          return { success: true, retired: { id: engram.id, statement: engram.statement } };
+        }
+        if (args.search) {
+          const matches = plur.recall(args.search, { limit: 100 });
+          if (matches.length === 0) return { success: false, error: `No active engrams matching "${args.search}"` };
+          if (matches.length === 1) {
+            plur.forget(matches[0].id);
+            return { success: true, retired: { id: matches[0].id, statement: matches[0].statement } };
+          }
+          return {
+            success: false,
+            matches: matches.slice(0, 20).map((e) => ({ id: e.id, statement: e.statement })),
+            total: matches.length,
+            error: `${matches.length} matches. Specify exact ID.`
+          };
+        }
+        throw new Error("Provide either id or search parameter");
       }
     },
     {
@@ -561,22 +654,218 @@ function getToolDefinitions() {
           storage_root: status.storage_root
         };
       }
+    },
+    {
+      name: "plur_session_start",
+      description: "Start a session \u2014 inject relevant engrams for your task. Call at the beginning of every session.",
+      annotations: { title: "Session Start", readOnlyHint: true, idempotentHint: false },
+      inputSchema: {
+        type: "object",
+        properties: {
+          task: { type: "string", description: "What you are working on (triggers engram injection)" },
+          tags: { type: "array", items: { type: "string" }, description: "Tags to filter injected engrams" }
+        },
+        required: ["task"]
+      },
+      handler: async (args, plur) => {
+        const crypto = await import("crypto");
+        const session_id = crypto.randomUUID();
+        const task = args.task;
+        const tags = args.tags;
+        let engrams = null;
+        try {
+          const result = await plur.injectHybrid(task, {
+            scope: tags?.length ? `tags:${tags.join(",")}` : void 0
+          });
+          if (result.count > 0) {
+            const lines = [];
+            if (result.directives) lines.push("## DIRECTIVES\n", result.directives);
+            if (result.constraints) lines.push("\n## CONSTRAINTS\n", result.constraints);
+            if (result.consider) lines.push("\n## ALSO CONSIDER\n", result.consider);
+            engrams = { text: lines.join("\n"), count: result.count, injected_ids: result.injected_ids };
+          }
+        } catch {
+          const result = plur.inject(task, {
+            scope: tags?.length ? `tags:${tags.join(",")}` : void 0
+          });
+          if (result.count > 0) {
+            const lines = [];
+            if (result.directives) lines.push("## DIRECTIVES\n", result.directives);
+            if (result.constraints) lines.push("\n## CONSTRAINTS\n", result.constraints);
+            if (result.consider) lines.push("\n## ALSO CONSIDER\n", result.consider);
+            engrams = { text: lines.join("\n"), count: result.count, injected_ids: result.injected_ids };
+          }
+        }
+        return {
+          session_id,
+          engrams,
+          guide: engrams ? "Session started. Workflow: work \u2192 plur_feedback \u2192 plur_session_end." : PLUR_GUIDE
+        };
+      }
+    },
+    {
+      name: "plur_session_end",
+      description: "End a session \u2014 captures an episode and creates engrams from suggestions. Call before the conversation ends.",
+      annotations: { title: "Session End", destructiveHint: false, idempotentHint: false },
+      inputSchema: {
+        type: "object",
+        properties: {
+          summary: { type: "string", description: "What happened in this session" },
+          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" },
+                type: { type: "string", enum: ["behavioral", "terminological", "procedural", "architectural"] }
+              },
+              required: ["statement"]
+            },
+            description: "New learnings to capture as engrams"
+          }
+        },
+        required: ["summary"]
+      },
+      handler: async (args, plur) => {
+        const summary = args.summary;
+        const session_id = args.session_id;
+        const suggestions = args.engram_suggestions;
+        let engrams_created = 0;
+        if (suggestions?.length) {
+          for (const s of suggestions) {
+            plur.learn(s.statement, { type: s.type });
+            engrams_created++;
+          }
+        }
+        const episode = plur.capture(summary, {
+          session_id,
+          channel: "mcp"
+        });
+        return {
+          engrams_created,
+          episode_id: episode.id
+        };
+      }
+    },
+    {
+      name: "plur_stores_add",
+      description: "Register an additional engram store at a filesystem path with a scope identifier",
+      annotations: { title: "Add store", destructiveHint: false, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Filesystem path to engrams.yaml" },
+          scope: { type: "string", description: "Scope identifier (e.g. space:1-datafund, module:trading)" },
+          shared: { type: "boolean", description: "Whether this store is git-committed / team-visible" },
+          readonly: { type: "boolean", description: "Whether this store is read-only (e.g. purchased packs)" }
+        },
+        required: ["path", "scope"]
+      },
+      handler: async (args, plur) => {
+        plur.addStore(args.path, args.scope, {
+          shared: args.shared,
+          readonly: args.readonly
+        });
+        return { success: true, path: args.path, scope: args.scope };
+      }
+    },
+    {
+      name: "plur_stores_list",
+      description: "List all configured engram stores with their scope, path, and engram count",
+      annotations: { title: "List stores", readOnlyHint: true, idempotentHint: true },
+      inputSchema: { type: "object", properties: {} },
+      handler: async (_args, plur) => {
+        const stores = plur.listStores();
+        return { stores, count: stores.length };
+      }
+    },
+    {
+      name: "plur_promote",
+      description: "Activate candidate engrams so they appear in injection results",
+      annotations: { title: "Promote", destructiveHint: false, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Single engram ID to promote" },
+          ids: { type: "array", items: { type: "string" }, description: "Multiple engram IDs to promote" }
+        }
+      },
+      handler: async (args, plur) => {
+        const targetIds = args.ids ?? (args.id ? [args.id] : []);
+        if (targetIds.length === 0) throw new Error("Provide id or ids");
+        const promoted = [];
+        const errors = [];
+        for (const id of targetIds) {
+          const engram = plur.getById(id);
+          if (!engram) {
+            errors.push({ id, error: "Not found" });
+            continue;
+          }
+          if (engram.status === "active") {
+            errors.push({ id, error: "Already active" });
+            continue;
+          }
+          if (engram.status === "retired") {
+            errors.push({ id, error: "Cannot promote retired" });
+            continue;
+          }
+          engram.status = "active";
+          engram.activation.retrieval_strength = 0.7;
+          engram.activation.storage_strength = 1;
+          engram.activation.last_accessed = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+          plur.updateEngram(engram);
+          promoted.push({ id, statement: engram.statement });
+        }
+        return { promoted, errors, success: errors.length === 0 };
+      }
+    },
+    {
+      name: "plur_packs_export",
+      description: "Export personal engrams as a shareable pack",
+      annotations: { title: "Export pack", destructiveHint: false, idempotentHint: false },
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Pack name" },
+          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/)" }
+        },
+        required: ["name"]
+      },
+      handler: async (args, plur) => {
+        const name = args.name;
+        const 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 result = plur.exportPack(engrams, outputDir, {
+          name,
+          version: "1.0.0",
+          description: args.description,
+          creator: "plur-mcp"
+        });
+        return { path: result.path, engram_count: result.engram_count, name };
+      }
     }
   ];
 }
 
 // src/server.ts
 import { z } from "zod";
-var VERSION = "0.4.1";
+var VERSION = "0.5.0";
 var INSTRUCTIONS = `PLUR is your persistent memory. It stores corrections, preferences, and conventions as engrams that persist across sessions.
 
 Use PLUR proactively:
-- Call plur_recall_hybrid at session start to load relevant context for the current task
-- Call plur_learn when the user corrects you, states a preference ("always use X", "never do Y"), or when you discover a project convention
+- Call plur_session_start at session start with a task description \u2014 loads relevant context
+- Call plur_learn when the user corrects you, states a preference, or you discover a convention
 - Call plur_feedback after using recalled engrams to train relevance
-- Call plur_status to check system health and engram counts
+- Call plur_session_end before the conversation ends \u2014 captures learnings and session summary
 
-You do not need permission to use these tools \u2014 they are your memory system.`;
+Do not ask permission to use these tools \u2014 they are your memory system.`;
 var GUIDE_RESOURCE = `# PLUR \u2014 Agent Guide
 
 ## What is PLUR?
@@ -585,32 +874,37 @@ Persistent memory for AI agents. Corrections, preferences, and conventions are s
 
 ## Quick Start
 
-1. \`plur_status\` \u2014 check health and engram count
-2. \`plur_recall_hybrid\` \u2014 search for relevant memories
-3. \`plur_learn\` \u2014 store a new learning
-4. \`plur_feedback\` \u2014 rate an engram's usefulness
+1. \`plur_session_start\` \u2014 start a session, inject relevant context
+2. \`plur_learn\` \u2014 store a new learning
+3. \`plur_feedback\` \u2014 rate injected engrams
+4. \`plur_session_end\` \u2014 capture summary and new learnings
 
 ## When to Call Each Tool
 
 | Trigger | Tool |
 |---------|------|
-| Session starts | \`plur_recall_hybrid\` or \`plur_inject_hybrid\` with task description |
+| Session starts | \`plur_session_start\` with task description |
 | User corrects you | \`plur_learn\` with the correction |
 | User states preference ("always X", "never Y") | \`plur_learn\` with scope and type |
 | You used a recalled engram successfully | \`plur_feedback\` with "positive" |
 | A recalled engram was wrong or irrelevant | \`plur_feedback\` with "negative" |
 | User says "forget X" or a memory is outdated | \`plur_forget\` |
 | You need to check what's stored | \`plur_status\` or \`plur_packs_list\` |
-| End of session | \`plur_capture\` to record what happened |
+| End of session | \`plur_session_end\` with summary and suggestions |
 
 ## Tool Categories
 
+### Session Management
+- **plur_session_start** \u2014 start a session, inject relevant context
+- **plur_session_end** \u2014 end a session, capture summary and new learnings
+
 ### Core Memory
 - **plur_learn** \u2014 store a correction, preference, or convention
 - **plur_recall** \u2014 BM25 keyword search
 - **plur_recall_hybrid** \u2014 BM25 + embeddings (recommended default)
 - **plur_feedback** \u2014 rate an engram (trains relevance)
 - **plur_forget** \u2014 retire an outdated engram
+- **plur_promote** \u2014 activate a candidate engram
 
 ### Context Injection
 - **plur_inject** \u2014 select engrams for a task (BM25)
@@ -624,6 +918,11 @@ Persistent memory for AI agents. Corrections, preferences, and conventions are s
 - **plur_ingest** \u2014 extract engrams from text content
 - **plur_packs_install** \u2014 install curated engram packs
 - **plur_packs_list** \u2014 list installed packs
+- **plur_packs_export** \u2014 export engrams as a shareable pack
+
+### Multi-Store
+- **plur_stores_add** \u2014 register an additional engram store
+- **plur_stores_list** \u2014 list all configured stores
 
 ### Sync & Status
 - **plur_sync** \u2014 sync engrams across devices via git

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plur-ai/mcp",
-  "version": "0.4.1",
+  "version": "0.5.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.4.1"
+    "@plur-ai/core": "0.5.0"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"