@xultrax-web/agent-memory-mcp 0.11.0 → 0.11.2

package/README.md

@@ -27,17 +27,51 @@ agent-memory save-rule no-emojis-ever \
   --enforce-on commits,chat_responses \
   --content "No emojis. Anywhere. Ever."
 
-agent-memory emit-companions  # writes ./AGENTS.md
+agent-memory emit-companions
+# writes AGENTS.md + CLAUDE.md + .cursor/rules/*.mdc + .gemini/instructions.md
+# (v0.11.1 — all four targets · use --target agents,claude to filter)
 ```
 
-Set `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project` to auto-regenerate companions on every rule save.
+Companion file targets (v0.11.1):
 
-Roadmap for the v0.11.x series:
+| Target   | Path                                                                                                   | Auto-loaded by                                                                        |
+| -------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| `agents` | `AGENTS.md`                                                                                            | Claude Code, Codex CLI, Cursor, Aider, Devin, Copilot, Gemini CLI, Windsurf, Amazon Q |
+| `claude` | `CLAUDE.md`                                                                                            | Claude Code (5-level hierarchy · managed/global/project/local/subdir)                 |
+| `cursor` | `.cursor/rules/operator-hard.mdc` (`alwaysApply: true`) + `operator-conventions.mdc` (agent-requested) | Cursor (MDC format)                                                                   |
+| `gemini` | `.gemini/instructions.md`                                                                              | Gemini CLI                                                                            |
 
-- `CLAUDE.md` + `.cursor/rules/*.mdc` + `.gemini/instructions.md` emitters (per-tool native formats)
-- Compliance Receipts (Macaroon-style HMAC tokens · protocol-level enforcement of our own destructive tools)
-- `check_action` tool (deterministic rule matching · optional Sampling enrichment where clients support it)
-- `audit` command (rule conflicts · staleness · receipt-denial log)
+Set `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project` to auto-regenerate all companions on every rule save.
+
+### Compliance Receipts (v0.11.2 · primitive · tool wiring in v0.11.3)
+
+Receipts are short-lived, HMAC-signed bearer tokens with caveats (Macaroon pattern · [Birgisson et al., NDSS 2014](https://research.google/pubs/pub41892/)). The novel protocol primitive in agent-memory-mcp: server-issued tokens that bind to action + session + rules-version-hash + expiry. Tampering breaks the HMAC. Rule changes invalidate stale receipts (because `rules_version` is part of the signed payload).
+
+```typescript
+import { issueReceipt, validateReceipt } from "@xultrax-web/agent-memory-mcp";
+
+// Server-internal: issue a receipt for a destructive action
+const r = issueReceipt({
+  caveats: [
+    { type: "action", value: "delete_memory" },
+    { type: "session", value: "sess_abc123" },
+  ],
+  ttl_seconds: 60,
+});
+
+// Later: validate before executing the destructive op
+const v = validateReceipt(r, {
+  required_caveats: [{ type: "action", value: "delete_memory" }],
+});
+if (!v.valid) throw new Error(v.reason);
+```
+
+HMAC key lives at `<MEMORY_DIR>/.keyring/hmac-key` · 32 random bytes · mode `0600`. v0.11.3 wires receipts into `delete_memory` + other destructive tools and adds the `check_action` MCP tool.
+
+### Roadmap for the v0.11.x series:
+
+- `check_action` tool · deterministic rule matching · optional Sampling enrichment where clients support it · issues Compliance Receipts when proposed action passes
+- `audit` command · rule conflicts · staleness · receipt-denial log
 
 ---
 

package/dist/index.js

@@ -27,6 +27,7 @@ import { CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema
 import Fuse from "fuse.js";
 import matter from "gray-matter";
 import { spawnSync } from "node:child_process";
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
@@ -1022,6 +1023,7 @@ function buildAgentsMdContent(rules) {
     }
     return parts.join("\n");
 }
+export const ALL_COMPANION_TARGETS = ["agents", "claude", "cursor", "gemini"];
 function resolveCompanionDir(explicit) {
     if (explicit && explicit.trim().length > 0)
         return explicit.trim();
@@ -1030,22 +1032,137 @@ function resolveCompanionDir(explicit) {
         return envOverride.trim();
     return process.cwd();
 }
+// CLAUDE.md content · same body as AGENTS.md but with a Claude-Code-specific
+// header. Claude Code's 5-level hierarchy (managed/global/project/local/subdir)
+// reads any CLAUDE.md it finds; we generate the project-root file by default.
+function buildClaudeMdContent(rules) {
+    const body = buildAgentsMdContent(rules);
+    // Replace the AGENTS.md-specific header sentence with a CLAUDE.md one
+    return body.replace(/^# Operator rules\n/, `# Operator rules · Claude Code\n\n> This is your CLAUDE.md — Claude Code reads it on session start.\n\n`);
+}
+// .gemini/instructions.md content · same body as AGENTS.md, slightly different
+// header.
+function buildGeminiInstructionsContent(rules) {
+    const body = buildAgentsMdContent(rules);
+    return body.replace(/^# Operator rules\n/, `# Operator rules · Gemini CLI\n\n> Loaded by Gemini CLI from .gemini/instructions.md on session start.\n\n`);
+}
+// Cursor consumes .cursor/rules/*.mdc files with their own YAML frontmatter.
+// Per spec: each file <150 lines, alwaysApply file <50 lines, dir total <500.
+// Strategy: one file per severity (hard / soft) — hard is alwaysApply, soft
+// is description-driven so the agent pulls it in when relevant.
+function buildCursorMdcFiles(rules) {
+    const hard = rules.filter((r) => r.severity === "hard");
+    const soft = rules.filter((r) => r.severity !== "hard");
+    const files = [];
+    if (hard.length > 0) {
+        const fm = [
+            "---",
+            `description: "Operator hard rules · always obey · auto-generated from agent-memory-mcp"`,
+            "alwaysApply: true",
+            "---",
+            "",
+            "# Operator hard rules",
+            "",
+            "These rules MUST be obeyed. Violations should be flagged and blocked.",
+            "",
+        ].join("\n");
+        files.push({
+            filename: "operator-hard.mdc",
+            content: fm + hard.map((r) => formatRuleAsMarkdown(r)).join("\n"),
+        });
+    }
+    if (soft.length > 0) {
+        const fm = [
+            "---",
+            `description: "Operator conventions · prefer to obey · pulled in by agent on relevance"`,
+            "alwaysApply: false",
+            "---",
+            "",
+            "# Operator conventions",
+            "",
+            "Soft rules · prefer to obey. The agent may consult these when the context warrants.",
+            "",
+        ].join("\n");
+        files.push({
+            filename: "operator-conventions.mdc",
+            content: fm + soft.map((r) => formatRuleAsMarkdown(r)).join("\n"),
+        });
+    }
+    return files;
+}
 function emitCompanions(opts = {}) {
     const outDir = resolveCompanionDir(opts.outDir);
+    const targets = opts.targets && opts.targets.length > 0 ? opts.targets : ALL_COMPANION_TARGETS;
     const rules = loadAllRules();
-    const agentsPath = join(outDir, "AGENTS.md");
-    const content = buildAgentsMdContent(rules);
-    // Best-effort directory creation (companion dir may not exist if user
-    // passes a fresh path); mkdirSync is idempotent with recursive:true.
+    // Best-effort directory creation; mkdirSync recursive is idempotent.
     try {
         mkdirSync(outDir, { recursive: true });
     }
     catch {
-        // Ignore — atomicWriteFile will surface a clearer error if needed.
+        // Ignore — atomicWriteFile surfaces a clearer error if needed.
+    }
+    const emitted = [];
+    if (targets.includes("agents")) {
+        const fp = join(outDir, "AGENTS.md");
+        atomicWriteFile(fp, buildAgentsMdContent(rules));
+        emitted.push(fp);
+    }
+    if (targets.includes("claude")) {
+        const fp = join(outDir, "CLAUDE.md");
+        atomicWriteFile(fp, buildClaudeMdContent(rules));
+        emitted.push(fp);
+    }
+    if (targets.includes("cursor")) {
+        const cursorDir = join(outDir, ".cursor", "rules");
+        try {
+            mkdirSync(cursorDir, { recursive: true });
+        }
+        catch {
+            // Ignore — atomicWriteFile surfaces clearer error if needed.
+        }
+        const files = buildCursorMdcFiles(rules);
+        if (files.length === 0) {
+            // No rules yet — drop a placeholder so the tool knows where to put them
+            const placeholderPath = join(cursorDir, "operator-rules.mdc");
+            const placeholder = [
+                "---",
+                `description: "Operator rules · auto-generated · no rules defined yet"`,
+                "alwaysApply: false",
+                "---",
+                "",
+                "No rules defined yet. Run `agent-memory save-rule` to add the first one.",
+                "",
+            ].join("\n");
+            atomicWriteFile(placeholderPath, placeholder);
+            emitted.push(placeholderPath);
+        }
+        else {
+            for (const f of files) {
+                const fp = join(cursorDir, f.filename);
+                atomicWriteFile(fp, f.content);
+                emitted.push(fp);
+            }
+        }
     }
-    atomicWriteFile(agentsPath, content);
-    logEvent("emit_companions", { outDir, rules_count: rules.length, files: ["AGENTS.md"] });
-    return { outDir, emitted: [agentsPath], rules_count: rules.length };
+    if (targets.includes("gemini")) {
+        const geminiDir = join(outDir, ".gemini");
+        try {
+            mkdirSync(geminiDir, { recursive: true });
+        }
+        catch {
+            // Ignore — atomicWriteFile surfaces clearer error if needed.
+        }
+        const fp = join(geminiDir, "instructions.md");
+        atomicWriteFile(fp, buildGeminiInstructionsContent(rules));
+        emitted.push(fp);
+    }
+    logEvent("emit_companions", {
+        outDir,
+        rules_count: rules.length,
+        targets,
+        files: emitted.map((p) => p.replace(outDir, "").replace(/^[\\/]/, "")),
+    });
+    return { outDir, emitted, rules_count: rules.length, targets };
 }
 function maybeAutoEmitCompanions() {
     const autoDir = process.env.AGENT_MEMORY_AUTO_EMIT_DIR;
@@ -1063,11 +1180,20 @@ function maybeAutoEmitCompanions() {
 }
 function toolEmitCompanions(args) {
     const outDir = typeof args.out_dir === "string" ? args.out_dir : undefined;
-    const r = emitCompanions({ outDir });
+    let targets;
+    if (Array.isArray(args.targets)) {
+        targets = args.targets
+            .filter((t) => typeof t === "string")
+            .filter((t) => ALL_COMPANION_TARGETS.includes(t));
+        if (targets.length === 0)
+            targets = undefined;
+    }
+    const r = emitCompanions({ outDir, targets });
+    const files = r.emitted.map((p) => p.replace(r.outDir, "").replace(/^[\\/]/, "")).join(", ");
     if (r.rules_count === 0) {
-        return `Emitted ${r.emitted[0]} with no rules yet · run save_rule to add the first one.`;
+        return `Emitted ${r.emitted.length} placeholder file(s) to ${r.outDir} (${files}) · no rules yet · run save_rule to add the first one.`;
     }
-    return `Emitted ${r.rules_count} rule${r.rules_count === 1 ? "" : "s"} to ${r.emitted.join(", ")}.`;
+    return `Emitted ${r.rules_count} rule${r.rules_count === 1 ? "" : "s"} across ${r.targets.length} target${r.targets.length === 1 ? "" : "s"} (${r.targets.join(", ")}) → ${r.emitted.length} file${r.emitted.length === 1 ? "" : "s"} at ${r.outDir}: ${files}`;
 }
 function toolListRules(_args) {
     const rules = loadAllRules();
@@ -1145,6 +1271,154 @@ function toolSaveRule(args) {
     });
 }
 // -------------------------------------------------------------
+// Compliance Receipts · v0.11.2 · the novel protocol primitive
+// -------------------------------------------------------------
+//
+// Receipts are short-lived, HMAC-signed bearer tokens with caveats
+// (attenuations). Macaroon-style. Issued by `check_action` (v0.11.3),
+// validated before our own destructive tools execute. Prior art:
+//
+//   Birgisson et al · "Macaroons: Cookies with Contextual Caveats for
+//   Decentralized Authorization in the Cloud" · Google Research,
+//   NDSS 2014 · https://research.google/pubs/pub41892/
+//
+// Why receipts work where MCP Sampling doesn't:
+//   - MCP Sampling is unsupported on Claude Code / Cursor / Cline /
+//     Codex CLI (the primary coding clients) per the MCP client matrix.
+//   - Receipts are server-issued protocol artifacts — they work on every
+//     client because the server controls both ends (issue + validate).
+//   - Receipts bind to: action + session + rules-version-hash + expiry.
+//     Tampering breaks the HMAC. Rule changes invalidate stale receipts.
+//
+// Storage:
+//   HMAC key lives at <MEMORY_DIR>/.keyring/hmac-key · 32 random bytes
+//   created on first use with mode 0o600 (owner read/write only).
+//   Caller-rotatable via `agent-memory rotate-key` (a v0.11.x follow-up).
+//
+// v0.11.2 ships the PRIMITIVE only — issuance + validation +
+// canonicalization. Tool wiring (delete_memory + check_action) lands
+// in v0.11.3.
+const KEYRING_DIR = join(MEMORY_DIR, ".keyring");
+const HMAC_KEY_FILE = join(KEYRING_DIR, "hmac-key");
+const RECEIPT_DEFAULT_TTL_SECONDS = 60;
+function loadOrCreateHmacKey() {
+    if (existsSync(HMAC_KEY_FILE)) {
+        return readFileSync(HMAC_KEY_FILE);
+    }
+    if (!existsSync(KEYRING_DIR)) {
+        mkdirSync(KEYRING_DIR, { recursive: true });
+    }
+    const key = randomBytes(32); // 256 bits · plenty for HMAC-SHA256
+    // mode 0o600 is owner-only on POSIX; Windows ignores mode but ACLs
+    // default to the user, so practically equivalent for our threat model.
+    writeFileSync(HMAC_KEY_FILE, key, { mode: 0o600 });
+    return key;
+}
+/**
+ * Compute the rules-version hash · first 16 hex chars of SHA-256 over
+ * the concatenated bytes of every type=rule memory file, in sorted
+ * filename order. Any rule add / edit / remove changes this hash,
+ * which invalidates outstanding receipts (they were issued against a
+ * different rule set).
+ */
+function computeRulesVersion() {
+    const rules = loadAllRules();
+    const sortedPaths = rules.map((r) => r.filePath).sort();
+    const hash = createHash("sha256");
+    for (const fp of sortedPaths) {
+        try {
+            hash.update(readFileSync(fp));
+        }
+        catch {
+            // File disappeared between listMemoryFiles + read; skip it.
+            // Next computation will reflect the change.
+        }
+    }
+    return hash.digest("hex").slice(0, 16);
+}
+/**
+ * Deterministic canonical form for HMAC input · caveats sorted by
+ * (type, value) so the order in which the caller listed them doesn't
+ * change the signature. JSON with no whitespace (single line) so the
+ * exact byte sequence is reproducible across platforms.
+ */
+function canonicalizeReceipt(r) {
+    const sortedCaveats = [...r.caveats].sort((a, b) => a.type === b.type ? a.value.localeCompare(b.value) : a.type.localeCompare(b.type));
+    return JSON.stringify({
+        id: r.id,
+        issued_at: r.issued_at,
+        expires_at: r.expires_at,
+        rules_version: r.rules_version,
+        caveats: sortedCaveats,
+    });
+}
+function signReceipt(r) {
+    const key = loadOrCreateHmacKey();
+    return createHmac("sha256", key).update(canonicalizeReceipt(r)).digest("hex");
+}
+/**
+ * Issue a fresh Compliance Receipt with the given caveats. The receipt
+ * is bound to the current rule-store hash; any rule edit invalidates it.
+ */
+export function issueReceipt(opts) {
+    const now = Math.floor(Date.now() / 1000);
+    const ttl = Math.max(1, opts.ttl_seconds ?? RECEIPT_DEFAULT_TTL_SECONDS);
+    const base = {
+        id: "rcpt_" + randomBytes(8).toString("hex"),
+        issued_at: now,
+        expires_at: now + ttl,
+        rules_version: computeRulesVersion(),
+        caveats: opts.caveats,
+    };
+    return { ...base, signature: signReceipt(base) };
+}
+/**
+ * Validate a Compliance Receipt against the current rule store + caller's
+ * required caveats. Returns {valid: true} on success, otherwise
+ * {valid: false, reason: <human-readable>}.
+ */
+export function validateReceipt(receipt, opts = {}) {
+    // 1. HMAC verification · constant-time compare to avoid timing leaks.
+    const expected = signReceipt({
+        id: receipt.id,
+        issued_at: receipt.issued_at,
+        expires_at: receipt.expires_at,
+        rules_version: receipt.rules_version,
+        caveats: receipt.caveats,
+    });
+    const expectedBuf = Buffer.from(expected, "hex");
+    const actualBuf = Buffer.from(receipt.signature, "hex");
+    if (expectedBuf.length !== actualBuf.length || !timingSafeEqual(expectedBuf, actualBuf)) {
+        return { valid: false, reason: "invalid signature" };
+    }
+    // 2. Expiry · receipts past their expires_at are dead.
+    const now = Math.floor(Date.now() / 1000);
+    if (now > receipt.expires_at) {
+        return { valid: false, reason: "receipt expired" };
+    }
+    // 3. Rules-version binding · any rule edit since issuance invalidates.
+    const currentRulesVersion = opts.current_rules_version ?? computeRulesVersion();
+    if (receipt.rules_version !== currentRulesVersion) {
+        return {
+            valid: false,
+            reason: `rules changed since receipt issued (was ${receipt.rules_version}, now ${currentRulesVersion})`,
+        };
+    }
+    // 4. Required-caveat check · each required pair must appear on the receipt.
+    if (opts.required_caveats) {
+        for (const required of opts.required_caveats) {
+            const found = receipt.caveats.find((c) => c.type === required.type && c.value === required.value);
+            if (!found) {
+                return {
+                    valid: false,
+                    reason: `missing required caveat: ${required.type}=${required.value}`,
+                };
+            }
+        }
+    }
+    return { valid: true };
+}
+// -------------------------------------------------------------
 // Git sync · multi-machine memory via git remote
 // -------------------------------------------------------------
 //
@@ -1466,7 +1740,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.11.0" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.11.2" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -1964,13 +2238,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         },
         {
             name: "emit_companions",
-            description: "Regenerate companion rule files (AGENTS.md) from the current rule memories. Writes to the directory in `out_dir`, the AGENT_MEMORY_COMPANION_DIR env var, or the current working directory in that priority order. AGENTS.md is the universal cross-tool standard (Linux Foundation / Agentic AI Foundation).",
+            description: "Regenerate companion rule files from the current rule memories. " +
+                "Writes one or more of: AGENTS.md (universal cross-tool standard, Linux Foundation), " +
+                "CLAUDE.md (Claude Code's 5-level hierarchy), .cursor/rules/*.mdc (Cursor's MDC format · hard rules get alwaysApply:true, soft rules become description-driven), " +
+                ".gemini/instructions.md (Gemini CLI). " +
+                "Default writes ALL four targets. Use `targets` to filter. Output dir resolves from `out_dir`, then AGENT_MEMORY_COMPANION_DIR env, then process.cwd().",
             inputSchema: {
                 type: "object",
                 properties: {
                     out_dir: {
                         type: "string",
-                        description: "Optional output directory. Defaults to AGENT_MEMORY_COMPANION_DIR env var, then process.cwd().",
+                        description: "Optional output directory. Defaults to AGENT_MEMORY_COMPANION_DIR env, then process.cwd().",
+                    },
+                    targets: {
+                        type: "array",
+                        items: {
+                            type: "string",
+                            enum: ["agents", "claude", "cursor", "gemini"],
+                        },
+                        description: "Which companion files to emit. Omit (or pass empty) to emit all four. Examples: ['agents'] for AGENTS.md only, ['claude','cursor'] for Claude Code + Cursor.",
                     },
                 },
             },
@@ -2312,7 +2598,15 @@ async function cliMain(command, rest) {
             }
             case "emit-companions": {
                 const out = flags.out ? String(flags.out) : undefined;
-                process.stdout.write(toolEmitCompanions({ out_dir: out }) + "\n");
+                const target = flags.target;
+                let targets;
+                if (typeof target === "string" && target.length > 0) {
+                    targets = target
+                        .split(",")
+                        .map((t) => t.trim())
+                        .filter((t) => t.length > 0);
+                }
+                process.stdout.write(toolEmitCompanions({ out_dir: out, targets }) + "\n");
                 return 0;
             }
             case "ui": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xultrax-web/agent-memory-mcp",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "mcpName": "io.github.xultrax-web/agent-memory-mcp",
   "description": "Markdown memory for AI agents. Plain files you can read, edit, grep, and commit. Operator-grade storage with atomic writes, file locking, tags, [[wiki-links]], find_related, git-backed multi-machine sync, and an Ink-based TUI.",
   "type": "module",
@@ -21,7 +21,8 @@
     "format:check": "prettier --check .",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "prepare": "husky"
   },
   "keywords": [
     "mcp",
@@ -65,11 +66,18 @@
     "@types/node": "^22.10.2",
     "@types/proper-lockfile": "^4.1.4",
     "@types/react": "^19.2.15",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.5",
     "prettier": "^3.8.3",
     "typescript": "^5.7.2",
     "vitest": "^4.1.7"
   },
   "engines": {
     "node": ">=20"
+  },
+  "lint-staged": {
+    "*.{ts,tsx,js,mjs,cjs,json,jsonc,md,yml,yaml}": [
+      "prettier --write"
+    ]
   }
 }