minnimemory 1.0.0-beta.1

package/dist/instructions.js

@@ -0,0 +1,270 @@
+/**
+ * The token-reduction instruction set.
+ *
+ * Ported from the MinniMemory v1.0 research file. These are the behavioural half of the
+ * product: restructuring a memory file into AlwaysOnMemory plus OnDemandMemory only pays off
+ * if the agent is actually told to route rather than read everything, so candidates 15-25 in
+ * particular are what make the emitted structure do anything at all.
+ *
+ * IMPORTANT, and it must stay in the generated output: this set is reasoned and audited but
+ * NOT measured. The source research states plainly that no live measurement pass has run, and
+ * that candidates 5 and 15-25 cannot be measured by the current single-turn harness at all.
+ * Nothing here may be presented to a user as a proven saving.
+ */
+/**
+ * The default profile resolves the redundancies the source research documents rather than
+ * emitting all 25 and letting them contradict each other:
+ *
+ * - #1 subsumes #6, #7, #10 and #12, so those four are off by default.
+ * - #3 and #11 directly conflict, so both are off and MERGED-3-11 replaces them.
+ * - #13 is off by default because it trades a clarifying question for an assumption, which is
+ *   a judgement call a tool should not make for someone silently.
+ */
+export const INSTRUCTIONS = [
+    // -------------------------------------------------------------- output side
+    {
+        id: "01",
+        title: "Answer-length discipline",
+        text: "Give the shortest complete answer. Do not restate the question, add a preamble such as \"Here is\" or \"Sure\", or offer further help unless asked.",
+        category: "output",
+        defaultOn: true,
+        note: "subsumes 06, 07, 10 and 12",
+    },
+    {
+        id: "02",
+        title: "No visible re-verification",
+        text: "Do not restate your reasoning, double-check, or re-explain your answer in the visible response. If you need to verify something, do it silently before answering.",
+        category: "output",
+        defaultOn: true,
+    },
+    {
+        id: "03",
+        title: "Format-appropriate compactness",
+        text: "For list-like or factual answers, use the most compact valid Markdown (tables, short bullets) instead of full prose paragraphs.",
+        category: "output",
+        defaultOn: false,
+        note: "conflicts with 11; replaced by MERGED-3-11",
+    },
+    {
+        id: "04",
+        title: "Reference, do not repeat",
+        text: "Do not repeat back information the user already provided or that appears earlier in this conversation. Reference it briefly instead of restating it in full.",
+        category: "output",
+        defaultOn: true,
+    },
+    {
+        id: "05",
+        title: "Cache-stable prompt",
+        text: "Keep the always-loaded text identical across calls. Per-request values, such as dates, names, or session data, go in the request, never in the always-loaded block.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "06",
+        title: "Scope discipline",
+        text: "Deliver exactly what was asked, at the scope implied. Do not add unrequested extras, alternatives, or follow-up suggestions.",
+        category: "output",
+        defaultOn: false,
+        note: "covered by 01",
+    },
+    {
+        id: "07",
+        title: "No closing offers",
+        text: "Do not end with an offer to do more, such as \"Let me know if\" or \"Want me to also\", unless it is the direct answer to what was asked.",
+        category: "output",
+        defaultOn: false,
+        note: "covered by 01",
+    },
+    {
+        id: "08",
+        title: "Silent corrections",
+        text: "If you notice and fix your own earlier mistake, correct it plainly in one line and move on. Do not narrate the mistake, apologize, or explain what went wrong.",
+        category: "output",
+        defaultOn: true,
+    },
+    {
+        id: "09",
+        title: "No restated instructions or inputs",
+        text: "Do not repeat the task description, the rules you were given, or the input data back before answering. Go straight to the answer.",
+        category: "output",
+        defaultOn: true,
+    },
+    {
+        id: "10",
+        title: "One answer, not a menu",
+        text: "Give one recommended answer or approach, not a list of alternatives, unless the user explicitly asked to compare options.",
+        category: "output",
+        defaultOn: false,
+        note: "covered by 01",
+    },
+    {
+        id: "11",
+        title: "Minimal formatting overhead",
+        text: "Use plain sentences for short answers. Reserve headers, bold, and bullet lists for content that is genuinely structured or long enough to need them.",
+        category: "output",
+        defaultOn: false,
+        note: "conflicts with 03; replaced by MERGED-3-11",
+    },
+    {
+        id: "12",
+        title: "No trailing summary",
+        text: "Do not add a closing recap or \"In summary\" paragraph restating what was already said, unless the response is long enough that a reader would actually need one.",
+        category: "output",
+        defaultOn: false,
+        note: "covered by 01",
+    },
+    {
+        id: "13",
+        title: "Assume, do not ask, on reversible defaults",
+        text: "For small ambiguous choices with a reasonable default, make the choice and state it in passing rather than asking a clarifying question first.",
+        category: "output",
+        defaultOn: false,
+        note: "off by default: trading a clarifying question for an assumption is a judgement call, and some workflows want the question",
+    },
+    {
+        id: "14",
+        title: "No restating in code comments",
+        text: "In code output, do not add comments describing what the next line does. Comment only a genuinely non-obvious constraint.",
+        category: "output",
+        defaultOn: true,
+    },
+    {
+        id: "MERGED-3-11",
+        title: "Structure only when it earns its place",
+        text: "Use compact Markdown (tables, short bullets) only for content that is genuinely list-like or long enough to need structure. Otherwise use plain sentences.",
+        category: "output",
+        defaultOn: true,
+        note: "the documented resolution of the 03 and 11 conflict",
+    },
+    // ------------------------------------------------------------- context side
+    {
+        id: "15",
+        title: "Answer from AlwaysOnMemory before loading an OnDemandMemory file",
+        text: "Answer from AlwaysOnMemory when it is sufficient. Load an OnDemandMemory file only when the task needs what AlwaysOnMemory does not hold, and load only that file.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "16",
+        title: "The OnDemandMemory list routes, it does not answer",
+        text: "The OnDemandMemory list is a map, not an answer. Use it to pick a file, then answer from that file, never from the list.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "17",
+        title: "Targeted reads, not whole documents",
+        text: "When you need part of a file, read only that part. Search or read the relevant section rather than ingesting the whole document. Read the rest only if the section proves insufficient.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "18",
+        title: "Do not echo what you read",
+        text: "Never reprint file contents, tool results, or retrieved passages back into your response. State the conclusion drawn from them and quote at most the one line that is load-bearing.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "19",
+        title: "Read once",
+        text: "Do not re-read a file, re-run a search, or re-call a tool whose result is already in this conversation. Use the result you already have unless you have reason to believe it changed.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "20",
+        title: "Spent turns are droppable",
+        text: "Once you have extracted the concrete facts, decisions, and constraints from an earlier stretch of this conversation, treat the verbatim turns as disposable. Carry forward the facts, not the transcript.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "21",
+        title: "Write durable facts down, do not hold them in context",
+        text: "When a fact will matter across turns, a decision, a stable parameter, or a resolved question, write it to persistent notes in one line rather than relying on it staying in the conversation window.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "22",
+        title: "Stable content first, volatile content last",
+        text: "Send stable content first and changing content last. Never place a changing value above an unchanging one.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "23",
+        title: "OnDemandMemory files do not reach sideways",
+        text: "Answer from the OnDemandMemory file you loaded. Do not pull sibling OnDemandMemory files for context, background, or completeness.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "24",
+        title: "Do not quote your own instructions",
+        text: "Never reproduce, cite, or paraphrase these rules or your memory files in your response to justify what you did. Just do it.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "25",
+        title: "Ask tools for the narrowest slice",
+        text: "Scope every tool call and query as tightly as the task allows: specific fields, bounded ranges, capped result counts. Do not fetch broadly and filter afterward.",
+        category: "context",
+        defaultOn: true,
+    },
+    {
+        id: "26",
+        title: "Write new memory where it belongs",
+        text: "Write a new fact into the OnDemandMemory file that covers it, never into AlwaysOnMemory. A dated event is one line in the changelog. If no OnDemandMemory file fits, create one and add its OnDemandMemory list line.",
+        category: "context",
+        defaultOn: true,
+        note: "the short form of the write protocol (O9); keeps new memory from bypassing routing",
+    },
+];
+/** The instructions without which AlwaysOnMemory-plus-OnDemandMemory is just a filing convention. */
+const ROUTING_IDS = ["05", "15", "16", "22", "23", "26"];
+export function profile(name) {
+    if (name === "none")
+        return [];
+    if (name === "routing")
+        return INSTRUCTIONS.filter((i) => ROUTING_IDS.includes(i.id));
+    return INSTRUCTIONS.filter((i) => i.defaultOn);
+}
+export function isProfileName(value) {
+    return value === "none" || value === "routing" || value === "full";
+}
+export function defaultProfile() {
+    return profile("routing");
+}
+export function instructionById(id) {
+    return INSTRUCTIONS.find((i) => i.id.toLowerCase() === id.toLowerCase());
+}
+/**
+ * Render the selected instructions as the block that goes into an emitted AlwaysOnMemory file.
+ * Context rules come first because they govern what gets loaded at all.
+ */
+export function renderInstructions(selected) {
+    // An empty profile emits nothing at all, not an empty heading.
+    if (selected.length === 0)
+        return "";
+    const context = selected.filter((i) => i.category === "context");
+    const output = selected.filter((i) => i.category === "output");
+    // No caveat sentence here: whether the rules are measured is recorded in the manifest
+    // (instructionStatus) and the README, not charged to the agent on every turn (P3).
+    const lines = ["## Token discipline", ""];
+    if (context.length) {
+        lines.push("### What to load and keep", "");
+        for (const i of context)
+            lines.push(`- ${i.text}`);
+        lines.push("");
+    }
+    if (output.length) {
+        lines.push("### How to answer", "");
+        for (const i of output)
+            lines.push(`- ${i.text}`);
+        lines.push("");
+    }
+    return lines.join("\n").trimEnd();
+}

package/dist/mcp.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The MCP server: read-only tools that serve a compiled workspace's routed OnDemandMemory files
+ * at runtime.
+ *
+ * This is v2 of routing (DESIGN.md section 6). v1, agent-driven, stays the default and keeps
+ * working with this server absent: AlwaysOnMemory already tells an agent which OnDemandMemory
+ * file to read via its own file tools. This server exists for the two cases the file route
+ * cannot cover: hosts with no persistent memory file, and repos with enough OnDemandMemory files
+ * that the list itself gets expensive to hold in every prefix.
+ *
+ * The read-only tools: `recall` (the best memory sections for a task description, content
+ * inline, under a token cap), `modules` (the OnDemandMemory list, no content), `outline`
+ * (headings only, so an agent can decide before paying for an OnDemandMemory file's body).
+ * `scan` and `reorganize` live in scan.ts and reorganize.ts.
+ *
+ * `recall` ranks section-level units with router.ts (stemmed BM25, heading path and manifest
+ * triggers weighted) and returns units, never whole OnDemandMemory files: interface rule O4
+ * after the 2026-09-04 audit. `rankOnDemandFiles` below is the older trigger-overlap ranker over
+ * the manifest alone; it needs no file content, so `bench` still uses it to model the
+ * agent-driven route where an agent reads a whole file the OnDemandMemory list pointed at. Both
+ * are deterministic, offline, and call no model.
+ */
+import { type Manifest } from "./compile.js";
+import { type Unit, type SearchIndex } from "./router.js";
+export declare class McpTargetError extends Error {
+}
+/** Load and validate the manifest for a compiled workspace, or throw with a clear fix. Accepts a
+ * version 3 manifest (the `modules` key) and normalises it in memory to the version 4 shape
+ * (`onDemandFiles`), so a workspace compiled before the vocabulary sweep keeps working. */
+export declare function loadManifest(root: string): Manifest;
+/**
+ * Read one OnDemandMemory file by its manifest entry: the raw bytes on disk and the text the
+ * router indexes. They differ for an episodic JSON file, which is served as the markdown it
+ * stands for (O3): the manifest hash is over the bytes, so a drift check needs `raw` and the
+ * index needs `text`. One read serves both. The path is re-checked here, and the file must
+ * resolve (symlinks followed) to somewhere inside the compiled directory, so neither a `..`
+ * segment nor a symlinked file can read outside `.minnimemory/`.
+ */
+export declare function loadOnDemandRaw(root: string, onDemandFile: string): {
+    raw: string;
+    text: string;
+};
+/** The text of one OnDemandMemory file as the router and the agent see it. Every existing
+ * caller wants only this; the raw bytes matter to the drift check in `getUnitIndex` alone. */
+export declare function loadOnDemandContent(root: string, onDemandFile: string): string;
+export { rankOnDemandFiles, type RankedOnDemandFile } from "./router.js";
+/**
+ * Heading-only outline of an OnDemandMemory file's content, so an agent can decide before paying
+ * for the body.
+ * sections() returns a synthetic level-0 "(document)" entry for content with no real heading -
+ * that is not a heading an agent should see in an outline, so it is filtered here rather than
+ * leaking a fake entry through the tool.
+ */
+export declare function outlineOf(content: string): string[];
+export interface RecallMatch {
+    onDemandFile: string;
+    file: string;
+    heading: string;
+    /** heading path inside the OnDemandMemory file, top down, ending with this unit */
+    path: string[];
+    kind: "section" | "entry";
+    /** 1-indexed, inclusive, within the OnDemandMemory file */
+    startLine: number;
+    endLine: number;
+    tokens: number;
+    score: number;
+    content: string;
+}
+export interface RecallResult {
+    query: string;
+    /** what one match is; always a section-level unit, stated so a caller never assumes a file */
+    unit: "section";
+    maxTokens: number;
+    matches: RecallMatch[];
+    /** OnDemandMemory files whose bytes no longer match the manifest hash: hand-edited since
+     * `init` wrote them (MM010). Found on the index rebuild, so it reflects the state of disk as
+     * of the last rebuild for this root. Empty on a clean workspace. */
+    drifted: string[];
+}
+export interface RecallOptions {
+    /** cap on returned tokens; the top hit is always returned even when it alone exceeds it */
+    maxTokens?: number;
+    /** restrict ranking to one OnDemandMemory file by name */
+    module?: string;
+}
+/**
+ * The unit index and units for `manifest` at `root`, rebuilding only when the signature above has
+ * changed since the last call for this root. `recall`'s `module` filter is applied to the result
+ * of ranking against this cached, whole-workspace index rather than by building a second,
+ * file-scoped index per call - one cache entry serves every query, filtered or not.
+ * `drifted` names the OnDemandMemory files whose bytes no longer hash to their manifest entry
+ * (MM010), computed on the same rebuild and cached alongside the index: with `check` off the
+ * compiled surface, `recall` is the tool that has to say a file was hand-edited since init.
+ */
+export declare function getUnitIndex(root: string, manifest: Manifest): {
+    index: SearchIndex;
+    units: Unit[];
+    drifted: string[];
+};
+/** Test-only: forget every cached unit index, so a test that edits files on disk between calls
+ * does not need to also fake mtime/size to bust the cache. */
+export declare function clearUnitIndexCache(): void;
+/**
+ * The best section-level units for a query, content inline, best first, under a token cap.
+ * A hit inside a changelog returns that entry, not the log (rule 17 applied to the interface's
+ * own tool). Manifest triggers join each OnDemandMemory file's units at heading weight, so an
+ * edited trigger steers recall without touching the file's text.
+ */
+export declare function recall(root: string, manifest: Manifest, query: string, options?: RecallOptions): RecallResult;

package/dist/mcp.js

@@ -0,0 +1,252 @@
+/**
+ * The MCP server: read-only tools that serve a compiled workspace's routed OnDemandMemory files
+ * at runtime.
+ *
+ * This is v2 of routing (DESIGN.md section 6). v1, agent-driven, stays the default and keeps
+ * working with this server absent: AlwaysOnMemory already tells an agent which OnDemandMemory
+ * file to read via its own file tools. This server exists for the two cases the file route
+ * cannot cover: hosts with no persistent memory file, and repos with enough OnDemandMemory files
+ * that the list itself gets expensive to hold in every prefix.
+ *
+ * The read-only tools: `recall` (the best memory sections for a task description, content
+ * inline, under a token cap), `modules` (the OnDemandMemory list, no content), `outline`
+ * (headings only, so an agent can decide before paying for an OnDemandMemory file's body).
+ * `scan` and `reorganize` live in scan.ts and reorganize.ts.
+ *
+ * `recall` ranks section-level units with router.ts (stemmed BM25, heading path and manifest
+ * triggers weighted) and returns units, never whole OnDemandMemory files: interface rule O4
+ * after the 2026-09-04 audit. `rankOnDemandFiles` below is the older trigger-overlap ranker over
+ * the manifest alone; it needs no file content, so `bench` still uses it to model the
+ * agent-driven route where an agent reads a whole file the OnDemandMemory list pointed at. Both
+ * are deterministic, offline, and call no model.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { episodicJsonToMarkdown } from "./episodic.js";
+import { sections } from "./text.js";
+import { COMPILED_DIR_NAME, driftHash } from "./compile.js";
+import { buildSearchIndex, RECALL_MAX_TOKENS, rankUnits, selectUnits, unitsOf } from "./router.js";
+export class McpTargetError extends Error {
+}
+const COMPILED_DIR = COMPILED_DIR_NAME;
+/**
+ * An OnDemandMemory file path the manifest is allowed to name: `OnDemandMemory/<name>.md`,
+ * nothing else. A cloned repo can ship any manifest it likes, and the server runs with the
+ * user's file permissions, so `file` is never trusted as a path (security audit 2026-09-02,
+ * finding 1).
+ */
+const ON_DEMAND_FILE = /^OnDemandMemory\/[A-Za-z0-9_][A-Za-z0-9_-]*\.(md|json)$/;
+const OnDemandFileEntrySchema = z.object({
+    name: z.string().min(1),
+    file: z.string().regex(ON_DEMAND_FILE, "OnDemandMemory file must be OnDemandMemory/<name>.md or .json"),
+    tokens: z.number(),
+    hash: z.string(),
+    triggers: z.array(z.string()),
+    sourceLines: z.tuple([z.number(), z.number()]),
+    reason: z.string(),
+    kind: z.string().optional(),
+    generated: z.boolean().optional(),
+});
+const ManifestSchemaV4 = z.object({
+    version: z.literal(4),
+    tokenizer: z.string(),
+    generatedFrom: z.string(),
+    sourceHash: z.string(),
+    order: z.array(z.string()),
+    prefix: z.object({ before: z.number(), after: z.number() }),
+    always: z.object({ file: z.string(), tokens: z.number(), hash: z.string() }),
+    stub: z.object({ file: z.string(), tokens: z.number(), hash: z.string() }),
+    onDemandFiles: z.array(OnDemandFileEntrySchema),
+});
+/** Version 3 shape, kept only so an already-compiled workspace's manifest.json still loads;
+ * `init --update` rewrites it as version 4. The one difference is the `modules` key, normalised
+ * to `onDemandFiles` below once parsed. */
+const ManifestSchemaV3 = z.object({
+    version: z.literal(3),
+    tokenizer: z.string(),
+    generatedFrom: z.string(),
+    sourceHash: z.string(),
+    order: z.array(z.string()),
+    prefix: z.object({ before: z.number(), after: z.number() }),
+    always: z.object({ file: z.string(), tokens: z.number(), hash: z.string() }),
+    stub: z.object({ file: z.string(), tokens: z.number(), hash: z.string() }),
+    modules: z.array(OnDemandFileEntrySchema),
+});
+/** Load and validate the manifest for a compiled workspace, or throw with a clear fix. Accepts a
+ * version 3 manifest (the `modules` key) and normalises it in memory to the version 4 shape
+ * (`onDemandFiles`), so a workspace compiled before the vocabulary sweep keeps working. */
+export function loadManifest(root) {
+    const manifestPath = path.join(root, COMPILED_DIR, "manifest.json");
+    if (!fs.existsSync(manifestPath)) {
+        throw new McpTargetError(`no compiled workspace at ${root}\n` +
+            `  expected ${COMPILED_DIR}/manifest.json - run "minnimemory init --write" first`);
+    }
+    const raw = fs.readFileSync(manifestPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new McpTargetError(`${manifestPath} is not valid JSON: ${err.message}`);
+    }
+    const v4 = ManifestSchemaV4.safeParse(parsed);
+    if (v4.success)
+        return v4.data;
+    const v3 = ManifestSchemaV3.safeParse(parsed);
+    if (v3.success) {
+        const { modules, version: _version, ...rest } = v3.data;
+        return { ...rest, version: 4, onDemandFiles: modules };
+    }
+    const first = v4.error.issues[0];
+    const where = first ? `${first.path.join(".")}: ${first.message}` : "invalid shape";
+    throw new McpTargetError(`${manifestPath} is not a valid manifest (${where}) - rerun init`);
+}
+/**
+ * Read one OnDemandMemory file by its manifest entry: the raw bytes on disk and the text the
+ * router indexes. They differ for an episodic JSON file, which is served as the markdown it
+ * stands for (O3): the manifest hash is over the bytes, so a drift check needs `raw` and the
+ * index needs `text`. One read serves both. The path is re-checked here, and the file must
+ * resolve (symlinks followed) to somewhere inside the compiled directory, so neither a `..`
+ * segment nor a symlinked file can read outside `.minnimemory/`.
+ */
+export function loadOnDemandRaw(root, onDemandFile) {
+    if (!ON_DEMAND_FILE.test(onDemandFile)) {
+        throw new McpTargetError(`refusing OnDemandMemory path outside OnDemandMemory/: ${onDemandFile}`);
+    }
+    const compiledDir = path.join(root, COMPILED_DIR);
+    const abs = path.join(compiledDir, onDemandFile);
+    if (!fs.existsSync(abs)) {
+        throw new McpTargetError(`OnDemandMemory file missing on disk: ${onDemandFile} (manifest is stale - rerun init)`);
+    }
+    const real = fs.realpathSync(abs);
+    const realDir = fs.realpathSync(compiledDir);
+    if (!real.startsWith(realDir + path.sep)) {
+        throw new McpTargetError(`refusing OnDemandMemory file that resolves outside ${COMPILED_DIR}/: ${onDemandFile}`);
+    }
+    const raw = fs.readFileSync(real, "utf8");
+    // O3: a JSON episodic file is served to the router and the agent as the markdown it stands for.
+    return { raw, text: onDemandFile.endsWith(".json") ? episodicJsonToMarkdown(raw) : raw };
+}
+/** The text of one OnDemandMemory file as the router and the agent see it. Every existing
+ * caller wants only this; the raw bytes matter to the drift check in `getUnitIndex` alone. */
+export function loadOnDemandContent(root, onDemandFile) {
+    return loadOnDemandRaw(root, onDemandFile).text;
+}
+// RankedOnDemandFile and rankOnDemandFiles moved to router.js (2026-09-13 audit round 2, D7c): they belong
+// beside the other ranking code, not on the mcp-server-facing module. Re-exported here so
+// bench.ts and every existing `from "./mcp.js"` import keeps working unchanged.
+export { rankOnDemandFiles } from "./router.js";
+/**
+ * Heading-only outline of an OnDemandMemory file's content, so an agent can decide before paying
+ * for the body.
+ * sections() returns a synthetic level-0 "(document)" entry for content with no real heading -
+ * that is not a heading an agent should see in an outline, so it is filtered here rather than
+ * leaking a fake entry through the tool.
+ */
+export function outlineOf(content) {
+    const lines = content.split(/\r?\n/);
+    return sections(lines)
+        .filter((s) => s.level > 0)
+        .map((s) => `${"#".repeat(s.level)} ${s.heading}`);
+}
+/**
+ * One cache entry per server root, holding the section-level unit index `recall` ranks against.
+ * Rebuilding it means re-reading and re-splitting every OnDemandMemory file and re-running
+ * BM25's document-frequency pass over the whole corpus - real work `recall` used to redo on every
+ * single call, even from the same still-unchanged workspace within one server session
+ * (2026-09-13 audit round 2, D5).
+ */
+const unitIndexCache = new Map();
+/** One OnDemandMemory file's contribution to the cache signature: its manifest hash plus what is
+ * actually on disk right now, so an edit made outside `init`/`update` (a hand edit to an
+ * OnDemandMemory file) still invalidates the cache even though the manifest itself did not
+ * change. */
+function onDemandFileSignature(root, onDemandFile, manifestHash) {
+    try {
+        const st = fs.statSync(path.join(root, COMPILED_DIR, onDemandFile));
+        return `${onDemandFile}:${manifestHash}:${st.mtimeMs}:${st.size}`;
+    }
+    catch {
+        return `${onDemandFile}:${manifestHash}:(missing)`;
+    }
+}
+function manifestSignature(root, manifest) {
+    const perFile = manifest.onDemandFiles.map((m) => onDemandFileSignature(root, m.file, m.hash)).join("|");
+    return `${manifest.sourceHash}:${manifest.always.hash}:${perFile}`;
+}
+/**
+ * The unit index and units for `manifest` at `root`, rebuilding only when the signature above has
+ * changed since the last call for this root. `recall`'s `module` filter is applied to the result
+ * of ranking against this cached, whole-workspace index rather than by building a second,
+ * file-scoped index per call - one cache entry serves every query, filtered or not.
+ * `drifted` names the OnDemandMemory files whose bytes no longer hash to their manifest entry
+ * (MM010), computed on the same rebuild and cached alongside the index: with `check` off the
+ * compiled surface, `recall` is the tool that has to say a file was hand-edited since init.
+ */
+export function getUnitIndex(root, manifest) {
+    const signature = manifestSignature(root, manifest);
+    const cached = unitIndexCache.get(root);
+    if (cached && cached.signature === signature) {
+        return { index: cached.index, units: cached.units, drifted: cached.drifted };
+    }
+    // A rebuild is the only place drift can be checked cheaply: the content is already being
+    // read and parsed here, and a cache hit means nothing on disk moved, so there is no new
+    // drift to find. The first call of any session rebuilds, which is what catches drift a
+    // previous session left behind. Hash the raw bytes, not the indexed text: an episodic
+    // JSON file is indexed as the markdown it stands for, but the manifest hashed the bytes.
+    // driftHash, not a raw hash, so a checkout that rewrote line endings is not drift.
+    const drifted = [];
+    const units = manifest.onDemandFiles.flatMap((m) => {
+        const { raw, text } = loadOnDemandRaw(root, m.file);
+        if (driftHash(raw) !== m.hash)
+            drifted.push(m.file);
+        return unitsOf({ name: m.name, file: m.file }, text);
+    });
+    const index = buildSearchIndex(units, new Map(manifest.onDemandFiles.map((m) => [m.name, m.triggers])));
+    unitIndexCache.set(root, { signature, index, units, drifted });
+    return { index, units, drifted };
+}
+/** Test-only: forget every cached unit index, so a test that edits files on disk between calls
+ * does not need to also fake mtime/size to bust the cache. */
+export function clearUnitIndexCache() {
+    unitIndexCache.clear();
+}
+/**
+ * The best section-level units for a query, content inline, best first, under a token cap.
+ * A hit inside a changelog returns that entry, not the log (rule 17 applied to the interface's
+ * own tool). Manifest triggers join each OnDemandMemory file's units at heading weight, so an
+ * edited trigger steers recall without touching the file's text.
+ */
+export function recall(root, manifest, query, options = {}) {
+    if (options.module !== undefined && !manifest.onDemandFiles.some((m) => m.name === options.module)) {
+        const known = manifest.onDemandFiles.map((m) => m.name).join(", ") || "(none)";
+        throw new McpTargetError(`unknown OnDemandMemory file "${options.module}". known OnDemandMemory files: ${known}`);
+    }
+    const { index, drifted } = getUnitIndex(root, manifest);
+    const maxTokens = options.maxTokens ?? RECALL_MAX_TOKENS;
+    let ranked = rankUnits(index, query);
+    if (options.module !== undefined) {
+        const wanted = options.module;
+        ranked = ranked.filter((r) => r.unit.onDemandFile === wanted);
+    }
+    const picked = selectUnits(ranked, maxTokens);
+    return {
+        query,
+        unit: "section",
+        maxTokens,
+        matches: picked.map(({ unit, score }) => ({
+            onDemandFile: unit.onDemandFile,
+            file: unit.file,
+            heading: unit.heading,
+            path: unit.path,
+            kind: unit.kind,
+            startLine: unit.startLine,
+            endLine: unit.endLine,
+            tokens: unit.tokens,
+            score,
+            content: unit.content,
+        })),
+        drifted,
+    };
+}