minnimemory 1.0.0-beta.1

package/dist/paths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Path containment, in one place.
+ *
+ * Three call sites needed the same check and each grew its own version, which is how they
+ * drifted apart: reorganize.ts resolved through the nearest existing ancestor, init.ts compared
+ * a plain resolve against a realpath'd root (so a workspace behind a symlink refused every
+ * write), and mcpServer.ts skipped the realpath entirely for a path that did not exist yet.
+ * A containment check that differs per caller is a containment check you cannot reason about.
+ */
+/**
+ * The real path of `abs`, following symlinks as far as the path exists and rejoining the
+ * not-yet-created remainder. A file that does not exist still gets its ancestors resolved, so a
+ * planned write into a symlinked directory is judged by where it would actually land.
+ */
+export declare function realPathOf(abs: string): string;
+/** Is `abs` the root itself, or somewhere beneath it, once both are resolved through symlinks? */
+export declare function containedIn(root: string, abs: string): boolean;
+/**
+ * Reject a caller-supplied relative path before it is joined to a root: absolute paths and any
+ * `..` segment. Checked on the string, because a `..` that resolves back inside the root is
+ * still a caller reaching for somewhere it was not given.
+ */
+export declare function isEscapingRelative(rel: string): boolean;
+/** Does `rel` pass through a directory named `name`? A segment test, not a prefix test. */
+export declare function hasSegment(rel: string, name: string): boolean;

package/dist/paths.js

@@ -0,0 +1,47 @@
+/**
+ * Path containment, in one place.
+ *
+ * Three call sites needed the same check and each grew its own version, which is how they
+ * drifted apart: reorganize.ts resolved through the nearest existing ancestor, init.ts compared
+ * a plain resolve against a realpath'd root (so a workspace behind a symlink refused every
+ * write), and mcpServer.ts skipped the realpath entirely for a path that did not exist yet.
+ * A containment check that differs per caller is a containment check you cannot reason about.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * The real path of `abs`, following symlinks as far as the path exists and rejoining the
+ * not-yet-created remainder. A file that does not exist still gets its ancestors resolved, so a
+ * planned write into a symlinked directory is judged by where it would actually land.
+ */
+export function realPathOf(abs) {
+    let existing = abs;
+    let remainder = "";
+    while (!fs.existsSync(existing)) {
+        remainder = path.join(path.basename(existing), remainder);
+        const parent = path.dirname(existing);
+        if (parent === existing)
+            return abs;
+        existing = parent;
+    }
+    const real = fs.realpathSync(existing);
+    return remainder ? path.join(real, remainder) : real;
+}
+/** Is `abs` the root itself, or somewhere beneath it, once both are resolved through symlinks? */
+export function containedIn(root, abs) {
+    const realRoot = fs.existsSync(root) ? fs.realpathSync(root) : path.resolve(root);
+    const real = realPathOf(abs);
+    return real === realRoot || real.startsWith(realRoot + path.sep);
+}
+/**
+ * Reject a caller-supplied relative path before it is joined to a root: absolute paths and any
+ * `..` segment. Checked on the string, because a `..` that resolves back inside the root is
+ * still a caller reaching for somewhere it was not given.
+ */
+export function isEscapingRelative(rel) {
+    return path.isAbsolute(rel) || rel.split(/[/\\]/).includes("..");
+}
+/** Does `rel` pass through a directory named `name`? A segment test, not a prefix test. */
+export function hasSegment(rel, name) {
+    return rel.split(/[/\\]/).includes(name);
+}

package/dist/recall.d.ts

@@ -0,0 +1,113 @@
+/**
+ * The recall engine: pure logic that loads a compiled workspace's manifest and serves its routed
+ * OnDemandMemory files at runtime. No SDK, no transport, no Zod - the MCP server that wires this
+ * onto actual tools lives in mcpServer.ts, kept separate on purpose so this half is testable from
+ * fixtures alone (renamed from mcp.ts 2026-09-16, C3, once mcpServer.ts had grown into the real
+ * server module and this file held none of the tool wiring its old name implied).
+ *
+ * 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 built on this: `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. `recallDir.ts` is the manifest-less
+ * counterpart, over a memory directory with no `.minnimemory/` compile step.
+ *
+ * `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/recall.js

@@ -0,0 +1,256 @@
+/**
+ * The recall engine: pure logic that loads a compiled workspace's manifest and serves its routed
+ * OnDemandMemory files at runtime. No SDK, no transport, no Zod - the MCP server that wires this
+ * onto actual tools lives in mcpServer.ts, kept separate on purpose so this half is testable from
+ * fixtures alone (renamed from mcp.ts 2026-09-16, C3, once mcpServer.ts had grown into the real
+ * server module and this file held none of the tool wiring its old name implied).
+ *
+ * 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 built on this: `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. `recallDir.ts` is the manifest-less
+ * counterpart, over a memory directory with no `.minnimemory/` compile step.
+ *
+ * `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 this recall-engine module. Re-exported here so
+// bench.ts and every existing `from "./recall.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,
+    };
+}

package/dist/recallDir.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Manifest-less recall over a memory folder (Layout B): an index file (one of
+ * discover.ts's `LIST_FILE_NAMES`) plus topic `.md` files, or a Claude Code auto-memory folder.
+ * No `.minnimemory/` compile step, no manifest - the same rankUnits/selectUnits pipeline
+ * recall() in recall.ts runs against a compiled workspace's manifest, built straight off files on
+ * disk instead. This is the "memory-dir" launch mode (detectPhase() in discover.ts), a new
+ * surface, not a change to the existing compiled or setup surfaces.
+ *
+ * Lexical only, offline, deterministic - same posture as recall()/router.ts: BM25 over stemmed
+ * terms, no embeddings, no model call, no network. The index file's hook lines
+ * ("- [Title](file.md) - hook text") are parsed into per-file triggers the same way
+ * Research/Pipeline/replay_ranker.mjs already does for its own offline replay.
+ *
+ * Never follows a `@path` import: this module simply does not implement that resolution, so a
+ * topic file naming one outside the directory has nothing to follow it with. Every file read
+ * passes paths.ts's containment check first, so a symlinked topic file cannot point recall()
+ * outside the directory it was asked to serve.
+ */
+import type { RecallResult } from "./recall.js";
+import { type SearchIndex } from "./router.js";
+export declare class RecallDirError extends Error {
+}
+/**
+ * The section-level unit index for a memory directory, rebuilt only when a topic file's or the
+ * index file's mtime/size has changed since the last call for this directory.
+ */
+export declare function getDirIndex(dir: string): SearchIndex;
+/** Test-only: forget every cached directory index, so a test that edits files on disk between
+ * calls does not also need to fake mtime/size to bust the cache. */
+export declare function clearDirIndexCache(): void;
+/** Every topic file's name plus, when an index file is present, the hook line it parsed to
+ * (`[]` when none was found). The listing recall() with no query, or a no-match miss, renders. */
+export interface DirFileEntry {
+    name: string;
+    file: string;
+    triggers: string[];
+}
+export declare function listDirFiles(dir: string): DirFileEntry[];
+export interface RecallDirOptions {
+    /** cap on returned tokens; the top hit is always returned even when it alone exceeds it */
+    maxTokens?: number;
+    /** restrict ranking to one topic file by name (extension stripped) */
+    file?: string;
+}
+/**
+ * The best section-level units for a query over a memory directory with no manifest, same shape
+ * as recall.ts's recall(). `drifted` is always empty here: drift (MM010) is a manifest concept, and
+ * a manifest-less directory has none to drift from.
+ */
+export declare function recallDir(dir: string, query: string, options?: RecallDirOptions): RecallResult;