@plur-ai/mcp 0.14.0 → 0.16.0

package/dist/{server-LAXRBVKA.js → chunk-TPL7QPPO.js}

@@ -1,27 +1,3 @@
-// src/server.ts
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-  ListToolsRequestSchema,
-  CallToolRequestSchema,
-  ListResourcesRequestSchema,
-  ReadResourceRequestSchema,
-  ListPromptsRequestSchema,
-  GetPromptRequestSchema,
-  ErrorCode,
-  McpError
-} from "@modelcontextprotocol/sdk/types.js";
-import { existsSync as existsSync2, readFileSync, writeFileSync } from "fs";
-import { join as join2 } from "path";
-import { homedir as homedir2 } from "os";
-import { Plur as Plur2, checkForUpdate } from "@plur-ai/core";
-
-// src/tools.ts
-import { existsSync, unlinkSync } from "fs";
-import { join } from "path";
-import { homedir } from "os";
-import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName } from "@plur-ai/core";
-
 // src/telemetry.ts
 import { recordEvent, flushIfNeeded, registerFlushOnExit } from "@plur-ai/core";
 function recordTelemetry(event) {
@@ -34,9 +10,13 @@ function recordTelemetry(event) {
 }
 
 // src/version.ts
-var VERSION = "0.14.0";
+var VERSION = "0.16.0";
 
 // src/tools.ts
+import { existsSync, unlinkSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName, SUGGEST_DISPLAY_MIN_CONFIDENCE } from "@plur-ai/core";
 import { z } from "zod";
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
   return async (prompt) => {
@@ -59,6 +39,95 @@ function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
     return data.choices?.[0]?.message?.content ?? "";
   };
 }
+var recallHandler = async (args, plur) => {
+  const mode = args.mode ?? "hybrid";
+  if (mode === "keyword") {
+    const results = await plur.recall(args.query, {
+      scope: args.scope,
+      domain: args.domain,
+      limit: args.limit
+    });
+    return {
+      results: results.map((e) => {
+        const supersededBy = e.relations?.superseded_by;
+        const annotation = supersededBy?.length ? ` [superseded by ${supersededBy.join(", ")}]` : "";
+        return {
+          id: e.id,
+          statement: e.statement + annotation,
+          type: e.type,
+          scope: e.scope,
+          domain: e.domain,
+          retrieval_strength: e.activation.retrieval_strength
+        };
+      }),
+      count: results.length,
+      mode: "keyword"
+    };
+  }
+  const budget = args.budget;
+  const cap = budget?.max_results ?? args.limit ?? 20;
+  const fetchLimit = budget?.max_results != null ? cap + 1 : cap;
+  const meta = await plur.recallHybridWithMeta(args.query, {
+    scope: args.scope,
+    domain: args.domain,
+    limit: fetchLimit
+  });
+  recordTelemetry("recall");
+  const truncatedByCount = budget?.max_results != null && meta.engrams.length > cap;
+  let truncated = truncatedByCount;
+  let boundedResults = truncatedByCount ? meta.engrams.slice(0, cap) : meta.engrams;
+  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;
+  const response = {
+    results: boundedResults.map((e) => {
+      const raw = e;
+      const supersededBy = e.relations?.superseded_by;
+      const annotation = supersededBy?.length ? ` [superseded by ${supersededBy.join(", ")}]` : "";
+      const base = {
+        id: e.id,
+        statement: e.statement + annotation,
+        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: meta.mode
+  };
+  if (meta.mode === "hybrid-degraded") {
+    response.warning = `Embedding layer unavailable \u2014 results are BM25-only. Run plur_doctor for diagnosis. Last error: ${meta.embedderError ?? "unknown"}`;
+  }
+  if (resolveRerankerName() !== "off") {
+    response.reranked = meta.reranked ?? 0;
+    const rr = plur.rerankerStatus();
+    if (boundedResults.length > 0 && (meta.reranked ?? 0) === 0 && rr.lastError) {
+      const corruptNote = rr.lastErrorKind === "corrupt-cache" ? " The model cache looks corrupt (truncated download) \u2014 purge and re-download, see plur_doctor." : "";
+      response.reranker_warning = `PLUR_RERANKER is set but the reranker did not engage \u2014 results are RRF-only (fusion order, no cross-encoder rerank).${corruptNote} Last error: ${rr.lastError}. Run plur_doctor for diagnosis.`;
+    }
+  }
+  return response;
+};
+var RECALL_HYBRID_DEPRECATION = "plur_recall_hybrid is deprecated since 0.16 \u2014 use plur_recall (mode defaults to hybrid). This alias will be removed in 0.18.";
 function jsonSchemaPropToZod(prop) {
   if (!prop || typeof prop !== "object") return z.unknown();
   const variants = prop.anyOf ?? prop.oneOf;
@@ -83,7 +152,10 @@ function jsonSchemaPropToZod(prop) {
           return val;
         }
       }
-      if (prop.items?.type === "string") {
+      const items = prop.items;
+      const itemVariants = items?.anyOf ?? items?.oneOf;
+      const itemsAcceptString = items?.type === "string" || Array.isArray(itemVariants) && itemVariants.some((v) => v?.type === "string");
+      if (itemsAcceptString) {
         return trimmed.length === 0 ? [] : trimmed.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
       }
       return val;
@@ -112,7 +184,10 @@ function validateToolArgs(tool, rawArgs) {
     const receivedFields = Object.keys(rawArgs);
     const details = parsed.error.issues.map((i) => `${i.path.join(".") || "root"}: ${i.message}`).join(", ");
     const hasArrayParam = Object.values(schema.properties ?? {}).some((p) => p?.type === "array");
-    const arrayBugHint = receivedFields.length === 0 && hasArrayParam ? ' Known client-side bug (plur-ai/plur#297): some MCP clients drop the entire arguments payload when an array-typed parameter is included. Retry passing array parameters as a JSON string (e.g. tags: "[\\"a\\",\\"b\\"]") or a comma-separated string (tags: "a, b") \u2014 the server coerces both back into arrays.' : "";
+    const missingArrayParams = parsed.error.issues.filter((i) => i.code === "invalid_type" && i.received === "undefined").map((i) => String(i.path[0] ?? "")).filter((k) => schema.properties?.[k]?.type === "array");
+    const totalDrop = receivedFields.length === 0 && hasArrayParam;
+    const partialDrop = missingArrayParams.length > 0;
+    const arrayBugHint = totalDrop || partialDrop ? " Known client-side bug (plur-ai/plur#297): some MCP clients drop " + (partialDrop ? `array-typed parameters from a large arguments payload while keeping the earlier fields (here: ${missingArrayParams.join(", ")}). This is size-sensitive \u2014 the same call often succeeds with a shorter payload, so shrink the other fields (e.g. a briefer summary) as well. ` : "the entire arguments payload when an array-typed parameter is included. ") + 'Retry passing array parameters as a JSON string (e.g. tags: "[\\"a\\",\\"b\\"]") or a comma-separated string (tags: "a, b") \u2014 the server coerces both back into arrays.' : "";
     const receivedNote = receivedFields.length > 0 ? `Received fields: [${receivedFields.join(", ")}].` : "Received no fields (the arguments object was empty).";
     return {
       ok: false,
@@ -153,7 +228,7 @@ var PLUR_GUIDE = `## PLUR Quick Start
 
 ### Core Tools
 - **plur_learn** \u2014 record corrections, preferences, patterns (CALL THIS OFTEN)
-- **plur_recall_hybrid** \u2014 search engrams by topic
+- **plur_recall** \u2014 search engrams by topic (default: hybrid BM25 + embeddings; use mode:"keyword" for BM25-only)
 - **plur_forget** \u2014 retire an outdated engram`;
 function getLlmFunction() {
   const openaiKey = process.env.OPENAI_API_KEY;
@@ -190,12 +265,22 @@ function _cleanExpiredSessions() {
     if (new Date(state.started_at).getTime() < cutoff) _sessionTelemetry.delete(id);
   }
 }
-var _activeSessionId;
+function _implicitSessionId() {
+  _cleanExpiredSessions();
+  if (_sessionTelemetry.size !== 1) return void 0;
+  return _sessionTelemetry.keys().next().value;
+}
+function _resolveInjectionSession(args) {
+  const explicit = args.session_id;
+  if (typeof explicit === "string" && explicit.length > 0) return explicit;
+  return _implicitSessionId();
+}
 function _recordInjectionTelemetry(session_id, injected_packs) {
-  if (!session_id || !injected_packs) return;
+  if (!session_id) return;
   const state = _sessionTelemetry.get(session_id);
   if (!state) return;
   state.injection_calls++;
+  if (!injected_packs) return;
   for (const [pack, count] of Object.entries(injected_packs)) {
     state.pack_counts[pack] = (state.pack_counts[pack] ?? 0) + count;
   }
@@ -204,10 +289,11 @@ var CURSOR_CORE_TOOL_NAMES = /* @__PURE__ */ new Set([
   "plur_session_start",
   "plur_session_end",
   "plur_learn",
-  "plur_recall_hybrid",
+  "plur_recall",
   "plur_feedback",
   "plur_forget",
   "plur_status",
+  "plur_receipt",
   "plur_doctor",
   "plur_packs_uninstall",
   "plur_tensions_purge"
@@ -240,6 +326,13 @@ function buildAdminDispatchTool(all) {
       if (!target) {
         return { error: `Unknown action "${action}". Valid actions: ${adminActions.join(", ")}`, success: false, _isError: true };
       }
+      if (target.annotations?.destructiveHint === true) {
+        return {
+          error: `"${action}" is a destructive operation and cannot be dispatched via plur_admin \u2014 call the ${action} tool directly (it is exposed in every profile) so your client sees its destructiveHint annotation.`,
+          success: false,
+          _isError: true
+        };
+      }
       const innerArgs = args.args ?? {};
       const validated = validateToolArgs(target, innerArgs);
       if (!validated.ok) {
@@ -254,12 +347,20 @@ function buildAdminDispatchTool(all) {
     }
   };
 }
-function getToolDefinitions(profile = "full") {
+function getToolDefinitions(profile = "lean") {
   const all = getAllToolDefinitions();
-  if (profile !== "cursor") return all;
+  if (profile === "full") return all;
   const core = all.filter((t) => CURSOR_CORE_TOOL_NAMES.has(t.name));
   return [...core, buildAdminDispatchTool(all)];
 }
+function receiptSummary(r) {
+  if (r.coverage.source === "none") {
+    return r.window.windowed ? `No retrievals recorded in the last ${r.window.requested_days} days.` : "No retrieval history yet \u2014 logging begins once memory is used.";
+  }
+  const since = r.window.windowed ? `the last ${r.window.requested_days} days` : `${r.coverage.complete_from}`;
+  const pct = Math.round(r.retrieved.activation_rate * 100);
+  return `Since ${since}, ${r.retrieved.taught_pairs} times a memory the user taught was retrieved into context (across ${r.retrieved.retrievals} retrievals in ${r.window.sessions} sessions; ${r.retrieved.engrams} distinct engrams). Activation ${pct}% is store COVERAGE over the logging window, not a quality score \u2014 it is expected to be low and to fall as more engrams are added.`;
+}
 function getAllToolDefinitions() {
   return [
     {
@@ -319,6 +420,18 @@ function getAllToolDefinitions() {
           const scopes = remote.map((s) => `"${s.scope}"`).join(", ");
           return { scope_hint: `Stored at "${engramScope}" because no scope was passed, but a team store is configured (${scopes}). If this is team/engineering knowledge, re-learn it with an explicit scope so it reaches the shared store; keep genuinely personal notes at the default scope.` };
         };
+        const domainHint = (wasRouted) => {
+          if (typeof args.domain === "string" && args.domain.length > 0) return {};
+          if (explicitScope || wasRouted) return {};
+          let coversScopes = [];
+          try {
+            coversScopes = plur.listScopeMetadata().filter((md) => (md.covers?.length ?? 0) > 0).map((md) => md.scope);
+          } catch {
+            return {};
+          }
+          if (coversScopes.length === 0) return {};
+          return { domain_hint: `No domain set \u2014 without a dotted domain this engram cannot auto-route to a covers-declaring scope (${coversScopes.join(", ")}) and is harder to re-scope later. Set domain on every plur_learn, shape "<org>.<team>.<area>" (e.g. "plur.engineering.mcp") \u2014 see the domain convention in CLAUDE.md.` };
+        };
         const temporalEcho = (engram) => {
           const extracted = engram.structured_data?._expiry_extracted;
           return {
@@ -344,12 +457,13 @@ function getAllToolDefinitions() {
             decision: "ADD",
             ...temporalEcho(engram),
             ...scopeHint(engram.scope, !!routed),
+            ...domainHint(!!routed),
             ...isOutbox ? { outbox: true, warning: "Remote write failed; engram queued locally for retry on next session start or plur_sync." } : {},
             ...demoted ? { demoted: true, requested_scope: demoted.from, warning: `Sensitive content (${demoted.patterns}) detected \u2014 stored at "${demoted.to}"/private instead of the requested shared scope "${demoted.from}". If this is a false positive, re-scope deliberately.` } : {},
             ...routed ? { routed: { scope: routed.scope, confidence: routed.confidence, reason: routed.reason }, info: `No scope was provided; auto-routed to "${routed.scope}" (confidence ${routed.confidence}) because its content matched that scope's covers. Pass an explicit scope to override.` } : {}
           };
         } catch (err) {
-          const engram = plur.learn(statement, context);
+          const engram = await plur.learn(statement, context);
           const isOutbox = !!engram.structured_data?._outbox;
           const routedFallback = engram.structured_data?._routed;
           mcpCanary.signal("learn_activity");
@@ -362,6 +476,7 @@ function getAllToolDefinitions() {
             decision: "ADD",
             ...temporalEcho(engram),
             ...scopeHint(engram.scope, !!routedFallback),
+            ...domainHint(!!routedFallback),
             ...isOutbox ? { outbox: true } : {},
             warning: `Remote write failed (${err.message}); engram queued for retry.`
           };
@@ -433,6 +548,17 @@ function getAllToolDefinitions() {
         for (const r of results) {
           if (r.input_index !== void 0) ids[r.input_index] = r.engram.id;
         }
+        let batchDomainHint = {};
+        const noDomainCount = raw.filter((e) => !(typeof e.domain === "string" && e.domain.length > 0) && !(typeof e.scope === "string" && e.scope.length > 0)).length;
+        if (noDomainCount > 0) {
+          try {
+            const coversScopes = plur.listScopeMetadata().filter((md) => (md.covers?.length ?? 0) > 0).map((md) => md.scope);
+            if (coversScopes.length > 0) {
+              batchDomainHint = { domain_hint: `${noDomainCount} of ${raw.length} item(s) had no domain and no explicit scope \u2014 they cannot auto-route to a covers-declaring scope (${coversScopes.join(", ")}) and are harder to re-scope later. Set domain on every item, shape "<org>.<team>.<area>" \u2014 see the domain convention in CLAUDE.md.` };
+            }
+          } catch {
+          }
+        }
         return {
           ids,
           results: results.map((r) => ({
@@ -445,53 +571,35 @@ function getAllToolDefinitions() {
             ...r.existing_id ? { existing_id: r.existing_id } : {}
           })),
           stats,
+          ...batchDomainHint,
           ...failures.length > 0 ? { failures, warning: `${failures.length} of ${raw.length} engram(s) failed to persist; the rest were written.` } : {}
         };
       }
     },
     {
       name: "plur_recall",
-      description: "Query engrams by BM25 keyword matching \u2014 use plur_recall_hybrid for semantic similarity. Note: a project-scope filter also returns personal-family engrams (local, global, user:*, agent:*); an explicit scope=global recall returns ALL personal-family engrams \u2014 wider than scope=global INJECT, which is targeted to the global namespace only.",
-      annotations: { title: "Recall (BM25)", readOnlyHint: true, idempotentHint: true },
+      description: 'Search engrams by topic. Default mode is hybrid (BM25 + local embeddings via RRF) \u2014 set mode:"keyword" for BM25-only. No API calls, fully local. Note: a project-scope filter also returns personal-family engrams (local, global, user:*, agent:*); an explicit scope=global recall returns ALL personal-family engrams \u2014 wider than scope=global INJECT, which is targeted to the global namespace only.',
+      annotations: { title: "Recall", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
           query: { type: "string", description: "Search query to find relevant engrams" },
+          mode: { type: "string", enum: ["hybrid", "keyword"], description: "Search mode \u2014 hybrid (default): BM25 + embeddings via RRF; keyword: BM25-only (faster, embeddings-independent). budget, caller_session_id and include_episodes apply to hybrid mode only \u2014 in keyword mode use limit to bound results." },
           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)" },
-          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" }
+          budget: { type: "object", description: 'Budget constraints for sub-agents. Hybrid mode only \u2014 ignored when mode:"keyword".', 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. Hybrid mode only \u2014 ignored when mode:"keyword".' },
+          include_episodes: { type: "boolean", description: 'If true, include linked episode summaries for each engram (SP2 episodic anchoring). Hybrid mode only \u2014 ignored when mode:"keyword".' }
         },
         required: ["query"]
       },
-      handler: async (args, plur) => {
-        const results = plur.recall(args.query, {
-          scope: args.scope,
-          domain: args.domain,
-          limit: args.limit
-        });
-        return {
-          results: results.map((e) => {
-            const supersededBy = e.relations?.superseded_by;
-            const annotation = supersededBy?.length ? ` [superseded by ${supersededBy.join(", ")}]` : "";
-            return {
-              id: e.id,
-              statement: e.statement + annotation,
-              type: e.type,
-              scope: e.scope,
-              domain: e.domain,
-              retrieval_strength: e.activation.retrieval_strength
-            };
-          }),
-          count: results.length
-        };
-      }
+      handler: recallHandler
     },
     {
       name: "plur_recall_hybrid",
-      description: "Hybrid search \u2014 BM25 + local embeddings merged via Reciprocal Rank Fusion. No API calls, fully local. Best default for most use cases.",
-      annotations: { title: "Recall (hybrid)", readOnlyHint: true, idempotentHint: true },
+      description: "[Deprecated since 0.16 \u2014 use plur_recall (mode defaults to hybrid). Alias kept for backwards compatibility; removal earliest 0.18.] Hybrid search \u2014 BM25 + local embeddings merged via Reciprocal Rank Fusion. No API calls, fully local.",
+      annotations: { title: "Recall (hybrid) [deprecated alias]", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
@@ -505,72 +613,12 @@ function getAllToolDefinitions() {
         },
         required: ["query"]
       },
+      // True forwarder — delegates to the canonical plur_recall handler and
+      // prepends the deprecation notice. No duplicated budget/episode/
+      // reranker logic, so a fix to plur_recall reaches this alias too.
       handler: async (args, plur) => {
-        const budget = args.budget;
-        const effectiveLimit = budget?.max_results ?? args.limit ?? 20;
-        const meta = await plur.recallHybridWithMeta(args.query, {
-          scope: args.scope,
-          domain: args.domain,
-          limit: effectiveLimit
-        });
-        recordTelemetry("recall");
-        const results = meta.engrams;
-        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;
-        const response = {
-          results: boundedResults.map((e) => {
-            const raw = e;
-            const supersededBy = e.relations?.superseded_by;
-            const annotation = supersededBy?.length ? ` [superseded by ${supersededBy.join(", ")}]` : "";
-            const base = {
-              id: e.id,
-              statement: e.statement + annotation,
-              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: meta.mode
-        };
-        if (meta.mode === "hybrid-degraded") {
-          response.warning = `Embedding layer unavailable \u2014 results are BM25-only. Run plur_doctor for diagnosis. Last error: ${meta.embedderError ?? "unknown"}`;
-        }
-        if (resolveRerankerName() !== "off") {
-          response.reranked = meta.reranked ?? 0;
-          const rr = plur.rerankerStatus();
-          if (boundedResults.length > 0 && (meta.reranked ?? 0) === 0 && rr.lastError) {
-            const corruptNote = rr.lastErrorKind === "corrupt-cache" ? " The model cache looks corrupt (truncated download) \u2014 purge and re-download, see plur_doctor." : "";
-            response.reranker_warning = `PLUR_RERANKER is set but the reranker did not engage \u2014 results are RRF-only (fusion order, no cross-encoder rerank).${corruptNote} Last error: ${rr.lastError}. Run plur_doctor for diagnosis.`;
-          }
-        }
-        return response;
+        const result = await recallHandler({ ...args, mode: "hybrid" }, plur);
+        return { deprecated: RECALL_HYBRID_DEPRECATION, ...result };
       }
     },
     {
@@ -582,16 +630,20 @@ function getAllToolDefinitions() {
         properties: {
           task: { type: "string", description: "The task description to inject context for" },
           budget: { type: "number", description: "Token budget for injection (default 2000)" },
-          scope: { type: "string", description: "Scope filter for engram selection" }
+          scope: { type: "string", description: "Scope filter for engram selection" },
+          session_id: { type: "string", description: "Session this injection belongs to (from plur_session_start). Optional when one session is open; required for correct attribution when several are." }
         },
         required: ["task"]
       },
       handler: async (args, plur) => {
-        const result = plur.inject(args.task, {
+        const session_id = _resolveInjectionSession(args);
+        const result = await plur.inject(args.task, {
           budget: args.budget,
-          scope: args.scope
+          scope: args.scope,
+          source: "inject",
+          session_id
         });
-        _recordInjectionTelemetry(_activeSessionId, result.injected_packs);
+        _recordInjectionTelemetry(session_id, result.injected_packs);
         return {
           directives: result.directives,
           consider: result.consider,
@@ -612,16 +664,20 @@ function getAllToolDefinitions() {
         properties: {
           task: { type: "string", description: "The task description to inject context for" },
           budget: { type: "number", description: "Token budget for injection (default 2000)" },
-          scope: { type: "string", description: "Scope filter for engram selection" }
+          scope: { type: "string", description: "Scope filter for engram selection" },
+          session_id: { type: "string", description: "Session this injection belongs to (from plur_session_start). Optional when one session is open; required for correct attribution when several are." }
         },
         required: ["task"]
       },
       handler: async (args, plur) => {
+        const session_id = _resolveInjectionSession(args);
         const result = await plur.injectHybrid(args.task, {
           budget: args.budget,
-          scope: args.scope
+          scope: args.scope,
+          source: "inject",
+          session_id
         });
-        _recordInjectionTelemetry(_activeSessionId, result.injected_packs);
+        _recordInjectionTelemetry(session_id, result.injected_packs);
         return {
           directives: result.directives,
           consider: result.consider,
@@ -701,7 +757,7 @@ function getAllToolDefinitions() {
       },
       handler: async (args, plur) => {
         if (args.list === true) {
-          const pinned = plur.listPinned();
+          const pinned = await plur.listPinned();
           return {
             count: pinned.length,
             pinned: pinned.map((e) => ({ id: e.id, statement: e.statement, scope: e.scope, domain: e.domain }))
@@ -731,7 +787,7 @@ function getAllToolDefinitions() {
       },
       handler: async (args, plur) => {
         if (args.id) {
-          const engram = plur.getById(args.id);
+          const engram = await plur.getById(args.id);
           if (engram) {
             if (engram.status === "retired") return { success: false, error: `Already retired: ${args.id}` };
             await plur.forget(args.id);
@@ -741,7 +797,7 @@ function getAllToolDefinitions() {
           return { success: true, retired: { id: args.id } };
         }
         if (args.search) {
-          const matches = plur.recall(args.search, { limit: 100 });
+          const matches = await plur.recall(args.search, { limit: 100 });
           if (matches.length === 0) return { success: false, error: `No active engrams matching "${args.search}"` };
           if (matches.length === 1) {
             await plur.forget(matches[0].id);
@@ -840,7 +896,7 @@ function getAllToolDefinitions() {
         required: ["content"]
       },
       handler: async (args, plur) => {
-        const candidates = plur.ingest(args.content, {
+        const candidates = await plur.ingest(args.content, {
           source: args.source,
           extract_only: args.extract_only,
           scope: args.scope,
@@ -859,32 +915,32 @@ function getAllToolDefinitions() {
     },
     {
       name: "plur_packs_preview",
-      description: "Preview a pack before installing \u2014 shows manifest, engram list, security scan, and warnings. Always call this before plur_packs_install to let the user review what they are importing.",
+      description: "Preview a pack before installing \u2014 shows manifest, engram list, security scan, and warnings. Always call this before plur_packs_install to let the user review what they are importing. Accepts a local directory path or an https:// URL pointing to a .tar.gz archive.",
       annotations: { title: "Preview pack", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
-          source: { type: "string", description: "Path to the pack directory to preview" }
+          source: { type: "string", description: "Path to the pack directory, or an https:// URL to a .tar.gz pack archive" }
         },
         required: ["source"]
       },
       handler: async (args, plur) => {
-        return plur.previewPack(args.source);
+        return await plur.previewPack(args.source);
       }
     },
     {
       name: "plur_packs_install",
-      description: "Install an engram pack from a directory path. Runs a mandatory security scan (blocks if secrets found), detects conflicts with existing engrams, and records install metadata in the registry. Call plur_packs_preview first to show the user what the pack contains.",
+      description: "Install an engram pack from a local directory path or an https:// URL pointing to a .tar.gz archive. Runs a mandatory security scan (blocks if secrets found), detects conflicts with existing engrams, and records install metadata in the registry. Call plur_packs_preview first to show the user what the pack contains.",
       annotations: { title: "Install pack", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
-          source: { type: "string", description: "Path to the pack directory to install" }
+          source: { type: "string", description: "Path to the pack directory, or an https:// URL to a .tar.gz pack archive" }
         },
         required: ["source"]
       },
       handler: async (args, plur) => {
-        const result = plur.installPack(args.source);
+        const result = await plur.installPack(args.source);
         return {
           installed: result.installed,
           name: result.name,
@@ -970,17 +1026,27 @@ function getAllToolDefinitions() {
           full: {
             type: "boolean",
             description: "Full reindex: drop the derived index (PGLite/SQLite) and rebuild from YAML. YAML is never modified. Use to recover from an out-of-sync index."
+          },
+          remote_type: {
+            type: "string",
+            enum: ["personal", "shared"],
+            description: "What the sync remote is for (#640). personal (default): mirror everything non-local, private included \u2014 a solo user's own backup. shared: push ONLY shared-scope, non-private engrams \u2014 personal-family and private engrams never reach the remote. Persist the choice in config.yaml as sync.remote_type instead of passing it per call."
           }
         }
       },
       handler: async (args, plur) => {
-        const result = plur.sync(args.remote, { full: args.full === true });
+        const result = await plur.sync(args.remote, {
+          full: args.full === true,
+          ...args.remote_type === "personal" || args.remote_type === "shared" ? { remoteType: args.remote_type } : {}
+        });
         await plur.waitForIndex();
         const indexError = plur.lastIndexError();
         let outbox_result;
+        let outbox_error;
         try {
           outbox_result = await plur.flushOutbox();
-        } catch {
+        } catch (err) {
+          outbox_error = err.message;
         }
         return {
           ...result,
@@ -994,6 +1060,10 @@ function getAllToolDefinitions() {
               pending: outbox_result.failed,
               warnings: outbox_result.expired_warnings
             }
+          } : {},
+          ...outbox_error ? {
+            outbox_error,
+            outbox_warning: `The outbox flush failed \u2014 ${outbox_error}. Engrams routed to a remote store are still queued locally and were NOT pushed. They retry on the next session_start or plur_sync.`
           } : {}
         };
       }
@@ -1033,11 +1103,11 @@ function getAllToolDefinitions() {
           args.llm_api_key,
           args.llm_model
         );
-        const sourceEngrams = plur.list({
+        const sourceEngrams = await plur.list({
           domain: args.domain,
           scope: args.scope
         });
-        const existingMetas = plur.list().filter((e) => e.id.startsWith("META-"));
+        const existingMetas = (await plur.list()).filter((e) => e.id.startsWith("META-"));
         const result = await extractMetaEngrams(sourceEngrams, llm, {
           run_validation: args.run_validation,
           existing_metas: existingMetas
@@ -1045,7 +1115,7 @@ function getAllToolDefinitions() {
         const isDryRun = args.dry_run === true;
         let saveStats = null;
         if (!isDryRun && result.results.length > 0) {
-          saveStats = plur.saveMetaEngrams(result.results);
+          saveStats = await plur.saveMetaEngrams(result.results);
         }
         return {
           engrams_analyzed: result.engrams_analyzed,
@@ -1081,7 +1151,7 @@ function getAllToolDefinitions() {
         }
       },
       handler: async (args, plur) => {
-        const allEngrams = plur.list();
+        const allEngrams = await plur.list();
         const metaEngrams = allEngrams.filter((e) => e.id.startsWith("META-"));
         const minConfidence = args.min_confidence ?? 0;
         const levelFilter = args.hierarchy_level;
@@ -1132,20 +1202,20 @@ function getAllToolDefinitions() {
         required: ["meta_engram_id", "test_domain", "llm_base_url", "llm_api_key"]
       },
       handler: async (args, plur) => {
-        const allEngrams = plur.list();
+        const allEngrams = await plur.list();
         const meta = allEngrams.find((e) => e.id === args.meta_engram_id);
         if (!meta) {
           throw new Error(`Meta-engram not found: ${args.meta_engram_id}`);
         }
         const testDomain = args.test_domain;
-        const testEngrams = plur.list({ domain: testDomain });
+        const testEngrams = await plur.list({ domain: testDomain });
         const llm = makeHttpLlm(
           args.llm_base_url,
           args.llm_api_key,
           args.llm_model
         );
         const result = await validateMetaEngram(meta, testEngrams, testDomain, llm);
-        plur.updateEngram(meta);
+        await plur.updateEngram(meta);
         return {
           meta_engram_id: result.meta_engram_id,
           test_domain: result.test_domain,
@@ -1170,7 +1240,7 @@ function getAllToolDefinitions() {
         }
       },
       handler: async (args, plur) => {
-        const status = plur.status({
+        const status = await plur.status({
           domain: args.domain,
           created_after: args.created_after
         });
@@ -1202,10 +1272,26 @@ function getAllToolDefinitions() {
               behind: minorVersionsBehind(versionCheck.current, versionCheck.latest)
             }
           } : {},
-          capabilities: mcpCanary.status()
+          capabilities: await mcpCanary.status()
         };
       }
     },
+    {
+      name: "plur_receipt",
+      description: 'Counted report of what your memory retrieved for you: engrams stored, how many were retrieved and how often, which are most relied on, and how much of the store is dormant. Local and read-only; every figure is directly counted, never estimated. IMPORTANT when relaying to the user: `activation_rate` is COVERAGE over the logging window (\u2248 how much of the store was surfaced), NOT a quality or effectiveness score \u2014 it is naturally low and FALLS as more engrams are added, so never present it as "memory is N% effective". A `summary` line is included; prefer relaying that.',
+      annotations: { title: "Memory receipt", readOnlyHint: true, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          days: { type: "number", description: "Restrict to the last N days (integer). Omit for all recorded history." }
+        }
+      },
+      handler: async (args, plur) => {
+        const days = typeof args.days === "number" && Number.isFinite(args.days) && args.days >= 1 ? Math.floor(args.days) : void 0;
+        const receipt = await plur.receipt(days ? { days } : void 0);
+        return { summary: receiptSummary(receipt), ...receipt };
+      }
+    },
     {
       name: "plur_doctor",
       description: 'Diagnose the PLUR ENGINE (embedder, hybrid search, remote-store auth) \u2014 not hook/MCP wiring. Reports whether the embedding model loaded, whether hybrid search is fully operational, and \u2014 for any configured enterprise/remote store \u2014 whether its auth is valid (probes /api/v1/me and decodes token expiry), so a dead or soon-to-expire token surfaces instead of hiding behind a "healthy" report. Run this first when recall feels off or team engrams stop syncing. Does NOT check .cursor/mcp.json, .cursor/hooks.json, or the live MCP tool count \u2014 for that, run the `plur doctor` CLI command in a terminal (a different, more thorough check with the same name).',
@@ -1222,7 +1308,7 @@ function getAllToolDefinitions() {
           plur.resetEmbedder();
           plur.resetReranker();
         }
-        const status = plur.status();
+        const status = await plur.status();
         const before = plur.embedderStatus();
         if (!before.disabled) {
           try {
@@ -1325,7 +1411,7 @@ function getAllToolDefinitions() {
               evalStatus = { result: run.result, stale: false };
               freshlyRun = !run.cached;
             } else {
-              evalStatus = plur.rerankerEvalStatus(rerankerName);
+              evalStatus = await plur.rerankerEvalStatus(rerankerName);
             }
             if (!evalStatus) {
               checks.push({
@@ -1358,7 +1444,7 @@ function getAllToolDefinitions() {
             });
           }
         }
-        const canaryStatuses = mcpCanary.status();
+        const canaryStatuses = await mcpCanary.status();
         for (const cs of canaryStatuses) {
           if (!cs.healthy) {
             checks.push({ check: `capability: ${cs.capability}`, ok: false, detail: cs.warning });
@@ -1420,16 +1506,17 @@ function getAllToolDefinitions() {
         const task = args.task;
         const tags = args.tags;
         _cleanExpiredSessions();
-        _activeSessionId = session_id;
         _sessionTelemetry.set(session_id, {
           pack_counts: {},
           injection_calls: 0,
           started_at: (/* @__PURE__ */ new Date()).toISOString()
         });
         let outbox_result;
+        let outbox_error;
         try {
           outbox_result = await plur.flushOutbox();
-        } catch {
+        } catch (err) {
+          outbox_error = err.message;
         }
         const remote_scopes = plur.getWritableRemoteScopes().map((s) => {
           const md = plur.getScopeMetadata(s.scope);
@@ -1444,7 +1531,7 @@ function getAllToolDefinitions() {
         const default_scope = explicit_default_scope ?? projectConfig.scope ?? null;
         const scope_source = explicit_default_scope ? "caller" : projectConfig.scope ? "project-config" : "none";
         plur.setSessionScope(default_scope);
-        const status = plur.status();
+        const status = await plur.status();
         const store_stats = {
           engram_count: status.engram_count,
           episode_count: status.episode_count,
@@ -1456,8 +1543,9 @@ function getAllToolDefinitions() {
         try {
           const result = await plur.injectHybrid(task, {
             scope: tags?.length ? `tags:${tags.join(",")}` : void 0,
-            session_id
+            session_id,
             // stamped on the co_injection provenance event (#452)
+            source: "session_start"
           });
           _recordInjectionTelemetry(session_id, result.injected_packs);
           if (result.count > 0) {
@@ -1468,9 +1556,10 @@ function getAllToolDefinitions() {
             engrams = { text: lines.join("\n"), count: result.count, injected_ids: result.injected_ids };
           }
         } catch {
-          const result = plur.inject(task, {
+          const result = await plur.inject(task, {
             scope: tags?.length ? `tags:${tags.join(",")}` : void 0,
-            session_id
+            session_id,
+            source: "session_start"
           });
           _recordInjectionTelemetry(session_id, result.injected_packs);
           if (result.count > 0) {
@@ -1512,7 +1601,7 @@ Auto-detected project scope: "${default_scope}" (from .plur.yaml in the current
         } else if (scope_source === "none") {
           guide += `
 
-\u26A0\uFE0F No project scope detected. plur_learn calls without explicit scope will be tagged "global" and will appear in EVERY project's future sessions. Create a .plur.yaml NOW to prevent this: scope: "project:<your-project-name>". (This is every project's PERSONAL recall context, NOT team shared stores \u2014 use an explicit shared scope like project:/group: to reach a team store.) Note: an explicit scope=global RECALL surfaces all your personal engrams, but scope=global INJECT is targeted to the global namespace only \u2014 don't be surprised if a local engram a global recall finds is absent from a global inject.`;
+\u26A0\uFE0F No project scope detected. plur_learn calls without explicit scope may AUTO-ROUTE to a registered team scope whose covers confidently match the engram's domain/tags (the response reports \`routed\` when that happens); otherwise they land at the unscoped default "global" and will appear in EVERY project's future sessions. Create a .plur.yaml NOW to prevent this: scope: "project:<your-project-name>". (This is every project's PERSONAL recall context, NOT team shared stores \u2014 use an explicit shared scope like project:/group: to reach a team store.) Note: an explicit scope=global RECALL surfaces all your personal engrams, but scope=global INJECT is targeted to the global namespace only \u2014 don't be surprised if a local engram a global recall finds is absent from a global inject.`;
         }
         if (remote_scopes.length > 0) {
           const safe = (x) => String(x ?? "").replace(/\s+/g, " ").trim().slice(0, 200);
@@ -1527,9 +1616,10 @@ Auto-detected project scope: "${default_scope}" (from .plur.yaml in the current
 
 Session default scope is set to "${default_scope}". To route an engram to a remote enterprise store instead, pass scope explicitly to plur_learn (available remote scopes: ${scopeList}).` : `
 
-Remote store scopes available: ${scopeList}. Set scope PER ENGRAM by content: when an engram is relevant to the team (engineering patterns, architecture decisions, project conventions), set scope to the matching remote scope in plur_learn. Personal preferences, local project details, and corrections specific to your workflow can be left unscoped (they land at the unscoped default, "global" \u2014 the cross-project personal namespace). Do NOT let TEAM knowledge fall back to "global" \u2014 without an explicit scope it will, and it will never reach the shared store.`;
+Remote store scopes available: ${scopeList}. Set scope PER ENGRAM by content: when an engram is relevant to the team (engineering patterns, architecture decisions, project conventions), set scope to the matching remote scope in plur_learn. Personal preferences, local project details, and corrections specific to your workflow can be left unscoped \u2014 but note an unscoped write whose domain/tags confidently match a team scope's covers AUTO-ROUTES to that shared team store (the response reports \`routed\` when that happens); otherwise it lands at the unscoped default, "global" \u2014 the cross-project personal namespace. Do NOT rely on auto-routing for TEAM knowledge \u2014 set the matching scope explicitly; a weak or absent covers match falls back to "global" and never reaches the shared store.`;
           try {
             const discoveries = await plur.discoverRemoteScopes({ timeoutMs: 3e3 });
+            plur.persistScopeMetadata(discoveries);
             const failures = discoveries.filter((d) => !d.ok);
             if (failures.length > 0) {
               const authExpired = failures.some((f) => /\b40[13]\b/.test(f.error ?? ""));
@@ -1541,12 +1631,11 @@ Remote store scopes available: ${scopeList}. Set scope PER ENGRAM by content: wh
 
 \u26A0\uFE0F ENTERPRISE STORE UNREACHABLE: ${urls}. Reads fall back to local; team-scoped writes queue in the outbox` + (pending > 0 ? ` (${pending} pending)` : "") + ` until it recovers. Check connectivity/VPN.`;
             }
-            const unregistered = [...new Set(discoveries.filter((d) => d.ok).flatMap((d) => d.unregistered))];
-            if (unregistered.length > 0) {
-              const list = unregistered.map((s) => `"${safe(s)}"`).join(", ");
+            const offerable = [...new Set(discoveries.filter((d) => d.ok).flatMap((d) => d.unregistered))].filter(isSharedScope);
+            if (offerable.length > 0) {
               guide += `
 
-\u{1F50E} Your token is authorized for ${unregistered.length} more scope(s) not yet registered: ${list}. Call plur_scopes_discover with register:true to add them all in one step.`;
+\u{1F50E} ${offerable.length} authorized scope(s) not yet registered. Tell the user they can run \`plur scopes\` to register or dismiss them per-scope (dismissed scopes stop being offered; \`plur scopes --reoffer\` re-surfaces them).`;
             }
           } catch {
           }
@@ -1585,6 +1674,10 @@ Remote store scopes available: ${scopeList}. Set scope PER ENGRAM by content: wh
               warnings: outbox_result.expired_warnings
             }
           } : {},
+          ...outbox_error ? {
+            outbox_error,
+            outbox_warning: `The outbox flush failed \u2014 ${outbox_error}. Engrams routed to a remote store are still queued locally and were NOT pushed. They retry on the next session_start or plur_sync.`
+          } : {},
           // Version staleness warning (issue #151)
           ...version_warning ? { version_warning, version: VERSION } : {}
         };
@@ -1650,7 +1743,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
                 `engram_suggestions[${i}] must be a string or {statement: string, type?: string}, got ${typeof s}`
               );
             }
-            plur.learn(statement, { type });
+            await plur.learn(statement, { type });
             engrams_created++;
           }
         }
@@ -1666,7 +1759,6 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         } : void 0;
         if (session_id) {
           _sessionTelemetry.delete(session_id);
-          if (_activeSessionId === session_id) _activeSessionId = void 0;
         }
         try {
           const plurDir = process.env.PLUR_PATH ?? join(homedir(), ".plur");
@@ -1681,7 +1773,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           }
         } catch {
         }
-        const status = plur.status();
+        const status = await plur.status();
         return {
           engrams_created,
           episode_id: episode.id,
@@ -1743,7 +1835,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
       inputSchema: { type: "object", properties: {} },
       handler: async (_args, plur) => {
         const stores = await plur.listStoresAsync();
-        const outboxCount = plur.outboxCount();
+        const outboxCount = await plur.outboxCount();
         return {
           stores,
           count: stores.length,
@@ -1753,29 +1845,33 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
     },
     {
       name: "plur_suggest_scope",
-      description: 'Suggest which registered scope(s) an engram belongs in, ranked by fit. Deterministic \u2014 no LLM, no network. Scores the statement keywords, optional domain (a dotted namespace like "plur.core.security"), and tags against the covers[] each scope declares. ADVISORY ONLY: this does not route or store anything; pass the chosen scope to plur_learn yourself. Returns candidates sorted by confidence (empty when nothing matches).',
+      description: 'Suggest which registered scope(s) an engram belongs in, ranked by fit. Deterministic \u2014 no LLM, no network. Scores the statement keywords, optional domain (a dotted namespace like "plur.core.security"), and tags against the covers[] each scope declares. ADVISORY ONLY: this does not route or store anything; pass the chosen scope to plur_learn yourself. Returns candidates sorted by confidence (empty when nothing matches). Candidates below min_confidence (default: scope_routing.min_confidence config, else 0.15) are suppressed \u2014 a lone coincidental keyword scores \u22480.12 and is noise, not signal (#670); pass min_confidence: 0 to see every scored candidate.',
       annotations: { title: "Suggest scope", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
         properties: {
           statement: { type: "string", description: "The engram statement to route" },
           domain: { type: "string", description: 'Optional dotted namespace for the engram (e.g. "plur.core.security") \u2014 strongest routing signal' },
-          tags: { type: "array", items: { type: "string" }, description: "Optional tags on the engram" }
+          tags: { type: "array", items: { type: "string" }, description: "Optional tags on the engram" },
+          min_confidence: { type: "number", minimum: 0, maximum: 1, description: "Suppress candidates below this confidence (0-1; out-of-range values are clamped). Default: scope_routing.min_confidence from config, else 0.15 \u2014 clips lone-keyword noise (\u22480.12) while keeping real multi-signal matches. Pass 0 for the unfiltered list." }
         },
         required: ["statement"]
       },
       handler: async (args, plur) => {
-        const candidates = plur.suggestScope({
+        const raw = args.min_confidence;
+        const explicit = typeof raw === "number" && Number.isFinite(raw) ? Math.min(1, Math.max(0, raw)) : void 0;
+        const minConfidence = explicit ?? plur.getScopeRoutingConfig().min_confidence ?? SUGGEST_DISPLAY_MIN_CONFIDENCE;
+        const candidates = await plur.suggestScope({
           statement: args.statement,
           domain: args.domain,
           tags: args.tags
-        });
-        return { candidates, count: candidates.length };
+        }, { minConfidence });
+        return { candidates, count: candidates.length, min_confidence: minConfidence };
       }
     },
     {
       name: "plur_scopes_discover",
-      description: "Discover which scopes your remote token is authorized for via the enterprise server (GET /api/v1/me), and which of those are not yet registered locally. Read-only by default; pass register:true to register all authorized-but-unregistered scopes in one step. Only shared-family scopes (group:/project:/space:/team:/org:/public) are auto-registered \u2014 personal-family scopes (global/local/user:*/agent:*) advertised by /me are skipped and surfaced in the result. Use this when you have access to multiple team scopes on one server.",
+      description: "Discover which scopes your remote token is authorized for via the enterprise server (GET /api/v1/me), and which of those are not yet registered locally. Read-only by default; pass register:true to register all authorized-but-unregistered scopes in one step. Only shared-family scopes (group:/project:/space:/team:/org:/public) are auto-registered \u2014 personal-family scopes (global/local/user:*/agent:*) advertised by /me are skipped and surfaced in the result, and scopes the user has dismissed are respected (NOT registered by the batch path; register one individually via the CLI `plur scopes register <scope>` to override, which also clears the dismissal). Use this when you have access to multiple team scopes on one server.",
       annotations: { title: "Discover scopes", readOnlyHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -1831,7 +1927,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         const promoted = [];
         const errors = [];
         for (const id of targetIds) {
-          const engram = plur.getById(id);
+          const engram = await plur.getById(id);
           if (!engram) {
             errors.push({ id, error: "Not found" });
             continue;
@@ -1848,7 +1944,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           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);
+          await plur.updateEngram(engram);
           promoted.push({ id, statement: engram.statement });
         }
         return { promoted, errors, success: errors.length === 0 };
@@ -1893,12 +1989,12 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           if (args.action === "resolve") {
             const winner = args.winner;
             if (!winner) throw new Error('action:"resolve" requires winner (the engram id to keep)');
-            const { record, retired_id } = plur.resolveTension(id, winner);
+            const { record, retired_id } = await plur.resolveTension(id, winner);
             return { record, retired: retired_id, message: `Tension ${id} resolved: ${winner} wins, ${retired_id} retired.` };
           }
           throw new Error(`Unknown action: ${args.action}. Use confirm, dismiss, or resolve.`);
         }
-        const engrams = plur.list({
+        const engrams = await plur.list({
           scope: args.scope,
           domain: args.domain
         });
@@ -1922,7 +2018,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
             temporal_discount: args.temporal_discount ?? tensionsConfig.temporal_discount,
             ...persist ? { exclude_pairs: new Set(plur.suppressedTensionPairKeys()) } : {}
           });
-          const persisted = persist && result.tensions.length > 0 ? plur.recordTensions(result.tensions) : void 0;
+          const persisted = persist && result.tensions.length > 0 ? await plur.recordTensions(result.tensions) : void 0;
           return {
             pairs_checked: result.pairs_checked,
             count: result.new_tensions,
@@ -1975,7 +2071,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
       annotations: { title: "Purge Tensions", destructiveHint: true, idempotentHint: true },
       inputSchema: { type: "object", properties: {} },
       handler: async (_args, plur) => {
-        const result = plur.purgeTensions();
+        const result = await plur.purgeTensions();
         return {
           purged_conflict_refs: result.purged_count,
           engrams_modified: result.engrams_modified,
@@ -1998,7 +2094,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         required: ["episode_id"]
       },
       handler: async (args, plur) => {
-        const engram = plur.episodeToEngram(args.episode_id, {
+        const engram = await plur.episodeToEngram(args.episode_id, {
           scope: args.scope,
           domain: args.domain,
           tags: args.tags
@@ -2035,7 +2131,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           };
         }
         const { listHistoryMonths, readHistory } = await import("@plur-ai/core");
-        const status = plur.status();
+        const status = await plur.status();
         const months = listHistoryMonths(status.storage_root);
         const allEvents = [];
         for (const month of months.reverse()) {
@@ -2108,7 +2204,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
       },
       handler: async (args, plur) => {
         const name = args.name;
-        let engrams = plur.list({
+        let engrams = await plur.list({
           domain: args.filter_domain,
           scope: args.filter_scope
         });
@@ -2122,9 +2218,9 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         if (filterType) {
           engrams = engrams.filter((e) => e.type === filterType);
         }
-        const { homedir: homedir3 } = await import("os");
-        const { join: join3 } = await import("path");
-        const outputDir = args.output_dir || join3(homedir3(), "plur-packs", name);
+        const { homedir: homedir2 } = await import("os");
+        const { join: join2 } = await import("path");
+        const outputDir = args.output_dir || join2(homedir2(), "plur-packs", name);
         const result = plur.exportPack(engrams, outputDir, {
           name,
           version: "1.0.0",
@@ -2189,7 +2285,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         }
       },
       handler: async (args, plur) => {
-        const status = plur.status();
+        const status = await plur.status();
         const storagePath = status.storage_root;
         if (!args.force_regenerate) {
           const cached = getProfileForInjection(storagePath);
@@ -2202,7 +2298,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         }
         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 engrams = await 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 };
       }
@@ -2210,351 +2306,11 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
   ];
 }
 
-// src/server.ts
-function serverPidPath(baseDir) {
-  return join2(baseDir ?? join2(homedir2(), ".plur"), "server.pid");
-}
-function readEnterpriseToken(baseDir) {
-  const configPath = join2(baseDir ?? join2(homedir2(), ".plur"), "config.json");
-  if (!existsSync2(configPath)) return void 0;
-  try {
-    const cfg = JSON.parse(readFileSync(configPath, "utf8"));
-    const ent = cfg?.enterprise;
-    if (!ent || typeof ent.url !== "string" || typeof ent.token !== "string") return void 0;
-    return { url: ent.url, token: ent.token, username: ent.username };
-  } catch {
-    return void 0;
-  }
-}
-var _pendingReload = false;
-function isPendingReload() {
-  return _pendingReload;
-}
-function clearPendingReload() {
-  _pendingReload = false;
-}
-var INSTRUCTIONS = `PLUR is your persistent memory. Corrections, preferences, and conventions persist across sessions as engrams.
-
-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.
-
-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
-
-SCOPE SELECTION (set scope PER engram, by content \u2014 not once per session):
-A single session produces engrams that belong in different stores. Choose the
-"scope" on EACH plur_learn call from what the engram is about:
-- Team / engineering / architecture / shared-convention knowledge \u2192 the matching
-  team store scope (e.g. "group:<org>/<team>"). plur_session_start lists the
-  scopes this install can write to \u2014 use them.
-- Personal preferences, your workflow, or details specific to one project \u2192 the
-  default/local scope (or "project:<name>").
-- "global" is for genuinely cross-project facts only (language gotchas, tool
-  quirks). Do NOT let team-relevant knowledge fall back to "global" by omitting
-  scope \u2014 with a team store configured it never reaches the team store. If no
-  scope fits, prefer the project/local default over global.
-
-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
-
-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/mcp init
-This installs hooks for automatic injection + session management. One-time global setup.`;
-var GUIDE_RESOURCE = `# PLUR \u2014 Agent Guide
-
-## What is PLUR?
-
-Persistent memory for AI agents. Corrections, preferences, and conventions are stored as **engrams** \u2014 small assertions that strengthen with use and decay when irrelevant (ACT-R model). Storage is plain YAML on disk. Search is fully local (BM25 + embeddings). Zero API calls.
-
-## Quick Start
-
-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_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_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)
-- **plur_inject_hybrid** \u2014 select engrams for a task (BM25 + embeddings, recommended)
-
-### Episodic Timeline
-- **plur_capture** \u2014 record what happened in a session
-- **plur_timeline** \u2014 query past episodes
-
-### Knowledge Management
-- **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
-
-**Note:** Multi-store is currently config-only. Recall and inject search the primary store. Cross-store search coming in a future release.
-
-### Sync & Status
-- **plur_sync** \u2014 sync engrams across devices via git
-- **plur_sync_status** \u2014 check sync state
-- **plur_status** \u2014 system health
-
-## Scoping
-
-Use \`scope\` to namespace engrams per project:
-- \`scope: "global"\` \u2014 applies everywhere (default)
-- \`scope: "project:my-app"\` \u2014 applies only to my-app
-- Scoped recall automatically includes global engrams
-
-## Storage
-
-\`\`\`
-~/.plur/
-\u251C\u2500\u2500 engrams.yaml     # learned knowledge
-\u251C\u2500\u2500 episodes.yaml    # session timeline
-\u2514\u2500\u2500 config.yaml      # settings
-\`\`\`
-
-Override with \`PLUR_PATH\` environment variable.
-`;
-async function createServer(plur, options) {
-  const instance = plur ?? new Plur2();
-  const tools = getToolDefinitions(options?.profile ?? "full");
-  checkForUpdate("@plur-ai/mcp", VERSION, (r) => {
-    if (r.updateAvailable) {
-      console.error(`[plur] Update available: ${r.current} \u2192 ${r.latest}. Run: npx @plur-ai/mcp@latest`);
-    }
-  });
-  const server = new Server(
-    { name: "plur-mcp", version: VERSION },
-    {
-      capabilities: {
-        tools: {},
-        resources: {},
-        prompts: {},
-        logging: {}
-      },
-      instructions: INSTRUCTIONS
-    }
-  );
-  server.setRequestHandler(ListToolsRequestSchema, async () => ({
-    tools: tools.map((t) => ({
-      name: t.name,
-      description: t.description,
-      inputSchema: t.inputSchema,
-      ...t.annotations && { annotations: t.annotations }
-    }))
-  }));
-  server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const tool = tools.find((t) => t.name === request.params.name);
-    if (!tool) {
-      return {
-        content: [{ type: "text", text: JSON.stringify({ error: `Unknown tool: ${request.params.name}`, success: false }) }],
-        isError: true
-      };
-    }
-    mcpCanary.tick();
-    try {
-      let args = request.params.arguments ?? {};
-      const validated = validateToolArgs(tool, args);
-      if (!validated.ok) {
-        return {
-          content: [{ type: "text", text: JSON.stringify(validated.errorPayload) }],
-          isError: true
-        };
-      }
-      args = validated.data;
-      const result = await tool.handler(args, instance);
-      let payload = result;
-      let resultIsError = false;
-      if (result && typeof result === "object" && result._isError === true) {
-        resultIsError = true;
-        const { _isError, ...rest } = result;
-        payload = rest;
-      }
-      return {
-        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-        ...resultIsError ? { isError: true } : {}
-      };
-    } catch (err) {
-      const message = err?.message ?? String(err);
-      server.sendLoggingMessage({ level: "error", data: `Tool ${request.params.name} failed: ${message}` });
-      return {
-        content: [{ type: "text", text: JSON.stringify({ error: message, success: false }) }],
-        isError: true
-      };
-    }
-  });
-  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
-    resources: [
-      {
-        uri: "plur://guide",
-        name: "PLUR Agent Guide",
-        description: "Complete reference for all PLUR tools, when to use them, scoping, and storage",
-        mimeType: "text/markdown"
-      },
-      {
-        uri: "plur://status",
-        name: "PLUR Status",
-        description: "Live system health \u2014 engram count, episode count, pack count, storage path",
-        mimeType: "application/json"
-      }
-    ]
-  }));
-  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-    const uri = request.params.uri;
-    if (uri === "plur://guide") {
-      const cursorNote = options?.profile === "cursor" ? `
-
-## Cursor tool profile
-
-Most tools above are NOT directly callable in this session \u2014 only ${[...CURSOR_CORE_TOOL_NAMES].join(", ")} are top-level tools here. Everything else in this guide is reachable through **plur_admin**: call it with \`{ action: "<tool name above>", args: {...} }\`.` : "";
-      return {
-        contents: [{
-          uri: "plur://guide",
-          mimeType: "text/markdown",
-          text: GUIDE_RESOURCE + cursorNote
-        }]
-      };
-    }
-    if (uri === "plur://status") {
-      const status = instance.status();
-      return {
-        contents: [{
-          uri: "plur://status",
-          mimeType: "application/json",
-          text: JSON.stringify({
-            engram_count: status.engram_count,
-            episode_count: status.episode_count,
-            pack_count: status.pack_count,
-            storage_root: status.storage_root,
-            version: VERSION
-          }, null, 2)
-        }]
-      };
-    }
-    throw new McpError(ErrorCode.InvalidRequest, `Unknown resource: ${uri}`);
-  });
-  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
-    prompts: [
-      {
-        name: "plur-getting-started",
-        description: "Step-by-step guide to set up and start using PLUR memory"
-      },
-      {
-        name: "plur-session-start",
-        description: "Load relevant context for a task \u2014 call at the start of each session",
-        arguments: [
-          { name: "task", description: "Brief description of the task or goal", required: true },
-          { name: "scope", description: "Project scope (e.g. project:my-app)", required: false }
-        ]
-      }
-    ]
-  }));
-  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
-    const name = request.params.name;
-    if (name === "plur-getting-started") {
-      const status = instance.status();
-      return {
-        description: "Get started with PLUR memory",
-        messages: [{
-          role: "user",
-          content: {
-            type: "text",
-            text: `I just set up PLUR. Here's my current status:
-
-- Engrams stored: ${status.engram_count}
-- Episodes recorded: ${status.episode_count}
-- Packs installed: ${status.pack_count}
-- Storage: ${status.storage_root}
-
-${status.engram_count === 0 ? `I have no memories yet. Help me get started by:
-1. Teaching me a coding preference or convention (I'll use plur_learn)
-2. Then recalling it to verify it works (I'll use plur_recall_hybrid)
-3. Rating the recall quality (I'll use plur_feedback)` : `I have ${status.engram_count} engrams stored. Try asking me something related to your project \u2014 I'll check my memory first.`}`
-          }
-        }]
-      };
-    }
-    if (name === "plur-session-start") {
-      const task = request.params.arguments?.task ?? "general work";
-      const scope = request.params.arguments?.scope;
-      return {
-        description: "Load relevant context for this session",
-        messages: [{
-          role: "user",
-          content: {
-            type: "text",
-            text: `Starting a new session. Task: ${task}${scope ? ` (scope: ${scope})` : ""}
-
-Please:
-1. Call plur_recall_hybrid with query "${task}"${scope ? ` and scope "${scope}"` : ""} to load relevant memories
-2. Review the recalled engrams and apply any relevant conventions or preferences
-3. If any recalled engrams are helpful, call plur_feedback with "positive"
-4. If any are irrelevant, call plur_feedback with "negative"`
-          }
-        }]
-      };
-    }
-    throw new McpError(ErrorCode.InvalidRequest, `Unknown prompt: ${name}`);
-  });
-  return server;
-}
-async function runStdio() {
-  const profile = process.env.PLUR_TOOL_PROFILE === "cursor" ? "cursor" : "full";
-  const server = await createServer(void 0, { profile });
-  registerFlushOnExit({});
-  try {
-    writeFileSync(serverPidPath(), String(process.pid));
-  } catch {
-  }
-  if (process.platform !== "win32") {
-    process.on("SIGUSR1", () => {
-      _pendingReload = true;
-    });
-  }
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
-}
 export {
-  INSTRUCTIONS,
-  clearPendingReload,
-  createServer,
-  isPendingReload,
-  readEnterpriseToken,
-  runStdio,
-  serverPidPath
+  registerFlushOnExit,
+  VERSION,
+  validateToolArgs,
+  mcpCanary,
+  CURSOR_CORE_TOOL_NAMES,
+  getToolDefinitions
 };