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

package/README.md

@@ -13,6 +13,44 @@ You can `cat` your memory. You can `grep` it. You can edit it in vim. You can co
 
 ---
 
+## New in v0.11 · rule memories + `AGENTS.md` emission
+
+A new memory type — `rule` — captures constraints the agent should respect, not just facts to recall. Rules carry optional frontmatter fields: `severity` (hard / soft), `scope`, `applies_when`, `matches`, `enforce_on`, and `last_verified`.
+
+When you save a rule (or run `agent-memory emit-companions`), the server projects every rule memory out to `AGENTS.md` — the cross-tool universal standard read natively by Claude Code, OpenAI Codex CLI, Cursor, Aider, Devin, GitHub Copilot, Gemini CLI, Windsurf, and Amazon Q. One source of truth in your memory store; every AI tool reads the same rules.
+
+```bash
+agent-memory save-rule no-emojis-ever \
+  --description "Never use emojis in commits, comments, or chat output." \
+  --severity hard \
+  --scope global \
+  --enforce-on commits,chat_responses \
+  --content "No emojis. Anywhere. Ever."
+
+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)
+```
+
+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:
+
+- 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)
+
+---
+
 ## What you get
 
 ```text

package/dist/index.js

@@ -168,7 +168,8 @@ function withLock(fn) {
 // -------------------------------------------------------------
 // Types & validation
 // -------------------------------------------------------------
-const VALID_TYPES = new Set(["user", "feedback", "project", "reference"]);
+const VALID_TYPES = new Set(["user", "feedback", "project", "reference", "rule"]);
+const VALID_RULE_SEVERITIES = new Set(["hard", "soft"]);
 // Slug rules: lowercase a-z + digits + hyphen + underscore, start with
 // a letter or digit, 1-80 chars. Underscores are allowed because Claude
 // Code's memory tree uses them; we want frictionless import.
@@ -182,6 +183,12 @@ const WIKI_LINK_PATTERN = /\[\[([a-z0-9][a-z0-9_-]{0,80})\]\]/g;
 export function memoryFilePath(name) {
     return join(MEMORY_DIR, `${name}.md`);
 }
+function parseStringArray(input) {
+    if (!Array.isArray(input))
+        return undefined;
+    const out = input.filter((x) => typeof x === "string" && x.length > 0);
+    return out.length > 0 ? out : undefined;
+}
 export function readMemory(name) {
     const fp = memoryFilePath(name);
     if (!existsSync(fp))
@@ -189,6 +196,7 @@ export function readMemory(name) {
     const raw = readFileSync(fp, "utf8");
     const parsed = matter(raw);
     const fm = parsed.data;
+    const severity = fm.severity === "hard" || fm.severity === "soft" ? fm.severity : undefined;
     return {
         name: fm.name ?? name,
         description: fm.description ?? "",
@@ -196,6 +204,14 @@ export function readMemory(name) {
         tags: Array.isArray(fm.tags) ? fm.tags.filter((t) => typeof t === "string") : [],
         body: parsed.content.trim(),
         filePath: fp,
+        severity,
+        scope: parseStringArray(fm.scope),
+        applies_when: parseStringArray(fm.applies_when),
+        matches: parseStringArray(fm.matches),
+        enforce_on: parseStringArray(fm.enforce_on),
+        last_verified: typeof fm.last_verified === "string" && /^\d{4}-\d{2}-\d{2}$/.test(fm.last_verified)
+            ? fm.last_verified
+            : undefined,
     };
 }
 export function listMemoryFiles() {
@@ -344,6 +360,8 @@ function toolSaveMemory(args) {
             conflicts: conflictWarning ? "warned" : undefined,
         });
         log("debug", "save_memory", { name, type, update: isUpdate });
+        if (type === "rule")
+            maybeAutoEmitCompanions();
         return `${isUpdate ? "Updated" : "Saved"} memory "${name}" (${type}) at ${fp}${conflictWarning}`;
     });
 }
@@ -915,6 +933,343 @@ function toolFindRelated(args) {
     return lines.join("\n");
 }
 // -------------------------------------------------------------
+// Rule memories · the v0.11 "memory as constraint" wedge
+// -------------------------------------------------------------
+//
+// Rules are first-class memories with type=rule. They differ from
+// other types in that they're meant to constrain agent behavior,
+// not just be retrievable facts. Three things differentiate them:
+//
+//   1. Frontmatter has severity / scope / applies_when / matches /
+//      enforce_on / last_verified · all optional, gracefully fall
+//      back when absent.
+//
+//   2. Companion-file emission · all type=rule memories project out
+//      to AGENTS.md (Linux-Foundation-stewarded universal standard
+//      read natively by Claude Code, Codex CLI, Cursor, Aider, Devin,
+//      Copilot, Gemini CLI, Windsurf, and Amazon Q as of late 2025).
+//      One source of truth, regenerated from the rule store.
+//
+//   3. `save_rule` is a convenience wrapper around save_memory that
+//      validates rule-specific fields, then auto-emits companions
+//      when AGENT_MEMORY_AUTO_EMIT_DIR is set in the environment
+//      (opt-in to avoid surprise file creation in arbitrary CWDs).
+function loadAllRules() {
+    return listMemoryFiles()
+        .map((n) => readMemory(n))
+        .filter((m) => m !== null && m.type === "rule")
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+function formatRuleAsMarkdown(rule) {
+    const lines = [];
+    const sev = rule.severity ? ` _(${rule.severity})_` : "";
+    lines.push(`### ${rule.name}${sev}`);
+    lines.push("");
+    if (rule.description)
+        lines.push(rule.description);
+    if (rule.scope && rule.scope.length > 0) {
+        lines.push(`- **Scope:** ${rule.scope.join(", ")}`);
+    }
+    if (rule.enforce_on && rule.enforce_on.length > 0) {
+        lines.push(`- **Enforce on:** ${rule.enforce_on.join(", ")}`);
+    }
+    if (rule.applies_when && rule.applies_when.length > 0) {
+        lines.push(`- **Applies when:**`);
+        for (const a of rule.applies_when)
+            lines.push(`  - ${a}`);
+    }
+    if (rule.matches && rule.matches.length > 0) {
+        lines.push(`- **Pattern matches:** \`${rule.matches.map((m) => m.replace(/`/g, "\\`")).join("` · `")}\``);
+    }
+    if (rule.last_verified)
+        lines.push(`- _Last verified: ${rule.last_verified}_`);
+    if (rule.body) {
+        lines.push("");
+        lines.push(rule.body);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function buildAgentsMdContent(rules) {
+    const today = new Date().toISOString().slice(0, 10);
+    const head = [
+        `# Operator rules`,
+        ``,
+        `> Auto-generated by agent-memory-mcp from \`${MEMORY_DIR}\` on ${today}.`,
+        `> Edit the source memory files at that path — not this file — and rerun \`agent-memory emit-companions\` to refresh.`,
+        `>`,
+        `> ${rules.length} rule${rules.length === 1 ? "" : "s"} active.`,
+        ``,
+    ];
+    if (rules.length === 0) {
+        head.push(`No rules defined yet. Run \`agent-memory save-rule …\` to add the first one.`);
+        return head.join("\n") + "\n";
+    }
+    const hard = rules.filter((r) => r.severity === "hard");
+    const soft = rules.filter((r) => r.severity !== "hard");
+    const parts = [...head];
+    if (hard.length > 0) {
+        parts.push(`## Hard rules · always obey`);
+        parts.push(``);
+        for (const r of hard)
+            parts.push(formatRuleAsMarkdown(r));
+    }
+    if (soft.length > 0) {
+        parts.push(`## Conventions · prefer to obey`);
+        parts.push(``);
+        for (const r of soft)
+            parts.push(formatRuleAsMarkdown(r));
+    }
+    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();
+    const envOverride = process.env.AGENT_MEMORY_COMPANION_DIR;
+    if (envOverride && envOverride.trim().length > 0)
+        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();
+    // Best-effort directory creation; mkdirSync recursive is idempotent.
+    try {
+        mkdirSync(outDir, { recursive: true });
+    }
+    catch {
+        // 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);
+            }
+        }
+    }
+    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;
+    if (!autoDir || autoDir.trim().length === 0)
+        return;
+    try {
+        emitCompanions({ outDir: autoDir });
+    }
+    catch (err) {
+        log("warn", "auto_emit_failed", {
+            outDir: autoDir,
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function toolEmitCompanions(args) {
+    const outDir = typeof args.out_dir === "string" ? args.out_dir : undefined;
+    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.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"} 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();
+    if (rules.length === 0)
+        return "No rules defined yet. Use save_rule to add one.";
+    const lines = [];
+    lines.push(c(ANSI.bold, `${rules.length} rule${rules.length === 1 ? "" : "s"} active:`));
+    lines.push("");
+    for (const r of rules) {
+        const sev = r.severity ? ` [${r.severity}]` : "";
+        const scope = r.scope && r.scope.length > 0 ? ` · scope: ${r.scope.join(", ")}` : "";
+        const stale = r.last_verified && Date.now() - new Date(r.last_verified).getTime() > 90 * 86400_000
+            ? c(ANSI.yellow, " · STALE >90d")
+            : "";
+        lines.push(`  ${r.name}${sev}${scope}${stale}`);
+        lines.push(`    ${r.description}`);
+    }
+    return lines.join("\n");
+}
+function toolSaveRule(args) {
+    const name = String(args.name ?? "").trim();
+    const description = String(args.description ?? "").trim();
+    const content = String(args.content ?? "").trim();
+    const severity = String(args.severity ?? "soft").trim();
+    if (!VALID_RULE_SEVERITIES.has(severity)) {
+        throw new Error(`Invalid severity "${severity}". Must be one of: ${Array.from(VALID_RULE_SEVERITIES).join(", ")}.`);
+    }
+    const scope = parseStringArray(args.scope);
+    const applies_when = parseStringArray(args.applies_when);
+    const matches = parseStringArray(args.matches);
+    const enforce_on = parseStringArray(args.enforce_on);
+    const last_verified = typeof args.last_verified === "string" && /^\d{4}-\d{2}-\d{2}$/.test(args.last_verified)
+        ? args.last_verified
+        : new Date().toISOString().slice(0, 10);
+    if (!SLUG_PATTERN.test(name)) {
+        throw new Error(`Invalid name "${name}". Use lowercase (a-z, 0-9, hyphen, underscore), 1-80 chars, must start with letter or digit.`);
+    }
+    if (!description)
+        throw new Error("description is required");
+    if (!content)
+        throw new Error("content is required");
+    ensureStorage();
+    const extras = [];
+    extras.push(`severity: ${severity}`);
+    if (scope)
+        extras.push(`scope: [${scope.map((s) => JSON.stringify(s)).join(", ")}]`);
+    if (applies_when)
+        extras.push(`applies_when: [${applies_when.map((s) => JSON.stringify(s)).join(", ")}]`);
+    if (matches)
+        extras.push(`matches: [${matches.map((s) => JSON.stringify(s)).join(", ")}]`);
+    if (enforce_on)
+        extras.push(`enforce_on: [${enforce_on.map((s) => JSON.stringify(s)).join(", ")}]`);
+    extras.push(`last_verified: ${last_verified}`);
+    const frontmatter = `---\n` +
+        `name: ${name}\n` +
+        `description: ${JSON.stringify(description)}\n` +
+        `type: rule\n` +
+        extras.map((e) => `${e}\n`).join("") +
+        `schema: ${SCHEMA_VERSION}\n` +
+        `---\n\n`;
+    const fp = memoryFilePath(name);
+    const isUpdate = existsSync(fp);
+    return withLock(() => {
+        atomicWriteFile(fp, frontmatter + content + "\n");
+        upsertIndexEntryUnlocked(name, description);
+        logEvent("save_rule", {
+            name,
+            severity,
+            update: isUpdate,
+            bytes: content.length,
+        });
+        log("debug", "save_rule", { name, severity, update: isUpdate });
+        maybeAutoEmitCompanions();
+        return `${isUpdate ? "Updated" : "Saved"} rule "${name}" (${severity}) at ${fp}`;
+    });
+}
+// -------------------------------------------------------------
 // Git sync · multi-machine memory via git remote
 // -------------------------------------------------------------
 //
@@ -1236,7 +1591,7 @@ function actionColor(action) {
 // -------------------------------------------------------------
 // Server wiring
 // -------------------------------------------------------------
-const server = new Server({ name: "agent-memory", version: "0.10.3" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+const server = new Server({ name: "agent-memory", version: "0.11.1" }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
 // -------------------------------------------------------------
 // Resource URI scheme
 // -------------------------------------------------------------
@@ -1479,8 +1834,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                     },
                     type: {
                         type: "string",
-                        enum: ["user", "feedback", "project", "reference"],
-                        description: "Memory type: user (about the person), feedback (rules to follow), project (state/context), reference (external pointers)",
+                        enum: ["user", "feedback", "project", "reference", "rule"],
+                        description: "Memory type: user (about the person), feedback (lessons + corrections), project (state/context), reference (external pointers), rule (constraint enforced via companion files — prefer the save_rule tool which validates rule-specific fields)",
                     },
                     content: {
                         type: "string",
@@ -1671,6 +2026,92 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "Pull memory updates from the configured git remote (fast-forward only). Run at the start of a session to get memories saved on other machines. Refuses to pull if there are uncommitted local changes.",
             inputSchema: { type: "object", properties: {} },
         },
+        {
+            name: "save_rule",
+            description: "Save (or update) a rule memory · the 'memory as constraint' wedge. " +
+                "Rules constrain agent behavior, not just store facts. Severity 'hard' = " +
+                "must obey; 'soft' = prefer to obey. Rules auto-project out to AGENTS.md " +
+                "(read by Claude Code, Codex CLI, Cursor, Aider, Devin, Copilot, Gemini CLI, " +
+                "Windsurf, and Amazon Q natively) when AGENT_MEMORY_AUTO_EMIT_DIR is set, or " +
+                "via the emit_companions tool on demand.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Short kebab-case slug, 1-80 chars (e.g. 'no-emojis-ever', 'tests-before-commit')",
+                    },
+                    description: {
+                        type: "string",
+                        description: "One-line summary of what the rule constrains",
+                    },
+                    content: {
+                        type: "string",
+                        description: "Markdown body. Lead with the rule itself, then **Why:** and **How to apply:** lines.",
+                    },
+                    severity: {
+                        type: "string",
+                        enum: ["hard", "soft"],
+                        description: "hard = must obey (rule violations are blocked when enforced); soft = prefer to obey (warned but allowed). Defaults to soft.",
+                    },
+                    scope: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Where this rule applies. Examples: ['global'], ['project:prefixcheck'], ['tool:git'].",
+                    },
+                    applies_when: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Natural-language conditions for when the rule triggers. Used by Sampling-enriched check_action on supporting clients.",
+                    },
+                    matches: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Regex patterns that deterministically signal a violation. Used by Tier-1 check_action on every client.",
+                    },
+                    enforce_on: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Action categories this rule constrains. Examples: 'file_writes', 'commits', 'pushes', 'chat_responses'.",
+                    },
+                    last_verified: {
+                        type: "string",
+                        description: "ISO date (YYYY-MM-DD) of last verification. Defaults to today.",
+                    },
+                },
+                required: ["name", "description", "content"],
+            },
+        },
+        {
+            name: "list_rules",
+            description: "List every active rule memory with severity, scope, and staleness markers (>90 days since last_verified). Use this to audit which rules are currently constraining the agent.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "emit_companions",
+            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, 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.",
+                    },
+                },
+            },
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1726,6 +2167,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             case "sync_pull":
                 result = toolSyncPull(args);
                 break;
+            case "save_rule":
+                result = toolSaveRule(args);
+                break;
+            case "list_rules":
+                result = toolListRules(args);
+                break;
+            case "emit_companions":
+                result = toolEmitCompanions(args);
+                break;
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }
@@ -1762,6 +2212,9 @@ const CLI_COMMANDS = new Set([
     "backlinks",
     "related",
     "sync",
+    "save-rule",
+    "list-rules",
+    "emit-companions",
     "ui",
     "import-claude-code",
     "help",
@@ -1955,6 +2408,58 @@ async function cliMain(command, rest) {
                 }) + "\n");
                 return 0;
             }
+            case "save-rule": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory save-rule <name> --description <d> [--severity hard|soft] " +
+                        "[--scope a,b,c] [--applies-when a,b] [--matches a,b] [--enforce-on a,b] " +
+                        "[--content <c> | --content-file <path> | --stdin]");
+                let content = String(flags.content ?? "");
+                if (flags["content-file"]) {
+                    content = readFileSync(String(flags["content-file"]), "utf8");
+                }
+                else if (flags.stdin) {
+                    content = await readStdin();
+                }
+                const csv = (v) => {
+                    if (typeof v !== "string" || v.trim().length === 0)
+                        return undefined;
+                    return v
+                        .split(",")
+                        .map((x) => x.trim())
+                        .filter((x) => x.length > 0);
+                };
+                const result = toolSaveRule({
+                    name,
+                    description: String(flags.description ?? ""),
+                    content,
+                    severity: String(flags.severity ?? "soft"),
+                    scope: csv(flags.scope),
+                    applies_when: csv(flags["applies-when"]),
+                    matches: csv(flags.matches),
+                    enforce_on: csv(flags["enforce-on"]),
+                    last_verified: flags["last-verified"] ? String(flags["last-verified"]) : undefined,
+                });
+                process.stdout.write(result + "\n");
+                return 0;
+            }
+            case "list-rules": {
+                process.stdout.write(toolListRules({}) + "\n");
+                return 0;
+            }
+            case "emit-companions": {
+                const out = flags.out ? String(flags.out) : undefined;
+                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": {
                 // Dynamic import so Ink + React only load when the TUI runs,
                 // keeping cold-start fast for MCP server + every other CLI command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xultrax-web/agent-memory-mcp",
-  "version": "0.10.3",
+  "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"
+    ]
   }
 }