@seanhogg/builderforce-memory-mcp 2026.10.2 → 2026.10.22

package/src/bin/stdio.ts

@@ -6,15 +6,20 @@
  *   BUILDERFORCE_MEMORY_DB        IndexedDB database name (default: MemoryStore default).
  *   BUILDERFORCE_MEMORY_READONLY  '1' to disable remember/forget tools.
  *   BUILDERFORCE_MEMORY_FILE      Absolute path to a JSON snapshot. Defaults to the
- *                                 shared per-machine store (~/.builderforce-memory/
- *                                 memory.json) so memory survives the respawn every
- *                                 MCP client does between sessions — without a
- *                                 snapshot fake-indexeddb loses everything on exit.
+ *                                 shared per-machine store — resolveMemoryFile():
+ *                                 ~/.builderforce-memory/memory.json, or the legacy
+ *                                 ~/.claude/builderforce-memory/memory.json when that
+ *                                 is where the live memory.json is — so memory
+ *                                 survives the respawn every MCP client does between
+ *                                 sessions. Compacted originals are archived beside it
+ *                                 (memory.archive.json); each overwrite keeps .bak.1-3.
  *   BUILDERFORCE_MEMORY_MODEL     Absolute path to a `.evermind` package (an
  *                                 `evermind-lm`). When set, recall is ranked by SSM
  *                                 embedding cosine FUSED with the lexical ranking
  *                                 instead of lexically alone. Pure CPU — no GPU is
  *                                 involved; see src/embedding/evermind-embedder.ts.
+ *                                 Also the model memory_compact's recall probe asks
+ *                                 before stubbing a fact; unset = nothing is compacted.
  *   BUILDERFORCE_MEMORY_TOKENIZER Tokenizer JSON matching that checkpoint. Defaults
  *                                 to `<model>.tokenizer.json`.
  *   BUILDERFORCE_MEMORY_VECTORS   Persistent vector-cache path. Defaults beside the
@@ -34,11 +39,16 @@
 
 import { createLocalMemoryStoreBackend } from "../backends/memory-store.js";
 import { createRecallEmbedder } from "../embedding/index.js";
+import { readFile } from "node:fs/promises";
 import { createExperienceHost } from "../experience/host.js";
 import { resolveMemoryFile } from "../install/server-spec.js";
+import { lazyRecallProbe } from "../model/recall-probe.js";
 import { runStdio } from "../transports/stdio.js";
 
-const memoryFile = resolveMemoryFile();
+const log = (line: string) => void process.stderr.write(`${line}\n`);
+// ONE resolver for installer, servers and hook: env, else whichever location holds
+// the live memory.json (logged when there is a choice), else the canonical default.
+const memoryFile = resolveMemoryFile(process.env, undefined, { log });
 
 const backend = await createLocalMemoryStoreBackend({
     dbName: process.env["BUILDERFORCE_MEMORY_DB"],
@@ -56,4 +66,9 @@ await runStdio(backend, {
     gatewayApiKey: process.env["BUILDERFORCE_API_KEY"],
     // Null unless BUILDERFORCE_MEMORY_EXPERIENCE=1 — Synapse's opt-in.
     experience: await createExperienceHost({ memoryFile }),
+    // memory_compact proves absorption with the configured Evermind before stubbing;
+    // no model → nothing is compacted (and the tool says so).
+    recallProbe: lazyRecallProbe(),
+    // A local subprocess may read the user's own export file for memory_restore.
+    readRestoreFile: (path) => readFile(path, "utf8"),
 });

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/experience/file-store.ts

@@ -11,6 +11,7 @@
 
 import type {
     Adaptation,
+    CurationRecord,
     Episode,
     EpisodeSummary,
     ExperienceSnapshot,
@@ -129,6 +130,10 @@ export class FileExperienceStore implements ExperienceStore {
         this.fresh();
         await this.inner.recordAdaptation(adaptation);
     }
+    async recordCuration(curation: CurationRecord): Promise<void> {
+        this.fresh();
+        await this.inner.recordCuration(curation);
+    }
 
     async snapshot(): Promise<ExperienceSnapshot> {
         this.fresh();

package/src/experience/train.ts

@@ -17,6 +17,7 @@
 import type {
     adaptPackage,
     curatePendingExperience,
+    curationRecords,
     experienceDocuments,
     packDocuments,
     CurationResult,
@@ -36,10 +37,16 @@ export interface TrainEngine {
     /** The opt-in curation step and the CPU embedder it scores with (engine ≥ 2026.10.2). */
     curatePendingExperience?: typeof curatePendingExperience;
     EvermindTextEmbedder?: typeof EvermindTextEmbedder;
+    /** The `curated_out` records to persist for a curation (engine ≥ 2026.10.3). */
+    curationRecords?: typeof curationRecords;
 }
 
-/** What curation left out of a pass, when it ran. */
-export type CurationReport = { dropped: CurationResult["dropped"] };
+/**
+ * What curation left out of a pass, when it ran: `dropped` this call, and
+ * `alreadyDropped` — left out by an earlier call, verdict still standing, so skipped
+ * without being embedded again.
+ */
+export type CurationReport = { dropped: CurationResult["dropped"]; alreadyDropped?: CurationResult["dropped"] };
 
 export type TrainOutcome =
     | { status: "nothing_new"; pending: 0; version: string }
@@ -103,8 +110,10 @@ export interface TrainExperienceOptions {
      * store's run outcomes, + near-duplicate removal against the batch AND the
      * recently learned procedures — docs/ml-task-catalog.md §4.2), scoring with the
      * model's own CPU embedder. Default false ⇒ every pending procedure is learned,
-     * exactly as before. A procedure curation drops is NOT recorded as learned, so a
-     * later pass reconsiders it.
+     * exactly as before. A procedure curation drops is NOT recorded as learned; it is
+     * recorded as `curated_out` (with the id it duplicates, or its quality score), and
+     * later curations skip it while that verdict stands — a duplicate until what it
+     * repeats is no longer learned, a low-quality one until it has new runs.
      */
     curate?: boolean;
 }
@@ -126,15 +135,20 @@ export async function trainExperience(
 
     let docs = pending;
     let curation: CurationReport | undefined;
+    /** The LM curation embedded with — untrained, loaded from `model.pkg` — reused by the first pass. */
+    let curationLm: ConstructorParameters<typeof EvermindTextEmbedder>[0] | undefined;
     if (opts.curate) {
         if (!engine.curatePendingExperience || !engine.EvermindTextEmbedder) throw new Error(CURATION_UNSUPPORTED);
         // The model being trained embeds for curation: its own notion of "the same procedure".
-        const lm = model.pkg.loadLM() as ConstructorParameters<typeof EvermindTextEmbedder>[0];
+        // Embedding never changes its weights, so the same LM is the first pass's copy.
+        curationLm = model.pkg.loadLM() as ConstructorParameters<typeof EvermindTextEmbedder>[0];
         const codec = model.codec as ConstructorParameters<typeof EvermindTextEmbedder>[1];
-        const embedder = new engine.EvermindTextEmbedder(lm, codec);
+        const embedder = new engine.EvermindTextEmbedder(curationLm, codec);
         const r = await engine.curatePendingExperience(pending, snap, { embedder, known });
         docs = r.kept;
-        curation = { dropped: r.dropped };
+        curation = { dropped: r.dropped, ...(r.alreadyDropped?.length ? { alreadyDropped: r.alreadyDropped } : {}) };
+        // Persist the verdicts, so the next call skips these instead of re-embedding them.
+        if (engine.curationRecords) await store.recordCuration(engine.curationRecords(r, snap, Date.now()));
     }
     if (docs.length === 0) return { status: "curated_out", pending: pending.length, version, curation: curation ?? { dropped: [] } };
 
@@ -145,8 +159,11 @@ export async function trainExperience(
     let lossSum = 0;
     let passes = 0;
     for (const pass of engine.packDocuments(docs, engine.EVERMIND_ADAPT_MAX_CHARS)) {
-        const r = engine.adaptPackage(pkg, model.codec, pass.map((d) => d.text).join("\n\n"), next);
-        if (!r) continue;
+        // Until a pass succeeds `pkg` is still `model.pkg`, so curation's untrained LM is its copy.
+        const lm = pkg === (model.pkg as unknown) ? curationLm : undefined;
+        const r = engine.adaptPackage(pkg, model.codec, pass.map((d) => d.text).join("\n\n"), next, lm ? { lm } : {});
+        if (!r) continue; // no trainable window: the LM was never touched
+        curationLm = undefined; // trained in place — spent
         pkg = r.pkg;
         lossSum += r.loss;
         passes++;