minnimemory 1.0.0-beta.1

package/dist/bench.d.ts

@@ -0,0 +1,98 @@
+/**
+ * `bench`: what a compiled workspace actually costs over a session.
+ *
+ * The number `init` prints is tokens *moved* out of the always-loaded prefix. That is not the
+ * same as tokens saved, and the difference is the whole reason this command exists (audit,
+ * 2026-09-01): an OnDemandMemory file the agent opens on turn 1 becomes a tool result in the
+ * conversation and is re-sent on every turn after it, so it costs the full session, not one
+ * turn. Real savings are the OnDemandMemory files a session never opens.
+ *
+ * Two things are computed here, and they are not the same kind of claim:
+ *
+ *   bounds()   exact arithmetic over the manifest, extracted to bounds.ts (2026-09-16, C3) so
+ *              init.ts's compile-verdict check can depend on just that, not the router/recall
+ *              machinery below. Re-exported here unchanged - see bounds.ts's own header.
+ *
+ *   model()    a session model over a caller-supplied workload. It routes each task with the
+ *              same deterministic ranker `recall` ships, then carries every opened OnDemandMemory
+ *              file forward for the rest of the session. This is a MODEL, and every number it
+ *              produces is conditional on the workload being representative. It is never a
+ *              measurement and must never be quoted as one.
+ *
+ * Neither is a live run. Observed token usage against a real agent loop is a separate rig
+ * (a real multi-turn session, with and without the compile) and is the only thing that may be called measured.
+ */
+import type { Manifest } from "./compile.js";
+import { BenchError, bounds, type BenchBounds } from "./bounds.js";
+export { BenchError, bounds, type BenchBounds };
+export interface BenchTurn {
+    turn: number;
+    task: string;
+    /** OnDemandMemory files opened on this turn, not counting ones already in context */
+    opened: string[];
+    /** every OnDemandMemory file in context at the end of this turn */
+    carried: string[];
+    compiledTokens: number;
+    baselineTokens: number;
+}
+export interface BenchModel {
+    /**
+     * What the router opened per turn: whole OnDemandMemory files (the agent-driven route, where
+     * an agent reads a file the OnDemandMemory list pointed at) or sections (the recall route,
+     * where the MCP tool returns units up to a token cap). The two are different sessions and must
+     * be labelled.
+     */
+    unit: "file" | "section";
+    turns: BenchTurn[];
+    baselineTotal: number;
+    compiledTotal: number;
+    saving: number;
+    savingPct: number;
+    onDemandOpened: string[];
+    onDemandNeverOpened: string[];
+    /** tasks that matched no OnDemandMemory file at all: the router had nothing to offer them */
+    unroutedTurns: number;
+    /**
+     * Cost of one more turn once every OnDemandMemory file this workload opens is already in
+     * context. This is the number that decides whether a longer session eventually wins: below
+     * the baseline the deficit is recoverable, at or above it the compiled shape is permanently
+     * more expensive for this workload no matter how long the session runs.
+     */
+    steadyStatePerTurn: number;
+    /** baseline minus steady state. Negative means every further turn loses more ground. */
+    steadyStateGainPerTurn: number;
+    /**
+     * The turn at which cumulative tokens first come out even or ahead, assuming no OnDemandMemory
+     * file opens after the workload ends. Undefined when the steady state never recovers.
+     */
+    breakEvenTurn?: number;
+}
+/**
+ * Parse a workload file: one task description per line, blank lines and `#` comments ignored.
+ * One line is one turn, and the count of lines is the session length - inventing extra turns by
+ * cycling the list would be fabricating session shape the caller did not describe.
+ */
+export declare function parseWorkload(content: string): string[];
+export declare function readWorkload(file: string): string[];
+/**
+ * Walk a workload turn by turn, opening whatever the shipped router matches and carrying it for
+ * the rest of the session.
+ *
+ * Stated assumptions, all of which move the number:
+ *   - one workload line is one turn, and the agent's own reasoning and tool results are not
+ *     counted on either side. Only memory tokens are compared, so the ratio here is not a
+ *     session bill.
+ *   - an OnDemandMemory file whose triggers match the task is opened in full. A real agent may
+ *     read one and stop, or skip one the list offered.
+ *   - an opened OnDemandMemory file stays in context to the end of the session, which is what
+ *     makes carried files expensive and is the effect this command exists to expose.
+ */
+export interface ModelOptions {
+    /**
+     * The compiled workspace root. When given, the model routes at section level with the same
+     * ranker and token cap `recall` uses, reading OnDemandMemory files from disk. Without it only
+     * the manifest is available, so the model routes whole OnDemandMemory files by their triggers.
+     */
+    root?: string;
+}
+export declare function model(manifest: Manifest, tasks: string[], options?: ModelOptions): BenchModel;

package/dist/bench.js

@@ -0,0 +1,142 @@
+/**
+ * `bench`: what a compiled workspace actually costs over a session.
+ *
+ * The number `init` prints is tokens *moved* out of the always-loaded prefix. That is not the
+ * same as tokens saved, and the difference is the whole reason this command exists (audit,
+ * 2026-09-01): an OnDemandMemory file the agent opens on turn 1 becomes a tool result in the
+ * conversation and is re-sent on every turn after it, so it costs the full session, not one
+ * turn. Real savings are the OnDemandMemory files a session never opens.
+ *
+ * Two things are computed here, and they are not the same kind of claim:
+ *
+ *   bounds()   exact arithmetic over the manifest, extracted to bounds.ts (2026-09-16, C3) so
+ *              init.ts's compile-verdict check can depend on just that, not the router/recall
+ *              machinery below. Re-exported here unchanged - see bounds.ts's own header.
+ *
+ *   model()    a session model over a caller-supplied workload. It routes each task with the
+ *              same deterministic ranker `recall` ships, then carries every opened OnDemandMemory
+ *              file forward for the rest of the session. This is a MODEL, and every number it
+ *              produces is conditional on the workload being representative. It is never a
+ *              measurement and must never be quoted as one.
+ *
+ * Neither is a live run. Observed token usage against a real agent loop is a separate rig
+ * (a real multi-turn session, with and without the compile) and is the only thing that may be called measured.
+ */
+import fs from "node:fs";
+import { loadOnDemandContent, rankOnDemandFiles } from "./recall.js";
+import { buildSearchIndex, rankUnits, selectUnits, unitsOf } from "./router.js";
+import { BenchError, bounds } from "./bounds.js";
+export { BenchError, bounds };
+/**
+ * Parse a workload file: one task description per line, blank lines and `#` comments ignored.
+ * One line is one turn, and the count of lines is the session length - inventing extra turns by
+ * cycling the list would be fabricating session shape the caller did not describe.
+ */
+export function parseWorkload(content) {
+    return content
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l !== "" && !l.startsWith("#"));
+}
+export function readWorkload(file) {
+    let content;
+    try {
+        content = fs.readFileSync(file, "utf8");
+    }
+    catch {
+        throw new BenchError(`cannot read workload file: ${file}`);
+    }
+    const tasks = parseWorkload(content);
+    if (tasks.length === 0) {
+        throw new BenchError(`workload file has no tasks: ${file}\n  one task description per line, # for comments`);
+    }
+    return tasks;
+}
+/** A unit's identity across turns: OnDemandMemory file plus start line. */
+function unitId(u) {
+    return `${u.onDemandFile}:${u.startLine}`;
+}
+function unitLabel(u) {
+    return `${u.onDemandFile} > ${u.heading}`;
+}
+function buildIndex(manifest, root) {
+    const units = manifest.onDemandFiles.flatMap((m) => unitsOf({ name: m.name, file: m.file }, loadOnDemandContent(root, m.file)));
+    return buildSearchIndex(units, new Map(manifest.onDemandFiles.map((m) => [m.name, m.triggers])));
+}
+export function model(manifest, tasks, options = {}) {
+    const index = options.root ? buildIndex(manifest, options.root) : undefined;
+    const unit = index ? "section" : "file";
+    // Carried things are identified by id; their token cost and display label are looked up.
+    const carried = new Set();
+    const tokensOf = new Map();
+    const labelOf = new Map();
+    const onDemandFileOf = new Map();
+    for (const m of manifest.onDemandFiles) {
+        tokensOf.set(m.name, m.tokens);
+        labelOf.set(m.name, m.name);
+        onDemandFileOf.set(m.name, m.name);
+    }
+    if (index) {
+        for (const u of index.units) {
+            tokensOf.set(unitId(u), u.tokens);
+            labelOf.set(unitId(u), unitLabel(u));
+            onDemandFileOf.set(unitId(u), u.onDemandFile);
+        }
+    }
+    const turns = [];
+    let unroutedTurns = 0;
+    tasks.forEach((task, i) => {
+        const matched = index
+            ? selectUnits(rankUnits(index, task)).map((r) => unitId(r.unit))
+            : rankOnDemandFiles(manifest, task)
+                .filter((r) => r.score > 0)
+                .map((m) => m.name);
+        if (matched.length === 0)
+            unroutedTurns++;
+        const opened = matched.filter((id) => !carried.has(id));
+        for (const id of opened)
+            carried.add(id);
+        const carriedTokens = [...carried].reduce((n, id) => n + (tokensOf.get(id) ?? 0), 0);
+        turns.push({
+            turn: i + 1,
+            task,
+            opened: opened.map((id) => labelOf.get(id) ?? id),
+            carried: [...carried].map((id) => labelOf.get(id) ?? id),
+            compiledTokens: manifest.prefix.after + carriedTokens,
+            baselineTokens: manifest.prefix.before,
+        });
+    });
+    const compiledTotal = turns.reduce((n, t) => n + t.compiledTokens, 0);
+    const baselineTotal = turns.reduce((n, t) => n + t.baselineTokens, 0);
+    const touchedOnDemandFiles = new Set([...carried].map((id) => onDemandFileOf.get(id) ?? id));
+    const opened = manifest.onDemandFiles.map((m) => m.name).filter((n) => touchedOnDemandFiles.has(n));
+    const carriedTokens = [...carried].reduce((n, id) => n + (tokensOf.get(id) ?? 0), 0);
+    const steadyStatePerTurn = manifest.prefix.after + carriedTokens;
+    const steadyStateGainPerTurn = manifest.prefix.before - steadyStatePerTurn;
+    const saving = baselineTotal - compiledTotal;
+    let breakEvenTurn;
+    if (saving >= 0) {
+        breakEvenTurn = turns.findIndex((_, i) => {
+            const upTo = turns.slice(0, i + 1);
+            return upTo.reduce((n, t) => n + t.baselineTokens - t.compiledTokens, 0) >= 0;
+        });
+        breakEvenTurn = breakEvenTurn >= 0 ? breakEvenTurn + 1 : undefined;
+    }
+    else if (steadyStateGainPerTurn > 0) {
+        breakEvenTurn = turns.length + Math.ceil(-saving / steadyStateGainPerTurn);
+    }
+    return {
+        unit,
+        turns,
+        baselineTotal,
+        compiledTotal,
+        saving,
+        savingPct: baselineTotal === 0 ? 0 : (saving / baselineTotal) * 100,
+        onDemandOpened: opened,
+        onDemandNeverOpened: manifest.onDemandFiles.map((m) => m.name).filter((n) => !touchedOnDemandFiles.has(n)),
+        unroutedTurns,
+        steadyStatePerTurn,
+        steadyStateGainPerTurn,
+        breakEvenTurn,
+    };
+}

package/dist/benchReport.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Rendering for `bench`. Kept apart from bench.ts so the arithmetic stays testable without
+ * string matching, matching how report.ts sits beside the rule engine.
+ *
+ * Every rendered block states what kind of claim it is. A number here is either exact arithmetic
+ * over the manifest (the bounds) or a model conditional on a caller-supplied workload, and the
+ * output says which, every time, without the reader having to know the difference already.
+ */
+import type { BenchBounds, BenchModel } from "./bench.js";
+export declare function renderBounds(b: BenchBounds, tokenizer: string): string;
+export declare function renderModel(m: BenchModel, tokenizer: string): string;
+export declare function renderNoWorkload(): string;

package/dist/benchReport.js

@@ -0,0 +1,128 @@
+/**
+ * Rendering for `bench`. Kept apart from bench.ts so the arithmetic stays testable without
+ * string matching, matching how report.ts sits beside the rule engine.
+ *
+ * Every rendered block states what kind of claim it is. A number here is either exact arithmetic
+ * over the manifest (the bounds) or a model conditional on a caller-supplied workload, and the
+ * output says which, every time, without the reader having to know the difference already.
+ */
+import { formatTokens } from "./tokenizer.js";
+function pct(part, whole) {
+    if (whole === 0)
+        return "0.0%";
+    return `${((part / whole) * 100).toFixed(1)}%`;
+}
+function signed(n) {
+    return n >= 0 ? `saves ${formatTokens(n)}` : `costs ${formatTokens(-n)} more`;
+}
+export function renderBounds(b, tokenizer) {
+    const out = [""];
+    out.push(`  exact, over ${formatTokens(b.turns)} turns. No workload, no assumptions.`);
+    out.push("");
+    out.push(`    original memory file      ${formatTokens(b.baselinePerTurn).padStart(8)} tokens per turn`);
+    out.push(`    compiled always-loaded    ${formatTokens(b.compiledPerTurn).padStart(8)} tokens per turn`);
+    out.push(`    OnDemandMemory, all of it   ${formatTokens(b.totalOnDemandTokens).padStart(8)} tokens, on demand`);
+    out.push("");
+    out.push(`    best case, no OnDemandMemory file ever opened`);
+    out.push(`      ${formatTokens(b.baselineTotal)} -> ${formatTokens(b.bestCaseTotal)} tokens, ` +
+        `${signed(b.bestCaseSaving)} (${pct(b.bestCaseSaving, b.baselineTotal)})`);
+    out.push("");
+    out.push(`    worst case, every OnDemandMemory file opened on turn 1 and carried`);
+    out.push(`      ${formatTokens(b.baselineTotal)} -> ${formatTokens(b.worstCaseTotal)} tokens, ` +
+        `${signed(b.worstCaseSaving)}`);
+    out.push("");
+    out.push(`    break-even: ${formatTokens(b.breakEvenCarriedTokens)} tokens of OnDemandMemory can sit in`);
+    out.push(`    context from turn 1 to the end and come out even. Past that the compiled`);
+    out.push(`    shape costs more than the file it replaced.`);
+    out.push("");
+    out.push(`  tokenizer: ${tokenizer}, an offline estimate`);
+    out.push("");
+    return out.join("\n");
+}
+export function renderModel(m, tokenizer) {
+    const out = [""];
+    const turns = m.turns.length;
+    out.push(`  MODEL, not a measurement. ${formatTokens(turns)} turns from the workload you supplied.`);
+    out.push(m.unit === "section"
+        ? `  routed at section level, as recall() does: a hit carries the section, not the file.`
+        : `  routed at file level, as an agent reading a whole file the OnDemandMemory list named would.`);
+    out.push("");
+    out.push(`    memory tokens over the session   ${formatTokens(m.baselineTotal)} -> ${formatTokens(m.compiledTotal)}`);
+    out.push(`    ${signed(m.saving)}${m.saving >= 0 ? ` (${m.savingPct.toFixed(1)}%)` : ""}`);
+    out.push("");
+    if (m.onDemandOpened.length > 0) {
+        out.push(`    opened and carried (${m.onDemandOpened.length}):`);
+        for (const name of m.onDemandOpened)
+            out.push(`      ${name}`);
+        out.push("");
+    }
+    if (m.onDemandNeverOpened.length > 0) {
+        out.push(`    never opened (${m.onDemandNeverOpened.length}) - this is where the saving comes from:`);
+        for (const name of m.onDemandNeverOpened)
+            out.push(`      ${name}`);
+        out.push("");
+    }
+    out.push(`    one more turn, once everything this workload opens is in context:`);
+    out.push(`      ${formatTokens(m.steadyStatePerTurn)} vs ${formatTokens(m.turns[0]?.baselineTokens ?? 0)} baseline, ` +
+        `${m.steadyStateGainPerTurn >= 0 ? `saves ${formatTokens(m.steadyStateGainPerTurn)}` : `costs ${formatTokens(-m.steadyStateGainPerTurn)} more`} per turn`);
+    out.push("");
+    if (m.saving < 0 && m.steadyStateGainPerTurn <= 0) {
+        out.push(`    this workload never breaks even. The OnDemandMemory files it opens are large enough that`);
+        out.push(`    carrying them costs more every turn than the original file did, so a longer`);
+        out.push(`    session loses more, not less. Splitting differently, or not compiling this`);
+        out.push(`    file at all, is the honest answer here.`);
+        out.push("");
+    }
+    else if (m.saving < 0 && m.breakEvenTurn !== undefined) {
+        out.push(`    behind by ${formatTokens(-m.saving)} at turn ${formatTokens(m.turns.length)}, ` +
+            `recovering ${formatTokens(m.steadyStateGainPerTurn)} per turn:`);
+        out.push(`    breaks even around turn ${formatTokens(m.breakEvenTurn)} if nothing further opens.`);
+        out.push("");
+    }
+    else if (m.saving >= 0 && m.breakEvenTurn !== undefined) {
+        out.push(`    ahead from turn ${formatTokens(m.breakEvenTurn)} onward.`);
+        out.push("");
+    }
+    if (m.unroutedTurns > 0) {
+        out.push(`    ${formatTokens(m.unroutedTurns)} of ${formatTokens(turns)} turns matched no OnDemandMemory file at all.`);
+        out.push(`    Those turns are cheap here, but a real agent may have needed something and`);
+        out.push(`    not been routed to it. Check them before trusting the total.`);
+        out.push("");
+    }
+    out.push(`  what this number is conditional on:`);
+    out.push(`    - your workload being what a real session looks like. It is your file;`);
+    out.push(`      the tool cannot tell whether it is representative.`);
+    if (m.unit === "section") {
+        out.push(`    - every section recall() returns being carried for the rest of the session,`);
+        out.push(`      up to its token cap per turn. A real agent may widen with outline() or`);
+        out.push(`      read the whole file anyway.`);
+    }
+    else {
+        out.push(`    - every OnDemandMemory file whose triggers match being opened in full. A real`);
+        out.push(`      agent may read one and stop, or ignore one the list offered.`);
+    }
+    out.push(`    - memory tokens only. Reasoning, tool results and conversation are excluded`);
+    out.push(`      from both sides, so this ratio is not a session bill.`);
+    out.push("");
+    out.push(`  For observed usage against a live agent, measure a real multi-turn session with`);
+    out.push(`  and without the compile. That is the only path allowed to call a number measured.`);
+    out.push("");
+    out.push(`  tokenizer: ${tokenizer}, an offline estimate`);
+    out.push("");
+    return out.join("\n");
+}
+export function renderNoWorkload() {
+    return [
+        "",
+        "  No workload given, so only the exact bounds above are available.",
+        "",
+        "  A session number needs a workload: a file with one task description per line,",
+        "  describing what you actually do in this repo.",
+        "",
+        "    minnimemory bench --workload tasks.txt",
+        "",
+        "  minnimemory ships no default task list on purpose. A number produced from tasks",
+        "  the tool invented for itself would say more about the tool than about your repo.",
+        "",
+    ].join("\n");
+}

package/dist/bounds.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `bounds`: exact arithmetic over a compiled manifest, no assumptions, no workload, nothing to
+ * disagree with. The best case (no OnDemandMemory file is ever opened), the worst case (every
+ * OnDemandMemory file is opened on turn 1 and carried for the rest of the session), and the
+ * break-even point between them.
+ *
+ * Extracted from bench.ts (2026-09-16, C3) so `init.ts`'s compile-verdict check - which only
+ * ever needed this exact arithmetic, never bench.ts's workload model - does not pull in the
+ * router/recall machinery `model()` needs. `bench.ts` re-exports everything here unchanged, so
+ * every existing `from "./bench.js"` import of `bounds`/`BenchBounds`/`BenchError` keeps working.
+ *
+ * See bench.ts's own header for the fuller picture: this is one of the two things it computes,
+ * and it is not the same kind of claim as `model()` - see that file.
+ */
+import type { Manifest } from "./compile.js";
+export declare class BenchError extends Error {
+}
+export interface BenchBounds {
+    turns: number;
+    /** the original memory file, re-sent whole on every turn */
+    baselinePerTurn: number;
+    /** the compiled stub as measured on disk: AlwaysOnMemory, the OnDemandMemory list, instruction
+     * block and assembly overhead */
+    compiledPerTurn: number;
+    baselineTotal: number;
+    /** no OnDemandMemory file is ever opened */
+    bestCaseTotal: number;
+    /** every OnDemandMemory file is opened on turn 1 and carried to the end */
+    worstCaseTotal: number;
+    bestCaseSaving: number;
+    /** negative when the compiled shape costs more than the original */
+    worstCaseSaving: number;
+    /**
+     * OnDemandMemory tokens that can sit in context from turn 1 to the end of the session and
+     * exactly break even. Equal to the per-turn prefix saving, because both are paid on every turn.
+     */
+    breakEvenCarriedTokens: number;
+    totalOnDemandTokens: number;
+}
+export declare function bounds(manifest: Manifest, turns: number): BenchBounds;

package/dist/bounds.js

@@ -0,0 +1,44 @@
+/**
+ * `bounds`: exact arithmetic over a compiled manifest, no assumptions, no workload, nothing to
+ * disagree with. The best case (no OnDemandMemory file is ever opened), the worst case (every
+ * OnDemandMemory file is opened on turn 1 and carried for the rest of the session), and the
+ * break-even point between them.
+ *
+ * Extracted from bench.ts (2026-09-16, C3) so `init.ts`'s compile-verdict check - which only
+ * ever needed this exact arithmetic, never bench.ts's workload model - does not pull in the
+ * router/recall machinery `model()` needs. `bench.ts` re-exports everything here unchanged, so
+ * every existing `from "./bench.js"` import of `bounds`/`BenchBounds`/`BenchError` keeps working.
+ *
+ * See bench.ts's own header for the fuller picture: this is one of the two things it computes,
+ * and it is not the same kind of claim as `model()` - see that file.
+ */
+export class BenchError extends Error {
+}
+export function bounds(manifest, turns) {
+    if (!Number.isInteger(turns) || turns < 1) {
+        throw new BenchError(`--turns must be a positive whole number (got ${turns})`);
+    }
+    const baselinePerTurn = manifest.prefix.before;
+    // The measured stub, not alwaysOnBody.tokens + onDemandList.tokens. The stub also carries the
+    // marker fences, the routing instruction and the separators between the assembled parts, which
+    // belong to the always-loaded cost and are attributed to neither file. Summing the parts
+    // understates the real prefix (25 tokens on a 2,190-token stub, measured 2026-09-04) and so
+    // overstates the saving, which is the one direction this tool must never be wrong in.
+    const compiledPerTurn = manifest.prefix.after;
+    const totalOnDemandTokens = manifest.onDemandFiles.reduce((n, m) => n + m.tokens, 0);
+    const baselineTotal = baselinePerTurn * turns;
+    const bestCaseTotal = compiledPerTurn * turns;
+    const worstCaseTotal = (compiledPerTurn + totalOnDemandTokens) * turns;
+    return {
+        turns,
+        baselinePerTurn,
+        compiledPerTurn,
+        baselineTotal,
+        bestCaseTotal,
+        worstCaseTotal,
+        bestCaseSaving: baselineTotal - bestCaseTotal,
+        worstCaseSaving: baselineTotal - worstCaseTotal,
+        breakEvenCarriedTokens: baselinePerTurn - compiledPerTurn,
+        totalOnDemandTokens,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/**
+ * minnimemory CLI.
+ *
+ * Exit codes: 0 clean, 1 findings at or above the --fail-on threshold, 2 execution error.
+ */
+/**
+ * Single switch for whether `mcp` starts the real server or the disabled placeholder. Exported
+ * so tests/cli.test.ts can pin it without needing a live stdio transport in the test process.
+ *
+ * Re-enabled 2026-09-10 for internal testing, then shipped publicly in the 1.0.0-beta.1 npm
+ * release (2026-09-15). Flip back to true to re-stash the server in a future release.
+ */
+export declare const MCP_STASHED = false;
+export declare function main(argv: string[]): number;