minnimemory 1.0.0-beta.1

package/dist/cli.js

@@ -0,0 +1,503 @@
+#!/usr/bin/env node
+/**
+ * minnimemory CLI.
+ *
+ * Exit codes: 0 clean, 1 findings at or above the --fail-on threshold, 2 execution error.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { BenchError, bounds, model, readWorkload } from "./bench.js";
+import { renderBounds, renderModel, renderNoWorkload } from "./benchReport.js";
+import { detectPhase, DiscoveryError } from "./discover.js";
+import { doctor } from "./doctor.js";
+import { parseHookInput, renderHook } from "./hook.js";
+import { init, InitError, renderPlan } from "./init.js";
+import { isProfileName } from "./instructions.js";
+import { loadManifest, McpTargetError, recall } from "./recall.js";
+import { createDisabledMcpServer, createMcpServer, DISABLED_MESSAGE } from "./mcpServer.js";
+import { recallDir, RecallDirError } from "./recallDir.js";
+import { exitCodeFor, renderHuman, renderJson } from "./report.js";
+import { RULES } from "./rules.js";
+import { VERSION } from "./version.js";
+/**
+ * Single switch for whether `mcp` starts the real server or the disabled placeholder. Exported
+ * so tests/cli.test.ts can pin it without needing a live stdio transport in the test process.
+ *
+ * Re-enabled 2026-09-10 for internal testing, then shipped publicly in the 1.0.0-beta.1 npm
+ * release (2026-09-15). Flip back to true to re-stash the server in a future release.
+ */
+export const MCP_STASHED = false;
+const USAGE = `
+minnimemory ${VERSION}  the agent memory compiler
+
+usage
+  minnimemory doctor [path]     audit a memory setup, change nothing
+  minnimemory init [path]       compile into .minnimemory/, dry run by default
+  minnimemory bench [path]      what the compiled shape costs over a session
+  minnimemory mcp [path]        start the MCP server. Serves check/recall by default;
+                                 --allow-write and --profile add more tools
+  minnimemory recall <path> <query...>
+                                 recall against a compiled workspace or a manifest-less memory
+                                 directory (Layout B), whichever <path> is, change nothing
+  minnimemory hook               Claude Code UserPromptSubmit hook: reads hook JSON from stdin,
+                                 prints a fenced memory block to stdout, or nothing on no hit.
+                                 Experimental until the gate in
+                                 Research/FlagShipInterfaces/README.md part (c) runs
+
+recall options
+  --max-tokens <n>        cap on returned tokens (default 1500); the top hit is always returned
+  --headings              print only "file > heading path (n tokens)" lines, not the content
+
+hook options
+  --max-tokens <n>        cap on returned tokens (default 600)
+  --headings              print only "file > heading path (n tokens)" lines, not the content
+  --dir <path>            an explicit memory directory (compiled or manifest-less), overriding
+                           the hook JSON's own cwd resolution (cwd/.minnimemory, else cwd's
+                           Claude Code auto-memory folder)
+
+init options
+  --write                 apply the compile. Without it, init only prints the plan
+  --force                 overwrite an existing .minnimemory/
+  --update                recompile a compiled workspace from its stub and OnDemandMemory files
+                           on disk
+  --budget <n>            always-loaded token budget AlwaysOnMemory must fit    (default 2000)
+  --profile <name>        how much token-discipline guidance to embed      (default auto)
+                            auto     none under the budget, routing at or over it
+                            none     structure only, embed nothing
+                            routing  the rules that make routing work, about 200 tokens
+                            full     the complete set, about 690 tokens
+  --allow-secrets         compile even when the source holds a credential-shaped string
+  --episodic-json         write episodic OnDemandMemory files (changelogs, logs) as JSON, not
+                           Markdown (O3)
+
+mcp options
+  Every tool definition is charged to the client's prefix on every turn, called or not, so the
+  server only advertises the profile you asked for, and the basic profile only the half its
+  workspace can use. Real costs (Research/TokenTest/tool_cost.mjs, approx-v2): basic on an uncompiled
+  root 368 tokens read-only, 1,025 with --allow-write; basic on a compiled root 329 read-only,
+  605 with --allow-write; full read-only 1,666, full --allow-write 2,668.
+  --profile <name>        basic (default) or full
+                            basic  the four verbs a developer actually uses, two per launch,
+                                   chosen from the workspace on disk: before a compile
+                                   (no .minnimemory/) check, plus optimize with --allow-write;
+                                   once compiled recall, plus sync with --allow-write. The
+                                   surface is fixed per process: after compiling, relaunch
+                            full   recall, modules, outline, scan, doctor, plan, always;
+                                   apply, update, reorganize with --allow-write. Today's nine
+                                   tools, unchanged - for maintainers and for an agent driving
+                                   a folder reorganization directly
+  --allow-write           adds the profile's write tools (basic: optimize, sync; full: apply,
+                           update, reorganize). Without it those tools are not registered at
+                           all: they are absent from tools/list, not present-and-refusing
+  --follow-external-imports
+                          let doctor/plan/scan (full) and check/optimize (basic) follow @path
+                           imports outside the server root. A launch flag, never a tool
+                           argument: a connected client must not be able to widen the server's
+                           reach by asking
+  --include-auto-memory   let doctor/plan/apply/update/scan (full) and check/optimize (basic)
+                           see the operator's OS-level Claude Code auto-memory folder, and
+                           allow "auto-memory" as a target where that tool resolves one. Off by
+                           default and separate from --follow-external-imports: reading the
+                           operator's own memory and following an imported file's @path are
+                           different reaches. A launch flag, never a tool argument
+
+bench options
+  --turns <n>             session length for the exact bounds                 (default 50)
+  --workload <file>       one task description per line. Without it, only the
+                           assumption-free bounds are reported
+  --whole-files           model an agent that reads the whole file the OnDemandMemory list named,
+                           instead of the sections recall() would return
+  --json                  machine-readable output
+
+doctor options
+  --json                  machine-readable output
+  --ci                    terse output, no colour
+  --follow-external-imports
+                          follow @path imports that resolve outside the target directory.
+                           Off by default: an @ line is content the scanned repo controls,
+                           and following one reads and reports files elsewhere on this machine
+  --fail-on <sev>         exit 1 at this severity or above: low, med, high   (default high)
+  --budget <n>            always-loaded token budget for MM001               (default 2000)
+  --only <ids>            run only these rules, comma separated
+  --ignore <ids>          skip these rules, comma separated
+  --rules                 list the rule set and exit
+  -h, --help              this message
+  -v, --version           print the version
+
+path defaults to the current directory. It may be a repo, a memory directory, or a single file.
+`;
+function listRules() {
+    const lines = ["", "  rule set", ""];
+    for (const r of RULES) {
+        lines.push(`  ${r.id.padEnd(8)}${r.severity.padEnd(6)}${r.title}`);
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function parseSeverity(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (value === "low" || value === "med" || value === "high")
+        return value;
+    throw new Error(`--fail-on must be one of low, med, high (got "${value}")`);
+}
+function parseIds(value) {
+    if (!value)
+        return [];
+    return value
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** `minnimemory recall`'s own rendering: full units by default, or with --headings only the
+ * "file > heading path (n tokens)" line an agent needs to decide whether to widen the query. */
+function renderRecall(result, headingsOnly) {
+    if (result.matches.length === 0) {
+        return `\n  no match for "${result.query}"\n\n`;
+    }
+    if (headingsOnly) {
+        return `${result.matches.map((m) => `${m.onDemandFile} > ${m.path.join(" > ")} (${m.tokens} tokens)`).join("\n")}\n`;
+    }
+    return `${result.matches
+        .map((m) => `## ${m.onDemandFile} > ${m.path.join(" > ")} (lines ${m.startLine}-${m.endLine}, ${m.tokens} tokens, score ${m.score})\n\n${m.content}`)
+        .join("\n\n---\n\n")}\n`;
+}
+function parseBudget(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new Error(`--budget must be a positive number (got "${value}")`);
+    return Math.floor(n);
+}
+/**
+ * Starts the MCP server. Called from main() for the `mcp` command unless MCP_STASHED is true
+ * (see that constant); also exercised directly by tests/mcp.test.ts and tests/mcpServer.test.ts.
+ */
+function runMcpCommand(target, values) {
+    let root;
+    try {
+        root = path.resolve(target);
+        if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+            throw new McpTargetError(`not a directory: ${root}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof McpTargetError) {
+            process.stderr.write(`\n  error: ${err.message}\n\n`);
+            return 2;
+        }
+        process.stderr.write(`\n  unexpected error: ${err.stack ?? String(err)}\n\n`);
+        return 2;
+    }
+    const profileName = values.profile ?? "basic";
+    if (profileName !== "basic" && profileName !== "full") {
+        process.stderr.write(`\n  error: --profile must be one of basic, full (got "${profileName}")\n\n`);
+        return 2;
+    }
+    // check/recall (basic) and recall/modules/outline (full) need a compiled workspace and
+    // report that themselves per call, the same way they already handle a missing manifest
+    // today; doctor/plan/scan (full) and check/optimize (basic) work on any target, compiled or
+    // not, and the write tools (behind --allow-write) are what makes one - which is the point of
+    // this command not failing fast here.
+    const server = createMcpServer(root, {
+        profile: profileName,
+        allowWrite: values["allow-write"] === true,
+        followExternalImports: values["follow-external-imports"] === true,
+        includeAutoMemory: values["include-auto-memory"] === true,
+    });
+    const transport = new StdioServerTransport();
+    // Fire-and-forget: the transport takes over stdin, which keeps the process alive on its own.
+    // main() stays synchronous everywhere else, so this is the one command that does not "finish"
+    // in the normal sense - it runs until the client disconnects (stdin closes).
+    server.connect(transport).catch((err) => {
+        process.stderr.write(`\n  mcp server failed: ${err.message ?? String(err)}\n`);
+        process.exitCode = 1;
+    });
+    return 0;
+}
+export function main(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                json: { type: "boolean", default: false },
+                write: { type: "boolean", default: false },
+                force: { type: "boolean", default: false },
+                update: { type: "boolean", default: false },
+                "allow-secrets": { type: "boolean", default: false },
+                "episodic-json": { type: "boolean", default: false },
+                "allow-write": { type: "boolean", default: false },
+                "follow-external-imports": { type: "boolean", default: false },
+                "include-auto-memory": { type: "boolean", default: false },
+                turns: { type: "string" },
+                workload: { type: "string" },
+                "whole-files": { type: "boolean", default: false },
+                "max-tokens": { type: "string" },
+                headings: { type: "boolean", default: false },
+                dir: { type: "string" },
+                profile: { type: "string" },
+                ci: { type: "boolean", default: false },
+                rules: { type: "boolean", default: false },
+                "fail-on": { type: "string" },
+                budget: { type: "string" },
+                only: { type: "string" },
+                ignore: { type: "string" },
+                help: { type: "boolean", short: "h", default: false },
+                version: { type: "boolean", short: "v", default: false },
+            },
+        });
+    }
+    catch (err) {
+        process.stderr.write(`\n  error: ${err.message}\n${USAGE}`);
+        return 2;
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    if (values.version) {
+        process.stdout.write(`${VERSION}\n`);
+        return 0;
+    }
+    if (values.rules) {
+        process.stdout.write(listRules());
+        return 0;
+    }
+    const command = positionals[0] ?? "doctor";
+    const target = positionals[1] ?? ".";
+    if (command === "init") {
+        const profileName = values.profile ?? "auto";
+        if (profileName !== "auto" && !isProfileName(profileName)) {
+            process.stderr.write(`\n  error: --profile must be one of auto, none, routing, full (got "${profileName}")\n\n`);
+            return 2;
+        }
+        let budget;
+        try {
+            budget = parseBudget(values.budget, 2000);
+        }
+        catch (err) {
+            process.stderr.write(`\n  error: ${err.message}\n\n`);
+            return 2;
+        }
+        const options = {
+            write: values.write === true,
+            force: values.force === true,
+            update: values.update === true,
+            allowSecrets: values["allow-secrets"] === true,
+            episodicJson: values["episodic-json"] === true,
+            profile: profileName,
+            budget,
+        };
+        try {
+            const plan = init(target, options);
+            process.stdout.write(renderPlan(plan, options));
+            return 0;
+        }
+        catch (err) {
+            if (err instanceof InitError || err instanceof DiscoveryError) {
+                process.stderr.write(`\n  error: ${err.message}\n\n`);
+                return 2;
+            }
+            process.stderr.write(`\n  unexpected error: ${err.stack ?? String(err)}\n\n`);
+            return 2;
+        }
+    }
+    if (command === "mcp") {
+        if (!MCP_STASHED)
+            return runMcpCommand(target, values);
+        // Re-stash path, dead while MCP_STASHED is false (see the constant's own comment above) but
+        // kept intact and reachable: flip the flag back to instantly return to a zero-tool
+        // placeholder instead of deleting this and having to rebuild it later. A connecting client
+        // gets a clean handshake either way - zero tools, DISABLED_MESSAGE in `instructions` - rather
+        // than a bare process-startup failure. tests/cli.test.ts pins MCP_STASHED, so either flip is
+        // a deliberate, visible change, not a silent one.
+        process.stderr.write(`\n  mcp: ${DISABLED_MESSAGE}\n\n`);
+        const server = createDisabledMcpServer();
+        const transport = new StdioServerTransport();
+        server.connect(transport).catch((err) => {
+            process.stderr.write(`\n  mcp server failed: ${err.message ?? String(err)}\n`);
+            process.exitCode = 1;
+        });
+        return 0;
+    }
+    if (command === "recall") {
+        const query = positionals.slice(2).join(" ").trim();
+        if (!query) {
+            process.stderr.write(`\n  error: recall needs a query: minnimemory recall <path> <query...>\n\n`);
+            return 2;
+        }
+        let maxTokens;
+        if (values["max-tokens"] !== undefined) {
+            const n = Number(values["max-tokens"]);
+            if (!Number.isFinite(n) || n <= 0) {
+                process.stderr.write(`\n  error: --max-tokens must be a positive number (got "${values["max-tokens"]}")\n\n`);
+                return 2;
+            }
+            maxTokens = Math.floor(n);
+        }
+        const root = path.resolve(target);
+        try {
+            const phase = detectPhase(root);
+            let result;
+            if (phase === "compiled") {
+                result = recall(root, loadManifest(root), query, { maxTokens });
+            }
+            else if (phase === "memory-dir") {
+                result = recallDir(root, query, { maxTokens });
+            }
+            else {
+                process.stderr.write(`\n  error: ${root} is neither a compiled workspace (.minnimemory/manifest.json) nor a manifest-less ` +
+                    `memory directory (an index file plus topic files) - nothing for recall to query\n\n`);
+                return 2;
+            }
+            process.stdout.write(renderRecall(result, values.headings === true));
+            return 0;
+        }
+        catch (err) {
+            if (err instanceof McpTargetError || err instanceof RecallDirError) {
+                process.stderr.write(`\n  error: ${err.message}\n\n`);
+                return 2;
+            }
+            process.stderr.write(`\n  unexpected error: ${err.stack ?? String(err)}\n\n`);
+            return 2;
+        }
+    }
+    if (command === "hook") {
+        // Exit 0 always: this runs as a Claude Code UserPromptSubmit hook, and a hook's stdout
+        // becomes context fed straight to the model, so a failure here must never surface as
+        // anything but silence on stdout. Everything that can go wrong (unreadable stdin, a bad
+        // target, no hit) is swallowed by renderHook() itself; this block only guards the read.
+        let raw = "";
+        try {
+            raw = fs.readFileSync(0, "utf8");
+        }
+        catch {
+            raw = "";
+        }
+        let maxTokens;
+        if (values["max-tokens"] !== undefined) {
+            const n = Number(values["max-tokens"]);
+            if (Number.isFinite(n) && n > 0)
+                maxTokens = Math.floor(n);
+        }
+        try {
+            const input = parseHookInput(raw);
+            const text = renderHook(input, { headings: values.headings === true, maxTokens, dir: values.dir });
+            if (text)
+                process.stdout.write(`${text}\n`);
+        }
+        catch (err) {
+            process.stderr.write(`\n  hook: ${err.message ?? String(err)}\n`);
+        }
+        return 0;
+    }
+    if (command === "bench") {
+        try {
+            const root = path.resolve(target);
+            const manifest = loadManifest(root);
+            const turns = values.turns === undefined ? 50 : Number(values.turns);
+            if (!Number.isFinite(turns)) {
+                throw new BenchError(`--turns must be a positive whole number (got "${values.turns}")`);
+            }
+            const b = bounds(manifest, turns);
+            if (values.workload === undefined) {
+                if (values.json === true) {
+                    process.stdout.write(`${JSON.stringify({ bounds: b, tokenizer: manifest.tokenizer }, null, 2)}\n`);
+                    return 0;
+                }
+                process.stdout.write(renderBounds(b, manifest.tokenizer));
+                process.stdout.write(renderNoWorkload());
+                return 0;
+            }
+            const tasks = readWorkload(values.workload);
+            // Section-level routing, the same path recall() takes. --whole-files models an agent
+            // that reads the entire file the OnDemandMemory list pointed at instead.
+            const m = model(manifest, tasks, values["whole-files"] === true ? {} : { root });
+            if (values.json === true) {
+                process.stdout.write(`${JSON.stringify({ bounds: b, model: m, tokenizer: manifest.tokenizer }, null, 2)}\n`);
+                return 0;
+            }
+            process.stdout.write(renderBounds(b, manifest.tokenizer));
+            process.stdout.write(renderModel(m, manifest.tokenizer));
+            return 0;
+        }
+        catch (err) {
+            if (err instanceof BenchError || err instanceof McpTargetError) {
+                process.stderr.write(`\n  error: ${err.message}\n\n`);
+                return 2;
+            }
+            process.stderr.write(`\n  unexpected error: ${err.stack ?? String(err)}\n\n`);
+            return 2;
+        }
+    }
+    if (command !== "doctor") {
+        process.stderr.write(`\n  error: unknown command "${command}"\n${USAGE}`);
+        return 2;
+    }
+    let config;
+    try {
+        config = {
+            budget: parseBudget(values.budget, 2000),
+            failOn: parseSeverity(values["fail-on"], "high"),
+            only: parseIds(values.only),
+            ignore: parseIds(values.ignore),
+            followExternalImports: values["follow-external-imports"] === true,
+        };
+    }
+    catch (err) {
+        process.stderr.write(`\n  error: ${err.message}\n\n`);
+        return 2;
+    }
+    try {
+        const result = doctor(target, config);
+        const resolved = { ...result, findings: result.findings };
+        const full = {
+            budget: config.budget ?? 2000,
+            failOn: config.failOn ?? "high",
+            only: config.only ?? [],
+            ignore: config.ignore ?? [],
+            maxListLine: 120,
+            followExternalImports: config.followExternalImports === true,
+            includeAutoMemory: true,
+        };
+        if (values.json) {
+            process.stdout.write(`${renderJson(resolved, full)}\n`);
+        }
+        else {
+            const color = !values.ci && !process.env["NO_COLOR"] && process.stdout.isTTY === true;
+            process.stdout.write(renderHuman(resolved, full, { color, ci: values.ci === true }));
+        }
+        return exitCodeFor(result.findings, full.failOn);
+    }
+    catch (err) {
+        if (err instanceof DiscoveryError) {
+            process.stderr.write(`\n  error: ${err.message}\n\n`);
+            return 2;
+        }
+        process.stderr.write(`\n  unexpected error: ${err.stack ?? String(err)}\n\n`);
+        return 2;
+    }
+}
+/** Only run when invoked as the binary, so tests can import `main` safely. */
+function invokedDirectly() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return path.resolve(fileURLToPath(import.meta.url)) === path.resolve(entry);
+    }
+    catch {
+        return false;
+    }
+}
+if (invokedDirectly()) {
+    process.exitCode = main(process.argv.slice(2));
+}