minnimemory 1.0.0-beta.1

package/dist/discover.js

@@ -0,0 +1,520 @@
+/**
+ * Work out what kind of memory setup we are pointed at, and which files the model
+ * actually pays for on every turn.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { ALWAYS_ON_FILE_NAME, COMPILED_DIR_NAME, isStub, ON_DEMAND_DIR_NAME } from "./compile.js";
+import { containedIn } from "./paths.js";
+import { LIST_END, LIST_START, regionOnly } from "./text.js";
+import { estimateTokens } from "./tokenizer.js";
+/** Memory files a host agent loads automatically. */
+export const HOST_FILES = ["CLAUDE.md", "AGENTS.md", "GEMINI.md", ".cursorrules"];
+/** Names that mean "this is the OnDemandMemory list for the directory". */
+export const LIST_FILE_NAMES = ["MEMORY.md", "index.md", "INDEX.md", "README.md"];
+const COMPILED_DIR = COMPILED_DIR_NAME;
+/**
+ * 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 const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", "__pycache__"]);
+export class DiscoveryError extends Error {
+}
+function toRel(root, abs) {
+    return path.relative(root, abs).split(path.sep).join("/");
+}
+function readFile(root, abs, kind, alwaysLoadedFlag, generated = false) {
+    const content = fs.readFileSync(abs, "utf8");
+    return {
+        abs,
+        rel: toRel(root, abs) || path.basename(abs),
+        content,
+        lines: content.split(/\r?\n/),
+        tokens: estimateTokens(content),
+        alwaysLoaded: alwaysLoadedFlag,
+        kind,
+        generated,
+    };
+}
+function listMarkdown(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && e.name.toLowerCase().endsWith(".md"))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}
+/** Compiled OnDemandMemory files: Markdown, or JSON for an episodic file written under O3. */
+function listOnDemandFiles(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((e) => e.isFile() && /\.(md|json)$/i.test(e.name))
+        .map((e) => path.join(dir, e.name))
+        .sort();
+}
+/** True for a regular file that is not a symlink. `lstat` on purpose: a cloned repo can ship a link. */
+export function isPlainFile(abs) {
+    try {
+        return fs.lstatSync(abs).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Cheap, read-free mirror of discover()'s own branching, stopping as soon as the answer is
+ * known: a host file present means `host-file` shape (not a memory directory), three or more
+ * loose markdown files means `memory-dir`, and only then is the OS-level auto-memory folder
+ * checked. Mirrors discover()'s priority order without reading any file's content. */
+function looksLikeMemoryDir(root) {
+    try {
+        if (findHostFile(root))
+            return false;
+    }
+    catch {
+        // A symlinked host file: discover() would throw; detectPhase resolves every failure to
+        // "setup", so this is not a memory-dir either.
+        return false;
+    }
+    if (listMarkdown(root).length >= 3)
+        return true;
+    const autoMemoryRoot = locateAutoMemoryDir(root);
+    if (autoMemoryRoot && listMarkdown(autoMemoryRoot).length > 0)
+        return true;
+    return false;
+}
+export function detectPhase(root) {
+    try {
+        const compiledDir = path.join(root, COMPILED_DIR);
+        if (fs.existsSync(compiledDir) && fs.statSync(compiledDir).isDirectory()) {
+            const manifestPath = path.join(compiledDir, "manifest.json");
+            return fs.existsSync(manifestPath) && fs.statSync(manifestPath).isFile() ? "compiled" : "setup";
+        }
+        return looksLikeMemoryDir(root) ? "memory-dir" : "setup";
+    }
+    catch {
+        return "setup";
+    }
+}
+function findHostFile(dir) {
+    for (const name of HOST_FILES) {
+        const candidate = path.join(dir, name);
+        if (isPlainFile(candidate))
+            return candidate;
+        let link = false;
+        try {
+            link = fs.lstatSync(candidate).isSymbolicLink();
+        }
+        catch {
+            link = false;
+        }
+        if (link) {
+            throw new DiscoveryError(`${name} in ${dir} is a symlink; refusing to follow it\n` +
+                `  a cloned repo can point a memory file at anything on your machine`);
+        }
+    }
+    return undefined;
+}
+/** Claude Code `@path` import syntax, read outside code spans and fenced blocks. */
+const RE_IMPORT = /(?:^|[\s(])@((?:~\/|\.{0,2}\/)?[\w.\-~][\w.\-~/\\]*)/g;
+const RE_FENCE = /^\s*(```|~~~)/;
+const MAX_IMPORT_DEPTH = 5;
+function stripCode(content) {
+    let inFence = false;
+    return content
+        .split(/\r?\n/)
+        .map((line) => {
+        if (RE_FENCE.test(line)) {
+            inFence = !inFence;
+            return "";
+        }
+        return inFence ? "" : line.replace(/`[^`]*`/g, " ");
+    })
+        .join("\n");
+}
+/**
+ * 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 function resolveImports(hostAbs, root, followExternal = false) {
+    const seen = new Set();
+    const files = [];
+    const skipped = [];
+    const visit = (abs, depth) => {
+        if (depth > MAX_IMPORT_DEPTH)
+            return;
+        let content;
+        try {
+            content = fs.readFileSync(abs, "utf8");
+        }
+        catch {
+            return;
+        }
+        const text = stripCode(content);
+        // A fresh regex per call, not the module-level RE_IMPORT: that one carries lastIndex state
+        // on its own instance, so a recursive visit() call sharing it resets the outer scan's
+        // position mid-loop.
+        const re = new RegExp(RE_IMPORT.source, "g");
+        let m;
+        while ((m = re.exec(text)) !== null) {
+            const raw = m[1] ?? "";
+            const target = raw.startsWith("~/")
+                ? path.join(os.homedir(), raw.slice(2))
+                : path.resolve(path.dirname(abs), raw);
+            if (seen.has(target) || target === hostAbs)
+                continue;
+            // Containment is decided before the file is touched: no existsSync, no stat, no read, so
+            // an out-of-root import cannot even be probed for existence.
+            if (!followExternal && !containedIn(root, target)) {
+                seen.add(target);
+                if (!skipped.includes(`@${raw}`))
+                    skipped.push(`@${raw}`);
+                continue;
+            }
+            if (!fs.existsSync(target) || !fs.statSync(target).isFile())
+                continue;
+            seen.add(target);
+            files.push(target);
+            visit(target, depth + 1);
+        }
+    };
+    visit(hostAbs, 1);
+    return { files, skipped };
+}
+/**
+ * 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 function pointerTargetOf(hostAbs, content) {
+    const meaningful = content
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l !== "" && !l.startsWith("#") && !l.startsWith("<!--"));
+    if (meaningful.length === 0 || meaningful.length > 2)
+        return undefined;
+    if (content.length > 400)
+        return undefined;
+    const line = meaningful[meaningful.length - 1] ?? "";
+    const m = /(?:^|[\s`@])([\w.\-]+\.md)\b/i.exec(line);
+    if (!m?.[1])
+        return undefined;
+    const target = path.join(path.dirname(hostAbs), m[1]);
+    if (path.resolve(target) === path.resolve(hostAbs))
+        return undefined;
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile())
+        return undefined;
+    return target;
+}
+/** Read the host file plus everything it imports, all always-loaded. */
+function readHostWithImports(root, hostAbs, followExternal = false) {
+    const host = readFile(root, hostAbs, "host", true);
+    const files = [host];
+    const included = new Set([path.resolve(hostAbs)]);
+    const { files: imported, skipped: skippedImports } = resolveImports(hostAbs, root, followExternal);
+    for (const abs of imported) {
+        if (included.has(path.resolve(abs)))
+            continue;
+        included.add(path.resolve(abs));
+        files.push(readFile(root, abs, "import", true));
+    }
+    const pointer = pointerTargetOf(hostAbs, host.content);
+    let pointerTarget;
+    if (pointer && !included.has(path.resolve(pointer))) {
+        files.push(readFile(root, pointer, "import", true));
+        pointerTarget = toRel(root, pointer);
+    }
+    else if (pointer) {
+        pointerTarget = toRel(root, pointer);
+    }
+    return { files, pointerTarget, skippedImports };
+}
+function findListFile(files) {
+    for (const name of LIST_FILE_NAMES) {
+        const hit = files.find((f) => path.basename(f) === name);
+        if (hit)
+            return hit;
+    }
+    return undefined;
+}
+/**
+ * Walk up from `start` looking for a `.git` entry (directory for a normal repo, file for a
+ * worktree checkout - either marks a repo root). Returns the repo root, or undefined outside
+ * any git repo. This mirrors Claude Code's own auto-memory location rule: memory is keyed to
+ * the git repo root, not to wherever a host file happens to live.
+ */
+function findGitRoot(start) {
+    let dir = start;
+    for (;;) {
+        if (fs.existsSync(path.join(dir, ".git")))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * 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 function claudeProjectSlug(absPath) {
+    return absPath.replace(/[^a-zA-Z0-9]/g, "-");
+}
+/** `CLAUDE_CONFIG_DIR` if set, else `~/.claude` - where a dev's Claude Code config actually lives. */
+function claudeConfigDir() {
+    return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), ".claude");
+}
+/**
+ * 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 function locateAutoMemoryDir(target) {
+    const abs = path.resolve(target);
+    const projectRoot = findGitRoot(abs) ?? abs;
+    const slug = claudeProjectSlug(projectRoot);
+    const candidate = path.join(claudeConfigDir(), "projects", slug, "memory");
+    if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory())
+        return candidate;
+    return undefined;
+}
+/**
+ * Read an auto-memory folder's files as MemoryFiles. MEMORY.md, when present, is the always-loaded
+ * OnDemandMemory list (capped at 200 lines/25KB by Claude Code itself, matched here as
+ * informational only - this tool does not enforce that cap, MM001's own budget check covers the
+ * always-loaded cost). Every other top-level .md file is a topic file, read on demand only,
+ * matching how Claude Code actually loads them. `archive/` and other subdirectories are not
+ * descended into - stale/historical content a dev deliberately moved out of the way, not live
+ * memory to audit.
+ *
+ * `rel` is computed against the auto-memory folder itself, not the caller's workspace root - the
+ * two roots are genuinely different directories on disk - and prefixed so a finding referencing
+ * one of these files reads unambiguously in a report.
+ */
+function readAutoMemoryFiles(memoryDir) {
+    const files = [];
+    let onDemandList;
+    const markdown = listMarkdown(memoryDir);
+    for (const abs of markdown) {
+        const isList = path.basename(abs) === "MEMORY.md";
+        const content = fs.readFileSync(abs, "utf8");
+        const file = {
+            abs,
+            rel: `(auto-memory)/${path.basename(abs)}`,
+            content,
+            lines: content.split(/\r?\n/),
+            tokens: estimateTokens(content),
+            alwaysLoaded: isList,
+            kind: isList ? "onDemandList" : "loose",
+        };
+        if (isList)
+            onDemandList = file;
+        files.push(file);
+    }
+    return { files, onDemandList };
+}
+/**
+ * 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 function discover(target, options = {}) {
+    const followExternal = options.followExternalImports === true;
+    const includeAutoMemory = options.includeAutoMemory !== false;
+    const abs = path.resolve(target);
+    if (!fs.existsSync(abs)) {
+        throw new DiscoveryError(`no such file or directory: ${abs}`);
+    }
+    const stat = fs.statSync(abs);
+    // A single file passed directly. It is the whole always-loaded prefix.
+    if (stat.isFile()) {
+        const root = path.dirname(abs);
+        return {
+            root,
+            shape: "single-file",
+            files: [readFile(root, abs, "host", true)],
+        };
+    }
+    const root = abs;
+    const compiledDir = path.join(root, COMPILED_DIR);
+    // Already compiled.
+    if (fs.existsSync(compiledDir) && fs.statSync(compiledDir).isDirectory()) {
+        const files = [];
+        let onDemandList;
+        // When the host file is a generated stub it already contains the AlwaysOnMemory body and
+        // the OnDemandMemory list inline, so counting those files again would double-charge the
+        // prefix.
+        const hostPath = findHostFile(root);
+        const inlined = hostPath !== undefined && isStub(fs.readFileSync(hostPath, "utf8"));
+        // AlwaysOnMemory.md holds always-on prose and the OnDemandMemory list in one file (the same
+        // join the stub uses). It is pushed once, whole, as the "alwaysOn" file so the always-loaded
+        // token total is not double-charged; `onDemandList` is a second view over the same bytes,
+        // its lines blanked outside the list's own marked region so a finding against it still names
+        // a real line number in AlwaysOnMemory.md, without a second copy of the shared content in
+        // ws.files.
+        const alwaysOnPath = path.join(compiledDir, ALWAYS_ON_FILE_NAME);
+        if (fs.existsSync(alwaysOnPath)) {
+            const content = fs.readFileSync(alwaysOnPath, "utf8");
+            const rel = toRel(root, alwaysOnPath) || path.basename(alwaysOnPath);
+            const lines = content.split(/\r?\n/);
+            files.push({
+                abs: alwaysOnPath,
+                rel,
+                content,
+                lines,
+                tokens: estimateTokens(content),
+                alwaysLoaded: !inlined,
+                kind: "alwaysOn",
+                generated: inlined,
+            });
+            const listLines = regionOnly(lines, LIST_START, LIST_END);
+            const listContent = listLines.join("\n");
+            if (listContent.trim()) {
+                onDemandList = {
+                    abs: alwaysOnPath,
+                    rel,
+                    content: listContent,
+                    lines: listLines,
+                    tokens: estimateTokens(listContent),
+                    alwaysLoaded: false,
+                    kind: "onDemandList",
+                    generated: true,
+                };
+            }
+        }
+        for (const m of listOnDemandFiles(path.join(compiledDir, ON_DEMAND_DIR_NAME))) {
+            files.push(readFile(root, m, "onDemand", false));
+        }
+        // The host file is re-sent every turn, and so is anything it imports.
+        let skippedImports = [];
+        if (hostPath) {
+            const hostRead = readHostWithImports(root, hostPath, followExternal);
+            files.push(...hostRead.files);
+            skippedImports = hostRead.skippedImports;
+        }
+        // Fold in auto-memory files too. The compiled OnDemandMemory list keeps the ws.onDemandList
+        // slot; the auto-memory MEMORY.md goes in autoMemoryList so MM004/MM006 can check each side
+        // against the list that routes to it.
+        const autoMemoryRoot = includeAutoMemory ? locateAutoMemoryDir(root) : undefined;
+        let autoMemoryList;
+        if (autoMemoryRoot) {
+            const autoMemory = readAutoMemoryFiles(autoMemoryRoot);
+            files.push(...autoMemory.files);
+            autoMemoryList = autoMemory.onDemandList;
+        }
+        // The manifest, for rules that compare disk against what init wrote (MM010). An unreadable
+        // or malformed manifest is not this function's problem: the workspace is still auditable
+        // without it, and mcp reports the manifest error itself when it needs one.
+        let manifest;
+        try {
+            const raw = JSON.parse(fs.readFileSync(path.join(compiledDir, "manifest.json"), "utf8"));
+            if (raw && typeof raw.sourceHash === "string" && raw.always && Array.isArray(raw.onDemandFiles)) {
+                manifest = raw;
+            }
+        }
+        catch {
+            manifest = undefined;
+        }
+        return { root, shape: "compiled", files, onDemandList, autoMemoryRoot, autoMemoryList, manifest, skippedImports };
+    }
+    // A repo with a host memory file but no compilation yet. This is the common case, and the one
+    // that gets the auto-memory folder folded in: there is no existing compiled OnDemandMemory
+    // list competing for the ws.onDemandList slot here, so the auto-memory MEMORY.md can take it,
+    // and MM004/MM006 (which key off ws.onDemandList) get real coverage over the auto-memory side,
+    // not just MM001/MM003 (which scan ws.files broadly regardless of which file holds the list
+    // slot).
+    const host = findHostFile(root);
+    if (host) {
+        const { files, pointerTarget, skippedImports } = readHostWithImports(root, host, followExternal);
+        let onDemandList;
+        const autoMemoryRoot = includeAutoMemory ? locateAutoMemoryDir(root) : undefined;
+        if (autoMemoryRoot) {
+            const autoMemory = readAutoMemoryFiles(autoMemoryRoot);
+            files.push(...autoMemory.files);
+            onDemandList = autoMemory.onDemandList;
+        }
+        return {
+            root,
+            shape: "host-file",
+            files,
+            onDemandList,
+            autoMemoryRoot,
+            autoMemoryList: onDemandList,
+            pointerTarget,
+            skippedImports,
+        };
+    }
+    // A bare directory of memory files.
+    const markdown = listMarkdown(root);
+    if (markdown.length >= 3) {
+        const listPath = findListFile(markdown);
+        const files = [];
+        let onDemandList;
+        for (const f of markdown) {
+            const isList = f === listPath;
+            // With an OnDemandMemory list present, only the list is always loaded and the rest are
+            // routed. With no list, there is nothing to route with, so the whole directory gets read.
+            const always = isList ? true : listPath === undefined;
+            const file = readFile(root, f, isList ? "onDemandList" : "loose", always);
+            if (isList)
+                onDemandList = file;
+            files.push(file);
+        }
+        return { root, shape: "memory-dir", files, onDemandList };
+    }
+    // A project with no host file of its own can still carry real memory: Claude Code keeps the
+    // auto-memory folder outside the project entirely, keyed by the git root. A project that has
+    // only ever been driven through auto-memory is memory worth auditing, not an empty target.
+    const autoMemoryRoot = includeAutoMemory ? locateAutoMemoryDir(root) : undefined;
+    if (autoMemoryRoot) {
+        const autoMemory = readAutoMemoryFiles(autoMemoryRoot);
+        if (autoMemory.files.length > 0) {
+            return {
+                root,
+                shape: "auto-memory",
+                files: autoMemory.files,
+                onDemandList: autoMemory.onDemandList,
+                autoMemoryRoot,
+                autoMemoryList: autoMemory.onDemandList,
+            };
+        }
+    }
+    throw new DiscoveryError(`no memory files found in ${abs}\n` +
+        `  looked for: ${HOST_FILES.join(", ")}, a ${COMPILED_DIR}/ directory, ` +
+        `a directory holding at least 3 markdown files, or a Claude Code auto-memory folder for it`);
+}

package/dist/doctor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The doctor orchestrator: discover a workspace, run the rule set over it, sort the results.
+ */
+import { type DoctorConfig, type DoctorResult, type Workspace } from "./types.js";
+export declare function resolveConfig(partial?: Partial<DoctorConfig>): DoctorConfig;
+/** Run the rule set against an already-discovered workspace. */
+export declare function auditWorkspace(workspace: Workspace, partial?: Partial<DoctorConfig>): DoctorResult;
+/** Discover and audit in one step. */
+export declare function doctor(target: string, partial?: Partial<DoctorConfig>): DoctorResult;

package/dist/doctor.js

@@ -0,0 +1,67 @@
+/**
+ * The doctor orchestrator: discover a workspace, run the rule set over it, sort the results.
+ */
+import { discover } from "./discover.js";
+import { RULES } from "./rules.js";
+import { TOKENIZER_ID } from "./tokenizer.js";
+import { alwaysLoaded, DEFAULT_CONFIG, SEVERITY_ORDER, } from "./types.js";
+export function resolveConfig(partial = {}) {
+    return { ...DEFAULT_CONFIG, ...partial };
+}
+function selectedRules(config) {
+    const only = config.only.map((s) => s.toUpperCase());
+    const ignore = config.ignore.map((s) => s.toUpperCase());
+    return RULES.filter((rule) => {
+        const id = rule.id.toUpperCase();
+        if (only.length > 0 && !only.includes(id))
+            return false;
+        if (ignore.includes(id))
+            return false;
+        return true;
+    });
+}
+/** Most severe first, then by rule id, then by file and line, so output is stable. */
+function sortFindings(findings) {
+    return [...findings].sort((a, b) => {
+        const sev = SEVERITY_ORDER[b.severity] - SEVERITY_ORDER[a.severity];
+        if (sev !== 0)
+            return sev;
+        if (a.rule !== b.rule)
+            return a.rule.localeCompare(b.rule);
+        if (a.file !== b.file)
+            return a.file.localeCompare(b.file);
+        return (a.startLine ?? 0) - (b.startLine ?? 0);
+    });
+}
+/** Run the rule set against an already-discovered workspace. */
+export function auditWorkspace(workspace, partial = {}) {
+    const config = resolveConfig(partial);
+    const findings = [];
+    for (const rule of selectedRules(config)) {
+        // A crashing rule must not take the whole run down with it.
+        try {
+            findings.push(...rule.run({ workspace, config }));
+        }
+        catch (err) {
+            findings.push({
+                rule: rule.id,
+                severity: "low",
+                message: `rule failed to run: ${err.message}`,
+                file: ".",
+            });
+        }
+    }
+    const loaded = alwaysLoaded(workspace);
+    return {
+        workspace,
+        findings: sortFindings(findings),
+        alwaysLoadedTokens: loaded.reduce((n, f) => n + f.tokens, 0),
+        alwaysLoadedFiles: loaded.length,
+        tokenizer: TOKENIZER_ID,
+    };
+}
+/** Discover and audit in one step. */
+export function doctor(target, partial = {}) {
+    const config = resolveConfig(partial);
+    return auditWorkspace(discover(target, { followExternalImports: config.followExternalImports, includeAutoMemory: config.includeAutoMemory }), partial);
+}

package/dist/episodic.d.ts

@@ -0,0 +1,47 @@
+/**
+ * O2 and O3: what kind of memory a section holds, and the JSON form for the episodic kind.
+ *
+ * O2 classifies every long-term unit as semantic (facts true now, edited in place),
+ * episodic (things that happened, append-only) or procedural (a learned rule, edited
+ * rarely). The compiler decides by section, not by filename, because a `project` file blends
+ * all three. O3 writes episodic content as JSON, on the documented finding that a model is
+ * less likely to rewrite or summarize JSON it was only meant to append to. The JSON form is
+ * lossless and reversible: `episodicToMarkdown(fromMarkdown(x))` gives back x.
+ */
+export type MemoryKind = "semantic" | "episodic" | "procedural";
+/** Decide a section's kind from its heading and body (O2). */
+export declare function classifyKind(heading: string, bodyLines: string[]): MemoryKind;
+export interface EpisodicEntry {
+    /** the first date found in the entry's opening line, when there is one */
+    date: string | null;
+    /** the entry's lines, verbatim, joined with newlines */
+    text: string;
+}
+export interface EpisodicFile {
+    format: "minnimemory-episodic";
+    version: 1;
+    heading: string;
+    kind: "episodic";
+    /** lines between the heading and the first entry, verbatim */
+    preamble: string;
+    entries: EpisodicEntry[];
+}
+/**
+ * Parse an OnDemandMemory file's markdown (a heading line then a body of mostly dated bullets) into the
+ * JSON form. Every line of the source lands in exactly one field, in order, so the markdown
+ * can be rebuilt byte for byte (trailing newlines aside).
+ */
+export declare function episodicFromMarkdown(markdown: string): EpisodicFile;
+/** The exact markdown the JSON came from. */
+export declare function episodicToMarkdown(mod: EpisodicFile, headingLevel?: number): string;
+/** Serialize for disk: two-space JSON, trailing newline, stable key order. */
+export declare function episodicToJson(mod: EpisodicFile): string;
+/**
+ * Read a `.json` OnDemandMemory file back into markdown for the router and the agent-facing tools.
+ *
+ * Validated field by field, not cast. This parses a file from the workspace, which on a cloned
+ * repo is a file someone else wrote; a bare `as EpisodicFile` turned a wrong-shaped `entries`
+ * into an unhandled TypeError surfacing as "unexpected error", where the manifest right beside
+ * it has been schema-checked all along.
+ */
+export declare function episodicJsonToMarkdown(json: string): string;