@plur-ai/mcp 0.19.4 → 0.20.1

package/README.md

@@ -63,7 +63,7 @@ By default (lean profile), your agent gets 12 tools. Everything else is reachabl
 | `plur_tensions_purge` | Clear stale/resolved tensions |
 | `plur_admin` | Dispatch to any other tool: `{ action: "plur_packs_install", args: {...} }` |
 
-Less commonly needed tools (`plur_recall_hybrid`, `plur_inject_hybrid`, `plur_learn_batch`, `plur_ingest`, `plur_sync`, `plur_packs_install`, `plur_packs_list`, `plur_capture`, `plur_timeline`, and more) are all reachable via `plur_admin`. Set `PLUR_TOOL_PROFILE=full` to expose all 43 tools directly.
+Less commonly needed tools (`plur_recall_hybrid`, `plur_inject_hybrid`, `plur_learn_batch`, `plur_ingest`, `plur_sync`, `plur_packs_install`, `plur_packs_list`, `plur_capture`, `plur_timeline`, `plur_provenance`, and more) are all reachable via `plur_admin`. Set `PLUR_TOOL_PROFILE=full` to expose all 44 tools directly.
 
 A `plur_*` name missing from `tools/list` means it moved behind the gateway, not that the server is down. `plur_admin { action: "help" }` returns every action with a one-line description and its argument schema; `plur_doctor` reports the same inventory as `tool_surface`.
 

package/dist/chunk-445S5QNU.js

@@ -0,0 +1,6 @@
+// src/version.ts
+var VERSION = "0.20.1";
+
+export {
+  VERSION
+};

package/dist/{chunk-6HBPG6IR.js → chunk-SWQDW42Z.js}

@@ -1,3 +1,7 @@
+import {
+  VERSION
+} from "./chunk-445S5QNU.js";
+
 // src/telemetry.ts
 import { recordEvent, flushIfNeeded, registerFlushOnExit } from "@plur-ai/core";
 function recordTelemetry(event) {
@@ -9,14 +13,11 @@ function recordTelemetry(event) {
   }
 }
 
-// src/version.ts
-var VERSION = "0.19.4";
-
 // 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, mcpRemoteWarningLine, doctorRemoteRemediation, normalizeEndpointUrl, REMOTE_STATUS_TTL_MS, PROBE_CLEARABLE_STATES } from "@plur-ai/core";
+import { extractMetaEngrams, validateMetaEngram, confidenceBand, generateProfile, getProfileForInjection, selectModelForOperation, getCachedUpdateCheck, minorVersionsBehind, scanForTensions, CapabilityCanary, readProjectConfig, isSharedScope, resolveRerankerName, getReranker, classifyRerankerFailure, hfCacheDirName, SUGGEST_DISPLAY_MIN_CONFIDENCE, mcpRemoteWarningLine, doctorRemoteRemediation, normalizeEndpointUrl, REMOTE_STATUS_TTL_MS, PROBE_CLEARABLE_STATES, bareEngramId, summariseProvenance, renderProvenanceSummary } from "@plur-ai/core";
 import { z } from "zod";
 function makeHttpLlm(baseUrl, apiKey, model = "gpt-4o-mini") {
   return async (prompt) => {
@@ -89,7 +90,7 @@ var recallHandler = async (args, plur) => {
         const measuredUnder = raw.measured_under;
         const measuredAnnotation = measuredUnder ? " [measured under: " + Object.entries(measuredUnder).filter(([, v]) => v != null).map(([k, v]) => `${k}=${v}`).join(", ") + "]" : "";
         return {
-          id: e.id,
+          id: raw._originalId ?? bareEngramId(e.id),
           statement: e.statement + annotation + measuredAnnotation,
           type: e.type,
           scope: e.scope,
@@ -153,7 +154,7 @@ var recallHandler = async (args, plur) => {
       const measuredUnder = raw.measured_under;
       const measuredAnnotation = measuredUnder ? " [measured under: " + Object.entries(measuredUnder).filter(([, v]) => v != null).map(([k, v]) => `${k}=${v}`).join(", ") + "]" : "";
       const base = {
-        id: e.id,
+        id: raw._originalId ?? bareEngramId(e.id),
         statement: e.statement + annotation + measuredAnnotation,
         type: e.type,
         scope: e.scope,
@@ -299,7 +300,11 @@ var PLUR_GUIDE = `## PLUR Quick Start
 5. Call **plur_session_end** before the conversation ends \u2014 suggest new engrams
 
 ### Core Tools
-- **plur_learn** \u2014 record corrections, preferences, patterns (CALL THIS OFTEN)
+- **plur_learn** \u2014 one assertion per call, small enough to act on at a glance. The
+  mechanism goes in \`rationale\`, the evidence in \`source\`. Call it often, and do not
+  force one: a bad engram costs injection budget forever, a missed one costs a re-ask.
+  For anything beyond a one-line correction, use the \`plur-create-engrams\` skill \u2014
+  it is the authoring contract, not a style preference.
 - **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() {
@@ -318,6 +323,32 @@ function sanitizeStatement(raw) {
   }
   return raw.slice(0, cut).trimEnd();
 }
+function composeHints(statement, rationale, source) {
+  const hints = [];
+  const chars = statement.length;
+  if (chars <= 400) return void 0;
+  if (/\b(on|proven|observed|stated|decided|confirmed)\s+20\d\d-\d\d-\d\d/i.test(statement)) {
+    hints.push("carries a dated observation \u2014 that is a citation, move it to `source`");
+  }
+  const engRefs = statement.match(/\b(ENG|ABS|META)-[A-Za-z0-9-]+/g);
+  if (engRefs && engRefs.length >= 2) {
+    hints.push(`names ${engRefs.length} other engrams \u2014 use relations.supersedes, or cite them in \`rationale\``);
+  }
+  if (/\b(because|since|the reason is|which is why)\b/i.test(statement) && !rationale) {
+    hints.push("argues its own case inline while `rationale` is empty \u2014 move the mechanism there");
+  }
+  if (/\b(and also|additionally|separately|furthermore)\b/i.test(statement)) {
+    hints.push('contains "and also" \u2014 that is a second engram, split it');
+  }
+  if (!rationale) {
+    hints.push("`rationale` is empty on a long statement: state the mechanism that makes this true, and therefore when it stops being true");
+  }
+  if (!source) {
+    hints.push("`source` is empty: where did this come from");
+  }
+  if (!hints.length) return void 0;
+  return { chars, misplaced: hints };
+}
 var mcpCanary = new CapabilityCanary({ threshold: 10 });
 mcpCanary.expect({
   id: "session_start_hook",
@@ -514,12 +545,12 @@ function getAllToolDefinitions() {
   return [
     {
       name: "plur_learn",
-      description: "Create an engram \u2014 record a reusable learning, preference, or correction. A write is never suppressed by similarity: exact content-hash duplicates NOOP, and anything merely SIMILAR is written and reported back in `dedup.near_duplicates` (closest existing engrams and their cosine scores) so you can supersede or merge deliberately. High similarity is a reason to look, not a decision \u2014 cosine cannot tell a duplicate from a correction of it. Multi-agent note: in an orchestration that spawns subagents, have the PARENT session own plur_learn writes \u2014 spawned subagents should return their findings as text for the parent to persist, rather than each calling plur_learn (tool availability is not guaranteed in every subagent context). See plur-ai/plur#281.",
+      description: "Create an engram \u2014 record a reusable learning, preference, or correction. A write is never suppressed by similarity: exact content-hash duplicates NOOP, and anything merely SIMILAR is written and reported back in `dedup.near_duplicates` (closest existing engrams, their cosine scores, and a preview of each neighbour's own statement \u2014 read them before moving on; that is what they are for) so you can supersede or merge deliberately. High similarity is a reason to look, not a decision \u2014 cosine cannot tell a duplicate from a correction of it. Multi-agent note: in an orchestration that spawns subagents, have the PARENT session own plur_learn writes \u2014 spawned subagents should return their findings as text for the parent to persist, rather than each calling plur_learn (tool availability is not guaranteed in every subagent context). See plur-ai/plur#281.",
       annotations: { title: "Learn", destructiveHint: false, idempotentHint: false },
       inputSchema: {
         type: "object",
         properties: {
-          statement: { type: "string", description: "The knowledge assertion to store" },
+          statement: { type: "string", description: 'ONE assertion, written so someone who was not there can act on it. Route the rest to the field whose job it is: the mechanism that makes it true goes in `rationale`, where it came from in `source`, when it applies in `tags`/`domain`. An "and also" means a second engram. Good: "Never name a client unless the user names them first, say the customer." Typical 100-300 chars; past ~600 you are carrying another field content. Length is a symptom, not the rule.' },
           type: {
             type: "string",
             enum: ["behavioral", "terminological", "procedural", "architectural"],
@@ -528,10 +559,10 @@ function getAllToolDefinitions() {
           scope: { type: "string", description: "Namespace, e.g. global, project:myapp" },
           domain: { type: "string", description: "Domain tag, e.g. software.deployment" },
           tags: { type: "array", items: { type: "string" }, description: "Searchable keyword tags \u2014 contribute to BM25/embedding recall, so concrete keywords pay off" },
-          rationale: { type: "string", description: "Why this knowledge matters \u2014 also enters the search corpus, helps recall by intent not just statement" },
+          rationale: { type: "string", description: 'The mechanism that makes the statement true, and therefore the condition under which it would STOP being true. One sentence. "Because the user said so on <date>" is a citation, not a mechanism: that belongs in `source`. This text is indexed, so a real mechanism also carries concrete nouns a future query can match. NOTE: constraints render without rationale (plur-ai/plur#1144), so a mechanism a prohibition needs the model to weigh must stay in the statement.' },
           source: { type: "string", description: "Origin of this knowledge (URL, conversation ref, etc.)" },
           pinned: { type: "boolean", description: "Always-load flag. If true, this engram bypasses the keyword-relevance gate at injection time. Use sparingly: meta-rules, safety conventions, core operating principles only." },
-          commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked", "draft"], description: "How firmly the user has committed to this belief (default: leaning). `draft` marks the engram as pending human approval \u2014 core stores and recalls it normally; enforcement is left to deployments with a review queue." },
+          commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked", "draft"], description: "How firmly the user has committed to this belief (default: leaning). `draft` marks the engram as pending human approval: core stores and RECALLS it normally but NEVER injects it (#1141), so an unapproved rule cannot shape agent behaviour. Retrieval stays open because reviewing something requires reading it." },
           locked_reason: { type: "string", description: "Why this engram is locked (only meaningful when commitment=locked)" },
           valid_from: { type: "string", description: "ISO date (YYYY-MM-DD) the knowledge becomes valid \u2014 inject/recall skip the engram before this date (#347)" },
           valid_until: { type: "string", description: 'ISO date (YYYY-MM-DD) the knowledge expires \u2014 inject/recall skip the engram after this date. Set this for any time-bound fact (offers, deadlines, temporary endpoints). When omitted, an explicit expiry phrase in the statement ("valid until 31 May 2026") is auto-parsed and echoed back (#347)' },
@@ -539,7 +570,7 @@ function getAllToolDefinitions() {
           session_id: { type: "string", description: "Session this write belongs to (from plur_session_start). Resolves the session default scope (incl. mid-session plur_session_scope changes) when no explicit scope is passed. Optional when one session is open; pass it when several are (#243)." },
           measured_under: {
             type: "object",
-            description: "Measurement context for numeric or benchmark-derived claims (#869). Records the conditions under which the asserted value was measured \u2014 model, source_type, hardware, dataset, date. When present, differing-condition measurements are stored as refinements rather than tensions. Omit for non-numeric engrams.",
+            description: "Measurement context for numeric or benchmark-derived claims (#869). Records the conditions under which the asserted value was measured \u2014 model, source_type, hardware, dataset, date. When present, the tension scanner does not treat two measurements from the same store taken under different configurations as a contradiction (the skipped pair is reported in the scan result). Omit for non-numeric engrams.",
             properties: {
               model: { type: "string", description: 'Model or system variant (e.g. "claude-opus-4", "gpt-4o")' },
               source_type: { type: "string", description: 'Source environment type (e.g. "local-git", "gitlab", "bench", "production")' },
@@ -547,6 +578,59 @@ function getAllToolDefinitions() {
               dataset: { type: "string", description: 'Dataset or workload identifier (e.g. "LongMemEval-S", "plur-bench-2026-Q2")' },
               date: { type: "string", description: "ISO date (YYYY-MM-DD) the measurement was taken" }
             }
+          },
+          attribution: {
+            type: "object",
+            description: 'Who is answerable for this memory (#961). Every sub-field optional; OMIT rather than guess \u2014 a memory with no agent is honest, one with an invented agent is worse than none. Set asserted_by to "unidentified" when nobody is identified, rather than leaving it out: absence cannot be told apart from a memory written before this existed.',
+            properties: {
+              asserted_by: { type: "string", description: 'Who or what asserted it. Any address: a local name, a Decentralized Identifier, or "unidentified".' },
+              runtime: {
+                type: "object",
+                description: "The software writing this. Usually known, so usually worth setting.",
+                properties: { name: { type: "string" }, version: { type: "string" } }
+              },
+              model: {
+                type: "object",
+                description: "The model behind the statement, if one was involved. Prompt TEXT is never stored, only a hash.",
+                properties: {
+                  name: { type: "string" },
+                  prompt_id: { type: "string" },
+                  prompt_version: { type: "string" },
+                  prompt_sha256: { type: "string" }
+                }
+              },
+              tool: {
+                type: "object",
+                description: "An extractor or importer, with its version.",
+                properties: { name: { type: "string" }, version: { type: "string" } }
+              },
+              on_behalf_of: { type: "string", description: "The party the runtime acted for." }
+            }
+          },
+          claim_class: {
+            type: "string",
+            enum: ["observed", "documented", "structural", "asserted", "inferred", "revised"],
+            description: 'What KIND of claim this is (#963), and the most useful single field for anyone later deciding how much to trust it. Use "asserted" when a PERSON stated it outright, "inferred" when YOU worked it out, "documented" when you took it from prose someone wrote, "observed" for a record of something that happened, "structural" when read off the shape of an artifact, "revised" for a rewrite. Omit only when it genuinely cannot be determined.'
+          },
+          license: {
+            type: "string",
+            description: 'Which licence governs reuse of this memory, as an SPDX-style identifier such as "cc-by-4.0" or "apache-2.0". Set it only when the user has actually said which licence applies \u2014 do NOT guess one. Left unset, a default applies that nobody chose, and a provenance record reports it as unchosen rather than presenting it as a decision.'
+          },
+          // Deliberately exposed to the LLM, reversing #139, which kept
+          // `visibility` off this schema because `public` is what gates pack
+          // export and shared git sync. Without it an agent cannot mark
+          // anything shareable, so every pack built from agent-written
+          // memories was empty (#970) — the walkthrough and the agent
+          // conversation demo both depend on it. The reason #139 was cautious
+          // still holds, and is answered elsewhere: every path `public` opens
+          // (pack export, shared sync, remote push, rescope, explicit update,
+          // outbox flush) scans the FULL engram — statement plus every other
+          // field, `attribution` and `license` included — before content
+          // leaves the machine. See `engramContentFields` in core.
+          visibility: {
+            type: "string",
+            enum: ["private", "public", "template"],
+            description: 'Whether this memory may leave this machine. Defaults to "private", which means it is EXCLUDED from every exported pack. Set "public" only when the user has said this is shareable with others \u2014 it is their decision, not yours. Without this an agent cannot mark anything shareable at all, so every memory it writes is private forever and any pack built from them is empty.'
           }
         },
         required: ["statement"]
@@ -556,17 +640,34 @@ function getAllToolDefinitions() {
         const context = {
           type: args.type,
           scope: args.scope,
-          domain: args.domain,
+          // .plur.yaml `domain:` as the default (#1148). The key was parsed by
+          // project-config and consumed nowhere, so setting it was a silent
+          // no-op — the same shape as injection.pinned_ratio before #1142.
+          // Domain is not decorative: scoreEngram counts every matching
+          // hierarchy segment as a FULL term hit, double the weight of a
+          // statement word, so a missing domain forfeits the strongest
+          // retrieval signal an author has. Explicit argument always wins.
+          domain: args.domain ?? readProjectConfig().domain ?? void 0,
           source: args.source,
           tags: args.tags,
           rationale: args.rationale,
           commitment: args.commitment,
           locked_reason: args.locked_reason,
+          // Quota-gated below, before the write — `plur_pin` was the only
+          // guarded entry point, and writing a NEW pinned engram is the other
+          // normal way to create a pin (#1138 review).
           pinned: args.pinned,
           valid_from: args.valid_from,
           valid_until: args.valid_until,
           supersedes: args.supersedes,
           measured_under: args.measured_under,
+          // Who is answerable, and what kind of claim this is (#961, #963).
+          // Passed through untouched: we never invent an agent, and we never
+          // guess a claim class the caller did not state.
+          attribution: args.attribution,
+          claim_class: args.claim_class,
+          license: args.license,
+          visibility: args.visibility,
           // #243: resolve which session's default scope governs this write —
           // explicit session_id first, else the lone open session. Never
           // persisted on the engram (LearnContext.session selects a scope, it
@@ -608,6 +709,20 @@ function getAllToolDefinitions() {
           };
         };
         const statement = sanitizeStatement(args.statement);
+        if (context.pinned === true) {
+          const q = await plur.pinnedQuota();
+          if (q.free <= 0) {
+            return {
+              success: false,
+              error: "pinned_quota_exceeded",
+              quota: q.quota,
+              used: q.used,
+              free: q.free,
+              pinned_count: q.count,
+              note: "The pinned set has no room left, so this engram cannot be pinned \u2014 a pin that does not fit is dropped at injection time, which is the silent failure the quota exists to prevent. Learn it unpinned (drop `pinned`), or unpin something first with plur_pin {list:true} to see the set and its costs, or raise `injection_budget` / `injection.pinned_ratio` in ~/.plur/config.yaml. The statement was NOT stored \u2014 re-send it once you have decided."
+            };
+          }
+        }
         try {
           const engram = await plur.learnRouted(statement, context);
           const isOutbox = !!engram.structured_data?._outbox;
@@ -616,6 +731,20 @@ function getAllToolDefinitions() {
           mcpCanary.signal("learn_activity");
           recordTelemetry("learn");
           const dedup = isOutbox ? void 0 : await plur.nearDuplicates(statement, context, engram.id);
+          const redraft = (() => {
+            const ids = args.supersedes;
+            if (!ids?.length) return void 0;
+            const today = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+            const sameDay = ids.filter((id) => {
+              const m = /(\d{4})-(\d{2})-?(\d{2})/.exec(id);
+              return m ? `${m[1]}-${m[2]}-${m[3]}` === today : false;
+            });
+            if (!sameDay.length) return void 0;
+            return {
+              superseded_today: sameDay,
+              note: "You are replacing an engram minted today \u2014 that is a redraft, not a correction, and it leaves a chain of near-identical records behind. Think the assertion through once and write it once. If the earlier one was simply wrong, retire it with plur_forget instead of stacking another supersede."
+            };
+          })();
           return {
             // #914: report the id in the form plur_recall hands back, so a
             // caller that records what it just learned and passes it to
@@ -632,6 +761,11 @@ function getAllToolDefinitions() {
             content_hash: engram.content_hash,
             decision: "ADD",
             ...dedup?.near_duplicates?.length ? { dedup } : {},
+            ...redraft ? { redraft } : {},
+            ...(() => {
+              const c = composeHints(statement, context?.rationale, context?.source);
+              return c ? { composition: c } : {};
+            })(),
             ...temporalEcho(engram),
             ...scopeHint(engram.scope, !!routed),
             ...domainHint(!!routed),
@@ -646,7 +780,11 @@ function getAllToolDefinitions() {
           mcpCanary.signal("learn_activity");
           recordTelemetry("learn");
           return {
-            id: engram.id,
+            // Mirror the happy-path fix (#914): report the namespaced form so a
+            // caller holding this id can pass it to plur_forget / plur_feedback
+            // without hitting the collision the id form mismatch causes.
+            // Outbox engrams stay local-form (same rule as line 1149).
+            id: isOutbox ? engram.id : plur.readIdFor(engram),
             statement: engram.statement,
             scope: engram.scope,
             type: engram.type,
@@ -673,7 +811,7 @@ function getAllToolDefinitions() {
             items: {
               type: "object",
               properties: {
-                statement: { type: "string", description: "The knowledge assertion to store" },
+                statement: { type: "string", description: 'ONE assertion, written so someone who was not there can act on it. Route the rest to the field whose job it is: the mechanism that makes it true goes in `rationale`, where it came from in `source`, when it applies in `tags`/`domain`. An "and also" means a second engram. Good: "Never name a client unless the user names them first, say the customer." Typical 100-300 chars; past ~600 you are carrying another field content. Length is a symptom, not the rule.' },
                 type: { type: "string", enum: ["behavioral", "terminological", "procedural", "architectural"], description: "Category of the engram" },
                 scope: { type: "string", description: "Namespace, e.g. global, project:myapp" },
                 domain: { type: "string", description: "Domain tag, e.g. software.deployment" },
@@ -681,7 +819,7 @@ function getAllToolDefinitions() {
                 rationale: { type: "string", description: "Why this knowledge matters \u2014 also enters the search corpus" },
                 source: { type: "string", description: "Origin of this knowledge (URL, conversation ref, etc.)" },
                 pinned: { type: "boolean", description: "Always-load flag. Use sparingly: meta-rules, safety conventions, core principles." },
-                commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked", "draft"], description: "How firmly the user has committed (default: leaning). `draft` marks the engram as pending human approval \u2014 core stores and recalls it normally; enforcement is left to deployments with a review queue." },
+                commitment: { type: "string", enum: ["exploring", "leaning", "decided", "locked", "draft"], description: "How firmly the user has committed (default: leaning). `draft` marks the engram as pending human approval: core stores and RECALLS it normally but NEVER injects it (#1141), so an unapproved rule cannot shape agent behaviour. Retrieval stays open because reviewing something requires reading it." },
                 valid_from: { type: "string", description: "ISO date (YYYY-MM-DD) the knowledge becomes valid" },
                 valid_until: { type: "string", description: "ISO date (YYYY-MM-DD) the knowledge expires" },
                 measured_under: {
@@ -735,7 +873,10 @@ function getAllToolDefinitions() {
         recordTelemetry("learn");
         const ids = raw.map(() => null);
         for (const r of results) {
-          if (r.input_index !== void 0) ids[r.input_index] = r.engram.id;
+          if (r.input_index !== void 0) {
+            const isOutbox = !!r.engram.structured_data?._outbox;
+            ids[r.input_index] = isOutbox ? r.engram.id : plur.readIdFor(r.engram);
+          }
         }
         let batchDomainHint = {};
         const routedInputs = /* @__PURE__ */ new Set();
@@ -755,19 +896,22 @@ function getAllToolDefinitions() {
         }
         return {
           ids,
-          results: results.map((r) => ({
-            input_index: r.input_index,
-            id: r.engram.id,
-            statement: r.engram.statement,
-            scope: r.engram.scope,
-            type: r.engram.type,
-            decision: r.decision,
-            ...r.existing_id ? { existing_id: r.existing_id } : {},
-            // #856 audit: `dedup` was computed and then dropped here, so the
-            // reporting it exists for reached no caller — "anything below the
-            // bar is still reported" was not observable anywhere.
-            ...r.dedup ? { dedup: r.dedup } : {}
-          })),
+          results: results.map((r) => {
+            const isOutbox = !!r.engram.structured_data?._outbox;
+            return {
+              input_index: r.input_index,
+              id: isOutbox ? r.engram.id : plur.readIdFor(r.engram),
+              statement: r.engram.statement,
+              scope: r.engram.scope,
+              type: r.engram.type,
+              decision: r.decision,
+              ...r.existing_id ? { existing_id: r.existing_id } : {},
+              // #856 audit: `dedup` was computed and then dropped here, so the
+              // reporting it exists for reached no caller — "anything below the
+              // bar is still reported" was not observable anywhere.
+              ...r.dedup ? { dedup: r.dedup } : {}
+            };
+          }),
           stats,
           ...batchDomainHint,
           ...failures.length > 0 ? { failures, warning: `${failures.length} of ${raw.length} engram(s) failed to persist; the rest were written.` } : {}
@@ -857,7 +1001,11 @@ function getAllToolDefinitions() {
           tokens_used: result.tokens_used,
           injected_ids: result.injected_ids,
           // #181: unresolved-tension warnings — flag contradicted context
-          ...result.warnings ? { warnings: result.warnings } : {}
+          ...result.warnings ? { warnings: result.warnings } : {},
+          // #1142: pinned engrams that did not fit. `pinned: true` reads as a
+          // promise; it is priority-subject-to-capacity, and a caller must be
+          // able to see what it did not get.
+          ...result.omitted_pinned?.length ? { omitted_pinned: result.omitted_pinned } : {}
         };
       }
     },
@@ -892,7 +1040,11 @@ function getAllToolDefinitions() {
           injected_ids: result.injected_ids,
           mode: "hybrid",
           // #181: unresolved-tension warnings — flag contradicted context
-          ...result.warnings ? { warnings: result.warnings } : {}
+          ...result.warnings ? { warnings: result.warnings } : {},
+          // #1142: pinned engrams that did not fit. `pinned: true` reads as a
+          // promise; it is priority-subject-to-capacity, and a caller must be
+          // able to see what it did not get.
+          ...result.omitted_pinned?.length ? { omitted_pinned: result.omitted_pinned } : {}
         };
         attachRemoteStoreDegradation(response, plur);
         return response;
@@ -958,7 +1110,7 @@ function getAllToolDefinitions() {
     },
     {
       name: "plur_pin",
-      description: "Toggle the always-load (pinned) flag on an engram. Pinned engrams bypass the keyword-relevance gate at injection time and are eligible for loading on every session, regardless of overlap with the user task. Use sparingly \u2014 meta-rules, safety conventions, core operating principles. Pass {id, pinned:true} to pin or {id, pinned:false} to unpin. List current pinned with {list:true}.",
+      description: `Toggle the always-load (pinned) flag on an engram. Pinned engrams bypass the keyword-relevance gate and load on every session regardless of overlap with the task. Use sparingly \u2014 meta-rules, safety conventions, core operating principles; a fact you need only sometimes should be recalled, not pinned. The pinned set has a QUOTA (injection_budget \xD7 injection.pinned_ratio): "always-load" only means anything if the set fits, so a pin that would exceed it is REFUSED with the current usage and unpin suggestions rather than silently dropping something already pinned. Resolve it by unpinning something or raising the limit \u2014 the choice is the user's, so surface it rather than picking one. Pass {id, pinned:true} to pin, {id, pinned:false} to unpin, {list:true} to list the set with its quota usage.`,
       annotations: { title: "Pin", destructiveHint: false, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -971,13 +1123,42 @@ function getAllToolDefinitions() {
       handler: async (args, plur) => {
         if (args.list === true) {
           const pinned = await plur.listPinned();
+          const q = await plur.pinnedQuota();
           return {
             count: pinned.length,
+            quota: { tokens: q.quota, used: q.used, free: q.free, over: q.over },
+            ...q.over ? { warning: `Pinned engrams use ${q.used} tokens against a ${q.quota}-token quota. The overflow is dropped at injection time, so some pinned engrams are NOT being loaded. Unpin some, or raise injection_budget / injection.pinned_ratio.` } : {},
             pinned: pinned.map((e) => ({ id: e.id, statement: e.statement, scope: e.scope, domain: e.domain }))
           };
         }
         if (!args.id) throw new Error("Provide id (or list:true to list pinned)");
         const target = args.pinned ?? true;
+        if (target === true) {
+          const q = await plur.pinnedQuota(args.id);
+          if (q.candidate && !q.candidate.fits) {
+            const deficit = q.candidate.would_be - q.quota;
+            const covering = [];
+            let freed = 0;
+            for (const e of q.entries) {
+              if (freed >= deficit) break;
+              covering.push(e);
+              freed += e.cost;
+            }
+            const suggestions = covering.slice(0, 5).map((e) => ({ id: e.id, frees: e.cost, net_feedback: e.net_feedback, last_accessed: e.last_accessed, statement: e.statement.slice(0, 100) }));
+            return {
+              success: false,
+              error: "pinned_quota_exceeded",
+              quota: q.quota,
+              used: q.used,
+              this_engram_cost: q.candidate.cost,
+              would_be: q.candidate.would_be,
+              over_by: deficit,
+              unpin_candidates: suggestions,
+              unpins_needed: covering.length,
+              note: `Pinned engrams are always-load, so the set cannot exceed its share of the injection budget \u2014 over-committing means silently dropping something already pinned. ` + (covering.length > suggestions.length ? `At least ${covering.length} unpins are needed to fit this one; the ${suggestions.length} largest are listed. ` : `Unpin ${covering.length === 1 ? "the suggestion" : "the suggestions"} below to fit this one. `) + "Or raise `injection_budget` / `injection.pinned_ratio` in ~/.plur/config.yaml. Candidates are ordered by what they free, NOT by importance: feedback covers ~4% of engrams so it cannot rank them, and a ranking that looks authoritative would put a thumb on a decision only the user can make."
+            };
+          }
+        }
         const updated = await plur.setPinnedAsync(args.id, target);
         if (!updated) throw new Error(`Engram not found: ${args.id}`);
         return {
@@ -996,6 +1177,10 @@ function getAllToolDefinitions() {
         properties: {
           id: { type: "string", description: "Exact engram ID to retire" },
           search: { type: "string", description: "Search term to find engram to retire" },
+          reason: {
+            type: "string",
+            description: "Why this is being retired. Recorded in the history log and on the engram (#959). Say what changed, not just that something did."
+          },
           scope: { type: "string", description: 'Which store holds it (#831). Ids are minted per store, so one id can name several unrelated engrams. Pass "primary" to stay on disk \u2014 the local primary store and any local secondary stores, never a remote \u2014 or a remote scope (e.g. "group:plur/plur-ai/engineering") to target that server. A scope matching no configured store is rejected, not guessed at. Omit it and an id resolving in two places is refused.' }
         }
       },
@@ -1005,17 +1190,17 @@ function getAllToolDefinitions() {
           const engram = scope ? void 0 : await plur.getById(args.id);
           if (engram) {
             if (engram.status === "retired") return { success: false, error: `Already retired: ${args.id}` };
-            await plur.forget(args.id, void 0, { force: true });
+            await plur.forget(args.id, args.reason, { force: true });
             return { success: true, retired: { id: engram.id, statement: engram.statement } };
           }
-          await plur.forget(args.id, void 0, { force: true, ...scope ? { scope } : {} });
+          await plur.forget(args.id, args.reason, { force: true, ...scope ? { scope } : {} });
           return { success: true, retired: { id: args.id, ...scope ? { scope } : {} } };
         }
         if (args.search) {
           const matches = await plur.recall(args.search, { limit: 100, remote: false });
           if (matches.length === 0) return { success: false, error: `No active engrams matching "${args.search}"` };
           if (matches.length === 1) {
-            await plur.forget(matches[0].id, void 0, { force: true });
+            await plur.forget(matches[0].id, args.reason, { force: true });
             return { success: true, retired: { id: matches[0].id, statement: matches[0].statement } };
           }
           return {
@@ -1162,6 +1347,20 @@ function getAllToolDefinitions() {
           conflicts: result.conflicts,
           security: result.security,
           registry: result.registry,
+          // ENGRAM-STANDARD-v1 §5.6.5: what was neutralized, by field, and the
+          // integrity verdict with "shipped none" distinct from "matched". Both
+          // were computed and then dropped at this surface, so an agent
+          // installing a pack could not tell the user either.
+          neutralized: result.neutralized,
+          integrity_check: result.integrity_check,
+          // The four provenance counts §5.6.5 requires a consumer to report:
+          // records found against engrams shipped, how many were unreadable,
+          // how many name an engram the pack does not contain, and how many
+          // engrams have no record. Computed by the preview install already
+          // runs, and dropped at this surface until now — so an agent
+          // installing a pack could not tell the user any of it. Absent when
+          // the pack shipped no provenance directory at all.
+          provenance: result.provenance,
           success: true
         };
       }
@@ -1518,6 +1717,8 @@ function getAllToolDefinitions() {
           // Core reports these; this hand-built response dropped them, so an
           // agent asking for status saw a healthy-looking `pack_count: 0`.
           ...status.store_errors ? { store_errors: status.store_errors } : {},
+          // Spreading-activation drop counters — absent when both are zero.
+          ...status.spread_drops ? { spread_drops: status.spread_drops } : {},
           // Version check (issue #151)
           ...versionCheck?.updateAvailable && versionCheck.latest ? {
             update_available: {
@@ -1530,9 +1731,99 @@ function getAllToolDefinitions() {
         };
       }
     },
+    {
+      name: "plur_provenance",
+      description: 'Where a memory came from: who asserted it, whether a person stated it or a model worked it out, when, what it came from, and whether you may reuse it. Read-only. Accepts an engram id or a search term \u2014 nobody remembers ids. IMPORTANT when relaying to the user: report the `not_recorded` list as prominently as the rest. A memory written before provenance was captured genuinely cannot say who asserted it, and presenting the record as complete would make it look more authoritative than it is. Nothing here is guessed. Prefer relaying `summary`; ask for format "record" only when a machine-readable document is actually needed. NOT plur_receipt: this describes the origin of ONE memory; plur_receipt counts how the whole store is being used.',
+      annotations: { title: "Where a memory came from", readOnlyHint: true, idempotentHint: true },
+      inputSchema: {
+        type: "object",
+        properties: {
+          id: { type: "string", description: "Exact engram id, e.g. ENG-2026-08-21-086" },
+          search: { type: "string", description: "Find the engram by what it says, if you do not know its id" },
+          format: {
+            type: "string",
+            enum: ["summary", "record"],
+            description: "summary (default) is prose a person can read. record is the JSON-LD document, for machines."
+          }
+          // No `save` here. This tool is annotated read-only and idempotent,
+          // and a host may run it without asking on that basis; a flag that
+          // writes files would make the annotation a lie. Writing a record is
+          // `plur provenance --write` on the command line, or
+          // `plur.writeProvenance()`.
+        }
+      },
+      handler: async (args, plur) => {
+        let id = args.id;
+        let matchedStatement;
+        let matchCount = 0;
+        const ellipsise = (t, n) => {
+          const chars = Array.from(t);
+          return chars.length > n ? `${chars.slice(0, n).join("")}\u2026` : t;
+        };
+        let alternatives = [];
+        if (!id && typeof args.search === "string" && args.search.length) {
+          const LIST = 3;
+          const matches = await plur.recall(args.search, { limit: 25, remote: false });
+          if (!matches.length) {
+            return {
+              found: false,
+              message: `Nothing matched "${args.search}". Try different words, or pass an exact id.`
+            };
+          }
+          id = matches[0].id;
+          matchedStatement = matches[0].statement;
+          matchCount = matches.length;
+          alternatives = matches.slice(1, LIST).map((m) => ({ id: m.id, statement: ellipsise(m.statement, 80) }));
+        }
+        if (!id) {
+          return { found: false, message: "Pass either an engram id or a search term." };
+        }
+        const record = await plur.provenanceFor(id, { mode: "portable" });
+        if (!record) {
+          return { found: false, message: `No engram with id ${id}.` };
+        }
+        if (args.format !== void 0 && args.format !== "summary" && args.format !== "record") {
+          return {
+            found: false,
+            message: `Unknown format "${String(args.format)}". Use "summary" for prose or "record" for the JSON-LD document.`
+          };
+        }
+        const summary = summariseProvenance(record);
+        if (args.format === "record") {
+          return {
+            found: true,
+            engram_id: id,
+            record,
+            // The same answers the summary gives. Asking for the document used
+            // to mean losing every reuse verdict, so the same question got an
+            // answer through one surface and silence through the other.
+            ...summary.fields,
+            not_recorded: summary.missing,
+            complete: summary.complete
+          };
+        }
+        return {
+          found: true,
+          engram_id: id,
+          ...matchedStatement ? { matched: matchedStatement.slice(0, 200) } : {},
+          summary: renderProvenanceSummary(summary),
+          // Structured values, NOT a line-split of the prose above. `facts`
+          // used to be exactly that: the same text a second time, which an
+          // agent pays for twice and cannot parse either copy of.
+          ...summary.fields,
+          not_recorded: summary.missing,
+          complete: summary.complete,
+          ...matchCount > 1 ? {
+            note: `${matchCount} engrams matched "${String(args.search)}"; this is the closest.` + (matchCount - 1 > alternatives.length ? ` Showing ${alternatives.length} of the other ${matchCount - 1}.` : ""),
+            match_count: matchCount,
+            other_matches: alternatives
+          } : {}
+        };
+      }
+    },
     {
       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.',
+      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. NOT plur_provenance: this counts usage across the whole store; plur_provenance says where a single memory came from.',
       annotations: { title: "Memory receipt", readOnlyHint: true, idempotentHint: true },
       inputSchema: {
         type: "object",
@@ -1822,6 +2113,7 @@ function getAllToolDefinitions() {
         const explicit_default_scope = args.default_scope ?? null;
         const default_scope = explicit_default_scope ?? projectConfig.scope ?? null;
         const scope_source = explicit_default_scope ? "caller" : projectConfig.scope ? "project-config" : "none";
+        const default_domain = projectConfig.domain ?? null;
         plur.setSessionScope(default_scope);
         plur.setSessionScope(default_scope, { session: session_id });
         {
@@ -1853,9 +2145,15 @@ function getAllToolDefinitions() {
           _recordInjectionTelemetry(session_id, result.injected_packs);
           if (result.count > 0) {
             const lines = [];
-            if (result.directives) lines.push("## DIRECTIVES\n", result.directives);
-            if (result.constraints) lines.push("\n## CONSTRAINTS\n", result.constraints);
+            if (result.constraints) lines.push("## CONSTRAINTS\n", result.constraints);
+            if (result.directives) lines.push("\n## DIRECTIVES\n", result.directives);
             if (result.consider) lines.push("\n## ALSO CONSIDER\n", result.consider);
+            if (result.omitted_pinned?.length) {
+              lines.push(
+                "\n## PINNED, NOT LOADED\n",
+                `${result.omitted_pinned.length} pinned engram(s) did not fit this injection: ${result.omitted_pinned.map((o) => o.id).join(", ")}. Treat them as unread, not as absent \u2014 recall one explicitly if the task touches it.`
+              );
+            }
             engrams = { text: lines.join("\n"), count: result.count, injected_ids: result.injected_ids };
           }
         } catch {
@@ -1867,9 +2165,15 @@ function getAllToolDefinitions() {
           _recordInjectionTelemetry(session_id, result.injected_packs);
           if (result.count > 0) {
             const lines = [];
-            if (result.directives) lines.push("## DIRECTIVES\n", result.directives);
-            if (result.constraints) lines.push("\n## CONSTRAINTS\n", result.constraints);
+            if (result.constraints) lines.push("## CONSTRAINTS\n", result.constraints);
+            if (result.directives) lines.push("\n## DIRECTIVES\n", result.directives);
             if (result.consider) lines.push("\n## ALSO CONSIDER\n", result.consider);
+            if (result.omitted_pinned?.length) {
+              lines.push(
+                "\n## PINNED, NOT LOADED\n",
+                `${result.omitted_pinned.length} pinned engram(s) did not fit this injection: ${result.omitted_pinned.map((o) => o.id).join(", ")}. Treat them as unread, not as absent \u2014 recall one explicitly if the task touches it.`
+              );
+            }
             engrams = { text: lines.join("\n"), count: result.count, injected_ids: result.injected_ids };
           }
         }
@@ -1972,6 +2276,7 @@ Tool profile "${session_tool_profile}": most plur_* tools are not exposed by nam
           // Remote scope routing info (#229)
           ...remote_scopes.length > 0 ? { remote_scopes } : {},
           ...default_scope ? { default_scope, scope_source } : {},
+          ...default_domain ? { default_domain, domain_source: "project-config" } : {},
           // Ask LLM to check back — MCP can't push, but we can request a follow-up
           follow_up: store_stats.engram_count === 0 ? "This is a fresh store with 0 engrams. After your first exchange with the user, review what you learned and call plur_learn for any corrections, preferences, or patterns. Build the memory from this session." : void 0,
           // On fresh install, suggest hook setup for reliable injection
@@ -2128,7 +2433,7 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         const summary = args.summary;
         const session_id = args.session_id;
         const suggestions = args.engram_suggestions;
-        let engrams_created = 0;
+        const items = [];
         if (Array.isArray(suggestions) && suggestions.length) {
           for (let i = 0; i < suggestions.length; i++) {
             const s = suggestions[i];
@@ -2145,14 +2450,31 @@ 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}`
               );
             }
-            await plur.learn(statement, { type });
-            engrams_created++;
+            items.push({ statement, type });
           }
         }
         const episode = plur.capture(summary, {
           session_id,
           channel: "mcp"
         });
+        let engrams_created = 0;
+        const engrams_failed = [];
+        for (let i = 0; i < items.length; i++) {
+          const { statement, type } = items[i];
+          try {
+            await plur.learn(statement, {
+              type,
+              // Link the engram back to the session that produced it (#960).
+              session_episode_id: episode.id,
+              // An end-of-session summary is the model's reading of what
+              // happened, not something the user stated outright (#963).
+              claim_class: "inferred"
+            });
+            engrams_created++;
+          } catch (err) {
+            engrams_failed.push({ index: i, statement: statement.slice(0, 80), error: err.message });
+          }
+        }
         const telemetry = session_id ? _sessionTelemetry.get(session_id) : void 0;
         const injection_summary = telemetry && telemetry.injection_calls > 0 ? {
           pack_counts: { ...telemetry.pack_counts },
@@ -2179,10 +2501,11 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         const status = await plur.status();
         return {
           engrams_created,
+          ...engrams_failed.length ? { engrams_failed } : {},
           episode_id: episode.id,
           total_engrams: status.engram_count,
           ...injection_summary ? { injection_summary } : {},
-          hint: engrams_created === 0 ? "No engrams captured this session. If any corrections, preferences, or patterns came up, consider calling plur_learn before ending." : void 0
+          hint: engrams_failed.length ? `${engrams_failed.length} suggestion(s) could not be stored \u2014 see engrams_failed. The rest were.` : engrams_created === 0 ? "No engrams captured this session. If any corrections, preferences, or patterns came up, consider calling plur_learn before ending." : void 0
         };
       }
     },
@@ -2459,12 +2782,15 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
             batch_size: args.batch_size,
             temporal_domains: tensionsConfig.temporal_domains,
             snapshot_pairs: tensionsConfig.snapshot_pairs,
+            measured_under_pairs: tensionsConfig.measured_under_pairs,
             temporal_discount: args.temporal_discount ?? tensionsConfig.temporal_discount,
             ...persist ? { exclude_pairs: new Set(plur.suppressedTensionPairKeys()) } : {}
           });
           const persisted = persist && result.tensions.length > 0 ? await plur.recordTensions(result.tensions) : void 0;
           return {
             pairs_checked: result.pairs_checked,
+            // #869 review: policy skips are reported, never silent.
+            skipped: result.skipped,
             count: result.new_tensions,
             ...persisted ? { persisted_new: persisted.new_count } : {},
             tensions: result.tensions.map((t, i) => ({
@@ -2642,7 +2968,11 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
           filter_tags: { type: "array", items: { type: "string" }, description: "Filter by tags" },
           filter_type: { type: "string", enum: ["behavioral", "procedural", "architectural", "terminological"], description: "Filter by engram type" },
           output_dir: { type: "string", description: "Output directory (default: ~/plur-packs/<name>)" },
-          creator: { type: "string", description: "Creator name" }
+          creator: { type: "string", description: "Creator name" },
+          license: {
+            type: "string",
+            description: 'Licence for the pack as a collection, e.g. "cc-by-4.0", "apache-2.0", "cc0-1.0", or "unlicensed" to grant nothing. REQUIRED unless the user has set provenance.default_license in their config \u2014 export fails without one. Ask the user which licence applies; do NOT guess. A pack goes to strangers, and leaving this blank does not leave it blank: a share-alike default fills in that nobody agreed to.'
+          }
         },
         required: ["name"]
       },
@@ -2665,12 +2995,27 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
         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",
-          description: args.description,
-          creator: args.creator || void 0
-        });
+        let result;
+        try {
+          result = plur.exportPack(engrams, outputDir, {
+            name,
+            version: "1.0.0",
+            description: args.description,
+            creator: args.creator || void 0,
+            license: args.license || void 0
+          });
+        } catch (err) {
+          const message = err.message;
+          if (/needs a licence/.test(message)) {
+            return {
+              exported: false,
+              error: "This pack has no licence, and export will not choose one.",
+              next_step: 'Ask the user which licence applies to this pack (for example cc-by-4.0, apache-2.0, cc0-1.0, or "unlicensed" to grant nothing) and call plur_packs_export again with `license` set. The user can also set provenance.default_license in their config to answer once.',
+              name
+            };
+          }
+          throw err;
+        }
         return {
           path: result.path,
           engram_count: result.engram_count,
@@ -2752,7 +3097,6 @@ Include at least one engram_suggestion if ANYTHING was learned. An empty suggest
 
 export {
   registerFlushOnExit,
-  VERSION,
   validateToolArgs,
   mcpCanary,
   CURSOR_CORE_TOOL_NAMES,

package/dist/index.js

@@ -1,11 +1,13 @@
 #!/usr/bin/env node
+import {
+  VERSION
+} from "./chunk-445S5QNU.js";
 
 // src/index.ts
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from "fs";
 import { join } from "path";
 import { fileURLToPath } from "url";
 import { homedir, platform } from "os";
-var VERSION = "0.19.4";
 var HELP = `plur-mcp v${VERSION} \u2014 persistent memory for AI agents
 
 Usage:
@@ -295,7 +297,7 @@ async function runInit() {
 async function runPacks() {
   const plurPath = process.env.PLUR_PATH ?? join(homedir(), ".plur");
   const { Plur } = await import("@plur-ai/core");
-  const { packsCommand } = await import("./packs-cli-YQTKUTWY.js");
+  const { packsCommand } = await import("./packs-cli-XXZTSBHW.js");
   const plur = new Plur({ path: plurPath });
   const result = await packsCommand(process.argv.slice(3), plur);
   if (result.stdout) process.stdout.write(result.stdout);
@@ -321,7 +323,7 @@ if (arg === "packs") {
   process.exit(0);
 }
 if (arg === "serve" || arg === void 0) {
-  const { runStdio } = await import("./server-IJLE4NG4.js");
+  const { runStdio } = await import("./server-LODRVEQB.js");
   runStdio().catch((err) => {
     console.error("Failed to start PLUR MCP server:", err);
     process.exit(1);

package/dist/{packs-cli-YQTKUTWY.js → packs-cli-XXZTSBHW.js}

@@ -7,8 +7,14 @@ async function packsCommand(args, plur) {
     if (!arg) return fail("Usage: plur-mcp packs install <path>\n");
     try {
       const result = await plur.installPack(arg);
-      return ok(`Installed pack '${result.name}' (${result.installed} engrams)
-`);
+      let out = `Installed pack '${result.name}' (${result.installed} engrams)
+`;
+      const n = result.neutralized;
+      if (n?.pinned_stripped) out += `  neutralized: pinned removed from ${n.pinned_stripped} engram(s)
+`;
+      if (n?.locked_downgraded) out += `  neutralized: commitment: locked downgraded to decided on ${n.locked_downgraded} engram(s)
+`;
+      return ok(out);
     } catch (err) {
       return fail(`Error: ${err.message}
 `);

package/dist/{server-IJLE4NG4.js → server-LODRVEQB.js}

@@ -1,13 +1,15 @@
 import {
   CURSOR_CORE_TOOL_NAMES,
-  VERSION,
   getToolDefinitions,
   mcpCanary,
   registerFlushOnExit,
   resolveToolProfile,
   setActiveToolProfile,
   validateToolArgs
-} from "./chunk-6HBPG6IR.js";
+} from "./chunk-SWQDW42Z.js";
+import {
+  VERSION
+} from "./chunk-445S5QNU.js";
 
 // src/server.ts
 import { Server, ProtocolError, ProtocolErrorCode } from "@modelcontextprotocol/server";

package/dist/tools-export.js

@@ -2,7 +2,8 @@ import {
   CURSOR_CORE_TOOL_NAMES,
   getToolDefinitions,
   validateToolArgs
-} from "./chunk-6HBPG6IR.js";
+} from "./chunk-SWQDW42Z.js";
+import "./chunk-445S5QNU.js";
 
 // src/tools-export.ts
 function getToolSchemas(profile) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plur-ai/mcp",
   "mcpName": "io.github.plur-ai/plur",
-  "version": "0.19.4",
+  "version": "0.20.1",
   "type": "module",
   "bin": {
     "plur-mcp": "dist/index.js"
@@ -16,7 +16,7 @@
     "@modelcontextprotocol/client": "2.0.0-beta.4",
     "@modelcontextprotocol/core": "2.0.0-beta.4",
     "zod": "^3.23.0",
-    "@plur-ai/core": "0.19.4"
+    "@plur-ai/core": "0.20.1"
   },
   "devDependencies": {
     "@types/node": "^25.5.0"
@@ -51,6 +51,7 @@
   },
   "scripts": {
     "build": "tsup",
-    "test": "vitest run"
+    "test": "vitest run",
+    "pretest": "npm run build"
   }
 }

package/packs/effective-memory/SKILL.md

@@ -11,11 +11,14 @@ x-datacore:
   match_terms: [memory, learn, remember, session, feedback, engram, forget, correction, preference, recall, verification, safety, plur]
   domain: plur.best-practices
   engram_count: 12
-  # Note: every engram in this pack carries `pinned: true` at the engram
-  # level, which is the actual "always-inject" mechanism (introduced in
-  # PLUR 0.9.4). Pack-level injection_policy: pinned is not a recognized
-  # value in 0.9.4 — keep it on_match here so loaders that respect it
-  # behave predictably; the per-engram pinned flags do the work.
+  # The engrams below still carry `pinned: true`, but INSTALL STRIPS IT.
+  # `sanitizePackEngrams` removes `pinned` and downgrades `commitment: locked`
+  # from every pack, this one included, because a pack is an archive from a
+  # stranger and its author does not get to decide what is always in front of
+  # the recipient's model. The flags are left in place so the intent is
+  # legible and so the behaviour returns if the host ever grows a way to
+  # grant it deliberately. `injection_policy: on_match` is what actually
+  # governs this pack. See plur-ai/plur#1019.
 ---
 
 # Effective Memory
@@ -24,7 +27,9 @@ Your agent has memory. These habits make it actually useful.
 
 Without them, memory is a growing pile of assertions nobody retrieves. With them, memory compounds — each session builds on the last, corrections stick, and the agent gets measurably better over time.
 
-This pack is **pinned** in PLUR 0.9.4+. Engrams here bypass keyword gating and are always eligible for injection at session start. They cover the meta-rules every agent needs regardless of domain: how to capture corrections, when to recall before answering, what "verified" means, how to stay safe with destructive actions, and why never to type a weekday from memory.
+These engrams cover the meta-rules every agent needs regardless of domain: how to capture corrections, when to recall before answering, what "verified" means, how to stay safe with destructive actions, and why never to type a weekday from memory.
+
+They were written to be **pinned** — always eligible for injection, bypassing keyword gating. That is no longer what happens. Install strips `pinned` from every pack, this one included, so these engrams are matched on keywords like any other (`injection_policy: on_match`, with the `match_terms` above). The stripping is right — a pack author should not be able to occupy a recipient's context unconditionally — but it means this pack's meta-rules only surface when a session's wording happens to touch them.
 
 ## Install
 
@@ -46,9 +51,13 @@ npx @plur-ai/cli@0.9.4 packs install effective-memory
 - **Discipline** — read before edit; don't ask "want to continue?" mid-task.
 - **Time** — never type a day-of-week from memory.
 
-## Why pinned
+## Why these were written pinned, and what happens instead
+
+Pinned engrams bypass the keyword-relevance gate in `scoreEngram` and the per-pack and per-domain caps in `fillTokenBudget`. Cross-cutting meta-rules are the case that justifies it: "call `plur_learn` when corrected" is relevant to every session and keyword-matches almost none of them.
+
+**Install strips the flag**, so that is not the behaviour you get. `sanitizePackEngrams` removes `pinned` and downgrades `commitment: locked` from every installed pack, and it is right to — a pack is an archive from a stranger, and letting its author decide what is permanently in front of your model is a privilege no producer should take by shipping a YAML field.
 
-Pinned engrams (introduced in PLUR 0.9.4) bypass the keyword-relevance gate in `scoreEngram` and per-pack/per-domain caps in `fillTokenBudget`. They are always eligible for injection regardless of how the user's query keywords overlap with the engram statement. Use this for cross-cutting meta-rules only; pinning everything defeats the purpose.
+The consequence is that this pack's rules are keyword-gated, which is a weaker guarantee than they were designed for. Whether a host should be able to grant always-inject to a pack it trusts deliberately — as opposed to a pack claiming it — is an open question, tracked in plur-ai/plur#1019.
 
 ## Versioning