@xultrax-web/agent-memory-mcp 0.11.6 → 0.12.0

package/dist/index.js

@@ -23,7 +23,7 @@
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolRequestSchema, CreateMessageResultSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import Fuse from "fuse.js";
 import matter from "gray-matter";
 import { spawnSync } from "node:child_process";
@@ -615,27 +615,27 @@ export function toolDeleteMemory(args) {
     const fp = memoryFilePath(name);
     if (!existsSync(fp))
         return `Memory "${name}" not found.`;
-    // v0.11.3 · receipt-gated path. If a receipt is supplied, validate it
-    // against the current rule set + required caveats. If validation fails,
-    // refuse the delete with a clear reason. If no receipt is supplied,
-    // proceed (back-compat) but log so audit can surface the gap. v0.12
-    // will require receipts unconditionally for destructive ops.
+    // v0.12.0 · receipt REQUIRED for delete_memory. The v0.11.x back-compat
+    // path (delete without receipt) is removed. Callers MUST first call
+    // check_action({action_type: 'deletions'}) to obtain a fresh receipt,
+    // then pass it to delete_memory as the `receipt` argument.
     const receipt = parseReceiptArg(args.receipt);
-    if (receipt) {
-        const v = validateReceipt(receipt, {
-            required_caveats: [{ type: "action_type", value: "deletions" }],
-        });
-        if (!v.valid) {
-            logEvent("delete_denied", { name, reason: v.reason, receipt_id: receipt.id });
-            throw new Error(`delete_memory refused · receipt invalid (${v.reason}). ` +
-                `Call check_action({action: 'delete memory ${name}', action_type: 'deletions'}) ` +
-                `to get a fresh receipt.`);
-        }
-        logEvent("delete_approved_via_receipt", { name, receipt_id: receipt.id });
-    }
-    else {
-        logEvent("delete_without_receipt", { name });
+    if (!receipt) {
+        logEvent("delete_refused_no_receipt", { name });
+        throw new Error(`delete_memory refused · receipt required (v0.12.0+). ` +
+            `Call check_action({action: 'delete memory ${name}', action_type: 'deletions'}) ` +
+            `first, then pass the issued receipt as the 'receipt' argument to delete_memory.`);
+    }
+    const v = validateReceipt(receipt, {
+        required_caveats: [{ type: "action_type", value: "deletions" }],
+    });
+    if (!v.valid) {
+        logEvent("delete_denied", { name, reason: v.reason, receipt_id: receipt.id });
+        throw new Error(`delete_memory refused · receipt invalid (${v.reason}). ` +
+            `Call check_action({action: 'delete memory ${name}', action_type: 'deletions'}) ` +
+            `to get a fresh receipt.`);
     }
+    logEvent("delete_approved_via_receipt", { name, receipt_id: receipt.id });
     return withLock(() => {
         ensureTrash();
         // Trash filename: <unix-ms>-<name>.md so restore can pick the
@@ -644,12 +644,9 @@ export function toolDeleteMemory(args) {
         const trashPath = join(TRASH_DIR, `${ts}-${name}.md`);
         renameSync(fp, trashPath);
         removeIndexEntryUnlocked(name);
-        logEvent("delete", { name, trash: `${ts}-${name}.md`, gated: !!receipt });
+        logEvent("delete", { name, trash: `${ts}-${name}.md`, gated: true });
         log("debug", "delete_memory", { name });
-        const gateMsg = receipt
-            ? ` (gated by receipt ${receipt.id})`
-            : " (no receipt · v0.11.3 back-compat path)";
-        return `Moved "${name}" to trash${gateMsg}. Restore with: agent-memory restore ${name}`;
+        return `Moved "${name}" to trash (gated by receipt ${receipt.id}). Restore with: agent-memory restore ${name}`;
     });
 }
 function toolRestoreMemory(args) {
@@ -1504,15 +1501,116 @@ export function checkActionAgainstRules(action, actionType) {
     }
     return { hard, soft, rules_evaluated: rules.length };
 }
-function toolCheckAction(args) {
+/**
+ * Tier-2 Sampling enrichment · runs ONE rule's natural-language
+ * applies_when conditions past an LLM via MCP sampling/createMessage.
+ * The server makes the request; the client decides (per MCP spec)
+ * whether to forward to its LLM, prompt the user, or refuse.
+ *
+ * On any error (client lacks sampling, user refused, unparseable
+ * response), returns null — Tier-2 silently degrades to "no extra
+ * violations found" and we ship the Tier-1 result.
+ */
+function clientSupportsSampling() {
+    // server.getClientCapabilities() is undefined before the MCP initialize
+    // handshake; once initialized, returns the capabilities the client
+    // declared. We only call Sampling if `sampling` is in there — saves a
+    // round-trip and prevents test harnesses (which don't respond to
+    // sampling/createMessage) from hanging.
+    try {
+        const caps = server.getClientCapabilities();
+        return !!caps?.sampling;
+    }
+    catch {
+        return false;
+    }
+}
+async function runTier2Sampling(rule, action, actionType) {
+    if (!rule.applies_when || rule.applies_when.length === 0)
+        return null;
+    if (!clientSupportsSampling())
+        return null;
+    const prompt = `You are evaluating whether a proposed action violates an operator rule.\n\n` +
+        `RULE:\n` +
+        `  name: ${rule.name}\n` +
+        `  description: ${rule.description}\n` +
+        `  severity: ${rule.severity ?? "soft"}\n` +
+        `  applies_when:\n` +
+        rule.applies_when.map((s) => `    - ${s}`).join("\n") +
+        `\n\nPROPOSED ACTION:\n` +
+        `  ${action}\n` +
+        `  (category: ${actionType})\n\n` +
+        `Does the proposed action match any of the "applies_when" conditions?\n` +
+        `Respond with strict JSON only, no commentary: {"violates": true|false, "reason": "..."}.\n` +
+        `If the action is ambiguous, answer false.`;
+    try {
+        const result = await server.request({
+            method: "sampling/createMessage",
+            params: {
+                messages: [{ role: "user", content: { type: "text", text: prompt } }],
+                systemPrompt: "You are a strict policy evaluator. Reply with JSON only.",
+                maxTokens: 200,
+                modelPreferences: { intelligencePriority: 0.8, speedPriority: 0.4 },
+            },
+        }, CreateMessageResultSchema);
+        const text = result.content.type === "text" ? result.content.text : "";
+        // Tolerate a stray code-fence around the JSON.
+        const cleaned = text.trim().replace(/^```(?:json)?\s*|\s*```$/g, "");
+        const parsed = JSON.parse(cleaned);
+        if (parsed.violates === true) {
+            return {
+                rule: rule.name,
+                severity: rule.severity ?? "soft",
+                reason: `Sampling judgment: ${parsed.reason ?? "applies_when matched"}`,
+            };
+        }
+        return null;
+    }
+    catch (err) {
+        // Sampling unsupported on this client, user refused, response
+        // unparseable, or any other transport-level failure. Degrade
+        // silently to Tier-1 only · we never block a check_action call
+        // because Tier-2 couldn't run.
+        log("debug", "tier2_sampling_skipped", {
+            rule: rule.name,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return null;
+    }
+}
+async function toolCheckAction(args) {
     const action = String(args.action ?? "").trim();
     const actionType = String(args.action_type ?? "").trim();
     const sessionId = typeof args.session_id === "string" ? args.session_id.trim() : "";
+    // Tier-2 Sampling is opt-out: defaults to true on clients that support
+    // it; gracefully degrades on clients that don't. Set to false to skip
+    // the LLM round-trip entirely (e.g. for batched/script use).
+    const tier2Enabled = args.use_sampling !== false;
     if (!action)
         throw new Error("action is required (the proposed action description)");
     if (!actionType)
         throw new Error("action_type is required (e.g. 'deletions', 'commits', 'file_writes', 'chat_responses')");
     const { hard, soft, rules_evaluated } = checkActionAgainstRules(action, actionType);
+    // Tier-2: run Sampling for any rule with applies_when that DIDN'T
+    // already match deterministically. Rules already flagged in Tier-1
+    // don't need a Sampling round-trip (we know they violate).
+    if (tier2Enabled) {
+        const tier1HitRules = new Set([...hard.map((v) => v.rule), ...soft.map((v) => v.rule)]);
+        const rules = loadAllRules();
+        const tier2Candidates = rules.filter((r) => r.applies_when &&
+            r.applies_when.length > 0 &&
+            !tier1HitRules.has(r.name) &&
+            (!r.enforce_on || r.enforce_on.length === 0 || r.enforce_on.includes(actionType)));
+        for (const rule of tier2Candidates) {
+            const violation = await runTier2Sampling(rule, action, actionType);
+            if (violation) {
+                if (violation.severity === "hard")
+                    hard.push(violation);
+                else
+                    soft.push(violation);
+            }
+        }
+    }
     if (hard.length > 0) {
         const result = {
             approved: false,
@@ -1681,7 +1779,14 @@ function recentDenials() {
     }));
 }
 function recentUnreceiptedDeletes() {
-    const records = readEventLog({ tail: AUDIT_EVENT_TAIL, action: "delete_without_receipt" });
+    // v0.11.x emitted "delete_without_receipt" when an unreceipted delete
+    // succeeded. v0.12.0 emits "delete_refused_no_receipt" when refusing.
+    // We surface BOTH event types so an audit run against pre-v0.12 logs
+    // still reports historical unreceipted deletes correctly.
+    const records = [
+        ...readEventLog({ tail: AUDIT_EVENT_TAIL, action: "delete_without_receipt" }),
+        ...readEventLog({ tail: AUDIT_EVENT_TAIL, action: "delete_refused_no_receipt" }),
+    ];
     return records.map((r) => ({
         ts: String(r.ts),
         name: String(r.name ?? ""),
@@ -2087,7 +2192,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.11.6" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.12.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -2411,18 +2516,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         {
             name: "delete_memory",
             description: "Move a memory to .trash/ (soft delete). The file is removed from the index but recoverable via restore_memory until you manually empty .trash/. " +
-                "v0.11.3+ accepts an optional `receipt` argument · pass a Compliance Receipt from check_action({action_type: 'deletions'}) to gate the delete against the rule store. " +
+                "v0.12.0+ · receipt REQUIRED. Caller MUST first call check_action({action: 'delete memory <name>', action_type: 'deletions'}) to obtain a fresh Compliance Receipt, then pass it to this tool as `receipt`. " +
                 "Receipts must carry the caveat {type: 'action_type', value: 'deletions'} or the delete refuses. " +
-                "Receipts not supplied are accepted (back-compat) but logged · v0.12 will require them.",
+                "Migration from v0.11.x: previously unreceipted deletes were accepted with a warning · now they throw. Add a check_action call before each delete_memory call.",
             inputSchema: {
                 type: "object",
                 properties: {
                     name: { type: "string", description: "The memory's name slug" },
                     receipt: {
-                        description: "Optional Compliance Receipt (object or JSON string) from check_action. v0.11.3 logs unreceipted deletes but doesn't block them yet.",
+                        description: "REQUIRED · Compliance Receipt (object or JSON string) from check_action with action_type=deletions. Without this, the delete is refused.",
                     },
                 },
-                required: ["name"],
+                required: ["name", "receipt"],
             },
         },
         {
@@ -2611,7 +2716,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "  - APPROVES: returns a short-lived Compliance Receipt (HMAC-signed, 60s default) the agent can pass to destructive tools (e.g. delete_memory) as proof of compliance.\n" +
                 "  - DENIES: returns structured hard_violations (severity:hard rules that block) and/or soft_warnings (severity:soft rules that warn but allow).\n\n" +
                 "Tier 1 (deterministic) matches the action against rule.matches regexes + rule.enforce_on category filter. Works on every MCP client.\n" +
-                "Tier 2 (Sampling-enriched LLM judgment on rule.applies_when) ships in v0.11.3.x for clients that support Sampling (Claude Desktop, VS Code Copilot).",
+                "Tier 2 (v0.11.7+) calls back to the client via MCP sampling/createMessage to judge rule.applies_when natural-language conditions. Auto-enabled on clients that declared the sampling capability; silently skipped on clients that didn't.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -2627,6 +2732,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                         type: "string",
                         description: "Optional session identifier · binds the issued receipt to this session via a caveat.",
                     },
+                    use_sampling: {
+                        type: "boolean",
+                        description: "Opt out of Tier-2 Sampling enrichment (default true). Set false for batched/scripted use where the Sampling round-trip would add latency. CLI invocations default this to false automatically.",
+                    },
                 },
                 required: ["action", "action_type"],
             },
@@ -2721,7 +2830,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                 result = toolEmitCompanions(args);
                 break;
             case "check_action":
-                result = toolCheckAction(args);
+                result = await toolCheckAction(args);
                 break;
             case "audit":
                 result = toolAudit(args);
@@ -2881,7 +2990,19 @@ async function cliMain(command, rest) {
                 const name = positional[0];
                 if (!name)
                     throw new Error("Usage: agent-memory delete <name>");
-                process.stdout.write(toolDeleteMemory({ name }) + "\n");
+                // v0.12.0+ · delete_memory requires a Compliance Receipt. The CLI
+                // is the trusted operator path (a human is running the command,
+                // not an AI agent), so we auto-issue a CLI-scoped receipt rather
+                // than make the operator chain `check-action` then paste JSON.
+                // MCP callers (AI agents) still must go through check_action
+                // explicitly — this short-circuit only fires from the CLI binary.
+                const receipt = issueReceipt({
+                    caveats: [
+                        { type: "action_type", value: "deletions" },
+                        { type: "issued_by", value: "cli" },
+                    ],
+                });
+                process.stdout.write(toolDeleteMemory({ name, receipt: JSON.stringify(receipt) }) + "\n");
                 return 0;
             }
             case "restore": {
@@ -3018,11 +3139,14 @@ async function cliMain(command, rest) {
                 if (!action || !actionType) {
                     throw new Error("Usage: agent-memory check-action '<action description>' --type <action_type> [--session <id>]");
                 }
-                process.stdout.write(toolCheckAction({
+                process.stdout.write((await toolCheckAction({
                     action,
                     action_type: actionType,
                     session_id: flags.session ? String(flags.session) : undefined,
-                }) + "\n");
+                    // CLI invocations don't have a Sampling-capable client attached,
+                    // so skip Tier 2 to avoid a timeout · keeps the CLI fast.
+                    use_sampling: false,
+                })) + "\n");
                 return 0;
             }
             case "audit": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xultrax-web/agent-memory-mcp",
-  "version": "0.11.6",
+  "version": "0.12.0",
   "mcpName": "io.github.xultrax-web/agent-memory-mcp",
   "description": "Codify how you work. Every AI tool obeys. Markdown rules + cross-tool companion files (AGENTS.md/CLAUDE.md/.cursor/rules/.gemini) + Compliance Receipts for protocol-level enforcement of destructive ops. Reference implementation of CRP 1.0. Works on every MCP client (no Sampling required).",
   "type": "module",