minnimemory 1.0.0-beta.1

package/dist/text.js

@@ -0,0 +1,395 @@
+/**
+ * Text primitives shared by the rule engine and the compiler.
+ */
+// No lazy capture followed by `\s*$`: that pair is quadratic on a heading padded with
+// thousands of spaces (security audit 2026-09-02). Trim in code instead.
+const RE_HEADING = /^(#{1,6})\s+(.*)$/;
+const RE_FENCE = /^\s*(?:```|~~~)/;
+/**
+ * Split lines into heading-delimited sections. Lines inside fenced code blocks are never
+ * headings: a shell comment like `# Machine-readable output` in a bash example is not a title.
+ * Found by the 2026-09-02 sweep, where one real CLAUDE.md gained a phantom H1 mid-file and
+ * half its content was duplicated into AlwaysOnMemory as "preamble".
+ */
+export function sections(lines) {
+    const out = [];
+    let current;
+    let inFence = false;
+    lines.forEach((line, i) => {
+        if (RE_FENCE.test(line)) {
+            inFence = !inFence;
+            return;
+        }
+        if (inFence)
+            return;
+        const m = RE_HEADING.exec(line);
+        if (!m)
+            return;
+        if (current) {
+            current.endLine = i;
+            out.push(current);
+        }
+        current = {
+            heading: (m[2] ?? "").trim(),
+            level: (m[1] ?? "#").length,
+            startLine: i + 1,
+            endLine: lines.length,
+        };
+    });
+    if (current)
+        out.push(current);
+    if (out.length === 0) {
+        out.push({ heading: "(document)", level: 0, startLine: 1, endLine: lines.length });
+    }
+    return out;
+}
+/** Split lines into blank-line-delimited blocks. */
+export function blocks(lines) {
+    const out = [];
+    let buf = [];
+    let start = 1;
+    const flush = (endLine) => {
+        const text = buf.join("\n").trim();
+        if (text)
+            out.push({ text, startLine: start, endLine });
+        buf = [];
+    };
+    lines.forEach((line, i) => {
+        if (line.trim() === "") {
+            flush(i);
+            start = i + 2;
+        }
+        else {
+            if (buf.length === 0)
+                start = i + 1;
+            buf.push(line);
+        }
+    });
+    flush(lines.length);
+    return out;
+}
+/** Normalise a block so cosmetic differences do not hide a duplicate. */
+export function normalise(text) {
+    return text
+        .split("\n")
+        .map((l) => l.replace(/^\s*(?:[-*+]|\d+\.|#{1,6})\s*/, "").trim())
+        .join(" ")
+        .replace(/\s+/g, " ")
+        .toLowerCase()
+        .trim();
+}
+/** Filesystem-safe, stable slug for a heading. */
+export function slugify(heading) {
+    const base = heading
+        .toLowerCase()
+        .replace(/[`*_~]/g, "")
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .replace(/_{2,}/g, "_");
+    const capped = base.length > 40 ? base.slice(0, 40).replace(/_[^_]*$/, "") : base;
+    return capped || base || "section";
+}
+/**
+ * Volatility: does this content change often, so that editing it would invalidate the cached
+ * always-loaded prefix?
+ *
+ * This is scored on evidence, not fired by a single word. The 2026-09-02 sweep over 23 real
+ * CLAUDE.md/AGENTS.md files from public repos showed that one-word matching flagged stable
+ * sections constantly: a version number inside a URL, "the next step" in a coding standard,
+ * "regenerate the changelog" in commit guidance, "pending activity" in a debugging note. Those
+ * are prose, not status. What actually marks status is a status heading, dated log entries,
+ * checklists, or several status phrases together.
+ *
+ * Scoring (a section is volatile at VOLATILITY_THRESHOLD or above):
+ *   status heading ("Current status", "Changelog", "Roadmap", "Open items"...)   +2
+ *   list item that starts with a date (a log entry)                               +1 each
+ *   strong status phrase ("as of 2026", "in progress", "blocked on")              +1 each
+ *   date anywhere else in a line                                                  +0.5 each
+ *   weak status word ("currently", "pending", "todo", "roadmap" in prose)         +0.5 each
+ *   checkbox item                                                    +0.25 each, at most +1
+ *   version string                                                                +0.25 each
+ * Inline code spans and URLs are removed from a line before matching, so a version in a link
+ * or a `TODO` in a code sample never counts.
+ */
+export const VOLATILITY_THRESHOLD = 2;
+/**
+ * Interface rule O7, the granularity clause: a section above this many tokens carries
+ * subheadings so that retrieval has a unit smaller than the whole. `doctor` flags a flat
+ * section over it (MM009); `init` splits a section over it at its subheadings into separate
+ * OnDemandMemory files, so the agent-driven route (an agent reading a whole file the
+ * OnDemandMemory list named) gets the same granularity `recall` gets from in-file sections.
+ */
+export const GRANULARITY_TOKENS = 800;
+/**
+ * A bullet (list marker or numbered item) whose first few words carry a date: a changelog or
+ * session-log entry. The single shared definition (2026-09-13 audit round 2, D7a) - episodic.ts,
+ * router.ts and rules.ts's MM009 each grew their own slightly different copy (one required a full
+ * day, one skipped numbered lists, one had an explicit checkbox branch this pattern's lazy
+ * 0-24-character window already covers). This is the widest of the three: numbered lists
+ * (`1.`/`1)`), a month-only date, and up to 24 characters (a checkbox, a bold marker, ...) before
+ * the date all count.
+ */
+export const RE_DATED_BULLET = /^\s*(?:[-*+]|\d+[.)])\s+(?:\*\*)?[^\n]{0,24}?\b20\d{2}-\d{2}(?:-\d{2})?\b/;
+const RE_ANY_BULLET = /^\s*(?:[-*+]|\d+[.)])\s+/;
+/**
+ * Is this body of lines "episodic": mostly a list of dated entries (a changelog, a session log)?
+ * At least 3 dated bullets, and at least half of all bullets dated. The one rule every episodic-
+ * detection call site in the codebase now shares, so "how many dated entries make a section a
+ * changelog" has one answer instead of three.
+ */
+export function isEpisodicBody(lines) {
+    const bullets = lines.filter((l) => RE_ANY_BULLET.test(l));
+    const dated = bullets.filter((l) => RE_DATED_BULLET.test(l));
+    return dated.length >= 3 && dated.length * 2 >= bullets.length;
+}
+// "status" counts only when it is the topic of the heading ("Status", "Current status",
+// "Project status"), not a word inside one ("PR Status (CI Failures and Reviews)").
+const RE_STATUS_HEADING = /(?:^\s*#*\s*(?:[\w-]+\s){0,2}status\s*$)|\b(?:changelog|change log|roadmap|to-?dos?|open items?|next steps|known issues|in progress|wip|backlog|progress log|session log|current (?:state|work|focus|sprint|plan))\b/i;
+const RE_DATE = /\b20\d{2}-\d{2}-\d{2}\b/g;
+const RE_CHECKBOX = /^\s*[-*+]\s*\[[ xX]\]/;
+const RE_STATUS_STRONG = /\b(?:as of (?:20\d{2}|today|now|this)|in progress|current (?:status|state|sprint|plan)|todo:|wip:|blocked on|still (?:open|pending|unresolved|blocked))\b/gi;
+// "currently" is weak: "currently unsupported" is a stable fact far more often than a status.
+const RE_STATUS_WEAK = /\b(?:currently|pending|next steps|changelog|roadmap|open items?|todo|wip)\b/gi;
+/** Checkboxes alone never decide: a PR-review checklist template is stable content. */
+const CHECKLIST_CAP = 1;
+const RE_VERSION = /\bv\d+\.\d+\.\d+\b/g;
+const RE_INLINE_CODE = /`[^`\n]*`/g;
+const RE_URL = /\bhttps?:\/\/\S+/g;
+function countMatches(re, text) {
+    re.lastIndex = 0;
+    let n = 0;
+    while (re.exec(text))
+        n++;
+    return n;
+}
+/**
+ * Score a run of lines. Pass the heading line as `heading` when the lines are a section body;
+ * pass an empty string for a headingless block. A heading with no body is never volatile: a
+ * title cannot be edited often when there is nothing under it to edit.
+ */
+export function volatility(heading, bodyLines) {
+    const body = bodyLines.join("\n");
+    if (body.trim() === "")
+        return { score: 0, reasons: [] };
+    let score = 0;
+    const found = { heading: 0, dated: 0, checklist: 0, status: 0, version: 0 };
+    if (RE_STATUS_HEADING.test(heading)) {
+        score += 2;
+        found.heading++;
+    }
+    for (const raw of bodyLines) {
+        const line = raw.replace(RE_INLINE_CODE, " ").replace(RE_URL, " ");
+        if (line.trim() === "")
+            continue;
+        if (RE_DATED_BULLET.test(line)) {
+            score += 1;
+            found.dated++;
+        }
+        else {
+            const dates = countMatches(RE_DATE, line);
+            if (dates > 0) {
+                score += 0.5 * dates;
+                found.dated += dates;
+            }
+        }
+        if (RE_CHECKBOX.test(line)) {
+            if (found.checklist * 0.25 < CHECKLIST_CAP)
+                score += 0.25;
+            found.checklist++;
+        }
+        const strong = countMatches(RE_STATUS_STRONG, line);
+        if (strong > 0) {
+            score += strong;
+            found.status += strong;
+        }
+        const weak = countMatches(RE_STATUS_WEAK, line);
+        if (weak > 0) {
+            score += 0.5 * weak;
+            found.status += weak;
+        }
+        const versions = countMatches(RE_VERSION, line);
+        if (versions > 0) {
+            score += 0.25 * versions;
+            found.version += versions;
+        }
+    }
+    const reasons = [];
+    if (found.heading)
+        reasons.push("a status heading");
+    if (found.dated)
+        reasons.push("dated entries");
+    if (found.checklist)
+        reasons.push("checklist items");
+    if (found.status)
+        reasons.push("status language");
+    if (found.version)
+        reasons.push("a version string");
+    return { score, reasons };
+}
+/** Reasons a headingless block is volatile; empty when it is not. */
+export function volatilityReasons(text) {
+    const v = volatility("", text.split("\n"));
+    return v.score >= VOLATILITY_THRESHOLD ? v.reasons : [];
+}
+/** Reasons a heading-led section is volatile; empty when it is not. */
+export function sectionVolatilityReasons(sectionLines) {
+    const v = volatility(sectionLines[0] ?? "", sectionLines.slice(1));
+    return v.score >= VOLATILITY_THRESHOLD ? v.reasons : [];
+}
+/** Delimiters around the generated regions of a stub: the OnDemandMemory list and the instruction block. */
+export const LIST_START = "<!-- minnimemory:ondemand-list -->";
+export const LIST_END = "<!-- /minnimemory:ondemand-list -->";
+export const INSTRUCTIONS_START = "<!-- minnimemory:instructions -->";
+export const INSTRUCTIONS_END = "<!-- /minnimemory:instructions -->";
+/**
+ * Locate one generated region. Only a single well-formed pair counts: the first opening marker
+ * that is followed by a closing marker. An unclosed opener, a second pair, or a closer with no
+ * opener is ignored, so a marker pasted into prose cannot hide the rest of a file from the
+ * rules (security audit 2026-09-02, finding 5). Returns 0-based inclusive line indices.
+ */
+export function generatedRegion(lines, start, end) {
+    const from = lines.findIndex((l) => l.trim() === start);
+    if (from < 0)
+        return undefined;
+    const to = lines.findIndex((l, i) => i > from && l.trim() === end);
+    if (to < 0)
+        return undefined;
+    return { from, to };
+}
+/**
+ * Blank out the generated regions, line for line so line numbers are preserved. The
+ * OnDemandMemory list is a routing manifest: its trigger words ("changelog", "open items") are
+ * labels for OnDemandMemory files, not status, and it only changes when a file is added or
+ * removed. The instruction block is fixed text. Auditing either as prose would make `doctor`
+ * flag `init`'s own output.
+ */
+export function stripGeneratedRegions(lines) {
+    const out = [...lines];
+    for (const [s, e] of [
+        [LIST_START, LIST_END],
+        [INSTRUCTIONS_START, INSTRUCTIONS_END],
+    ]) {
+        const r = generatedRegion(out, s, e);
+        if (!r)
+            continue;
+        for (let i = r.from; i <= r.to; i++)
+            out[i] = "";
+    }
+    return out;
+}
+/** Kept for callers that only know about the OnDemandMemory list region. */
+export const stripGeneratedList = stripGeneratedRegions;
+/**
+ * The inverse of `stripGeneratedRegions`: blank every line outside one marked region, keeping
+ * the region's own lines verbatim at their real position. Line numbers stay meaningful for a
+ * region carved out of a larger always-loaded file (compile.ts's merged AlwaysOnMemory.md holds
+ * always-on prose and the OnDemandMemory list in one file; this is how a caller gets just the
+ * list's lines back without losing the line numbers a finding reports against the real file).
+ */
+export function regionOnly(lines, start, end) {
+    const region = generatedRegion(lines, start, end);
+    if (!region)
+        return lines.map(() => "");
+    return lines.map((l, i) => (i >= region.from && i <= region.to ? l : ""));
+}
+/**
+ * Leading YAML frontmatter: a `---` line first, closed by the next `---` line. Returned as the
+ * verbatim lines plus the 1-indexed line number where the document body begins. Frontmatter has
+ * to stay first in a file to remain frontmatter, so the compiler carries it through untouched
+ * instead of treating it as preamble prose.
+ */
+export function splitFrontmatter(lines) {
+    if ((lines[0] ?? "").trim() !== "---")
+        return { frontmatter: [], bodyStartLine: 1 };
+    for (let i = 1; i < lines.length; i++) {
+        if ((lines[i] ?? "").trim() === "---") {
+            return { frontmatter: lines.slice(0, i + 1), bodyStartLine: i + 2 };
+        }
+    }
+    // An opening fence with no close is not frontmatter, just a line of dashes.
+    return { frontmatter: [], bodyStartLine: 1 };
+}
+export const STOPWORDS = new Set([
+    "the", "and", "for", "that", "this", "with", "from", "are", "was", "were", "you", "your", "our", "its", "it",
+    "not", "but", "all", "any", "can", "has", "have", "had", "will", "would", "should", "must", "may", "when",
+    "what", "which", "who", "how", "why", "into", "over", "under", "then", "than", "them", "they", "their",
+    "itself", "himself", "herself", "themselves", "yourself", "yourselves", "ourselves",
+    "there", "here", "only", "also", "just", "use", "used", "using", "via", "per", "one", "two", "three", "new",
+    "run", "see", "get", "set", "add", "make", "made", "does", "did", "done", "been", "being", "each", "every",
+    "some", "such", "same", "other", "more", "most", "less", "least", "very", "much", "many", "few", "own",
+    "about", "after", "before", "between", "during", "without", "within", "because", "while", "where",
+    "these", "those", "both", "either", "neither", "however", "therefore", "instead", "rather", "always",
+    "never", "often", "already", "still", "yet", "once", "first", "last", "next", "file", "files", "line",
+    "lines", "code", "project", "repo", "repository", "note", "notes", "md", "http", "https", "www", "com",
+    // contraction fragments left behind by word splitting
+    "don", "doesn", "isn", "aren", "wasn", "weren", "won", "wouldn", "couldn", "shouldn", "didn", "hasn",
+    "haven", "hadn", "ll", "ve", "re", "ain", "let", "its",
+    // generic filler that ranks high on frequency but routes nowhere
+    "actually", "enough", "happens", "result", "results", "content", "thing", "things", "way", "ways",
+    "need", "needs", "want", "wants", "give", "given", "gets", "goes", "going", "take", "takes", "comes",
+    "asked", "asks", "answer", "answers", "said", "says", "tell", "tells", "show", "shows", "know", "known",
+    "something", "anything", "everything", "nothing", "someone", "anyone", "everyone", "stuff", "kind",
+    "sort", "lot", "bit", "good", "bad", "best", "worse", "worst", "real", "really", "quite", "pretty",
+    // seen ranking as triggers in the 2026-09-02 real-world sweep; none of them route anywhere
+    "etc", "foo", "bar", "baz", "important", "key", "existing", "adding", "acting", "case", "empty",
+    "closest", "check", "change", "changes", "changed", "following", "above", "below", "example",
+    "examples", "section", "sections", "item", "items", "step", "steps", "open", "closed", "list",
+    // the connective in a merged OnDemandMemory file's heading ("Common tasks through Changelog")
+    "through",
+]);
+/** A code token's raw frequency inside a fenced block, relative to a comment or prose word. */
+export const CODE_WEIGHT = 0.2;
+/**
+ * Split body text into (fragment, weight) pieces for keyword extraction: prose and `#` comment
+ * text keep weight 1, the command/flag/tool-name text around a comment inside a fenced code
+ * block is down-weighted, so a repeated tool name doesn't drown out a rare-but-specific comment
+ * word under raw frequency. Found live (2026-09-09): an OnDemandMemory file whose only mentions of "UAC" and
+ * "window" were in comments lost to "npm"/"venv"/"pester" appearing many times across unrelated
+ * commands sharing one section, so a question phrased the way a user actually asks it ("run
+ * without a UAC prompt") matched no trigger at all. Shared by `keywords()` below and
+ * `router.ts`'s `selectTriggers()`, the two places that rank candidate routing words this way.
+ */
+export function weightedFragments(body) {
+    const out = [];
+    let inFence = false;
+    for (const line of body.split(/\r?\n/)) {
+        if (RE_FENCE.test(line)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (!inFence) {
+            out.push({ text: line, weight: 1 });
+            continue;
+        }
+        const hash = line.indexOf("#");
+        if (hash === -1) {
+            out.push({ text: line, weight: CODE_WEIGHT });
+            continue;
+        }
+        out.push({ text: line.slice(0, hash), weight: CODE_WEIGHT });
+        out.push({ text: line.slice(hash + 1), weight: 1 });
+    }
+    return out;
+}
+/**
+ * Pull candidate routing keywords out of a piece of text.
+ * Frequency-ranked, stopword-filtered, and biased toward terms in the heading.
+ */
+export function keywords(heading, body, limit = 6) {
+    const counts = new Map();
+    const add = (source, weight) => {
+        const words = source.toLowerCase().match(/[a-z][a-z0-9_-]{2,}/g) ?? [];
+        for (const w of words) {
+            if (STOPWORDS.has(w))
+                continue;
+            counts.set(w, (counts.get(w) ?? 0) + weight);
+        }
+    };
+    add(heading, 5);
+    for (const { text, weight } of weightedFragments(body))
+        add(text, weight);
+    return [...counts.entries()]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, limit)
+        .map(([w]) => w);
+}

package/dist/tokenizer.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Offline token estimation.
+ *
+ * `doctor` and `init` must work with no network access and no API key, so the default
+ * tokenizer is a heuristic rather than a real BPE encoder.
+ *
+ * approx-v2, calibrated 2026-09-02. The rules below were fitted against OpenAI's o200k_base
+ * encoder (the cl100k_base result is within 1%) over 73 real memory files: 23 CLAUDE.md and
+ * AGENTS.md files from public repositories plus a 50-file personal Claude Code memory
+ * directory, 240 KB in total. Result on whole files: estimate / o200k mean 1.00, standard
+ * deviation 0.04, range 0.91 to 1.08. The previous approx-v1 overstated by 43% on the same
+ * corpus, worst on code-heavy files, because it charged every punctuation character a whole
+ * token and every four letters a token.
+ *
+ * Anthropic does not publish the tokenizer for current Claude models, so this is calibrated
+ * to a proxy, and figures the tool prints are comparable with each other rather than exact
+ * for any one model. Numbers are always labelled with this tokenizer id.
+ */
+export declare const TOKENIZER_ID = "approx-v2";
+/**
+ * Estimate the number of tokens in a string.
+ * Deterministic, allocation-light, and safe on empty input.
+ */
+export declare function estimateTokens(text: string): number;
+/** Format a token count for display, for example 11240 -> "11,240". */
+export declare function formatTokens(n: number): string;

package/dist/tokenizer.js

@@ -0,0 +1,69 @@
+/**
+ * Offline token estimation.
+ *
+ * `doctor` and `init` must work with no network access and no API key, so the default
+ * tokenizer is a heuristic rather than a real BPE encoder.
+ *
+ * approx-v2, calibrated 2026-09-02. The rules below were fitted against OpenAI's o200k_base
+ * encoder (the cl100k_base result is within 1%) over 73 real memory files: 23 CLAUDE.md and
+ * AGENTS.md files from public repositories plus a 50-file personal Claude Code memory
+ * directory, 240 KB in total. Result on whole files: estimate / o200k mean 1.00, standard
+ * deviation 0.04, range 0.91 to 1.08. The previous approx-v1 overstated by 43% on the same
+ * corpus, worst on code-heavy files, because it charged every punctuation character a whole
+ * token and every four letters a token.
+ *
+ * Anthropic does not publish the tokenizer for current Claude models, so this is calibrated
+ * to a proxy, and figures the tool prints are comparable with each other rather than exact
+ * for any one model. Numbers are always labelled with this tokenizer id.
+ */
+export const TOKENIZER_ID = "approx-v2";
+const RE_PIECES = /\s+|[A-Za-z]+|[0-9]+|[^\sA-Za-z0-9]/g;
+/** Fitted so the corpus mean lands on 1.00; the rule set alone lands on 0.95. */
+const CALIBRATION = 1.05;
+/**
+ * Estimate the number of tokens in a string.
+ * Deterministic, allocation-light, and safe on empty input.
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    const pieces = text.match(RE_PIECES);
+    if (!pieces)
+        return 0;
+    let tokens = 0;
+    let previousSymbol = null;
+    for (const piece of pieces) {
+        const first = piece.charCodeAt(0);
+        // Whitespace run: a single space merges into the following word; each newline costs one.
+        if (piece.trimStart() === "") {
+            for (let i = 0; i < piece.length; i++) {
+                if (piece.charCodeAt(i) === 10)
+                    tokens++;
+            }
+            previousSymbol = null;
+            continue;
+        }
+        // Letters: common words up to about seven letters are one token; longer words split
+        // roughly every five letters after that.
+        if ((first >= 65 && first <= 90) || (first >= 97 && first <= 122)) {
+            tokens += 1 + Math.floor(Math.max(0, piece.length - 7) / 5);
+            previousSymbol = null;
+            continue;
+        }
+        // Digits: encoders group numbers in runs of up to three digits.
+        if (first >= 48 && first <= 57) {
+            tokens += Math.ceil(piece.length / 3);
+            previousSymbol = null;
+            continue;
+        }
+        // A punctuation or symbol character. Most merge with a neighbour (":/" "()" "**"), so one
+        // costs well under a token, and a repeat of the same symbol ("---", "```") costs less again.
+        tokens += previousSymbol === piece ? 0.35 : 0.7;
+        previousSymbol = piece;
+    }
+    return Math.round(tokens * CALIBRATION);
+}
+/** Format a token count for display, for example 11240 -> "11,240". */
+export function formatTokens(n) {
+    return n.toLocaleString("en-US");
+}

package/dist/types.d.ts

@@ -0,0 +1,156 @@
+/**
+ * Shared types for the minnimemory rule engine.
+ */
+export type Severity = "low" | "med" | "high";
+export declare const SEVERITY_ORDER: Record<Severity, number>;
+/** What role a memory file plays in the context window. */
+export type FileKind = 
+/** the host's own memory file, for example CLAUDE.md */
+"host"
+/** compiled AlwaysOnMemory body */
+ | "alwaysOn"
+/** compiled OnDemandMemory list */
+ | "onDemandList"
+/** compiled OnDemandMemory file */
+ | "onDemand"
+/** an uncompiled memory file sitting loose in a directory */
+ | "loose"
+/** a file the host file pulls in: a Claude Code `@path` import, or the target of a pointer stub */
+ | "import";
+export interface MemoryFile {
+    abs: string;
+    /** path relative to the workspace root, always with forward slashes */
+    rel: string;
+    content: string;
+    lines: string[];
+    tokens: number;
+    /** true when this file is re-sent to the model on every turn */
+    alwaysLoaded: boolean;
+    kind: FileKind;
+    /**
+     * True when this file's content is intentionally mirrored into a generated stub.
+     * Duplication rules skip these: the copy is the design, not a defect.
+     */
+    generated?: boolean;
+}
+export type WorkspaceShape = 
+/** a single memory file passed directly */
+"single-file"
+/** a repo with a host memory file at its root */
+ | "host-file"
+/** a repo already compiled into .minnimemory/ */
+ | "compiled"
+/** a directory of memory files, with or without an OnDemandMemory list */
+ | "memory-dir"
+/** a project with no host file of its own whose Claude Code auto-memory folder exists */
+ | "auto-memory";
+export interface Workspace {
+    root: string;
+    shape: WorkspaceShape;
+    files: MemoryFile[];
+    /** the OnDemandMemory list, when one was found */
+    onDemandList?: MemoryFile;
+    /**
+     * The auto-memory folder's own MEMORY.md, when that folder was folded in. It governs the
+     * `(auto-memory)/` topic files, while `onDemandList` governs compiled OnDemandMemory files;
+     * MM004 and MM006 check each file against the list that actually routes to it.
+     */
+    autoMemoryList?: MemoryFile;
+    /**
+     * The auto-memory folder folded into this workspace, when Claude Code's own project-key
+     * algorithm resolves one for `root` (or its git repo root) and it exists on disk. A genuinely
+     * different directory than `root` - see discover.ts's locateAutoMemoryDir(). Undefined means
+     * none was found, not that the lookup was skipped.
+     */
+    autoMemoryRoot?: string;
+    /**
+     * Set when the host file is a pointer stub: a tiny file whose whole content names another
+     * memory file ("@AGENTS.md", "AGENTS.md", "See `AGENTS.md`"). The named file is what the
+     * agent actually reads, so it is included as an always-loaded import and `init` compiles it
+     * instead of the stub. Workspace-relative path of that target.
+     */
+    pointerTarget?: string;
+    /**
+     * The compiled workspace's manifest, parsed, when the shape is `compiled` and the file is
+     * valid JSON. Rules that compare what is on disk against what `init` wrote (MM010, drift)
+     * read it from here; nothing else does, and an unreadable manifest simply leaves it unset.
+     */
+    manifest?: CompiledManifest;
+    /**
+     * `@path` imports that pointed outside the root and were not followed. Present so a report
+     * can say the always-loaded total is incomplete rather than quietly under-counting it.
+     */
+    skippedImports?: string[];
+}
+/** The subset of manifest.json the rule engine reads; the full shape lives in compile.ts. */
+export interface CompiledManifest {
+    sourceHash: string;
+    always: {
+        file: string;
+        hash: string;
+    };
+    /** absent in a workspace compiled before manifest v3, so MM010 checks it only when present */
+    stub?: {
+        file: string;
+        hash: string;
+    };
+    onDemandFiles: {
+        name: string;
+        file: string;
+        hash: string;
+    }[];
+}
+export interface Finding {
+    rule: string;
+    severity: Severity;
+    message: string;
+    /** workspace-relative path */
+    file: string;
+    /** 1-indexed, inclusive */
+    startLine?: number;
+    endLine?: number;
+    /** tokens implicated by this finding, when the number is meaningful */
+    tokens?: number;
+    /** short suggested remedy */
+    hint?: string;
+    /** true for the synthetic "and N more" marker, which always sorts last in its group */
+    overflow?: boolean;
+}
+export interface DoctorConfig {
+    /** token ceiling for the always-loaded prefix (MM001) */
+    budget: number;
+    /** rule ids to skip */
+    ignore: string[];
+    /** when non-empty, run only these rule ids */
+    only: string[];
+    /** exit non-zero at this severity or above */
+    failOn: Severity;
+    /** OnDemandMemory list line character cap (MM006) */
+    maxListLine: number;
+    /** follow `@path` imports that resolve outside the workspace root (off by default) */
+    followExternalImports: boolean;
+    /** fold in the OS-level Claude Code auto-memory folder (on by default - see DiscoverOptions) */
+    includeAutoMemory: boolean;
+}
+export declare const DEFAULT_CONFIG: DoctorConfig;
+export interface RuleContext {
+    workspace: Workspace;
+    config: DoctorConfig;
+}
+export interface Rule {
+    id: string;
+    severity: Severity;
+    title: string;
+    run(ctx: RuleContext): Finding[];
+}
+export interface DoctorResult {
+    workspace: Workspace;
+    findings: Finding[];
+    /** total tokens re-sent on every turn */
+    alwaysLoadedTokens: number;
+    /** number of files contributing to the always-loaded prefix */
+    alwaysLoadedFiles: number;
+    tokenizer: string;
+}
+/** Files that are re-sent on every turn. */
+export declare function alwaysLoaded(ws: Workspace): MemoryFile[];

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * Shared types for the minnimemory rule engine.
+ */
+export const SEVERITY_ORDER = { low: 0, med: 1, high: 2 };
+export const DEFAULT_CONFIG = {
+    budget: 2000,
+    ignore: [],
+    only: [],
+    failOn: "high",
+    maxListLine: 120,
+    followExternalImports: false,
+    includeAutoMemory: true,
+};
+/** Files that are re-sent on every turn. */
+export function alwaysLoaded(ws) {
+    return ws.files.filter((f) => f.alwaysLoaded);
+}

package/dist/version.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The single source of the version string. Before this file, "0.1.0" was hand-typed in four
+ * places (cli.ts's own VERSION constant, and both McpServer constructors in mcpServer.ts), which
+ * is how they drift: a bump to one place with the others forgotten is silent, since nothing
+ * compares them.
+ */
+export declare const VERSION = "1.0.0-beta.1";