@seanhogg/builderforce-memory-mcp 2026.10.3 → 2026.10.22

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({