@plur-ai/mcp 0.8.0 → 0.8.3

package/dist/index.js

@@ -4,7 +4,7 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join } from "path";
 import { homedir } from "os";
-var VERSION = "0.8.0";
+var VERSION = "0.8.3";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
@@ -56,9 +56,15 @@ var CLAUDE_MD_SECTION = `## PLUR Memory
 
 You have persistent memory via PLUR. Corrections, preferences, and conventions persist across sessions as engrams.
 
+### Architecture
+
+PLUR is installed **globally** \u2014 one MCP server, one engram store (\`~/.plur/\`), available in every project. You do NOT need per-project installation. Multi-project scoping uses \`domain\` and \`scope\` fields on engrams, not separate stores.
+
+Hooks inject engrams automatically on every first message \u2014 you do not need to call \`plur_session_start\` manually (though you can for explicit session tracking).
+
 ### Session Workflow
 
-1. **Start**: Call \`plur_session_start\` with task description \u2014 injects relevant engrams
+1. **Automatic**: Hooks inject relevant engrams on first message \u2014 no action needed
 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
@@ -66,36 +72,12 @@ You have persistent memory via PLUR. Corrections, preferences, and conventions p
 
 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";
@@ -198,6 +180,10 @@ async function runInit() {
   results.push(`CLAUDE.md: ${claudeMdStatus}`);
   process.stdout.write(`PLUR initialized.
 
+  Architecture: PLUR is a global tool \u2014 one MCP server, one engram
+  store (~/.plur/), available in every project. Multi-project scoping
+  uses domain/scope fields on engrams, not separate installations.
+
   ${results.join("\n  ")}
 
 `);
@@ -226,7 +212,7 @@ if (arg === "init") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-JG4LLIW5.js");
+  const { runStdio } = await import("./server-YEWTBXTD.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{server-JG4LLIW5.js → server-YEWTBXTD.js}

@@ -14,7 +14,7 @@ import {
 import { Plur as Plur2, checkForUpdate } from "@plur-ai/core";
 
 // src/tools.ts
-import { extractMetaEngrams, validateMetaEngram, confidenceBand } from "@plur-ai/core";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation } from "@plur-ai/core";
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
   return async (prompt) => {
     const response = await fetch(`${baseUrl.replace(/\/$/, "")}/chat/completions`, {
@@ -65,6 +65,13 @@ var PLUR_GUIDE = `## PLUR Quick Start
 - **plur_learn** \u2014 record corrections, preferences, patterns (CALL THIS OFTEN)
 - **plur_recall_hybrid** \u2014 search engrams by topic
 - **plur_forget** \u2014 retire an outdated engram`;
+function getLlmFunction() {
+  const openaiKey = process.env.OPENAI_API_KEY;
+  const openrouterKey = process.env.OPENROUTER_API_KEY;
+  if (openrouterKey) return makeHttpLlm("https://openrouter.ai/api/v1", openrouterKey, "openai/gpt-4o-mini");
+  if (openaiKey) return makeHttpLlm("https://api.openai.com/v1", openaiKey, "gpt-4o-mini");
+  return void 0;
+}
 function getToolDefinitions() {
   return [
     {
@@ -108,12 +115,17 @@ function getToolDefinitions() {
             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" }
+          derived_from: { type: "string", description: "Source engram ID this was derived from" },
+          commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked"], description: "Commitment level (default: leaning)" },
+          locked_reason: { type: "string", description: "Reason for locking (when commitment=locked)" },
+          memory_class: { type: "string", enum: ["semantic", "episodic", "procedural", "metacognitive"], description: "Memory classification (auto-set from type if omitted)" },
+          session_episode_id: { type: "string", description: "Link to current session episode for episodic anchoring" }
         },
         required: ["statement"]
       },
       handler: async (args, plur) => {
-        const engram = plur.learn(args.statement, {
+        const llm = getLlmFunction();
+        const context = {
           type: args.type,
           scope: args.scope,
           domain: args.domain,
@@ -124,9 +136,28 @@ function getToolDefinitions() {
           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 };
+          derived_from: args.derived_from,
+          commitment: args.commitment,
+          locked_reason: args.locked_reason,
+          memory_class: args.memory_class,
+          session_episode_id: args.session_episode_id,
+          llm
+        };
+        try {
+          const result = await plur.learnAsync(args.statement, context);
+          return {
+            id: result.engram.id,
+            statement: result.engram.statement,
+            scope: result.engram.scope,
+            type: result.engram.type,
+            decision: result.decision,
+            existing_id: result.existing_id,
+            tensions: result.tensions
+          };
+        } catch {
+          const engram = plur.learn(args.statement, context);
+          return { id: engram.id, statement: engram.statement, scope: engram.scope, type: engram.type, decision: "ADD" };
+        }
       }
     },
     {
@@ -140,7 +171,9 @@ function getToolDefinitions() {
           scope: { type: "string", description: "Filter by scope (also includes global)" },
           domain: { type: "string", description: "Filter by domain prefix" },
           limit: { type: "number", description: "Max results to return (default 20)" },
-          min_strength: { type: "number", description: "Minimum retrieval strength (0-1)" }
+          min_strength: { type: "number", description: "Minimum retrieval strength (0-1)" },
+          budget: { type: "object", description: "Budget constraints for sub-agents", properties: { max_tokens: { type: "number" }, max_results: { type: "number" } } },
+          caller_session_id: { type: "string", description: "Caller session ID for budget enforcement" }
         },
         required: ["query"]
       },
@@ -175,27 +208,62 @@ function getToolDefinitions() {
           scope: { type: "string", description: "Filter by scope (also includes global)" },
           domain: { type: "string", description: "Filter by domain prefix" },
           limit: { type: "number", description: "Max results to return (default 20)" },
-          min_strength: { type: "number", description: "Minimum retrieval strength (0-1)" }
+          min_strength: { type: "number", description: "Minimum retrieval strength (0-1)" },
+          budget: { type: "object", description: "Budget constraints for sub-agents", properties: { max_tokens: { type: "number" }, max_results: { type: "number" }, ttl_seconds: { type: "number" } } },
+          caller_session_id: { type: "string", description: "Session ID of calling agent for budget enforcement" },
+          include_episodes: { type: "boolean", description: "If true, include linked episode summaries for each engram (SP2 episodic anchoring)" }
         },
         required: ["query"]
       },
       handler: async (args, plur) => {
+        const budget = args.budget;
+        const effectiveLimit = budget?.max_results ?? args.limit ?? 20;
         const results = await plur.recallHybrid(args.query, {
           scope: args.scope,
           domain: args.domain,
-          limit: args.limit,
+          limit: effectiveLimit,
           min_strength: args.min_strength
         });
+        let truncated = false;
+        let boundedResults = results;
+        if (budget?.max_results && results.length > budget.max_results) {
+          boundedResults = results.slice(0, budget.max_results);
+          truncated = true;
+        }
+        if (budget?.max_tokens) {
+          let tokenCount = 0;
+          const withinBudget = [];
+          for (const e of boundedResults) {
+            const tokens = Math.ceil(e.statement.length / 4) + 20;
+            if (tokenCount + tokens > budget.max_tokens) {
+              truncated = true;
+              break;
+            }
+            withinBudget.push(e);
+            tokenCount += tokens;
+          }
+          boundedResults = withinBudget;
+        }
+        const includeEpisodes = args.include_episodes === true;
         return {
-          results: results.map((e) => ({
-            id: e.id,
-            statement: e.statement,
-            type: e.type,
-            scope: e.scope,
-            domain: e.domain,
-            retrieval_strength: e.activation.retrieval_strength
-          })),
-          count: results.length,
+          results: boundedResults.map((e) => {
+            const raw = e;
+            const base = {
+              id: e.id,
+              statement: e.statement,
+              type: e.type,
+              scope: e.scope,
+              domain: e.domain,
+              retrieval_strength: e.activation.retrieval_strength
+            };
+            if (includeEpisodes && raw.episode_ids?.length > 0) {
+              const episodes = plur.timeline({ search: "" });
+              base.episodes = episodes.filter((ep) => raw.episode_ids.includes(ep.id)).map((ep) => ({ id: ep.id, summary: ep.summary, timestamp: ep.timestamp }));
+            }
+            return base;
+          }),
+          count: boundedResults.length,
+          truncated,
           mode: "hybrid"
         };
       }
@@ -735,7 +803,10 @@ function getToolDefinitions() {
           engram_count: status.engram_count,
           episode_count: status.episode_count,
           pack_count: status.pack_count,
-          storage_root: status.storage_root
+          storage_root: status.storage_root,
+          locked_count: status.locked_count,
+          tension_count: status.tension_count,
+          versioned_engram_count: status.versioned_engram_count ?? 0
         };
       }
     },
@@ -937,6 +1008,147 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         return { promoted, errors, success: errors.length === 0 };
       }
     },
+    {
+      name: "plur_tensions",
+      description: "List engram pairs that have conflicting knowledge \u2014 shows tensions in your memory that may need resolution",
+      annotations: { title: "Tensions", readOnlyHint: true, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          scope: { type: "string", description: "Filter by scope" },
+          domain: { type: "string", description: "Filter by domain prefix" }
+        }
+      },
+      handler: async (args, plur) => {
+        const engrams = plur.list({
+          scope: args.scope,
+          domain: args.domain
+        });
+        const tensions = [];
+        const seen = /* @__PURE__ */ new Set();
+        for (const engram of engrams) {
+          if (!engram.relations?.conflicts?.length) continue;
+          for (const conflictId of engram.relations.conflicts) {
+            const pairKey = [engram.id, conflictId].sort().join(":");
+            if (seen.has(pairKey)) continue;
+            seen.add(pairKey);
+            const other = engrams.find((e) => e.id === conflictId);
+            if (!other) continue;
+            tensions.push({
+              engram_a: { id: engram.id, statement: engram.statement, type: engram.type },
+              engram_b: { id: other.id, statement: other.statement, type: other.type },
+              detected_at: engram.activation.last_accessed
+            });
+          }
+        }
+        return { tensions, count: tensions.length };
+      }
+    },
+    {
+      name: "plur_episode_to_engram",
+      description: "Promote an episode to a persistent episodic engram \u2014 useful when a session event deserves long-term memory",
+      annotations: { title: "Episode to Engram", destructiveHint: false, idempotentHint: false },
+      inputSchema: {
+        type: "object",
+        properties: {
+          episode_id: { type: "string", description: "Episode ID to promote (from plur_timeline)" },
+          scope: { type: "string", description: "Scope for the new engram" },
+          domain: { type: "string", description: "Domain tag for the new engram" },
+          tags: { type: "array", items: { type: "string" }, description: "Tags for the new engram" }
+        },
+        required: ["episode_id"]
+      },
+      handler: async (args, plur) => {
+        const engram = plur.episodeToEngram(args.episode_id, {
+          scope: args.scope,
+          domain: args.domain,
+          tags: args.tags
+        });
+        return {
+          id: engram.id,
+          statement: engram.statement,
+          memory_class: engram.knowledge_type?.memory_class,
+          episode_ids: engram.episode_ids,
+          source: engram.source
+        };
+      }
+    },
+    {
+      name: "plur_history",
+      description: "View the event-sourced history of an engram or all recent history \u2014 shows creation, updates, feedback, and evolution events",
+      annotations: { title: "History", readOnlyHint: true, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          engram_id: { type: "string", description: "Filter history for a specific engram ID. If omitted, returns recent history across all engrams." },
+          limit: { type: "number", description: "Max events to return (default 50)" }
+        }
+      },
+      handler: async (args, plur) => {
+        const engramId = args.engram_id;
+        const limit = args.limit ?? 50;
+        if (engramId) {
+          const events = plur.getEngramHistory(engramId);
+          return {
+            engram_id: engramId,
+            events: events.slice(-limit),
+            total: events.length
+          };
+        }
+        const { listHistoryMonths, readHistory } = await import("@plur-ai/core");
+        const status = plur.status();
+        const months = listHistoryMonths(status.storage_root);
+        const allEvents = [];
+        for (const month of months.reverse()) {
+          const events = readHistory(status.storage_root, month);
+          allEvents.push(...events);
+          if (allEvents.length >= limit) break;
+        }
+        return {
+          events: allEvents.slice(-limit),
+          total: allEvents.length
+        };
+      }
+    },
+    {
+      name: "plur_report_failure",
+      description: "Report a failure for a procedural engram \u2014 triggers procedure evolution via LLM if configured. Only works on procedural engrams. Max 3 revisions per procedure per 24h.",
+      annotations: { title: "Report Failure", destructiveHint: false, idempotentHint: false },
+      inputSchema: {
+        type: "object",
+        properties: {
+          engram_id: { type: "string", description: "ID of the procedural engram that failed" },
+          failure_context: { type: "string", description: "Description of what went wrong when following this procedure" },
+          llm_base_url: { type: "string", description: "OpenAI-compatible API base URL for procedure evolution" },
+          llm_api_key: { type: "string", description: "API key for the LLM" },
+          llm_model: { type: "string", description: "Model name (default: gpt-4o-mini)" }
+        },
+        required: ["engram_id", "failure_context"]
+      },
+      handler: async (args, plur) => {
+        let llm;
+        if (args.llm_base_url && args.llm_api_key) {
+          llm = makeHttpLlm(
+            args.llm_base_url,
+            args.llm_api_key,
+            args.llm_model
+          );
+        }
+        const result = await plur.reportFailure(
+          args.engram_id,
+          args.failure_context,
+          llm
+        );
+        return {
+          engram_id: result.engram.id,
+          statement: result.engram.statement,
+          evolved: result.evolved,
+          engram_version: result.engram.engram_version ?? 1,
+          failure_episode_id: result.episode.id,
+          note: result.evolved ? "Procedure was improved based on the failure report" : "Failure logged but procedure was not rewritten (no LLM configured or LLM unavailable)"
+        };
+      }
+    },
     {
       name: "plur_packs_export",
       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.",
@@ -990,20 +1202,55 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           name
         };
       }
+    },
+    {
+      name: "plur_profile",
+      description: "Generate or retrieve a cognitive profile \u2014 a narrative summary synthesized from stored engrams. Cached for 24h.",
+      annotations: { title: "Cognitive profile", readOnlyHint: true, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          scope: { type: "string", description: "Filter engrams by scope" },
+          llm_base_url: { type: "string", description: "OpenAI-compatible API base URL" },
+          llm_api_key: { type: "string", description: "API key for the LLM" },
+          llm_model: { type: "string", description: "Model name" },
+          force_regenerate: { type: "boolean", description: "Force regeneration (default false)" }
+        }
+      },
+      handler: async (args, plur) => {
+        const status = plur.status();
+        const storagePath = status.storage_root;
+        if (!args.force_regenerate) {
+          const cached = getProfileForInjection(storagePath);
+          if (cached) return { profile: cached, source: "cache" };
+        }
+        if (!args.llm_base_url || !args.llm_api_key) {
+          const cached = getProfileForInjection(storagePath);
+          if (cached) return { profile: cached, source: "stale_cache" };
+          return { profile: null, error: "No cached profile. Provide llm_base_url and llm_api_key." };
+        }
+        const model = args.llm_model ?? selectModelForOperation("profile", status.config?.llm);
+        const llm = makeHttpLlm(args.llm_base_url, args.llm_api_key, model);
+        const engrams = plur.list({ scope: args.scope });
+        const profile = await generateProfile(engrams, llm, storagePath, status.config?.profile?.cache_ttl_hours ?? 24);
+        return { profile, source: "generated", engram_count: engrams.length, model };
+      }
     }
   ];
 }
 
 // src/server.ts
 import { z } from "zod";
-var VERSION = "0.8.0";
+var VERSION = "0.8.3";
 var INSTRUCTIONS = `PLUR is your persistent memory. Corrections, preferences, and conventions persist across sessions as engrams.
 
-REQUIRED at session boundaries:
-- FIRST ACTION of every session: call plur_session_start with a task description
-- LAST ACTION before conversation ends: call plur_session_end with summary + engram_suggestions
+PLUR is a GLOBAL tool \u2014 one MCP server, one engram store (~/.plur/), available in every project. Multi-project scoping uses domain/scope fields on engrams, not separate installations.
+
+SESSION LIFECYCLE:
+- With hooks installed (plur init): engrams are injected automatically on first message. You do NOT need to call plur_session_start \u2014 it happens via hooks. Just call plur_session_end before the conversation ends.
+- Without hooks: call plur_session_start at the start, plur_session_end at the end.
 
-REQUIRED during the session:
+DURING the session:
 - When user corrects you ("no, use X not Y") \u2192 call plur_learn immediately
 - When user states a preference ("always X", "never Y") \u2192 call plur_learn immediately
 - When you discover a codebase convention or pattern \u2192 call plur_learn
@@ -1012,12 +1259,10 @@ 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
-This installs Claude Code hooks for automatic engram injection. Without hooks, injection only happens when you call plur_session_start.`;
+Setup: If this is a fresh install, suggest the user run: npx @plur-ai/mcp init
+This installs hooks for automatic injection + session management. One-time global setup.`;
 var GUIDE_RESOURCE = `# PLUR \u2014 Agent Guide
 
 ## What is PLUR?

package/package.json

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