minnimemory 1.0.0-beta.1

package/dist/compile.js

@@ -0,0 +1,516 @@
+/**
+ * The compiler: turn one memory file into a cache-stable AlwaysOnMemory body plus routed
+ * OnDemandMemory files.
+ *
+ * Pure by design. Everything here is string in, strings out, so the whole compile can be
+ * tested from fixtures and diffed before anything touches a user's disk.
+ *
+ * Structure follows the tiered-memory pattern already running in production in the Minni
+ * agents (AlwaysOnMemory.md, OnDemandMemory/, fixed assembly order), and the emitted
+ * instruction block comes from the MinniMemory v1.0 research set. See instructions.ts.
+ */
+import { createHash } from "node:crypto";
+import { defaultProfile, profile as profileFor, renderInstructions } from "./instructions.js";
+import { classifyKind, episodicFromMarkdown, episodicToJson } from "./episodic.js";
+import { renderWriteProtocolFile, WRITE_PROTOCOL_HEADING, WRITE_PROTOCOL_FILE_NAME, WRITE_PROTOCOL_TRIGGERS, } from "./writeProtocol.js";
+import { blocks, GRANULARITY_TOKENS, LIST_END, LIST_START, INSTRUCTIONS_END, INSTRUCTIONS_START, keywords, sections, sectionVolatilityReasons, slugify, splitFrontmatter, volatilityReasons, } from "./text.js";
+import { selectTriggers } from "./router.js";
+import { estimateTokens } from "./tokenizer.js";
+/** Marker identifying a host file this tool generated, so it is never double counted. */
+export const STUB_MARKER = "<!-- minnimemory:stub v1 -->";
+/** Default always-loaded budget in tokens; matches doctor's MM001 default. */
+export const DEFAULT_BUDGET = 2000;
+/**
+ * Rough cost of one OnDemandMemory list line and of the fixed list scaffolding (markers,
+ * heading, and the routing line the `none` profile adds), used only to keep AlwaysOnMemory
+ * placement inside the budget. Measured with approx-v2 on the list-form OnDemandMemory list
+ * (2026-09-04 audit); the previous table form cost 159 fixed while the estimator assumed 90.
+ */
+const LIST_LINE_COST = 22;
+const LIST_BASE_COST = 40;
+/** Headings whose content is identity or invariant, so it belongs in AlwaysOnMemory. */
+export const ALWAYS_ON_HINTS = /\b(identity|overview|about|purpose|mission|principles?|conventions?|rules?|constraints?|boundar\w*|guardrails?|guidelines?|style|tone|standards?|polic(?:y|ies)|invariants?|philosophy|decisions?)\b/i;
+/**
+ * Below this, an OnDemandMemory file is not worth routing to: the list line and the decision
+ * to load it cost more than just having read the content. Consecutive small sections are merged.
+ */
+const MIN_ON_DEMAND_TOKENS = 400;
+function hash(text) {
+    return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+/**
+ * The hash MM010 and recall's drift check both compare against a manifest entry.
+ *
+ * CRLF-normalised and trailing-whitespace-trimmed on purpose: a checkout can rewrite line
+ * endings with nobody editing anything, and a file that differs only that way has not drifted.
+ * One copy, because the dated-bullet regex taught us what three copies of a rule costs
+ * (2026-09-13 audit, D7).
+ */
+export function driftHash(content) {
+    return hash(content.replace(/\r\n/g, "\n").trimEnd());
+}
+/**
+ * Shared with rules.ts's MM010 check against AlwaysOnMemory.md and the stub: sha256 slice 16
+ * with no normalisation, the caller's job (CRLF-only, no trimEnd - those files are written
+ * verbatim, so trimming would blur an edit driftHash would forgive on purpose for OnDemandMemory
+ * files but should not here).
+ */
+export { hash as verbatimHash };
+/** Pick the heading level that actually divides the document into topics. */
+function detectSplitLevel(all) {
+    for (let level = 2; level <= 4; level++) {
+        if (all.filter((s) => s.level === level).length >= 2)
+            return level;
+    }
+    // A document of only H1s still needs splitting somewhere.
+    if (all.filter((s) => s.level === 1).length >= 2)
+        return 1;
+    return 2;
+}
+function textOf(lines, startLine, endLine) {
+    return lines.slice(startLine - 1, endLine).join("\n").trimEnd();
+}
+/**
+ * Choose each OnDemandMemory file's list triggers against the whole file set (router.ts
+ * selectTriggers): frequency here times rarity elsewhere, headings weighted. Replaces the
+ * frequency-only keywords() pick plus a post-hoc prune, which produced `bars, free, merged` for
+ * a trading-app memory file (audit 2026-09-04). The per-file keywords() call remains the
+ * fallback for paths that see one file at a time (init --update).
+ */
+function assignTriggers(onDemandFiles) {
+    const chosen = selectTriggers(onDemandFiles.map((m) => ({ name: m.name, heading: m.heading, content: m.content })));
+    for (const m of onDemandFiles)
+        m.triggers = chosen.get(m.name) ?? m.triggers;
+}
+/**
+ * Merge runs of small consecutive sections into OnDemandMemory files worth routing to.
+ * Order is preserved, so the fixed assembly order still matches document order.
+ */
+function mergeSmall(onDemandFiles, min) {
+    const out = [];
+    let bucket = [];
+    const flush = () => {
+        if (bucket.length === 0)
+            return;
+        const first = bucket[0];
+        if (!first) {
+            bucket = [];
+            return;
+        }
+        if (bucket.length === 1) {
+            out.push(first);
+            bucket = [];
+            return;
+        }
+        const last = bucket[bucket.length - 1] ?? first;
+        const content = bucket.map((b) => b.content).join("\n\n");
+        const triggers = [...new Set(bucket.flatMap((b) => b.triggers))].slice(0, 8);
+        // A merged OnDemandMemory file must not inherit the first section's name: a file called
+        // current_status.md that also holds testing and deployment misleads the reader
+        // and the agent about what is inside it.
+        const name = slugify(`${first.heading} to ${last.heading}`);
+        out.push({
+            name,
+            file: `${ON_DEMAND_DIR_NAME}/${name}.md`,
+            heading: `${first.heading} through ${last.heading}`,
+            content,
+            tokens: estimateTokens(content),
+            triggers,
+            sourceStartLine: first.sourceStartLine,
+            sourceEndLine: last.sourceEndLine,
+            reason: bucket.some((b) => b.reason === "volatile")
+                ? "volatile"
+                : bucket.some((b) => b.reason === "over-budget")
+                    ? "over-budget"
+                    : "task-specific",
+            kind: first.kind,
+        });
+        bucket = [];
+    };
+    for (const m of onDemandFiles) {
+        // A file the granularity split produced stands alone: flush whatever was accumulating,
+        // emit it untouched, and start a fresh bucket after it. So does an episodic section (O2):
+        // it is append-only and may become JSON (O3), so it never shares a file with prose.
+        if (m.split || m.kind === "episodic") {
+            flush();
+            out.push(m);
+            continue;
+        }
+        // Kinds are edited differently (O2), so a bucket holds one kind only.
+        if (bucket.length > 0 && bucket[0]?.kind !== m.kind)
+            flush();
+        bucket.push(m);
+        if (bucket.reduce((n, b) => n + b.tokens, 0) >= min)
+            flush();
+    }
+    flush();
+    return out;
+}
+/**
+ * The list title is deliberately not derived from the document title: a title can carry a
+ * date or a status word ("Minni (renamed 2026-08-11)"), and the list must stay free of anything
+ * the volatility rules would flag. The whole list is fenced with markers so `doctor` can tell a
+ * routing manifest from prose.
+ *
+ * One line per OnDemandMemory file and nothing that restates a Part 2 rule (P4). Rules 15, 16,
+ * 22 and 23 already say how to use the list and sit in the same prefix whenever a discipline
+ * block is embedded; the previous table-plus-prose form repeated them at 159 tokens per compile.
+ * Only the `none` profile, which embeds no block, gets one routing line after the list. Assembly
+ * order is the manifest's `order`, not prefix text.
+ */
+/** The directory `init` writes next to the host file. Named here, where the stub's
+ * OnDemandMemory list is rendered, so the two can never disagree about where a file lives. */
+export const COMPILED_DIR_NAME = ".minnimemory";
+/** The one always-loaded file inside the compiled directory: AlwaysOnMemory body plus the
+ * OnDemandMemory list. */
+export const ALWAYS_ON_FILE_NAME = "AlwaysOnMemory.md";
+/** The OnDemandMemory files directory inside the compiled directory. */
+export const ON_DEMAND_DIR_NAME = "OnDemandMemory";
+function renderOnDemandList(onDemandFiles, withRoutingLine, pathPrefix = "") {
+    const lines = [LIST_START, "# OnDemandMemory"];
+    if (onDemandFiles.length === 0) {
+        lines.push("No OnDemandMemory files. Everything lives in AlwaysOnMemory.", LIST_END, "");
+        return lines.join("\n");
+    }
+    // Paths are relative to the file the list sits in. AlwaysOnMemory.md lives inside the
+    // compiled directory beside OnDemandMemory/; the stub lives one level up, in the project, and
+    // an agent that reads `OnDemandMemory/x.md` from there finds nothing. The 2026-09-05 session
+    // measurement caught exactly that: the agent tried the bare path, missed, and gave up.
+    for (const m of onDemandFiles) {
+        lines.push(`- \`${pathPrefix}${m.file}\`: ${m.triggers.join(", ")}`);
+    }
+    if (withRoutingLine) {
+        lines.push("", "Read an OnDemandMemory file only when the task needs it, and answer from it, never from this list.");
+    }
+    lines.push(LIST_END, "");
+    return lines.join("\n");
+}
+/** The instruction block, fenced so `doctor` skips it and `init --update` can strip it. */
+function renderInstructionRegion(profile) {
+    const body = renderInstructions(profile);
+    if (!body)
+        return "";
+    return [INSTRUCTIONS_START, body.trimEnd(), INSTRUCTIONS_END].join("\n");
+}
+function renderAlwaysOnBody(frontmatter, title, preamble, alwaysOnSections, profile) {
+    const parts = [];
+    if (frontmatter)
+        parts.push(frontmatter, "");
+    parts.push(`# ${title}`, "");
+    if (preamble.trim())
+        parts.push(preamble.trim(), "");
+    for (const s of alwaysOnSections)
+        parts.push(s.trim(), "");
+    const instructions = renderInstructionRegion(profile);
+    if (instructions)
+        parts.push(instructions, "");
+    return parts.join("\n");
+}
+/**
+ * Frontmatter, when present, stays the very first thing in the stub: a YAML header that is not
+ * on line 1 stops being a header. The generated-file marker follows it. `alwaysOnBody` here is
+ * the AlwaysOnMemory body without its frontmatter, since the stub places the frontmatter itself.
+ */
+function renderStub(frontmatter, alwaysOnBody, onDemandList, onDemandCount) {
+    const parts = [];
+    if (frontmatter)
+        parts.push(frontmatter);
+    parts.push(STUB_MARKER, "<!-- generated by minnimemory; edit .minnimemory/ instead -->", "");
+    parts.push(alwaysOnBody.trimEnd(), "");
+    if (onDemandCount > 0)
+        parts.push(onDemandList.trimEnd(), "");
+    return parts.join("\n");
+}
+/**
+ * `.minnimemory/AlwaysOnMemory.md`: the AlwaysOnMemory body (already carries its own
+ * frontmatter) plus the OnDemandMemory list, the same join the stub uses, written to its own
+ * file instead of into the host file.
+ */
+function renderAlwaysOn(alwaysOnBody, onDemandList, onDemandCount) {
+    const parts = [alwaysOnBody.trimEnd(), ""];
+    if (onDemandCount > 0)
+        parts.push(onDemandList.trimEnd(), "");
+    return parts.join("\n");
+}
+/**
+ * Is this host file a stub this tool generated? Only a marker on the first line after any
+ * frontmatter counts. A marker quoted in a code block, or anywhere else in prose, is text
+ * (security audit 2026-09-02, finding 5).
+ */
+export function isStub(source) {
+    const lines = source.split(/\r?\n/);
+    const { bodyStartLine } = splitFrontmatter(lines);
+    return (lines[bodyStartLine - 1] ?? "").trim() === STUB_MARKER;
+}
+export function compile(source, options) {
+    const lines = source.split(/\r?\n/);
+    const { frontmatter: frontmatterLines, bodyStartLine } = splitFrontmatter(lines);
+    const frontmatter = frontmatterLines.join("\n");
+    const all = sections(lines).filter((s) => s.startLine >= bodyStartLine);
+    const profile = options.profile ?? (options.profileName ? profileFor(options.profileName) : defaultProfile());
+    const splitLevel = options.splitLevel ?? detectSplitLevel(all);
+    const splits = all.filter((s) => s.level === splitLevel);
+    const firstSplitLine = splits[0]?.startLine ?? lines.length + 1;
+    // The title is an H1 that comes before the first split heading. An H1 further down is a
+    // section like any other, not the document's name.
+    const titleSection = all.find((s) => s.level === 1 && s.startLine < firstSplitLine);
+    const title = titleSection?.heading ?? options.sourceName.replace(/\.md$/i, "");
+    // Everything above the first split heading is preamble. That includes any prose that sits
+    // above the title line, so nothing written before the H1 is lost.
+    const preambleStart = bodyStartLine;
+    const preambleLines = titleSection
+        ? [
+            ...lines.slice(bodyStartLine - 1, titleSection.startLine - 1),
+            ...lines.slice(titleSection.startLine, firstSplitLine - 1),
+        ]
+        : lines.slice(bodyStartLine - 1, firstSplitLine - 1);
+    const preamble = preambleLines.join("\n").trimEnd();
+    const alwaysOnSections = [];
+    const onDemandFiles = [];
+    // The preamble is not exempt from the cache-stability law. Split it per block and route the
+    // volatile blocks out, so a dated audit note cannot sit in the always-loaded prefix just
+    // because it happened to appear above the first heading.
+    const preambleBlocks = blocks(preamble.split("\n"));
+    const stablePreamble = preambleBlocks.filter((b) => volatilityReasons(b.text).length === 0);
+    const volatilePreamble = preambleBlocks.filter((b) => volatilityReasons(b.text).length > 0);
+    if (volatilePreamble.length > 0) {
+        const content = ["## Notes", "", ...volatilePreamble.map((b) => b.text)].join("\n\n");
+        onDemandFiles.push({
+            name: "notes",
+            file: `${ON_DEMAND_DIR_NAME}/notes.md`,
+            heading: "Notes",
+            content,
+            tokens: estimateTokens(content),
+            triggers: keywords("notes status", content),
+            sourceStartLine: preambleStart,
+            sourceEndLine: firstSplitLine - 1,
+            reason: "volatile",
+        });
+    }
+    const preambleText = stablePreamble.map((b) => b.text).join("\n\n");
+    const entries = splits.map((s, i) => {
+        const next = splits[i + 1];
+        const endLine = next ? next.startLine - 1 : lines.length;
+        const content = textOf(lines, s.startLine, endLine);
+        const volatile = sectionVolatilityReasons(content.split("\n"));
+        // The cache-stability law: volatile content never enters the always-loaded prefix,
+        // no matter how always-on-like its heading reads.
+        const alwaysOnCandidate = ALWAYS_ON_HINTS.test(s.heading) && volatile.length === 0;
+        return { section: s, content, endLine, tokens: estimateTokens(content), volatile, alwaysOnCandidate };
+    });
+    // The stable preamble competes for AlwaysOnMemory like any other candidate. Real AGENTS.md
+    // files put a thousand tokens of prose before the first H2; exempting that from the budget
+    // would push every actual rule section out instead.
+    if (preambleText.trim()) {
+        entries.unshift({
+            section: { heading: title, level: 0, startLine: preambleStart, endLine: firstSplitLine - 1 },
+            content: preambleText,
+            endLine: firstSplitLine - 1,
+            tokens: estimateTokens(preambleText),
+            volatile: [],
+            alwaysOnCandidate: true,
+            preamble: true,
+        });
+    }
+    // Budget-aware placement. A heading can read as always-on ("Architecture guidelines", "Code
+    // Style") and still be thousands of tokens; keeping every such section in AlwaysOnMemory just
+    // moves the MM001 finding from the source to the compiled output. Smallest candidates are kept
+    // first, because a short set of invariants is what AlwaysOnMemory is for, and whatever does
+    // not fit is routed to an OnDemandMemory file with the reason recorded so the user can see it
+    // and raise --budget.
+    const budget = options.budget ?? DEFAULT_BUDGET;
+    const candidates = entries.filter((e) => e.alwaysOnCandidate).sort((a, b) => a.tokens - b.tokens);
+    const onDemandEstimate = entries.length - candidates.length + (volatilePreamble.length > 0 ? 1 : 0);
+    let used = estimateTokens(renderAlwaysOnBody("", title, "", [], profile)) + LIST_BASE_COST + LIST_LINE_COST * onDemandEstimate;
+    const kept = new Set();
+    for (const c of candidates) {
+        if (used + c.tokens <= budget) {
+            kept.add(c);
+            used += c.tokens;
+        }
+    }
+    const demoted = candidates.filter((c) => !kept.has(c));
+    const stableText = entries.find((e) => e.preamble && kept.has(e))?.content ?? "";
+    for (const e of entries) {
+        if (kept.has(e)) {
+            if (!e.preamble)
+                alwaysOnSections.push(e.content);
+            continue;
+        }
+        if (e.preamble) {
+            const name = slugify(`${title} overview`);
+            onDemandFiles.push({
+                name,
+                file: `${ON_DEMAND_DIR_NAME}/${name}.md`,
+                heading: `${title} overview`,
+                content: `## ${title} overview\n\n${e.content}`,
+                tokens: e.tokens,
+                triggers: keywords(`${title} overview`, e.content),
+                sourceStartLine: e.section.startLine,
+                sourceEndLine: e.endLine,
+                reason: "over-budget",
+            });
+            continue;
+        }
+        const reason = e.volatile.length > 0 ? "volatile" : e.alwaysOnCandidate ? "over-budget" : "task-specific";
+        // The granularity clause (O7) on the agent-driven route: an agent that reads a whole file
+        // the OnDemandMemory list named pays the whole file, so a section over the threshold is
+        // emitted as one OnDemandMemory file per subheading, the parent heading and its intro lines
+        // first. Every line lands in exactly one file, in document order, so losslessness and the
+        // assembly order both hold. A flat section has nothing to split on; doctor's MM009 says so.
+        const subs = e.tokens >= GRANULARITY_TOKENS
+            ? all.filter((s) => s.level === splitLevel + 1 && s.startLine > e.section.startLine && s.startLine <= e.endLine)
+            : [];
+        if (subs.length > 0) {
+            const first = subs[0];
+            const introEnd = first.startLine - 1;
+            const intro = textOf(lines, e.section.startLine, introEnd);
+            const introTokens = estimateTokens(intro);
+            // A parent heading plus a sentence or two is not worth its own list line, so it rides
+            // with the first subheading instead. Only a substantial intro becomes its own file.
+            const introStandsAlone = introTokens >= LIST_LINE_COST * 2;
+            if (introStandsAlone) {
+                onDemandFiles.push({
+                    name: slugify(e.section.heading),
+                    file: `${ON_DEMAND_DIR_NAME}/${slugify(e.section.heading)}.md`,
+                    heading: e.section.heading,
+                    content: intro,
+                    tokens: introTokens,
+                    triggers: keywords(e.section.heading, intro),
+                    sourceStartLine: e.section.startLine,
+                    sourceEndLine: introEnd,
+                    reason,
+                    split: true,
+                });
+            }
+            subs.forEach((sub, i) => {
+                const next = subs[i + 1];
+                const end = next ? next.startLine - 1 : e.endLine;
+                const isFirst = i === 0;
+                const startLine = !introStandsAlone && isFirst ? e.section.startLine : sub.startLine;
+                const content = textOf(lines, startLine, end);
+                const heading = `${e.section.heading}: ${sub.heading}`;
+                const name = slugify(heading);
+                onDemandFiles.push({
+                    name,
+                    file: `${ON_DEMAND_DIR_NAME}/${name}.md`,
+                    heading,
+                    content,
+                    tokens: estimateTokens(content),
+                    triggers: keywords(heading, content),
+                    sourceStartLine: startLine,
+                    sourceEndLine: end,
+                    reason,
+                    split: true,
+                });
+            });
+            continue;
+        }
+        const name = slugify(e.section.heading);
+        onDemandFiles.push({
+            name,
+            file: `${ON_DEMAND_DIR_NAME}/${name}.md`,
+            heading: e.section.heading,
+            content: e.content,
+            tokens: e.tokens,
+            triggers: keywords(e.section.heading, e.content),
+            sourceStartLine: e.section.startLine,
+            sourceEndLine: e.endLine,
+            reason,
+        });
+    }
+    // O2 before merging: the kind decides what may share a file.
+    for (const m of onDemandFiles)
+        m.kind = m.kind ?? classifyKind(m.heading, m.content.split("\n").slice(1));
+    const merged = options.onDemandFilesOverride ?? mergeSmall(onDemandFiles, MIN_ON_DEMAND_TOKENS);
+    // Slugs must be unique or OnDemandMemory files overwrite each other on disk.
+    const seen = new Map();
+    for (const m of merged) {
+        const n = seen.get(m.name) ?? 0;
+        seen.set(m.name, n + 1);
+        if (n > 0) {
+            m.name = `${m.name}_${n + 1}`;
+            m.file = `${ON_DEMAND_DIR_NAME}/${m.name}.md`;
+        }
+    }
+    assignTriggers(merged);
+    // O2: every OnDemandMemory file carries its kind. O3: an episodic file is written as JSON
+    // when asked, and its on-disk bytes are what gets hashed and counted, so tokens follow the JSON.
+    for (const m of merged) {
+        if (m.generated)
+            continue;
+        m.kind = m.kind ?? classifyKind(m.heading, m.content.split("\n").slice(1));
+        if (options.episodicJson && m.kind === "episodic" && m.file.endsWith(".md")) {
+            m.content = episodicToJson(episodicFromMarkdown(m.content)).trimEnd();
+            m.file = m.file.replace(/\.md$/, ".json");
+            m.tokens = estimateTokens(m.content);
+        }
+    }
+    // O9: the write protocol rides as a routed OnDemandMemory file, never in the prefix. Appended
+    // last so the source OnDemandMemory files keep document order, and skipped when an override
+    // already has it.
+    if (options.writeProtocol !== false && !merged.some((m) => m.name === WRITE_PROTOCOL_FILE_NAME)) {
+        const content = renderWriteProtocolFile();
+        merged.push({
+            name: WRITE_PROTOCOL_FILE_NAME,
+            file: `${ON_DEMAND_DIR_NAME}/${WRITE_PROTOCOL_FILE_NAME}.md`,
+            heading: WRITE_PROTOCOL_HEADING,
+            content,
+            tokens: estimateTokens(content),
+            triggers: [...WRITE_PROTOCOL_TRIGGERS],
+            sourceStartLine: 0,
+            sourceEndLine: 0,
+            reason: "generated",
+            kind: "procedural",
+            generated: true,
+        });
+    }
+    const stubBody = renderAlwaysOnBody("", title, stableText, alwaysOnSections, profile);
+    const alwaysOnBody = renderAlwaysOnBody(frontmatter, title, stableText, alwaysOnSections, profile);
+    const onDemandList = renderOnDemandList(merged, profile.length === 0);
+    const stubOnDemandList = renderOnDemandList(merged, profile.length === 0, `${COMPILED_DIR_NAME}/`);
+    const stub = renderStub(frontmatter, stubBody, stubOnDemandList, merged.length);
+    const alwaysOn = renderAlwaysOn(alwaysOnBody, onDemandList, merged.length);
+    return {
+        title,
+        sourceName: options.sourceName,
+        sourceHash: hash(source),
+        frontmatter,
+        alwaysOnBody,
+        onDemandList,
+        alwaysOn,
+        stub,
+        onDemandFiles: merged,
+        before: estimateTokens(source),
+        after: estimateTokens(stub),
+        instructionTokens: estimateTokens(renderInstructions(profile)),
+        budget,
+        demoted: demoted
+            .sort((a, b) => a.section.startLine - b.section.startLine)
+            .map((d) => ({ heading: d.section.heading, tokens: d.tokens })),
+    };
+}
+export function buildManifest(compiled, tokenizer) {
+    return {
+        version: 4,
+        tokenizer,
+        generatedFrom: compiled.sourceName,
+        sourceHash: compiled.sourceHash,
+        instructionStatus: "output-side rules measured 2026-09-05; context-side rules unmeasured; see the Measurement policy section of the MinniMemoryMCP README",
+        order: compiled.onDemandFiles.map((m) => m.name),
+        prefix: { before: compiled.before, after: compiled.after },
+        always: { file: ALWAYS_ON_FILE_NAME, tokens: estimateTokens(compiled.alwaysOn), hash: hash(compiled.alwaysOn) },
+        stub: { file: compiled.sourceName, tokens: estimateTokens(compiled.stub), hash: hash(compiled.stub) },
+        onDemandFiles: compiled.onDemandFiles.map((m) => ({
+            name: m.name,
+            file: m.file,
+            tokens: m.tokens,
+            hash: driftHash(m.content),
+            triggers: m.triggers,
+            sourceLines: [m.sourceStartLine, m.sourceEndLine],
+            reason: m.reason,
+            kind: m.kind,
+            generated: m.generated ?? false,
+        })),
+    };
+}

package/dist/discover.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Work out what kind of memory setup we are pointed at, and which files the model
+ * actually pays for on every turn.
+ */
+import type { Workspace } from "./types.js";
+/** Memory files a host agent loads automatically. */
+export declare const HOST_FILES: string[];
+/** Names that mean "this is the OnDemandMemory list for the directory". */
+export declare const LIST_FILE_NAMES: string[];
+/**
+ * Directories never descended into when looking for memory content.
+ * This governs traversal only. A directory named here is still audited when the user
+ * points at it explicitly, which is how an archived corpus gets inspected.
+ */
+export declare const SKIP_DIRS: Set<string>;
+export declare class DiscoveryError extends Error {
+}
+/** True for a regular file that is not a symlink. `lstat` on purpose: a cloned repo can ship a link. */
+export declare function isPlainFile(abs: string): boolean;
+/**
+ * Which tool surface a root can support, decided from directory entries alone.
+ *
+ * `createMcpServer` needs the shape of a root before it registers anything, on every launch.
+ * `discover()` cannot serve that: it reads the content of every memory file and folds in the
+ * auto-memory folder, which is most of the 310 to 380ms `doctor` cost the 2026-09-13 audit
+ * measured against a 68-file corpus. This probe does `stat` only, never a read, and tests the
+ * one distinction that changes the answer: `discover()` checks for `.minnimemory/` before it
+ * checks any other shape, so agreeing with it on a compiled root is the whole job. Every other
+ * shape it can return maps to the same "setup" surface.
+ *
+ * Every failure resolves to "setup": that surface holds the tools that diagnose and repair a
+ * root, so a root we cannot classify gets the tools that can tell the user why.
+ *
+ * Requires `manifest.json` inside `.minnimemory/` too (stat only, never read): a bare
+ * `.minnimemory/` directory with nothing compiled into it yet is `setup`, not `compiled`.
+ *
+ * `memory-dir` (added 2026-09-16, manifest-less recall): a root with no `.minnimemory/` at all
+ * that would still discover() to shape `memory-dir` or `auto-memory` - an index file (one of
+ * `LIST_FILE_NAMES`) plus topic files, three or more loose markdown files with no index, or a
+ * Claude Code auto-memory folder with content. Decided the same cheap way as the rest of this
+ * function: directory entries and a stat per candidate, never a file read, so this stays the
+ * probe discover() itself is too expensive to be. A root with a `.minnimemory/` directory (even
+ * an empty one, or one missing its manifest) never falls through to this check - `.minnimemory/`
+ * existing at all means "setup", exactly as before.
+ */
+export type WorkspacePhase = "compiled" | "memory-dir" | "setup";
+export declare function detectPhase(root: string): WorkspacePhase;
+export interface ImportResolution {
+    /** absolute paths of imported files inside the workspace root */
+    files: string[];
+    /**
+     * Imports that resolved outside the root and were not read. Reported as the raw text the
+     * memory file wrote, never as a resolved absolute path: the point is to not disclose where
+     * on this machine the target would have been.
+     */
+    skipped: string[];
+}
+/**
+ * Resolve the files a memory file pulls into the always-loaded prefix through `@path` imports,
+ * the way Claude Code does: relative to the importing file, `~/` allowed, recursive to a depth
+ * of five, each file once. A path that does not resolve is ignored rather than reported: an
+ * `@` in prose is not an error.
+ *
+ * Imports that land outside `root` are NOT followed unless `followExternal` is set.
+ *
+ * The memory file being audited is frequently one you did not write - the whole pitch is
+ * pointing this at a repo, including in CI - and an `@` line is content that repo controls.
+ * Following `@~/.claude/CLAUDE.md` from a cloned repo read seventeen files out of the auditor's
+ * home directory, whose headings, frontmatter, body-derived keywords and credential prefixes
+ * then surfaced in doctor and scan output. This is the same threat findHostFile already refuses
+ * symlinks for ("a cloned repo can point a memory file at anything on your machine"); imports
+ * were the second door to the same room.
+ *
+ * Following them remains correct for your own repo, where an out-of-root import genuinely is
+ * part of the prefix you pay for, so it stays available - as a decision the person running the
+ * tool makes, not one the scanned repo makes for them.
+ */
+export declare function resolveImports(hostAbs: string, root: string, followExternal?: boolean): ImportResolution;
+/**
+ * A pointer stub is a host file whose entire content, headings and comments aside, names one
+ * other memory file: "@AGENTS.md", "AGENTS.md", "See `AGENTS.md` for the shared instructions".
+ * Eight of the twenty-three public CLAUDE.md files in the 2026-09-02 sweep were exactly this.
+ * Returns the absolute path of the named file when it exists next to the host, else undefined.
+ */
+export declare function pointerTargetOf(hostAbs: string, content: string): string | undefined;
+/**
+ * Claude Code's own project-key algorithm, reverse-engineered empirically (not published), and
+ * verified against this machine's real `~/.claude/projects/` folder names across a dozen
+ * independent examples, including nested repos and a path containing `&`: every character that
+ * is not a-z, A-Z, or 0-9 becomes a single `-`. No collapsing of adjacent replacements, no case
+ * change. `C:\Code` -> `C--Code`; `C:\Code\Widgets\App` -> `C--Code-Widgets-App`.
+ */
+export declare function claudeProjectSlug(absPath: string): string;
+/**
+ * Locate the auto-memory folder that belongs to `target`, the same way Claude Code itself would
+ * resolve it: git-repo-root if `target` is inside a repo, `target` itself otherwise, then
+ * Claude Code's own slug algorithm. Returns undefined, never throws, when nothing is found there -
+ * most targets simply have never been launched with Claude Code and that is not an error.
+ */
+export declare function locateAutoMemoryDir(target: string): string | undefined;
+export interface DiscoverOptions {
+    /**
+     * Follow `@path` imports that resolve outside the workspace root. Off by default: the file
+     * being audited is often one you did not write. See resolveImports.
+     */
+    followExternalImports?: boolean;
+    /**
+     * Fold in Claude Code's OS-level auto-memory folder (`~/.claude/projects/<slug>/memory/`),
+     * outside the target directory entirely. Default true - this is the two-location unification
+     * feature, and the CLI's own `doctor`/`bench` intentionally see it with no flag needed, since
+     * the operator running the CLI on their own machine and the memory it audits are the same
+     * party. Explicitly set false for the MCP server's scan/doctor tools: a target confined to
+     * "this server's root" per their own descriptions must not silently widen to the operator's
+     * entire global memory, the same category of reach `followExternalImports` already gates for
+     * `@path` imports (2026-09-10 audit).
+     */
+    includeAutoMemory?: boolean;
+}
+/**
+ * Inspect `target` and build a Workspace.
+ *
+ * The important output is which files carry `alwaysLoaded: true`, because that set is what
+ * the whole tool is trying to shrink.
+ */
+export declare function discover(target: string, options?: DiscoverOptions): Workspace;