minnimemory 1.0.0-beta.1

package/dist/scan.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Structured, whole-directory inventory of a memory setup for an agent to reorganize.
+ *
+ * This is the deterministic half of "AI-scanned reorganization" (project_minnimemory memory,
+ * 2026-09-03): scan.ts computes facts - frontmatter, section boundaries, volatility evidence,
+ * candidate routing keywords, cross-file duplicate blocks - the same primitives doctor/init
+ * already use. It never classifies, merges, or judges; it hands a calling agent everything it
+ * would otherwise have to re-derive by reading every file by hand. The agent (not this module,
+ * not an API call - see the locked "no LLM in init/doctor" decision) does the O1-O5/CoALA
+ * judgment and produces a ReorganizePlan for reorganize.ts to apply.
+ */
+import { type MemoryKind } from "./episodic.js";
+import type { WorkspaceShape } from "./types.js";
+export interface Frontmatter {
+    name?: string;
+    description?: string;
+    /** metadata.type - the auto-memory category (user/feedback/project/reference) when present */
+    type?: string;
+}
+export interface SectionScan {
+    heading: string;
+    level: number;
+    startLine: number;
+    endLine: number;
+    tokens: number;
+    volatile: boolean;
+    volatilityReasons: string[];
+    /** O2: semantic, episodic or procedural, decided per section */
+    kind: MemoryKind;
+    keywords: string[];
+}
+export interface FileScan {
+    rel: string;
+    tokens: number;
+    isList: boolean;
+    alwaysLoaded: boolean;
+    frontmatter?: Frontmatter;
+    sections: SectionScan[];
+}
+export interface DuplicateScan {
+    /** short preview, not the full block - keep the scan itself cheap to hold in context */
+    preview: string;
+    tokensWastedPerExtraCopy: number;
+    occurrences: {
+        file: string;
+        startLine: number;
+        endLine: number;
+    }[];
+}
+export interface MemoryScan {
+    root: string;
+    shape: WorkspaceShape;
+    /** `@path` imports outside the root that were not followed; see discover.resolveImports */
+    skippedImports?: string[];
+    totalTokens: number;
+    alwaysLoadedTokens: number;
+    files: FileScan[];
+    duplicates: DuplicateScan[];
+}
+export interface FileScanSummary {
+    rel: string;
+    tokens: number;
+    isList: boolean;
+    alwaysLoaded: boolean;
+    frontmatter?: Frontmatter;
+    sectionCount: number;
+    volatileSectionCount: number;
+    kinds: Record<MemoryKind, number>;
+}
+export interface MemoryScanSummary {
+    root: string;
+    shape: WorkspaceShape;
+    skippedImports?: string[];
+    totalTokens: number;
+    alwaysLoadedTokens: number;
+    files: FileScanSummary[];
+    duplicates: {
+        groups: number;
+        tokensWasted: number;
+    };
+}
+/**
+ * The rollup a caller reaches for first: counts and per-file totals, not every section's
+ * heading, keywords and volatility reasons (the `full` shape below). 2026-09-13 audit round 2,
+ * D4 - `scan`'s default output on a real memory directory of any size was mostly detail nobody
+ * asked for yet; `detail: "full"` still returns the original shape when a caller actually wants
+ * every section.
+ */
+export declare function summarize(scan: MemoryScan): MemoryScanSummary;
+/**
+ * Restrict a scan to exactly the named files (matched against `rel`), recomputing the token
+ * totals over just that subset so they describe what is actually returned. A name that matches
+ * nothing is reported back in `unknownFiles` rather than silently dropped. `duplicates` are left
+ * as computed over the whole workspace: a block duplicated between a kept file and a filtered-out
+ * one is still worth knowing about, and pretending the other copy does not exist would hide
+ * exactly the fact this field exists to surface.
+ */
+export declare function filterScanFiles(scan: MemoryScan, files: string[] | undefined): {
+    scan: MemoryScan;
+    unknownFiles: string[];
+};
+/**
+ * Scan any target discover() can resolve - a bare memory directory, a Claude Code auto-memory
+ * folder (directly or via a project root), a host-file repo - into a full structured inventory.
+ * Read-only, no writes, safe to call as often as needed while drafting a plan.
+ */
+export declare function scanMemoryDir(target: string, options?: {
+    followExternalImports?: boolean;
+    includeAutoMemory?: boolean;
+}): MemoryScan;

package/dist/scan.js

@@ -0,0 +1,173 @@
+/**
+ * Structured, whole-directory inventory of a memory setup for an agent to reorganize.
+ *
+ * This is the deterministic half of "AI-scanned reorganization" (project_minnimemory memory,
+ * 2026-09-03): scan.ts computes facts - frontmatter, section boundaries, volatility evidence,
+ * candidate routing keywords, cross-file duplicate blocks - the same primitives doctor/init
+ * already use. It never classifies, merges, or judges; it hands a calling agent everything it
+ * would otherwise have to re-derive by reading every file by hand. The agent (not this module,
+ * not an API call - see the locked "no LLM in init/doctor" decision) does the O1-O5/CoALA
+ * judgment and produces a ReorganizePlan for reorganize.ts to apply.
+ */
+import { discover } from "./discover.js";
+import { classifyKind } from "./episodic.js";
+import { findDuplicateBlocks } from "./rules.js";
+import { keywords as extractKeywords, sectionVolatilityReasons, sections, splitFrontmatter } from "./text.js";
+import { estimateTokens } from "./tokenizer.js";
+/**
+ * The rollup a caller reaches for first: counts and per-file totals, not every section's
+ * heading, keywords and volatility reasons (the `full` shape below). 2026-09-13 audit round 2,
+ * D4 - `scan`'s default output on a real memory directory of any size was mostly detail nobody
+ * asked for yet; `detail: "full"` still returns the original shape when a caller actually wants
+ * every section.
+ */
+export function summarize(scan) {
+    const files = scan.files.map((f) => {
+        const kinds = { semantic: 0, episodic: 0, procedural: 0 };
+        let volatileSectionCount = 0;
+        for (const s of f.sections) {
+            kinds[s.kind]++;
+            if (s.volatile)
+                volatileSectionCount++;
+        }
+        return {
+            rel: f.rel,
+            tokens: f.tokens,
+            isList: f.isList,
+            alwaysLoaded: f.alwaysLoaded,
+            ...(f.frontmatter ? { frontmatter: f.frontmatter } : {}),
+            sectionCount: f.sections.length,
+            volatileSectionCount,
+            kinds,
+        };
+    });
+    const tokensWasted = scan.duplicates.reduce((n, d) => n + d.tokensWastedPerExtraCopy * Math.max(0, d.occurrences.length - 1), 0);
+    return {
+        root: scan.root,
+        shape: scan.shape,
+        ...(scan.skippedImports?.length ? { skippedImports: scan.skippedImports } : {}),
+        totalTokens: scan.totalTokens,
+        alwaysLoadedTokens: scan.alwaysLoadedTokens,
+        files,
+        duplicates: { groups: scan.duplicates.length, tokensWasted },
+    };
+}
+/**
+ * Restrict a scan to exactly the named files (matched against `rel`), recomputing the token
+ * totals over just that subset so they describe what is actually returned. A name that matches
+ * nothing is reported back in `unknownFiles` rather than silently dropped. `duplicates` are left
+ * as computed over the whole workspace: a block duplicated between a kept file and a filtered-out
+ * one is still worth knowing about, and pretending the other copy does not exist would hide
+ * exactly the fact this field exists to surface.
+ */
+export function filterScanFiles(scan, files) {
+    if (!files || files.length === 0)
+        return { scan, unknownFiles: [] };
+    const wanted = new Set(files);
+    const kept = scan.files.filter((f) => wanted.has(f.rel));
+    const keptRels = new Set(kept.map((f) => f.rel));
+    const unknownFiles = files.filter((f) => !keptRels.has(f));
+    const totalTokens = kept.reduce((n, f) => n + f.tokens, 0);
+    const alwaysLoadedTokens = kept.filter((f) => f.alwaysLoaded).reduce((n, f) => n + f.tokens, 0);
+    return {
+        scan: { ...scan, files: kept, totalTokens, alwaysLoadedTokens },
+        unknownFiles,
+    };
+}
+/**
+ * A minimal, deliberately non-general YAML reader for exactly the frontmatter shape this
+ * project's memory files use: flat `key: value` lines plus one level of nesting under
+ * `metadata:`. Not a YAML parser - a real one is a dependency this offline-first tool does not
+ * need for three known keys.
+ */
+function parseFrontmatter(lines) {
+    if (lines.length === 0)
+        return undefined;
+    const body = lines.slice(1, -1); // drop the two `---` fence lines
+    const out = {};
+    let inMetadata = false;
+    const unquote = (v) => v.trim().replace(/^["']|["']$/g, "");
+    for (const raw of body) {
+        const indented = /^\s+/.test(raw) && raw.trim() !== "";
+        if (!indented)
+            inMetadata = /^metadata\s*:/.test(raw.trim());
+        const m = /^\s*([\w.-]+)\s*:\s*(.*)$/.exec(raw);
+        if (!m)
+            continue;
+        const key = m[1] ?? "";
+        const value = unquote(m[2] ?? "");
+        if (!indented && key === "name" && value)
+            out.name = value;
+        else if (!indented && key === "description" && value)
+            out.description = value;
+        else if (indented && inMetadata && key === "type" && value)
+            out.type = value;
+    }
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function scanFile(file, isList) {
+    const { frontmatter: fmLines, bodyStartLine } = splitFrontmatter(file.lines);
+    const bodyLines = file.lines.slice(bodyStartLine - 1);
+    const sectionScans = sections(bodyLines).map((s) => {
+        const sectionLines = bodyLines.slice(s.startLine - 1, s.endLine);
+        const reasons = sectionVolatilityReasons(sectionLines);
+        const bodyOnly = sectionLines.slice(1).join("\n");
+        return {
+            heading: s.heading,
+            level: s.level,
+            // offset back into the whole-file line numbering, since sections() above only saw bodyLines
+            startLine: s.startLine + bodyStartLine - 1,
+            endLine: s.endLine + bodyStartLine - 1,
+            tokens: estimateTokens(sectionLines.join("\n")),
+            volatile: reasons.length > 0,
+            volatilityReasons: reasons,
+            kind: classifyKind(s.heading, sectionLines.slice(1)),
+            keywords: extractKeywords(s.heading, bodyOnly),
+        };
+    });
+    return {
+        rel: file.rel,
+        tokens: file.tokens,
+        isList,
+        alwaysLoaded: file.alwaysLoaded,
+        frontmatter: parseFrontmatter(fmLines),
+        sections: sectionScans,
+    };
+}
+const PREVIEW_LEN = 160;
+/**
+ * Scan any target discover() can resolve - a bare memory directory, a Claude Code auto-memory
+ * folder (directly or via a project root), a host-file repo - into a full structured inventory.
+ * Read-only, no writes, safe to call as often as needed while drafting a plan.
+ */
+export function scanMemoryDir(target, options = {}) {
+    const ws = discover(target, {
+        followExternalImports: options.followExternalImports === true,
+        includeAutoMemory: options.includeAutoMemory !== false,
+    });
+    const files = ws.files.map((f) => scanFile(f, f === ws.onDemandList || f === ws.autoMemoryList));
+    const duplicates = findDuplicateBlocks(ws.files).map(({ occurrences, wastedTokens }) => {
+        const first = occurrences[0];
+        const text = first ? first.block.text : "";
+        return {
+            preview: text.length > PREVIEW_LEN ? `${text.slice(0, PREVIEW_LEN)}…` : text,
+            tokensWastedPerExtraCopy: occurrences.length > 1 ? Math.round(wastedTokens / (occurrences.length - 1)) : 0,
+            occurrences: occurrences.map((o) => ({
+                file: o.file.rel,
+                startLine: o.block.startLine,
+                endLine: o.block.endLine,
+            })),
+        };
+    });
+    const totalTokens = ws.files.reduce((n, f) => n + f.tokens, 0);
+    const alwaysLoadedTokens = ws.files.filter((f) => f.alwaysLoaded).reduce((n, f) => n + f.tokens, 0);
+    return {
+        root: ws.root,
+        shape: ws.shape,
+        ...(ws.skippedImports?.length ? { skippedImports: ws.skippedImports } : {}),
+        totalTokens,
+        alwaysLoadedTokens,
+        files,
+        duplicates,
+    };
+}

package/dist/text.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Text primitives shared by the rule engine and the compiler.
+ */
+export interface Section {
+    /** heading text with the hashes stripped */
+    heading: string;
+    /** 1 for #, 2 for ##, and so on. 0 for the synthetic preamble section. */
+    level: number;
+    /** 1-indexed, inclusive */
+    startLine: number;
+    endLine: number;
+}
+export interface Block {
+    text: string;
+    startLine: number;
+    endLine: number;
+}
+/**
+ * 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 declare function sections(lines: string[]): Section[];
+/** Split lines into blank-line-delimited blocks. */
+export declare function blocks(lines: string[]): Block[];
+/** Normalise a block so cosmetic differences do not hide a duplicate. */
+export declare function normalise(text: string): string;
+/** Filesystem-safe, stable slug for a heading. */
+export declare function slugify(heading: string): string;
+/**
+ * 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 declare 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 declare 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 declare const RE_DATED_BULLET: RegExp;
+/**
+ * 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 declare function isEpisodicBody(lines: string[]): boolean;
+export interface Volatility {
+    score: number;
+    /** distinct kinds of evidence found, in a fixed order, for messages */
+    reasons: string[];
+}
+/**
+ * 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 declare function volatility(heading: string, bodyLines: string[]): Volatility;
+/** Reasons a headingless block is volatile; empty when it is not. */
+export declare function volatilityReasons(text: string): string[];
+/** Reasons a heading-led section is volatile; empty when it is not. */
+export declare function sectionVolatilityReasons(sectionLines: string[]): string[];
+/** Delimiters around the generated regions of a stub: the OnDemandMemory list and the instruction block. */
+export declare const LIST_START = "<!-- minnimemory:ondemand-list -->";
+export declare const LIST_END = "<!-- /minnimemory:ondemand-list -->";
+export declare const INSTRUCTIONS_START = "<!-- minnimemory:instructions -->";
+export declare 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 declare function generatedRegion(lines: string[], start: string, end: string): {
+    from: number;
+    to: number;
+} | undefined;
+/**
+ * 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 declare function stripGeneratedRegions(lines: string[]): string[];
+/** Kept for callers that only know about the OnDemandMemory list region. */
+export declare const stripGeneratedList: typeof 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 declare function regionOnly(lines: string[], start: string, end: string): string[];
+/**
+ * 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 declare function splitFrontmatter(lines: string[]): {
+    frontmatter: string[];
+    bodyStartLine: number;
+};
+export declare const STOPWORDS: Set<string>;
+/** A code token's raw frequency inside a fenced block, relative to a comment or prose word. */
+export declare 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 declare function weightedFragments(body: string): {
+    text: string;
+    weight: number;
+}[];
+/**
+ * Pull candidate routing keywords out of a piece of text.
+ * Frequency-ranked, stopword-filtered, and biased toward terms in the heading.
+ */
+export declare function keywords(heading: string, body: string, limit?: number): string[];