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

package/README.md

@@ -27,14 +27,24 @@ 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):
+
+| 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                                                                            |
+
+Set `AGENT_MEMORY_AUTO_EMIT_DIR=/path/to/project` to auto-regenerate all companions on every rule save.
 
 Roadmap for the v0.11.x series:
 
-- `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)

package/dist/index.js

@@ -1022,6 +1022,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 +1031,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 +1179,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();
@@ -1466,7 +1591,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.1" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -1964,13 +2089,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 +2449,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.1",
   "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"
+    ]
   }
 }