@seanhogg/builderforce-memory-mcp 2026.10.2 → 2026.10.22

package/src/restore.ts

@@ -0,0 +1,144 @@
+/**
+ * Restore — bringing the full text of a compaction stub back from an export.
+ *
+ * A stub written before compaction archived its originals is the ONLY copy left:
+ * the text is gone (`contentLost`). The text often still exists elsewhere — a
+ * memory export (`[{ key, content }]`), or the Evermind coordinator's `mem:` record
+ * dump (`[{ id, text }]`) — and this module decides which record restores which
+ * stub. Pure and dependency-free; the `memory_restore` tool does the I/O.
+ *
+ * Matching, in order:
+ *   1. by key — a record's `key`, or its `id` with any `mem:` prefix dropped;
+ *   2. by text — the record's first line starts with the stub's pointer line (the
+ *      original first line the stub kept). Only a UNIQUE match restores; two stubs
+ *      sharing a pointer are reported ambiguous rather than guessed.
+ */
+
+import { STUB_PREFIX, firstLine, isStub, stubPointer, type ArchivedFact } from "./compaction.js";
+
+/** One record from a restore source, normalised. */
+export interface RestoreRecord {
+    /** The memory key the record names, when it names one. */
+    key?: string;
+    /** The full text. */
+    content: string;
+}
+
+/** A stub that may be restored. */
+export interface RestoreTarget {
+    key: string;
+    /** The stored stub body. */
+    stub: string;
+}
+
+export interface RestoreMatch {
+    key: string;
+    content: string;
+    via: "key" | "text";
+}
+
+export interface RestorePlan {
+    matches: RestoreMatch[];
+    /** Records that matched no target. */
+    unmatched: number;
+    /** Targets more than one stub could claim by text, left alone. */
+    ambiguous: string[];
+}
+
+/** Array-valued properties a wrapped export may keep its rows under. */
+const WRAPPER_KEYS = ["entries", "memories", "records", "items", "data", "facts"];
+
+function rowsOf(parsed: unknown): unknown[] {
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && typeof parsed === "object") {
+        const obj = parsed as Record<string, unknown>;
+        for (const k of WRAPPER_KEYS) {
+            const v = obj[k];
+            if (Array.isArray(v)) return v;
+        }
+        // A lone record (a one-line JSON Lines file parses as plain JSON).
+        if (typeof obj["content"] === "string" || typeof obj["text"] === "string") return [obj];
+    }
+    return [];
+}
+
+function toRecord(raw: unknown): RestoreRecord | null {
+    if (!raw || typeof raw !== "object") return null;
+    const r = raw as Record<string, unknown>;
+    const content = typeof r["content"] === "string" ? r["content"] : typeof r["text"] === "string" ? r["text"] : null;
+    if (content === null || !content.trim() || isStub(content)) return null;
+    const named = typeof r["key"] === "string" ? r["key"] : typeof r["id"] === "string" ? r["id"] : undefined;
+    const key = named?.replace(/^mem:/, "").trim();
+    return key ? { key, content } : { content };
+}
+
+/**
+ * Parse a restore source: a JSON array, an object wrapping one (`{ entries: [...] }`
+ * and similar), or JSON Lines. Rows without text, or whose text is itself a stub,
+ * are dropped — restoring a stub with a stub restores nothing.
+ */
+export function parseRestoreSource(text: string): RestoreRecord[] {
+    let rows: unknown[];
+    try {
+        rows = rowsOf(JSON.parse(text));
+    } catch {
+        rows = [];
+        for (const line of text.split(/\r?\n/)) {
+            if (!line.trim()) continue;
+            try {
+                rows.push(JSON.parse(line));
+            } catch {
+                /* not a record */
+            }
+        }
+    }
+    return rows.map(toRecord).filter((r): r is RestoreRecord => r !== null);
+}
+
+const norm = (s: string) => s.toLowerCase().replace(/\s+/g, " ").trim();
+
+/** Shortest pointer line a text match may rest on — below it, a prefix proves nothing. */
+export const MIN_POINTER_CHARS = 12;
+
+/** Decide which record restores which stub. */
+export function planRestore(records: RestoreRecord[], targets: RestoreTarget[]): RestorePlan {
+    const byKey = new Map(targets.map((t) => [t.key, t]));
+    const pointers = targets.map((t) => ({ key: t.key, pointer: norm(stubPointer(t.stub)) }));
+    const matched = new Map<string, RestoreMatch>();
+    const ambiguous = new Set<string>();
+    let unmatched = 0;
+
+    for (const r of records) {
+        if (r.key && byKey.has(r.key)) {
+            if (!matched.has(r.key)) matched.set(r.key, { key: r.key, content: r.content, via: "key" });
+            continue;
+        }
+        const head = norm(firstLine(r.content, 100_000));
+        const hits = pointers.filter((p) => p.pointer.length >= MIN_POINTER_CHARS && head.startsWith(p.pointer));
+        if (hits.length === 1) {
+            const key = hits[0]!.key;
+            if (!matched.has(key)) matched.set(key, { key, content: r.content, via: "text" });
+            continue;
+        }
+        if (hits.length > 1) for (const h of hits) ambiguous.add(h.key);
+        else unmatched++;
+    }
+    // A key claimed unambiguously by key-match stays restored even if a text match was ambiguous.
+    const matches = [...matched.values()];
+    for (const m of matches) ambiguous.delete(m.key);
+    return { matches, unmatched, ambiguous: [...ambiguous] };
+}
+
+const escapeRegExp = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const STUB_VERSION = new RegExp(`^\\s*${escapeRegExp(STUB_PREFIX)} v(\\d+)\\]`);
+
+/** The Evermind version a stub names (`[absorbed→Evermind v7] …` → 7), 0 when unreadable. */
+export function stubVersion(stub: string): number {
+    const m = STUB_VERSION.exec(stub);
+    return m ? Number(m[1]) : 0;
+}
+
+/** The archive row that makes a restored stub lossless again. */
+export function restoredArchive(match: RestoreMatch, stub: string, now = Date.now()): ArchivedFact {
+    return { key: match.key, content: match.content, stub, version: stubVersion(stub), archivedAt: now };
+}

package/src/tools.ts

@@ -15,8 +15,9 @@
  */
 
 import { z } from "zod";
-import type { MemoryBackend, RankedRecall, RecallHit, RecallMethod, RememberInput } from "./backend.js";
-import { DEFAULT_STUB_CHARS, planCompaction, type CompactionSkip } from "./compaction.js";
+import type { MemoryBackend, RankedRecall, RecallHit, RecallMethod } from "./backend.js";
+import { CONTENT_LOST_LABEL, type RecallProbe } from "./compaction.js";
+import { appendCompactionTools } from "./compaction-tools.js";
 import { buildExperienceTools } from "./experience/tools.js";
 import type { ExperienceHost } from "./experience/host.js";
 import { appendGatewayCostTools } from "./gateway-tools.js";
@@ -44,6 +45,18 @@ export interface MemoryToolsOptions {
      * beside the memory tools. See {@link createExperienceHost}.
      */
     experience?: ExperienceHost | null;
+    /**
+     * The local model `memory_compact` proves absorption with before it stubs a
+     * fact (see `planLosslessCompaction`). Null/absent → compaction stubs nothing
+     * and says why. The bins pass `lazyRecallProbe()` (the configured Evermind).
+     */
+    recallProbe?: RecallProbe | null;
+    /**
+     * Reads a restore source by path for `memory_restore`. Only hosts that may read
+     * their own disk pass it (the stdio bin); without it the tool takes inline JSON
+     * only, so a networked server never reads a caller-named file.
+     */
+    readRestoreFile?: (path: string) => Promise<string>;
 }
 
 const DEFAULT_MAX_RESULTS = 5;
@@ -62,6 +75,9 @@ const RANKER_LINE: Record<RecallMethod, string> = {
     lexical: "Ranked by: lexical recall (fallback - no embedding model loaded).",
 };
 
+/** A stub whose original is gone is surfaced WITH the label, never as a plain fact. */
+const lostLabel = (h: RecallHit): string => (h.contentLost ? ` ${CONTENT_LOST_LABEL}` : "");
+
 function renderHits(hits: RecallHit[], maxChars: number, method?: RecallMethod): string {
     const ranker = method ? `\n${RANKER_LINE[method]}` : "";
     if (hits.length === 0) return `No matching memories.${ranker}`;
@@ -70,7 +86,7 @@ function renderHits(hits: RecallHit[], maxChars: number, method?: RecallMethod):
             .map((h) => {
                 const tags = h.tags?.length ? ` tags=[${h.tags.join(", ")}]` : "";
                 const score = h.score != null ? ` score=${h.score.toFixed(3)}` : "";
-                return `• ${h.key}${score}${tags}\n  ${clip(h.content, maxChars)}`;
+                return `• ${h.key}${score}${tags}${lostLabel(h)}\n  ${clip(h.content, maxChars)}`;
             })
             .join("\n") + ranker
     );
@@ -90,19 +106,6 @@ async function rankedRecall(
     return { hits: await backend.recall(query, topK) };
 }
 
-const SKIP_REASONS: Record<CompactionSkip["reason"], string> = {
-    not_found: "not found",
-    already_compacted: "already compacted",
-    not_smaller: "already shorter than its stub",
-};
-
-/** 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");
-}
-
 /**
  * Builds the memory tool set bound to `backend`. Write tools are included only
  * when `writable` is not false AND the backend actually implements them.
@@ -156,7 +159,9 @@ export function buildMemoryTools(backend: MemoryBackend, opts: MemoryToolsOption
                     const key = String(args["key"] ?? "");
                     if (!key) return fail("key is required.");
                     const hit = await backend.get(key);
-                    return hit ? ok(`• ${hit.key}\n  ${hit.content}`) : ok(`No memory found for key "${key}".`);
+                    return hit
+                        ? ok(`• ${hit.key}${lostLabel(hit)}\n  ${hit.content}`)
+                        : ok(`No memory found for key "${key}".`);
                 } catch (err) {
                     return fail(`get failed: ${String(err)}`);
                 }
@@ -226,82 +231,8 @@ export function buildMemoryTools(backend: MemoryBackend, opts: MemoryToolsOption
         });
     }
 
-    // memory_compact — the FIRST-CLASS compaction path. It writes through the live
-    // store (get → plan → remember), so a durable backend's in-memory state and its
-    // on-disk snapshot agree afterwards. Compacting the snapshot file behind the
-    // server's back instead is what races: the server still holds the full bodies and
-    // re-snapshots over them on its next write. Requires read + write, so it is
-    // registered alongside the other write tools.
-    if (writable && backend.remember) {
-        tools.push({
-            name: "memory_compact",
-            description:
-                "Shrink memories that have already been absorbed elsewhere (folded into a model, " +
-                "summarised into a longer-lived note) down to a one-line pointer stub, reclaiming the " +
-                "context they were eating. Call this AFTER something durable has learned the facts — " +
-                "never as a way to tidy up, because the full body is gone afterwards. 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.
-                    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 = planCompaction(keys.map((key) => ({ key, content: hits.get(key)?.content })), {
-                        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"]),
-                    });
-
-                    // Preserve tags/importance — compaction shortens a body, it does not
-                    // reclassify the fact.
-                    const writes: RememberInput[] = plan.writes.map((w) => {
-                        const prev = hits.get(w.key);
-                        return { key: w.key, content: w.content, tags: prev?.tags, importance: prev?.importance };
-                    });
-                    if (writes.length > 0) {
-                        if (backend.rememberMany) await backend.rememberMany(writes);
-                        else for (const w of writes) await backend.remember!(w);
-                    }
-
-                    return ok(renderCompaction(plan.writes.length, plan.bytesSaved, plan.skipped));
-                } catch (err) {
-                    return fail(`compact failed: ${String(err)}`);
-                }
-            },
-        });
-    }
+    // memory_compact + memory_restore — the lossless compaction pair (compaction-tools.ts).
+    if (writable && backend.remember) appendCompactionTools(tools, backend, opts);
 
     if (writable && backend.forget) {
         tools.push({