@seanhogg/builderforce-memory-mcp 2026.7.14 → 2026.9.28

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@seanhogg/builderforce-memory-mcp",
-  "version": "2026.7.14",
+  "version": "2026.9.28",
+  "mcpName": "io.github.SeanHogg/builderforce-memory",
   "description": "BuilderForce Agent Memory — MCP transport. Exposes @seanhogg/builderforce-memory to any MCP client (Claude Agent SDK in-process, stdio, or HTTP) over a pluggable MemoryBackend, with token-saving fetch-on-demand recall.",
   "type": "module",
   "main": "dist/index.js",
@@ -10,6 +11,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./compaction": {
+      "types": "./dist/compaction.d.ts",
+      "import": "./dist/compaction.js"
     }
   },
   "bin": {
@@ -20,6 +25,7 @@
   "files": [
     "dist",
     "src",
+    "server.json",
     "README.md",
     "LICENSE"
   ],
@@ -50,7 +56,8 @@
   },
   "peerDependencies": {
     "@anthropic-ai/claude-agent-sdk": ">=0.1.0",
-    "@seanhogg/builderforce-memory": "^2026.7.13",
+    "@seanhogg/builderforce-memory": "^2026.9.28",
+    "@seanhogg/builderforce-memory-engine": "^2026.9.28",
     "fake-indexeddb": "^6.0.0"
   },
   "peerDependenciesMeta": {
@@ -60,6 +67,9 @@
     "@seanhogg/builderforce-memory": {
       "optional": true
     },
+    "@seanhogg/builderforce-memory-engine": {
+      "optional": true
+    },
     "fake-indexeddb": {
       "optional": true
     }
@@ -73,7 +83,8 @@
     "fake-indexeddb": "^6.0.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory": "2026.7.14"
+    "@seanhogg/builderforce-memory-engine": "2026.9.28",
+    "@seanhogg/builderforce-memory": "2026.9.28"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -83,7 +94,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "tsc && node --test tests/install.test.mjs tests/tools.test.mjs tests/http.test.mjs",
+    "test": "tsc && node --test tests/install.test.mjs tests/tools.test.mjs tests/http.test.mjs tests/compaction.test.mjs tests/recall-method.test.mjs",
     "lint": "eslint src/",
     "typecheck:native": "tsgo --noEmit"
   }

package/server.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.SeanHogg/builderforce-memory",
+  "title": "Builderforce Memory",
+  "description": "Token-saving persistent memory for AI agents. Recall durable facts — decisions, fixes, project context, user preferences — instead of re-reading files or chat history, and remember new ones as you learn them.",
+  "repository": {
+    "url": "https://github.com/SeanHogg/builderforce-memory",
+    "source": "github",
+    "subfolder": "packages/memory-mcp"
+  },
+  "version": "2026.9.28",
+  "websiteUrl": "https://builderforce.ai",
+  "packages": [
+    {
+      "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
+      "identifier": "@seanhogg/builderforce-memory-mcp",
+      "version": "2026.9.28",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "BUILDERFORCE_MEMORY_FILE",
+          "description": "Absolute path to the JSON snapshot that makes memory survive restarts. Defaults to ~/.builderforce-memory/memory.json, which every MCP host on the machine shares.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "filepath"
+        },
+        {
+          "name": "BUILDERFORCE_MEMORY_READONLY",
+          "description": "Set to 1 to expose recall only (disables memory_remember and memory_forget).",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        },
+        {
+          "name": "BUILDERFORCE_API_KEY",
+          "description": "Builderforce tenant API key (bfk_*). When set, additionally exposes the token_usage and model_efficiency cost tools.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}

package/src/backend.ts

@@ -28,6 +28,21 @@ export interface RecallHit {
     timestamp?: number;
 }
 
+/**
+ * Which ranker produced a recall ordering.
+ *
+ * Same vocabulary the gateway's Evermind recall/validate result uses, so a host
+ * renders one chip ("Semantic recall" / "Lexical recall (fallback)") no matter
+ * which layer answered.
+ */
+export type RecallMethod = "embedding" | "lexical";
+
+/** A recall ordering plus the ranker that produced it. */
+export interface RankedRecall {
+    hits: RecallHit[];
+    method: RecallMethod;
+}
+
 /** Arguments for writing a memory. */
 export interface RememberInput {
     key: string;
@@ -52,6 +67,17 @@ export interface MemoryBackend {
      */
     recall(query: string, topK: number): Promise<RecallHit[]>;
 
+    /**
+     * {@link recall} with the ranker named. Optional; callers MUST fall back to
+     * plain `recall` (and report nothing) when it is absent.
+     *
+     * It exists because "did this ordering come from the SSM embedding or from
+     * word overlap?" is the difference between semantic recall and a fallback, and
+     * an answer that silently degrades to lexical is indistinguishable from one
+     * that did not. A backend that knows which path it took says so here.
+     */
+    recallRanked?(query: string, topK: number): Promise<RankedRecall>;
+
     /** Exact lookup by key. Returns undefined when absent or expired. */
     get(key: string): Promise<RecallHit | undefined>;
 
@@ -61,6 +87,16 @@ export interface MemoryBackend {
     /** Store or overwrite a memory. Optional — read-only backends omit it. */
     remember?(input: RememberInput): Promise<void>;
 
+    /**
+     * Store several memories as ONE durable unit. Optional; callers MUST fall
+     * back to a `remember` loop when it is absent.
+     *
+     * It exists for the batch writer (`memory_compact`): a durable backend that
+     * flushes after every write would otherwise re-serialise the entire store
+     * once per compacted key, which is quadratic in the size of the store.
+     */
+    rememberMany?(inputs: RememberInput[]): Promise<void>;
+
     /** Delete a memory by key. Optional — read-only backends omit it. */
     forget?(key: string): Promise<void>;
 }

package/src/backends/memory-store.ts

@@ -2,13 +2,19 @@
  * MemoryStoreBackend — local adapter mapping @seanhogg/builderforce-memory's MemoryStore
  * onto the MemoryBackend seam.
  *
- * Recall quality: when an SSM runtime is supplied it is forwarded to
- * `recallSimilar`, so recall uses SSM-embedding cosine similarity and improves
- * as the model is adapted/distilled. With no runtime it transparently falls
- * back to Jaccard word-overlap (still useful, just lexical).
+ * Recall quality: when a text embedder is supplied it is forwarded to the store's
+ * `recallRanked`, so the ordering is the shared hybrid retrieval — the SSM
+ * embedding's cosine ranking FUSED with BM25 by Reciprocal Rank Fusion — and it
+ * sharpens as the model is adapted/distilled. With no embedder the same call
+ * degrades to the lexical ranking alone. Either way the backend reports which of
+ * the two produced the ordering (`method`), so a silent degrade is visible.
+ *
+ * The embedder does NOT have to be a GPU runtime: `EvermindTextEmbedder` from the
+ * engine is a pure-CPU `EvermindLM`, which is what lets the headless stdio server
+ * rank recall semantically (see ./evermind-embedder.ts).
  */
 
-import type { MemoryBackend, RecallHit, RememberInput } from "../backend.js";
+import type { MemoryBackend, RankedRecall, RecallHit, RememberInput } from "../backend.js";
 
 // Structural views of the @seanhogg/builderforce-memory surface we use, so this package
 // type-checks without a hard dependency on the runtime package.
@@ -25,14 +31,20 @@ interface MemoryStoreLike {
     recall(key: string): Promise<MemoryEntryLike | undefined>;
     recallAll(): Promise<MemoryEntryLike[]>;
     recallByTag(tag: string): Promise<MemoryEntryLike[]>;
-    recallSimilar(query: string, topK: number, runtime?: unknown): Promise<MemoryEntryLike[]>;
+    /** Hybrid (dense⊕BM25) recall with each hit's fused score and the ranker used. */
+    recallRanked(
+        query: string,
+        topK: number,
+        runtime?: unknown,
+    ): Promise<{ hits: Array<{ entry: MemoryEntryLike; score: number }>; method: "embedding" | "lexical" }>;
     forget(key: string): Promise<void>;
 }
 
-function toHit(e: MemoryEntryLike): RecallHit {
+function toHit(e: MemoryEntryLike, score?: number): RecallHit {
     return {
         key: e.key,
         content: e.content,
+        ...(score === undefined ? {} : { score }),
         tags: e.tags,
         importance: e.importance,
         timestamp: e.timestamp,
@@ -46,9 +58,14 @@ export class MemoryStoreBackend implements MemoryBackend {
         private readonly runtime?: unknown,
     ) {}
 
+    /** Plain recall — {@link recallRanked} with the ranker's name dropped. ONE path. */
     async recall(query: string, topK: number): Promise<RecallHit[]> {
-        const entries = await this.store.recallSimilar(query, topK, this.runtime);
-        return entries.map(toHit);
+        return (await this.recallRanked(query, topK)).hits;
+    }
+
+    async recallRanked(query: string, topK: number): Promise<RankedRecall> {
+        const ranked = await this.store.recallRanked(query, topK, this.runtime);
+        return { hits: ranked.hits.map((h) => toHit(h.entry, h.score)), method: ranked.method };
     }
 
     async get(key: string): Promise<RecallHit | undefined> {
@@ -69,6 +86,11 @@ export class MemoryStoreBackend implements MemoryBackend {
         });
     }
 
+    /** The store has no batch write; sequencing here keeps ONE definition of a write. */
+    async rememberMany(inputs: RememberInput[]): Promise<void> {
+        for (const input of inputs) await this.remember(input);
+    }
+
     async forget(key: string): Promise<void> {
         await this.store.forget(key);
     }
@@ -79,9 +101,11 @@ export interface LocalBackendOptions {
     /** IndexedDB database name. Defaults to MemoryStore's own default ('ssmjs'). */
     dbName?: string;
     /**
-     * Optional SSMRuntime for embedding-based recall. Omit for lexical (Jaccard)
-     * recall. In the agent-runtime, pass `ssmMemoryService.runtime` here to reuse
-     * the already-loaded Evermind runtime instead of standing up a second model.
+     * Optional text embedder — anything with `embed(text): Promise<Float32Array>`.
+     * Omit for lexical-only recall. Pass the agent-runtime's
+     * `ssmMemoryService.runtime` to reuse an already-loaded GPU Evermind, or an
+     * `EvermindTextEmbedder` (pure CPU) via {@link createEvermindEmbedder} on a
+     * headless host.
      */
     runtime?: unknown;
     /**
@@ -93,6 +117,10 @@ export interface LocalBackendOptions {
      * When set, the store is hydrated from the file on creation and re-snapshotted
      * after every remember/forget, giving durable cross-process memory. TTLs are
      * dropped on persist: the snapshot is the durable long-term tier.
+     *
+     * The file is also WATCHED: it is a shared artifact (other processes compact it
+     * in place), so the store re-hydrates from disk whenever it changed underneath —
+     * see {@link DiskPersistedBackend} for the loop guard.
      */
     persistFile?: string;
 }
@@ -110,16 +138,70 @@ type FsLike = {
     writeFileSync(path: string, data: string): void;
     mkdirSync(path: string, opts: { recursive: boolean }): void;
     existsSync(path: string): boolean;
+    statSync(path: string): { mtimeMs: number; size: number };
 };
 type PathLike = { dirname(p: string): string };
 
+/** Identity of the snapshot file as this process last left it. */
+interface FileStamp {
+    mtimeMs: number;
+    size: number;
+    /** Digest of the exact bytes — settles the case where a file is touched but unchanged. */
+    hash: string;
+}
+
+/**
+ * FNV-1a over the snapshot text. Non-cryptographic on purpose: this only has to
+ * separate "someone rewrote the file" from "the mtime moved but the bytes are
+ * ours", and node:crypto is deliberately not imported here (this module must stay
+ * bundleable for the browser, where the disk path is never taken).
+ */
+function contentHash(text: string): string {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < text.length; i++) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16);
+}
+
+/** Parse a snapshot's text into its durable entries, or null when unusable. */
+function parseSnapshot(text: string): SnapshotEntry[] | null {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(text);
+    } catch {
+        return null;
+    }
+    if (!Array.isArray(parsed)) return null;
+    return (parsed as SnapshotEntry[]).filter(
+        (raw) => !!raw && typeof raw.key === "string" && typeof raw.content === "string",
+    );
+}
+
 /**
  * Wraps a MemoryStoreBackend so every write is mirrored to a JSON file, and
  * hydrates that file back into the store on boot. This is what turns a respawned
  * stdio subprocess into a persistent memory: the store itself is in-memory, the
  * file is the source of truth across process lifetimes.
+ *
+ * It also WATCHES the file for external edits. The snapshot is a shared artifact —
+ * the BuilderForce VS Code extension compacts absorbed entries by rewriting it
+ * directly, and a second server instance may be mirroring the same path. Without a
+ * watch this server, still holding the pre-edit bodies, would silently re-snapshot
+ * over that work on its very next remember/forget; the edit would only stick once
+ * the client respawned the subprocess. So every operation first calls
+ * {@link DiskPersistedBackend.ensureFresh}, which re-hydrates the store from disk
+ * when — and only when — the file changed underneath us.
+ *
+ * The loop guard is the {@link FileStamp} recorded immediately AFTER each of our own
+ * writes: the next check stats the file, sees the same mtime+size, and returns
+ * without reading a byte. A stat per call is the entire steady-state cost.
  */
 class DiskPersistedBackend implements MemoryBackend {
+    /** How the file looked when this process last wrote or read it. */
+    private stamp: FileStamp | null = null;
+
     constructor(
         private readonly inner: MemoryStoreBackend,
         private readonly store: MemoryStoreLike,
@@ -127,26 +209,99 @@ class DiskPersistedBackend implements MemoryBackend {
         private readonly fs: FsLike,
     ) {}
 
-    recall(query: string, topK: number): Promise<RecallHit[]> {
+    async recall(query: string, topK: number): Promise<RecallHit[]> {
+        await this.ensureFresh();
         return this.inner.recall(query, topK);
     }
-    get(key: string): Promise<RecallHit | undefined> {
+    async recallRanked(query: string, topK: number): Promise<RankedRecall> {
+        await this.ensureFresh();
+        return this.inner.recallRanked(query, topK);
+    }
+    async get(key: string): Promise<RecallHit | undefined> {
+        await this.ensureFresh();
         return this.inner.get(key);
     }
-    recallByTag(tag: string, limit: number): Promise<RecallHit[]> {
+    async recallByTag(tag: string, limit: number): Promise<RecallHit[]> {
+        await this.ensureFresh();
         return this.inner.recallByTag(tag, limit);
     }
 
     async remember(input: RememberInput): Promise<void> {
+        await this.ensureFresh();
         await this.inner.remember(input);
         await this.snapshot();
     }
 
+    /** Batch write — ONE snapshot for the whole set, so compacting N keys is not N full rewrites. */
+    async rememberMany(inputs: RememberInput[]): Promise<void> {
+        await this.ensureFresh();
+        await this.inner.rememberMany(inputs);
+        await this.snapshot();
+    }
+
     async forget(key: string): Promise<void> {
+        await this.ensureFresh();
         await this.inner.forget(key);
         await this.snapshot();
     }
 
+    /**
+     * Re-read the snapshot into the store when the file changed since we last
+     * touched it. Also the BOOT hydration: with no stamp yet, an existing file is
+     * always read in — one routine, so disk and memory can never diverge by taking
+     * two different paths.
+     */
+    async ensureFresh(): Promise<void> {
+        if (!this.fs.existsSync(this.file)) return;
+
+        let st: { mtimeMs: number; size: number };
+        try {
+            st = this.fs.statSync(this.file);
+        } catch {
+            return;
+        }
+        // Fast path: byte-for-byte what we last wrote. No read, no parse, no writes.
+        if (this.stamp && st.mtimeMs === this.stamp.mtimeMs && st.size === this.stamp.size) return;
+
+        let text: string;
+        try {
+            text = this.fs.readFileSync(this.file, "utf8");
+        } catch {
+            return;
+        }
+        const hash = contentHash(text);
+        // Touched (mtime moved) but identical content — re-stamp, don't re-hydrate.
+        if (this.stamp && hash === this.stamp.hash) {
+            this.stamp = { mtimeMs: st.mtimeMs, size: st.size, hash };
+            return;
+        }
+
+        const entries = parseSnapshot(text);
+        // Corrupt/partial snapshot (a half-written file, say): keep what we have
+        // rather than wiping the live store, and leave the stamp alone so the next
+        // call re-checks.
+        if (!entries) return;
+
+        await this.replaceStore(entries);
+        this.stamp = { mtimeMs: st.mtimeMs, size: st.size, hash };
+    }
+
+    /**
+     * Make the in-memory store equal the snapshot: drop keys the file no longer has,
+     * then replay every entry (a re-remember overwrites, so a body shortened to a
+     * stub on disk becomes the stub in memory). Replayed as durable — TTLs are
+     * dropped on persist; the snapshot is the long-term tier.
+     */
+    private async replaceStore(entries: SnapshotEntry[]): Promise<void> {
+        const wanted = new Set(entries.map((e) => e.key));
+        for (const existing of await this.store.recallAll()) {
+            if (!wanted.has(existing.key)) await this.store.forget(existing.key);
+        }
+        for (const raw of entries) {
+            await this.store.remember(raw.key, raw.content, { tags: raw.tags, importance: raw.importance });
+        }
+    }
+
     private async snapshot(): Promise<void> {
         const entries = await this.store.recallAll();
         const out: SnapshotEntry[] = entries.map((e) => ({
@@ -155,24 +310,16 @@ class DiskPersistedBackend implements MemoryBackend {
             tags: e.tags,
             importance: e.importance,
         }));
-        this.fs.writeFileSync(this.file, JSON.stringify(out, null, 2));
-    }
-}
-
-/** Reads a snapshot file and replays it into the store as durable (no-TTL) entries. */
-async function hydrateFromDisk(store: MemoryStoreLike, file: string, fs: FsLike): Promise<void> {
-    if (!fs.existsSync(file)) return;
-    let parsed: unknown;
-    try {
-        parsed = JSON.parse(fs.readFileSync(file, "utf8"));
-    } catch {
-        // Corrupt/partial snapshot — start clean rather than crash the server.
-        return;
-    }
-    if (!Array.isArray(parsed)) return;
-    for (const raw of parsed as SnapshotEntry[]) {
-        if (!raw || typeof raw.key !== "string" || typeof raw.content !== "string") continue;
-        await store.remember(raw.key, raw.content, { tags: raw.tags, importance: raw.importance });
+        const json = JSON.stringify(out, null, 2);
+        this.fs.writeFileSync(this.file, json);
+        // Stamp OUR write immediately — this is what stops the watch above from
+        // treating our own output as an external edit (and looping).
+        try {
+            const st = this.fs.statSync(this.file);
+            this.stamp = { mtimeMs: st.mtimeMs, size: st.size, hash: contentHash(json) };
+        } catch {
+            this.stamp = null;
+        }
     }
 }
 
@@ -212,6 +359,8 @@ export async function createLocalMemoryStoreBackend(opts: LocalBackendOptions =
     const dir = path.dirname(opts.persistFile);
     if (dir && !fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 
-    await hydrateFromDisk(store, opts.persistFile, fs);
-    return new DiskPersistedBackend(backend, store, opts.persistFile, fs);
+    const persisted = new DiskPersistedBackend(backend, store, opts.persistFile, fs);
+    // Boot hydration IS the freshness check with no stamp yet — see ensureFresh().
+    await persisted.ensureFresh();
+    return persisted;
 }

package/src/bin/http.ts

@@ -9,16 +9,28 @@
  *   BUILDERFORCE_MEMORY_TOKEN     Bearer token required on every request (recommended).
  *   BUILDERFORCE_MEMORY_DB        IndexedDB database name.
  *   BUILDERFORCE_MEMORY_READONLY  '1' to disable remember/forget tools.
+ *   BUILDERFORCE_MEMORY_FILE      JSON snapshot path (also sites the vector cache).
+ *   BUILDERFORCE_MEMORY_MODEL     `.evermind` package to rank recall by SSM embedding
+ *                                 (pure CPU, no GPU). Unset = lexical ranking.
+ *   BUILDERFORCE_MEMORY_TOKENIZER Tokenizer JSON for that checkpoint.
+ *   BUILDERFORCE_MEMORY_VECTORS   Persistent vector-cache path.
  *   BUILDERFORCE_GATEWAY_URL      Gateway base URL (default https://api.builderforce.ai).
  *   BUILDERFORCE_API_KEY          `bfk_*` tenant key. When set, exposes the cost tools.
  */
 
 import http from "node:http";
 import { createLocalMemoryStoreBackend } from "../backends/memory-store.js";
+import { createRecallEmbedder } from "../embedding/index.js";
+import { resolveMemoryFile } from "../install/server-spec.js";
 import { createMemoryHttpHandler } from "../transports/http.js";
 
+const memoryFile = resolveMemoryFile();
+
 const backend = await createLocalMemoryStoreBackend({
     dbName: process.env["BUILDERFORCE_MEMORY_DB"],
+    // Same embedder decision as the stdio bin, from the same helper — the two
+    // servers must not rank recall differently.
+    runtime: (await createRecallEmbedder({ memoryFile })) ?? undefined,
 });
 
 const handler = createMemoryHttpHandler(backend, {

package/src/bin/install.ts

@@ -22,6 +22,7 @@ import nodeFs from "node:fs";
 import { HOSTS } from "../install/hosts.js";
 import { installMemoryServer, type HostSelector } from "../install/install.js";
 import { installClaudeCombo } from "../install/claude-hooks.js";
+import { defaultMemoryFile } from "../install/server-spec.js";
 
 function argValue(name: string): string | undefined {
     const hit = process.argv.find((a) => a.startsWith(`--${name}=`));
@@ -54,7 +55,7 @@ const hosts: HostSelector =
           ? "all"
           : hostArg.split(",").map((s) => s.trim()).filter(Boolean);
 
-const memoryFile = argValue("memory-file") ?? path.join(os.homedir(), ".builderforce-memory", "memory.json");
+const memoryFile = argValue("memory-file") ?? defaultMemoryFile();
 
 let results;
 try {
@@ -111,6 +112,6 @@ if (results.length === 0) {
     );
 } else {
     process.stdout.write(
-        `\nDone — ${wrote} config(s) written. Store: ${memoryFile}\nRestart the agent(s) to connect. Tools: memory_recall · memory_remember · memory_get · memory_recall_by_tag · memory_forget\n`,
+        `\nDone — ${wrote} config(s) written. Store: ${memoryFile}\nRestart the agent(s) to connect. Tools: memory_recall · memory_remember · memory_get · memory_recall_by_tag · memory_forget · memory_compact\n`,
     );
 }

package/src/bin/stdio.ts

@@ -5,25 +5,42 @@
  * Env:
  *   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. When set, memory
- *                                 persists across process restarts — REQUIRED for an
- *                                 MCP client that respawns this server each session
- *                                 (otherwise fake-indexeddb loses everything on exit).
+ *   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.
+ *   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.
+ *   BUILDERFORCE_MEMORY_TOKENIZER Tokenizer JSON matching that checkpoint. Defaults
+ *                                 to `<model>.tokenizer.json`.
+ *   BUILDERFORCE_MEMORY_VECTORS   Persistent vector-cache path. Defaults beside the
+ *                                 snapshot, so a respawned subprocess does not
+ *                                 re-embed the whole store on its first recall.
  *   BUILDERFORCE_GATEWAY_URL      Gateway base URL (default https://api.builderforce.ai).
  *   BUILDERFORCE_API_KEY          `bfk_*` tenant key. When set, exposes the cost tools
  *                                 (token_usage, model_efficiency).
  *
- * Recall is lexical (Jaccard) here — this headless binary does not stand up the
- * SSM runtime/GPU. For SSM-embedding recall, embed the package in-process and
- * pass `runtime` to createLocalMemoryStoreBackend (see README).
+ * With no model configured recall ranks lexically (BM25) and the tool result SAYS
+ * so ("Ranked by: lexical recall (fallback …)"), so a degrade is never silent.
  */
 
 import { createLocalMemoryStoreBackend } from "../backends/memory-store.js";
+import { createRecallEmbedder } from "../embedding/index.js";
+import { resolveMemoryFile } from "../install/server-spec.js";
 import { runStdio } from "../transports/stdio.js";
 
+const memoryFile = resolveMemoryFile();
+
 const backend = await createLocalMemoryStoreBackend({
     dbName: process.env["BUILDERFORCE_MEMORY_DB"],
-    persistFile: process.env["BUILDERFORCE_MEMORY_FILE"],
+    persistFile: memoryFile,
+    // Null when no model is configured (or it fails to load) — recall then stays
+    // lexical rather than the server refusing to start over an optional model.
+    runtime: (await createRecallEmbedder({ memoryFile })) ?? undefined,
 });
 
 await runStdio(backend, {