@seanhogg/builderforce-memory-mcp 2026.10.3 → 2026.10.22

package/src/compaction-tools.ts

@@ -0,0 +1,206 @@
+/**
+ * The lossless compaction pair — `memory_compact` and `memory_restore` — split out
+ * of tools.ts the same way the gateway and experience families are.
+ *
+ * `memory_compact` stubs a fact only after archiving its original and proving the
+ * local Evermind absorbed it; `memory_restore` brings back the text of stubs that
+ * predate archiving (`contentLost`). The rules are compaction.ts / restore.ts; this
+ * module is only their I/O against a MemoryBackend.
+ */
+
+import { z } from "zod";
+import type { MemoryBackend, RecallHit, RememberInput } from "./backend.js";
+import { DEFAULT_STUB_CHARS, planLosslessCompaction, type CompactionSkip } from "./compaction.js";
+import { parseRestoreSource, planRestore, restoredArchive, type RestoreTarget } from "./restore.js";
+import { fail, ok, type MemoryTool } from "./tool-core.js";
+import type { MemoryToolsOptions } from "./tools.js";
+
+const SKIP_REASONS: Record<CompactionSkip["reason"], string> = {
+    not_found: "not found",
+    already_compacted: "already compacted",
+    not_smaller: "already shorter than its stub",
+    no_probe: "no local Evermind model to prove it was absorbed (set BUILDERFORCE_MEMORY_MODEL)",
+    probe_failed: "the Evermind model could not answer a recall question about it — not absorbed yet",
+    no_archive: "this backend cannot archive the original, so stubbing would lose it",
+};
+
+/** One-line compaction receipt: what shrank, what it saved, and what was left alone. */
+function renderCompaction(compacted: number, bytesSaved: number, skipped: CompactionSkip[]): string {
+    const lines = [`Compacted ${compacted} memory(ies), ${bytesSaved} character(s) reclaimed.`];
+    for (const s of skipped) lines.push(`• skipped ${s.key} — ${SKIP_REASONS[s.reason]}`);
+    return lines.join("\n");
+}
+
+/** `memory_restore` input: inline JSON always; a file path only where the host may read its disk. */
+function restoreSchema(allowFile: boolean): z.ZodRawShape {
+    const shape: z.ZodRawShape = {
+        json: z.string().optional().describe("The export itself, as JSON text (array, or JSON Lines)."),
+    };
+    if (allowFile) shape["file"] = z.string().optional().describe("Path to a JSON export file to restore from.");
+    return shape;
+}
+
+/** Write a batch through the backend's batch path when it has one. */
+async function writeAll(backend: MemoryBackend, writes: RememberInput[]): Promise<void> {
+    if (writes.length === 0) return;
+    if (backend.rememberMany) await backend.rememberMany(writes);
+    else for (const w of writes) await backend.remember!(w);
+}
+
+/** Registers `memory_compact` and `memory_restore`. Caller checks the backend is writable. */
+export function appendCompactionTools(
+    tools: MemoryTool[],
+    backend: MemoryBackend,
+    opts: Pick<MemoryToolsOptions, "recallProbe" | "readRestoreFile">,
+): void {
+    // memory_compact — the FIRST-CLASS compaction path. It writes through the live
+    // store (get → plan → archive → remember), so a durable backend's in-memory state
+    // and its on-disk snapshot agree afterwards. It is LOSSLESS: each original is
+    // archived before its body is stubbed, and only facts the local Evermind answers
+    // a recall probe about are stubbed at all (see planLosslessCompaction).
+    tools.push({
+        name: "memory_compact",
+        description:
+            "Shrink memories that have already been absorbed into the local Evermind model down to " +
+            "a one-line pointer stub, reclaiming the context they were eating. Each fact is first " +
+            "checked with a recall question put to the model; facts it cannot answer stay as they " +
+            "are. The full original is archived and memory_recall / memory_get still return it, so " +
+            "nothing is lost. Already-compacted keys are skipped, so repeating the call is safe.",
+        inputSchema: {
+            keys: z.array(z.string()).min(1).describe("Exact keys of the memories to compact."),
+            stub: z
+                .string()
+                .optional()
+                .describe(
+                    "Explicit replacement body applied to every listed key. Omit to generate " +
+                        "'[absorbed→Evermind vN] <first line>' from each entry's own first line.",
+                ),
+            version: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("Version of the model that absorbed these facts; appears in the generated stub."),
+            maxChars: z
+                .number()
+                .int()
+                .min(20)
+                .max(500)
+                .optional()
+                .describe(`Max characters of the generated pointer line (default ${DEFAULT_STUB_CHARS}).`),
+        },
+        handler: async (args) => {
+            try {
+                const raw = args["keys"];
+                const keys = Array.isArray(raw) ? raw.map((k) => String(k)).filter(Boolean) : [];
+                if (keys.length === 0) return fail("keys is required.");
+
+                // ONE read pass: the hit carries both the body the plan reasons about
+                // and the tags/importance the rewrite must preserve. A stub resolved to
+                // its archive reports the STORED stub in `hit.stub` — that is what the
+                // plan must see, or an archived fact would be compacted again.
+                const hits = new Map<string, RecallHit>();
+                for (const key of keys) {
+                    const hit = await backend.get(key);
+                    if (hit) hits.set(key, hit);
+                }
+
+                const plan = await planLosslessCompaction(
+                    keys.map((key) => {
+                        const hit = hits.get(key);
+                        return { key, content: hit ? (hit.stub ?? hit.content) : undefined };
+                    }),
+                    {
+                        stub: typeof args["stub"] === "string" ? (args["stub"] as string) : undefined,
+                        version: args["version"] == null ? undefined : Number(args["version"]),
+                        maxChars: args["maxChars"] == null ? undefined : Number(args["maxChars"]),
+                        probe: opts.recallProbe ?? null,
+                        canArchive: typeof backend.archive === "function",
+                    },
+                );
+
+                if (plan.writes.length > 0) {
+                    // Originals FIRST, durably — only then may the bodies become stubs.
+                    await backend.archive!(plan.writes.map((w) => w.archive));
+                    // Preserve tags/importance — compaction shortens a body, it does not
+                    // reclassify the fact.
+                    await writeAll(
+                        backend,
+                        plan.writes.map((w) => {
+                            const prev = hits.get(w.key);
+                            return { key: w.key, content: w.content, tags: prev?.tags, importance: prev?.importance };
+                        }),
+                    );
+                }
+
+                return ok(renderCompaction(plan.writes.length, plan.bytesSaved, plan.skipped));
+            } catch (err) {
+                return fail(`compact failed: ${String(err)}`);
+            }
+        },
+    });
+
+    // memory_restore — the way back for stubs whose original was never archived
+    // (`contentLost`). The text is matched to a stub by key, or by its first line
+    // against the stub's pointer, then archived beside the stub (the stub stays, so
+    // the token saving stays) — or written back as the body on a backend that
+    // cannot archive.
+    tools.push({
+        name: "memory_restore",
+        description:
+            "Restore the full text of memories marked '(content lost)' — compaction stubs whose " +
+            "original was never kept — from an export. Accepts [{key, content}] (a memory export) " +
+            "or the Evermind coordinator's [{id, text}] record dump; records are matched by key, " +
+            "else by their first line against the stub. Restored memories recall in full again.",
+        inputSchema: restoreSchema(!!opts.readRestoreFile),
+        handler: async (args) => {
+            try {
+                const file = typeof args["file"] === "string" ? (args["file"] as string) : "";
+                let text = typeof args["json"] === "string" ? (args["json"] as string) : "";
+                if (file && opts.readRestoreFile) text = await opts.readRestoreFile(file);
+                if (!text.trim()) return fail(opts.readRestoreFile ? "file or json is required." : "json is required.");
+
+                const records = parseRestoreSource(text);
+                if (records.length === 0) return fail("no restorable records (need {key, content} or {id, text} rows).");
+
+                // Targets: the lost stubs (all of them when the backend can list them,
+                // else just the keys the records name).
+                const keys = new Set<string>(backend.lostKeys ? await backend.lostKeys() : []);
+                for (const r of records) if (r.key) keys.add(r.key);
+                const targets: RestoreTarget[] = [];
+                const hits = new Map<string, RecallHit>();
+                for (const key of keys) {
+                    const hit = await backend.get(key);
+                    if (!hit?.contentLost) continue;
+                    hits.set(key, hit);
+                    targets.push({ key, stub: hit.content });
+                }
+
+                const plan = planRestore(records, targets);
+                if (plan.matches.length > 0) {
+                    if (backend.archive) {
+                        await backend.archive(plan.matches.map((m) => restoredArchive(m, hits.get(m.key)!.content)));
+                    } else {
+                        await writeAll(
+                            backend,
+                            plan.matches.map((m) => {
+                                const prev = hits.get(m.key);
+                                return { key: m.key, content: m.content, tags: prev?.tags, importance: prev?.importance };
+                            }),
+                        );
+                    }
+                }
+
+                const lines = [
+                    `Restored ${plan.matches.length} memory(ies) of ${targets.length} with lost content.`,
+                    ...plan.matches.map((m) => `• ${m.key} (matched by ${m.via})`),
+                ];
+                if (plan.ambiguous.length > 0) lines.push(`Ambiguous (left alone): ${plan.ambiguous.join(", ")}`);
+                if (plan.unmatched > 0) lines.push(`${plan.unmatched} record(s) matched no lost memory.`);
+                return ok(lines.join("\n"));
+            } catch (err) {
+                return fail(`restore failed: ${String(err)}`);
+            }
+        },
+    });
+}

package/src/compaction.ts

@@ -1,5 +1,5 @@
 /**
- * Compaction — turning an ABSORBED memory into a terse pointer stub.
+ * Compaction — turning an ABSORBED memory into a terse pointer stub, LOSSLESSLY.
  *
  * Once a fact has been folded into an Evermind (or any downstream learner) the
  * full body has done its job: keeping it verbatim in the store means every
@@ -7,10 +7,24 @@
  * Compaction replaces the body with a one-line `[absorbed→Evermind vN] <first
  * line>` pointer, so the fact stops filling context while it stays findable.
  *
+ * Two rules make that safe:
+ *   1. The full original is ARCHIVED before the body is stubbed — in a sidecar
+ *      `<memory>.archive.json` beside the snapshot, never inside it, so it survives
+ *      the snapshot round-trip, an external rewrite of the snapshot, and the
+ *      store's entry cap / eviction. Recall resolves a stub back to its archive.
+ *   2. A fact is stubbed only after a RECALL PROBE passes: a question generated
+ *      from the fact is put to the local Evermind model, and an answer that does
+ *      not carry the fact (or no model at all) leaves the fact uncompacted —
+ *      "absorbed" is proven, not asserted.
+ *
+ * A stub with no archive is a fact whose text is gone (compacted before rule 1
+ * existed): {@link isContentLost} names it, and every reader labels it with
+ * {@link CONTENT_LOST_LABEL} until `memory_restore` brings the text back.
+ *
  * The rules live here — not in the tool handler and not in a transport — because
  * BOTH the in-process `memory_compact` tool and any external compactor (the
- * BuilderForce VS Code extension rewrites the snapshot directly) must produce
- * byte-identical stubs; otherwise re-running either one re-stubs the other's work.
+ * BuilderForce VS Code extension) must produce byte-identical stubs and the same
+ * archive; otherwise re-running either one re-stubs the other's work.
  *
  * Dependency-free and published as its own subpath
  * (`@seanhogg/builderforce-memory-mcp/compaction`), so an external compactor imports
@@ -48,25 +62,60 @@ export function memoryStub(content: string, version: number, maxChars = DEFAULT_
     return `${STUB_PREFIX} v${version}] ${firstLine(content, maxChars)}`;
 }
 
+/** The pointer text inside a stub (after the `] `), without a trailing ellipsis. */
+export function stubPointer(stub: string): string {
+    const s = stub.trim();
+    const close = s.indexOf("] ");
+    const pointer = isStub(s) && close >= 0 ? s.slice(close + 2) : s;
+    return pointer.replace(/…$/, "").trim();
+}
+
 /** One entry considered for compaction. */
 export interface CompactionCandidate {
     key: string;
     content: string;
 }
 
-/** A body rewrite the caller should apply. */
+/**
+ * The full original of a compacted fact — what the archive keeps so a stub is
+ * never the only copy. Written BEFORE the stub replaces the body.
+ */
+export interface ArchivedFact {
+    key: string;
+    /** The original, full body. */
+    content: string;
+    /** The stub that replaced it. */
+    stub: string;
+    /** Evermind version that absorbed it. */
+    version: number;
+    /** Unix ms the archive row was written. */
+    archivedAt: number;
+}
+
+/** A body rewrite the caller should apply — archive `archive` FIRST, then write `content`. */
 export interface CompactionWrite {
     key: string;
     /** The stub that replaces the entry's body. */
     content: string;
     /** Characters recovered by this rewrite. */
     bytesSaved: number;
+    /** The original body, to be archived before the stub is written. */
+    archive: ArchivedFact;
 }
 
 /** Why a candidate was left alone. */
 export interface CompactionSkip {
     key: string;
-    reason: "not_found" | "already_compacted" | "not_smaller";
+    reason:
+        | "not_found"
+        | "already_compacted"
+        | "not_smaller"
+        /** No local model to probe with — the fact cannot be proven absorbed. */
+        | "no_probe"
+        /** The model could not answer the probe question generated from the fact. */
+        | "probe_failed"
+        /** The caller cannot archive the original, so stubbing would lose it. */
+        | "no_archive";
 }
 
 /** The decided plan: what to write, what to leave, and the total recovered. */
@@ -84,18 +133,23 @@ export interface CompactionOptions {
     version?: number;
     /** Max characters of a generated pointer line. Default {@link DEFAULT_STUB_CHARS}. */
     maxChars?: number;
+    /** Clock for {@link ArchivedFact.archivedAt}. Default `Date.now()`. */
+    now?: number;
 }
 
 /**
- * Decide the compaction for a set of candidates. Pure — no I/O — so the same
- * rules are unit-testable and reusable by any caller that can read and write
- * memories. `undefined` content means the key was not found.
+ * Decide the STRUCTURAL compaction for a set of candidates: what is already a
+ * stub, what would not shrink. Pure — no I/O — and NOT the whole contract: a
+ * caller must still archive each write's `archive` before applying it, and prove
+ * absorption — {@link planLosslessCompaction} runs this and then the probe.
+ * `undefined` content means the key was not found.
  */
 export function planCompaction(
     candidates: Array<CompactionCandidate | { key: string; content: undefined }>,
     opts: CompactionOptions = {},
 ): CompactionPlan {
     const version = opts.version ?? 0;
+    const now = opts.now ?? Date.now();
     const maxChars = Math.max(20, opts.maxChars ?? DEFAULT_STUB_CHARS);
     const writes: CompactionWrite[] = [];
     const skipped: CompactionSkip[] = [];
@@ -118,9 +172,174 @@ export function planCompaction(
             continue;
         }
         const saved = content.length - stub.length;
-        writes.push({ key: c.key, content: stub, bytesSaved: saved });
+        writes.push({
+            key: c.key,
+            content: stub,
+            bytesSaved: saved,
+            archive: { key: c.key, content, stub, version, archivedAt: now },
+        });
         bytesSaved += saved;
     }
 
     return { writes, skipped, bytesSaved };
 }
+
+// ── Recall probe ─────────────────────────────────────────────────────────────
+
+/**
+ * The local model compaction asks before it stubs a fact. `answer` returns the
+ * model's text for a question, or null when it cannot answer at all.
+ */
+export interface RecallProbe {
+    answer(question: string): Promise<string | null>;
+}
+
+/** A question generated from one fact, and the token a correct answer must carry. */
+export interface ProbeQuestion {
+    question: string;
+    expected: string;
+}
+
+const PROBE_BLANK = "____";
+
+/** Tokens of a line that a cloze question can blank: alphanumeric, 4+ chars. */
+function probeTokens(line: string): string[] {
+    return (line.match(/[A-Za-z0-9][A-Za-z0-9_.-]*[A-Za-z0-9]/g) ?? []).filter((t) => t.length >= 4);
+}
+
+/** How identifying a token is: digits and capitals beat length (a name/version IS the fact). */
+function salience(token: string): number {
+    return (/[0-9]/.test(token) ? 100 : 0) + (/[A-Z]/.test(token) ? 50 : 0) + token.length;
+}
+
+/**
+ * A cloze question over the fact's pointer line: its most identifying token is
+ * blanked and the model must supply it. Deterministic, so the same fact always
+ * gets the same question. Null when the line has nothing worth blanking.
+ */
+export function probeQuestionFor(key: string, content: string): ProbeQuestion | null {
+    const line = firstLine(content, 400);
+    const tokens = probeTokens(line);
+    if (tokens.length === 0) return null;
+    let expected = tokens[0]!;
+    for (const t of tokens) if (salience(t) > salience(expected)) expected = t;
+    const at = line.indexOf(expected);
+    const cloze = `${line.slice(0, at)}${PROBE_BLANK}${line.slice(at + expected.length)}`;
+    return {
+        question: `Stored memory "${key}": ${cloze}\nThe missing word (${PROBE_BLANK}) is:`,
+        expected,
+    };
+}
+
+/** True when the model's answer carries the blanked token (case-insensitive). */
+export function probePasses(answer: string | null | undefined, expected: string): boolean {
+    if (typeof answer !== "string" || !expected) return false;
+    return answer.toLowerCase().includes(expected.toLowerCase());
+}
+
+/** Options for {@link planLosslessCompaction}. */
+export interface LosslessCompactionOptions extends CompactionOptions {
+    /** The local model to prove absorption with. Null/absent → nothing is stubbed. */
+    probe?: RecallProbe | null;
+    /** False when the caller cannot archive originals → nothing is stubbed. Default true. */
+    canArchive?: boolean;
+}
+
+/**
+ * The full compaction contract: {@link planCompaction}'s structural rules, then a
+ * recall probe per surviving write. A write is kept only when the model answers
+ * the question generated from its fact; otherwise the fact stays uncompacted and
+ * the reason is recorded. The caller then archives every write's `archive` BEFORE
+ * applying its stub.
+ */
+export async function planLosslessCompaction(
+    candidates: Array<CompactionCandidate | { key: string; content: undefined }>,
+    opts: LosslessCompactionOptions = {},
+): Promise<CompactionPlan> {
+    const structural = planCompaction(candidates, opts);
+    const writes: CompactionWrite[] = [];
+    const skipped: CompactionSkip[] = [...structural.skipped];
+    for (const w of structural.writes) {
+        if (opts.canArchive === false) {
+            skipped.push({ key: w.key, reason: "no_archive" });
+            continue;
+        }
+        if (!opts.probe) {
+            skipped.push({ key: w.key, reason: "no_probe" });
+            continue;
+        }
+        const q = probeQuestionFor(w.key, w.archive.content);
+        let answer: string | null = null;
+        if (q) {
+            try {
+                answer = await opts.probe.answer(q.question);
+            } catch {
+                answer = null;
+            }
+        }
+        if (!q || !probePasses(answer, q.expected)) {
+            skipped.push({ key: w.key, reason: "probe_failed" });
+            continue;
+        }
+        writes.push(w);
+    }
+    return { writes, skipped, bytesSaved: writes.reduce((n, w) => n + w.bytesSaved, 0) };
+}
+
+// ── Archive + lost content ───────────────────────────────────────────────────
+
+/**
+ * Label every reader attaches to a stub whose original text no longer exists
+ * anywhere (compacted before archiving existed).
+ */
+export const CONTENT_LOST_LABEL = "(content lost — re-verify before relying on it)";
+
+/**
+ * Where the archive lives: beside the snapshot, under the same name — the same
+ * convention as the vector cache (`memory.json` → `memory.archive.json`).
+ */
+export function defaultArchiveFile(memoryFile: string): string {
+    return memoryFile.replace(/\.json$/i, "") + ".archive.json";
+}
+
+/** True when `content` is a stub AND no archived original exists for it. */
+export function isContentLost(content: string, archived: ArchivedFact | undefined): boolean {
+    return isStub(content) && !archived;
+}
+
+/** On-disk archive: key → the latest archived original for that key. Never pruned. */
+export interface ArchiveSnapshot {
+    version: 1;
+    facts: Record<string, ArchivedFact>;
+}
+
+/** Parse archive text; an absent/corrupt file is an empty archive. */
+export function parseArchive(text: string | null | undefined): Record<string, ArchivedFact> {
+    if (!text) return {};
+    let parsed: Partial<ArchiveSnapshot> | null;
+    try {
+        parsed = JSON.parse(text) as Partial<ArchiveSnapshot> | null;
+    } catch {
+        return {};
+    }
+    const facts = parsed && typeof parsed === "object" ? parsed.facts : undefined;
+    if (!facts || typeof facts !== "object") return {};
+    // Null prototype: a memory key is arbitrary text, "__proto__" included.
+    const out: Record<string, ArchivedFact> = Object.create(null) as Record<string, ArchivedFact>;
+    for (const [key, f] of Object.entries(facts)) {
+        if (f && typeof f.content === "string") out[key] = { ...f, key };
+    }
+    return out;
+}
+
+/**
+ * Merge `facts` into archive text, returning the next text. Rows are only ever
+ * added or replaced by a newer archive of the same key — never removed — so a
+ * forgotten or evicted stub keeps its original.
+ */
+export function mergeArchive(text: string | null | undefined, facts: ArchivedFact[]): string {
+    const all = parseArchive(text);
+    for (const f of facts) all[f.key] = f;
+    const snap: ArchiveSnapshot = { version: 1, facts: all };
+    return `${JSON.stringify(snap, null, 2)}\n`;
+}

package/src/index.ts

@@ -18,8 +18,12 @@ export { createRecallEmbedder, createEvermindEmbedder, CachedTextEmbedder, defau
 export type { EvermindEmbedderOptions, PersistentTextEmbedder, TextEmbedderLike, RecallEmbedderEnv } from "./embedding/index.js";
 
 // ── Local backend (IndexedDB via @seanhogg/builderforce-memory) ────────────────────────
-export { MemoryStoreBackend, createLocalMemoryStoreBackend } from "./backends/memory-store.js";
-export type { LocalBackendOptions } from "./backends/memory-store.js";
+export { MemoryStoreBackend, createLocalMemoryStoreBackend, DEFAULT_RECALL_RANKING } from "./backends/memory-store.js";
+export type { LocalBackendOptions, MemoryStoreBackendOptions, RecallRanking } from "./backends/memory-store.js";
+export { FileFactArchive, MemoryFactArchive } from "./persistence/fact-archive.js";
+export type { FactArchive } from "./persistence/fact-archive.js";
+export { SharedJsonFile, DEFAULT_BACKUPS, backupFile } from "./persistence/shared-json-file.js";
+export type { SharedJsonFileOptions } from "./persistence/shared-json-file.js";
 
 // ── Tool core ─────────────────────────────────────────────────────────────────
 export { buildMemoryTools } from "./tools.js";
@@ -32,12 +36,42 @@ export { createExperienceHost, EXPERIENCE_ENV } from "./experience/host.js";
 export type { ExperienceHost, ExperienceHostOptions, ExperienceEngine } from "./experience/host.js";
 export { nextExperienceVersion } from "./experience/train.js";
 
-// ── Compaction (absorbed fact → one-line pointer stub) ───────────────────────
-// Exported so an EXTERNAL compactor (the BuilderForce VS Code extension rewrites
-// the snapshot file directly) can produce byte-identical stubs, keeping the two
-// paths idempotent with respect to each other.
-export { STUB_PREFIX, DEFAULT_STUB_CHARS, isStub, firstLine, memoryStub, planCompaction } from "./compaction.js";
-export type { CompactionCandidate, CompactionWrite, CompactionSkip, CompactionPlan, CompactionOptions } from "./compaction.js";
+// ── Compaction (absorbed fact → one-line pointer stub, LOSSLESS) ─────────────
+// Exported so an EXTERNAL compactor (the BuilderForce VS Code extension) produces
+// byte-identical stubs AND follows the same archive + recall-probe rules, keeping
+// the two paths idempotent with respect to each other.
+export {
+    STUB_PREFIX,
+    DEFAULT_STUB_CHARS,
+    CONTENT_LOST_LABEL,
+    isStub,
+    isContentLost,
+    firstLine,
+    memoryStub,
+    stubPointer,
+    planCompaction,
+    planLosslessCompaction,
+    probeQuestionFor,
+    probePasses,
+    defaultArchiveFile,
+    parseArchive,
+    mergeArchive,
+} from "./compaction.js";
+export type {
+    ArchivedFact,
+    ArchiveSnapshot,
+    CompactionCandidate,
+    CompactionWrite,
+    CompactionSkip,
+    CompactionPlan,
+    CompactionOptions,
+    LosslessCompactionOptions,
+    ProbeQuestion,
+    RecallProbe,
+} from "./compaction.js";
+export { createRecallProbe, lazyRecallProbe, generatorProbe, PROBE_MAX_NEW_TOKENS } from "./model/recall-probe.js";
+export { parseRestoreSource, planRestore, restoredArchive, stubVersion, MIN_POINTER_CHARS } from "./restore.js";
+export type { RestoreRecord, RestoreTarget, RestoreMatch, RestorePlan } from "./restore.js";
 
 // ── Transports ──────────────────────────────────────────────────────────────
 export { createMemoryMcpServer } from "./transports/sdk.js";
@@ -53,8 +87,19 @@ export type { HttpHandlerOptions } from "./transports/http.js";
 export { hashToken, timingSafeEqualStr, buildTenantIndex, bearerToken, RateLimiter } from "./transports/auth.js";
 
 // ── Multi-host installer (wire the stdio server into any MCP-capable agent) ───
-export { buildServerSpec, defaultMemoryFile, resolveMemoryFile, MCP_PACKAGE, MCP_BIN, MEMORY_FILE_ENV, RUNTIME_PEERS } from "./install/server-spec.js";
-export type { StdioServerSpec, ServerSpecOptions } from "./install/server-spec.js";
+export {
+    buildServerSpec,
+    defaultMemoryFile,
+    memoryFileCandidates,
+    resolveMemoryFile,
+    CANONICAL_MEMORY_SEGMENTS,
+    LEGACY_MEMORY_SEGMENTS,
+    MCP_PACKAGE,
+    MCP_BIN,
+    MEMORY_FILE_ENV,
+    RUNTIME_PEERS,
+} from "./install/server-spec.js";
+export type { StdioServerSpec, ServerSpecOptions, MemoryFileProbe, ResolveMemoryFileOptions } from "./install/server-spec.js";
 export { installMemoryServer } from "./install/install.js";
 export type { InstallOptions, InstallResult, InstallStatus, HostSelector, FsLike } from "./install/install.js";
 export { HOSTS, SERVER_KEY, findHost } from "./install/hosts.js";