@seanhogg/builderforce-memory-mcp 2026.7.14 → 2026.9.28

package/dist/bin/stdio.d.ts

@@ -5,17 +5,27 @@
  * 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.
  */
 export {};
 //# sourceMappingURL=stdio.d.ts.map

package/dist/bin/stdio.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/bin/stdio.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG"}
+{"version":3,"file":"stdio.d.ts","sourceRoot":"","sources":["../../src/bin/stdio.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG"}

package/dist/bin/stdio.js

@@ -5,23 +5,39 @@
  * 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, {
     writable: process.env["BUILDERFORCE_MEMORY_READONLY"] !== "1",

package/dist/bin/stdio.js.map

@@ -1 +1 @@
-{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/bin/stdio.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,MAAM,OAAO,GAAG,MAAM,6BAA6B,CAAC;IAChD,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;IAC7C,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;CACvD,CAAC,CAAC;AAEH,MAAM,QAAQ,CAAC,OAAO,EAAE;IACpB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,KAAK,GAAG;IAC7D,2EAA2E;IAC3E,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,IAAI,6BAA6B;IACpF,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;CACrD,CAAC,CAAC"}
+{"version":3,"file":"stdio.js","sourceRoot":"","sources":["../../src/bin/stdio.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AAC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD,MAAM,UAAU,GAAG,iBAAiB,EAAE,CAAC;AAEvC,MAAM,OAAO,GAAG,MAAM,6BAA6B,CAAC;IAChD,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,wBAAwB,CAAC;IAC7C,WAAW,EAAE,UAAU;IACvB,6EAA6E;IAC7E,2EAA2E;IAC3E,OAAO,EAAE,CAAC,MAAM,oBAAoB,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,IAAI,SAAS;CACrE,CAAC,CAAC;AAEH,MAAM,QAAQ,CAAC,OAAO,EAAE;IACpB,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,8BAA8B,CAAC,KAAK,GAAG;IAC7D,2EAA2E;IAC3E,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC,IAAI,6BAA6B;IACpF,aAAa,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;CACrD,CAAC,CAAC"}

package/dist/compaction.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Compaction — turning an ABSORBED memory into a terse pointer stub.
+ *
+ * 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
+ * subsequent recall pays for text the model already carries in its weights.
+ * Compaction replaces the body with a one-line `[absorbed→Evermind vN] <first
+ * line>` pointer, so the fact stops filling context while it stays findable.
+ *
+ * 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.
+ *
+ * Dependency-free and published as its own subpath
+ * (`@seanhogg/builderforce-memory-mcp/compaction`), so an external compactor imports
+ * these rules instead of re-implementing them — the marker below is the shared
+ * idempotency contract between the two processes.
+ */
+/**
+ * Marker that opens every compacted stub — also the idempotency guard. An entry
+ * whose content already starts with this is skipped, so compacting twice (or
+ * from two processes) never double-stubs.
+ */
+export declare const STUB_PREFIX = "[absorbed\u2192Evermind";
+/** Default cap on the pointer line carried inside a stub. */
+export declare const DEFAULT_STUB_CHARS = 140;
+/** True when a body is already a compaction stub. */
+export declare function isStub(content: string): boolean;
+/** The first non-empty line of a body, trimmed to `max` chars — the stub's pointer text. */
+export declare function firstLine(content: string, max?: number): string;
+/** Build the terse stub that replaces an absorbed entry's body. */
+export declare function memoryStub(content: string, version: number, maxChars?: number): string;
+/** One entry considered for compaction. */
+export interface CompactionCandidate {
+    key: string;
+    content: string;
+}
+/** A body rewrite the caller should apply. */
+export interface CompactionWrite {
+    key: string;
+    /** The stub that replaces the entry's body. */
+    content: string;
+    /** Characters recovered by this rewrite. */
+    bytesSaved: number;
+}
+/** Why a candidate was left alone. */
+export interface CompactionSkip {
+    key: string;
+    reason: "not_found" | "already_compacted" | "not_smaller";
+}
+/** The decided plan: what to write, what to leave, and the total recovered. */
+export interface CompactionPlan {
+    writes: CompactionWrite[];
+    skipped: CompactionSkip[];
+    bytesSaved: number;
+}
+/** Options controlling how a stub body is produced. */
+export interface CompactionOptions {
+    /** Explicit replacement body. Omit to generate a pointer from each entry's own first line. */
+    stub?: string;
+    /** Evermind version that absorbed the facts; appears in a generated stub. Default 0. */
+    version?: number;
+    /** Max characters of a generated pointer line. Default {@link DEFAULT_STUB_CHARS}. */
+    maxChars?: 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.
+ */
+export declare function planCompaction(candidates: Array<CompactionCandidate | {
+    key: string;
+    content: undefined;
+}>, opts?: CompactionOptions): CompactionPlan;
+//# sourceMappingURL=compaction.d.ts.map

package/dist/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../src/compaction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,WAAW,4BAAuB,CAAC;AAEhD,6DAA6D;AAC7D,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC,qDAAqD;AACrD,wBAAgB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAqB,GAAG,MAAM,CAO3E;AAED,mEAAmE;AACnE,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,SAAqB,GAAG,MAAM,CAElG;AAED,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,8CAA8C;AAC9C,MAAM,WAAW,eAAe;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,4CAA4C;IAC5C,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,cAAc;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,GAAG,mBAAmB,GAAG,aAAa,CAAC;CAC7D;AAED,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC3B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAC9B,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC1B,UAAU,EAAE,KAAK,CAAC,mBAAmB,GAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC,EAC5E,IAAI,GAAE,iBAAsB,GAC7B,cAAc,CA6BhB"}

package/dist/compaction.js

@@ -0,0 +1,77 @@
+/**
+ * Compaction — turning an ABSORBED memory into a terse pointer stub.
+ *
+ * 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
+ * subsequent recall pays for text the model already carries in its weights.
+ * Compaction replaces the body with a one-line `[absorbed→Evermind vN] <first
+ * line>` pointer, so the fact stops filling context while it stays findable.
+ *
+ * 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.
+ *
+ * Dependency-free and published as its own subpath
+ * (`@seanhogg/builderforce-memory-mcp/compaction`), so an external compactor imports
+ * these rules instead of re-implementing them — the marker below is the shared
+ * idempotency contract between the two processes.
+ */
+/**
+ * Marker that opens every compacted stub — also the idempotency guard. An entry
+ * whose content already starts with this is skipped, so compacting twice (or
+ * from two processes) never double-stubs.
+ */
+export const STUB_PREFIX = "[absorbed→Evermind";
+/** Default cap on the pointer line carried inside a stub. */
+export const DEFAULT_STUB_CHARS = 140;
+/** True when a body is already a compaction stub. */
+export function isStub(content) {
+    return content.trimStart().startsWith(STUB_PREFIX);
+}
+/** The first non-empty line of a body, trimmed to `max` chars — the stub's pointer text. */
+export function firstLine(content, max = DEFAULT_STUB_CHARS) {
+    const line = content
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .find((l) => l.length > 0) ?? "";
+    return line.length > max ? `${line.slice(0, max - 1).trimEnd()}…` : line;
+}
+/** Build the terse stub that replaces an absorbed entry's body. */
+export function memoryStub(content, version, maxChars = DEFAULT_STUB_CHARS) {
+    return `${STUB_PREFIX} v${version}] ${firstLine(content, maxChars)}`;
+}
+/**
+ * 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.
+ */
+export function planCompaction(candidates, opts = {}) {
+    const version = opts.version ?? 0;
+    const maxChars = Math.max(20, opts.maxChars ?? DEFAULT_STUB_CHARS);
+    const writes = [];
+    const skipped = [];
+    let bytesSaved = 0;
+    for (const c of candidates) {
+        const content = c.content;
+        if (typeof content !== "string" || !content.trim()) {
+            skipped.push({ key: c.key, reason: "not_found" });
+            continue;
+        }
+        if (isStub(content)) {
+            skipped.push({ key: c.key, reason: "already_compacted" });
+            continue;
+        }
+        const stub = opts.stub ?? memoryStub(content, version, maxChars);
+        // Never grow an entry — a "compaction" that costs tokens is a regression.
+        if (stub.length >= content.length) {
+            skipped.push({ key: c.key, reason: "not_smaller" });
+            continue;
+        }
+        const saved = content.length - stub.length;
+        writes.push({ key: c.key, content: stub, bytesSaved: saved });
+        bytesSaved += saved;
+    }
+    return { writes, skipped, bytesSaved };
+}
+//# sourceMappingURL=compaction.js.map

package/dist/compaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.js","sourceRoot":"","sources":["../src/compaction.ts"],"names":[],"mappings":"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"}

package/dist/embedding/evermind-embedder.d.ts

@@ -0,0 +1,119 @@
+/**
+ * evermind-embedder — SSM-embedding recall for a HEADLESS host, with no GPU.
+ *
+ * The stdio/HTTP servers used to rank recall by word overlap because standing up
+ * the embedding model was assumed to mean standing up WebGPU. It does not:
+ * `EvermindLM` is a pure-CPU model and `EvermindLM.embed()` mean-pools + L2-
+ * normalises the same hidden state the GPU `HybridMambaModel.embed()` does, to the
+ * same contract. So a headless Node process can embed — it just needs the
+ * checkpoint and the tokenizer that produced its token ids.
+ *
+ * This module is the loader for that pair, plus the ONE thing a per-session
+ * subprocess needs to make embedding affordable: a vector cache that OUTLIVES the
+ * process. Recall embeds the query plus every stored memory; recomputing 200
+ * memory embeddings on the first recall of every session would cost more than the
+ * lexical ranking it replaces. The cache is stamped with the model's fingerprint,
+ * so an adapted checkpoint invalidates it wholesale rather than silently mixing
+ * vectors from two different models.
+ *
+ * It mirrors how this package already persists memories: a JSON file alongside the
+ * memory snapshot, written by the process that owns it, tolerant of a corrupt or
+ * absent file (drop it and recompute — a cache is never the source of truth).
+ */
+/** The seam `MemoryStore.recallRanked(query, k, runtime)` consumes. */
+export interface TextEmbedderLike {
+    embed(text: string): Promise<Float32Array>;
+    /** Vector width. */
+    readonly dimensions: number;
+    /** Model identity — vectors are only comparable within one fingerprint. */
+    readonly fingerprint: string;
+}
+/** A text embedder that also owns a persistent cache. */
+export interface PersistentTextEmbedder extends TextEmbedderLike {
+    /** Write any pending vectors to disk now. Safe to call repeatedly. */
+    flush(): void;
+}
+export interface EvermindEmbedderOptions {
+    /**
+     * Absolute path to a `.evermind` package holding an `evermind-lm` checkpoint.
+     * This is the model whose hidden state becomes the embedding.
+     */
+    modelFile: string;
+    /**
+     * Absolute path to the tokenizer JSON that produced the checkpoint's token ids
+     * (`BPETokenizer.toObject()`, or a Hugging Face `tokenizer.json`).
+     *
+     * Only needed for a package that does NOT embed its own tokenizer. Token ids are
+     * meaningless without the exact vocabulary behind them, so an `.evermind` built
+     * with `PackageMeta.tokenizer` carries one and is self-contained — that is
+     * preferred over any file, because a file can be the WRONG vocabulary while the
+     * embedded one is checksummed and vocab-size-checked against the checkpoint.
+     * Resolution order: the package's own tokenizer, then this path, then a sibling
+     * `<modelFile>.tokenizer.json`.
+     */
+    tokenizerFile?: string;
+    /**
+     * Absolute path for the persistent vector cache. Omit to disable persistence
+     * (vectors are still cached in memory for the life of the process).
+     */
+    cacheFile?: string;
+    /** Max vectors retained in the cache (LRU past this). Default 4000. */
+    maxEntries?: number;
+    /** Debounce before a dirty cache is written back, ms. Default 500. */
+    flushDelayMs?: number;
+}
+type FsLike = {
+    readFileSync(path: string, enc: "utf8"): string;
+    readFileSync(path: string): Uint8Array;
+    writeFileSync(path: string, data: string): void;
+    existsSync(path: string): boolean;
+};
+/**
+ * Build a CPU text embedder from a `.evermind` package + its tokenizer, wrapped in
+ * a persistent vector cache.
+ *
+ * Returns `null` — never throws — when the engine peer is absent, a file is
+ * missing, or the package is not an `evermind-lm`. Recall then stays on the
+ * lexical ranking and says so, which is the correct degrade: a memory server that
+ * refuses to start because an OPTIONAL model is unavailable is worse than one that
+ * ranks by word overlap.
+ */
+export declare function createEvermindEmbedder(opts: EvermindEmbedderOptions): Promise<PersistentTextEmbedder | null>;
+/**
+ * Wraps a text embedder with an LRU vector cache mirrored to a JSON file.
+ *
+ * Exported for hosts that already hold an embedder (a GPU runtime, say) and want
+ * the same cross-process cache — there is one implementation of "cache these
+ * vectors on disk", not one per embedder.
+ */
+export declare class CachedTextEmbedder implements PersistentTextEmbedder {
+    private readonly inner;
+    private readonly fs;
+    readonly dimensions: number;
+    readonly fingerprint: string;
+    /** text → vector. Map insertion order is the LRU order. */
+    private readonly cache;
+    private readonly file;
+    private readonly maxEntries;
+    private readonly flushDelayMs;
+    private dirty;
+    private timer;
+    constructor(inner: TextEmbedderLike, fs: FsLike, opts: Pick<EvermindEmbedderOptions, "cacheFile" | "maxEntries" | "flushDelayMs">);
+    embed(text: string): Promise<Float32Array>;
+    /** Write pending vectors now, cancelling any scheduled write. */
+    flush(): void;
+    private put;
+    /**
+     * Debounce the write-back: one recall embeds the query plus every new memory,
+     * and that burst should cost ONE file write, not one per vector.
+     */
+    private schedule;
+    /**
+     * Read the cache back. A cache stamped with a DIFFERENT fingerprint is from a
+     * different (or adapted) model, so its vectors are not comparable with this
+     * model's — it is dropped whole rather than mixed in.
+     */
+    private hydrate;
+}
+export {};
+//# sourceMappingURL=evermind-embedder.d.ts.map

package/dist/embedding/evermind-embedder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evermind-embedder.d.ts","sourceRoot":"","sources":["../../src/embedding/evermind-embedder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,uEAAuE;AACvE,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3C,oBAAoB;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAuB,SAAQ,gBAAgB;IAC5D,sEAAsE;IACtE,KAAK,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACpC;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAC;CACzB;AAkBD,KAAK,MAAM,GAAG;IACV,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAChD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;IACvC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC,CAAC;AA+BF;;;;;;;;;GASG;AACH,wBAAsB,sBAAsB,CACxC,IAAI,EAAE,uBAAuB,GAC9B,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAgCxC;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,YAAW,sBAAsB;IAazD,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAbvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,2DAA2D;IAC3D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAqB;IAC1C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,KAAK,CAA8C;gBAGtC,KAAK,EAAE,gBAAgB,EACvB,EAAE,EAAE,MAAM,EAC3B,IAAI,EAAE,IAAI,CAAC,uBAAuB,EAAE,WAAW,GAAG,YAAY,GAAG,cAAc,CAAC;IAU9E,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAahD,iEAAiE;IACjE,KAAK,IAAI,IAAI;IAmBb,OAAO,CAAC,GAAG;IAUX;;;OAGG;IACH,OAAO,CAAC,QAAQ;IAUhB;;;;OAIG;IACH,OAAO,CAAC,OAAO;CAelB"}

package/dist/embedding/evermind-embedder.js

@@ -0,0 +1,201 @@
+/**
+ * evermind-embedder — SSM-embedding recall for a HEADLESS host, with no GPU.
+ *
+ * The stdio/HTTP servers used to rank recall by word overlap because standing up
+ * the embedding model was assumed to mean standing up WebGPU. It does not:
+ * `EvermindLM` is a pure-CPU model and `EvermindLM.embed()` mean-pools + L2-
+ * normalises the same hidden state the GPU `HybridMambaModel.embed()` does, to the
+ * same contract. So a headless Node process can embed — it just needs the
+ * checkpoint and the tokenizer that produced its token ids.
+ *
+ * This module is the loader for that pair, plus the ONE thing a per-session
+ * subprocess needs to make embedding affordable: a vector cache that OUTLIVES the
+ * process. Recall embeds the query plus every stored memory; recomputing 200
+ * memory embeddings on the first recall of every session would cost more than the
+ * lexical ranking it replaces. The cache is stamped with the model's fingerprint,
+ * so an adapted checkpoint invalidates it wholesale rather than silently mixing
+ * vectors from two different models.
+ *
+ * It mirrors how this package already persists memories: a JSON file alongside the
+ * memory snapshot, written by the process that owns it, tolerant of a corrupt or
+ * absent file (drop it and recompute — a cache is never the source of truth).
+ */
+const DEFAULT_MAX_ENTRIES = 4000;
+const DEFAULT_FLUSH_DELAY_MS = 500;
+/** Indirect import so the optional engine peer is never statically resolved. */
+function dynamicImport(m) {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+    return new Function("m", "return import(m)")(m);
+}
+/**
+ * Load the tokenizer spec from `file`, accepting either `BPETokenizer.toObject()`
+ * output or a Hugging Face `tokenizer.json`.
+ */
+function loadCodec(engine, fs, file) {
+    const spec = JSON.parse(fs.readFileSync(file, "utf8"));
+    const tok = new engine.BPETokenizer();
+    if (spec.vocab && spec.merges)
+        tok.loadFromSpec(spec);
+    else
+        tok.loadHuggingFace(spec);
+    return tok;
+}
+/**
+ * Build a CPU text embedder from a `.evermind` package + its tokenizer, wrapped in
+ * a persistent vector cache.
+ *
+ * Returns `null` — never throws — when the engine peer is absent, a file is
+ * missing, or the package is not an `evermind-lm`. Recall then stays on the
+ * lexical ranking and says so, which is the correct degrade: a memory server that
+ * refuses to start because an OPTIONAL model is unavailable is worse than one that
+ * ranks by word overlap.
+ */
+export async function createEvermindEmbedder(opts) {
+    try {
+        const engine = (await dynamicImport("@seanhogg/builderforce-memory-engine"));
+        if (!engine?.EvermindModelPackage || !engine.BPETokenizer || !engine.EvermindTextEmbedder)
+            return null;
+        const fs = (await dynamicImport("node:fs"));
+        if (!fs.existsSync(opts.modelFile))
+            return null;
+        const bytes = fs.readFileSync(opts.modelFile);
+        const blob = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+        const pkg = engine.EvermindModelPackage.fromBlob(blob);
+        if (pkg.manifest.modelType !== "evermind-lm")
+            return null;
+        // Prefer the package's OWN tokenizer. It is checksummed and cross-checked
+        // against the checkpoint's vocab size at package time, so it cannot be the
+        // wrong vocabulary — which a separate file silently can be. Falling back to a
+        // file keeps every package written before the section existed working.
+        const embedded = pkg.loadTokenizer?.() ?? null;
+        let codec;
+        if (embedded) {
+            codec = embedded;
+        }
+        else {
+            const tokenizerFile = opts.tokenizerFile ?? `${opts.modelFile}.tokenizer.json`;
+            if (!fs.existsSync(tokenizerFile))
+                return null;
+            codec = loadCodec(engine, fs, tokenizerFile);
+        }
+        const inner = new engine.EvermindTextEmbedder(pkg.loadLM(), codec);
+        return new CachedTextEmbedder(inner, fs, opts);
+    }
+    catch {
+        // Any failure to stand the model up is a degrade, not a fault.
+        return null;
+    }
+}
+/**
+ * Wraps a text embedder with an LRU vector cache mirrored to a JSON file.
+ *
+ * Exported for hosts that already hold an embedder (a GPU runtime, say) and want
+ * the same cross-process cache — there is one implementation of "cache these
+ * vectors on disk", not one per embedder.
+ */
+export class CachedTextEmbedder {
+    inner;
+    fs;
+    dimensions;
+    fingerprint;
+    /** text → vector. Map insertion order is the LRU order. */
+    cache = new Map();
+    file;
+    maxEntries;
+    flushDelayMs;
+    dirty = false;
+    timer = null;
+    constructor(inner, fs, opts) {
+        this.inner = inner;
+        this.fs = fs;
+        this.dimensions = inner.dimensions;
+        this.fingerprint = inner.fingerprint;
+        this.file = opts.cacheFile;
+        this.maxEntries = Math.max(1, opts.maxEntries ?? DEFAULT_MAX_ENTRIES);
+        this.flushDelayMs = Math.max(0, opts.flushDelayMs ?? DEFAULT_FLUSH_DELAY_MS);
+        this.hydrate();
+    }
+    async embed(text) {
+        const hit = this.cache.get(text);
+        if (hit) {
+            // LRU touch — re-insert so this entry becomes most-recently-used.
+            this.cache.delete(text);
+            this.cache.set(text, hit);
+            return hit;
+        }
+        const vec = await this.inner.embed(text);
+        this.put(text, vec);
+        return vec;
+    }
+    /** Write pending vectors now, cancelling any scheduled write. */
+    flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (!this.dirty || !this.file)
+            return;
+        const payload = {
+            fingerprint: this.fingerprint,
+            dimensions: this.dimensions,
+            vectors: [...this.cache.entries()].map(([text, v]) => [text, Array.from(v)]),
+        };
+        try {
+            this.fs.writeFileSync(this.file, JSON.stringify(payload));
+            this.dirty = false;
+        }
+        catch {
+            // A cache that cannot be written is still a working in-memory cache.
+        }
+    }
+    put(text, vec) {
+        if (this.cache.size >= this.maxEntries) {
+            const lru = this.cache.keys().next().value;
+            if (lru !== undefined)
+                this.cache.delete(lru);
+        }
+        this.cache.set(text, vec);
+        this.dirty = true;
+        this.schedule();
+    }
+    /**
+     * Debounce the write-back: one recall embeds the query plus every new memory,
+     * and that burst should cost ONE file write, not one per vector.
+     */
+    schedule() {
+        if (!this.file || this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.flush();
+        }, this.flushDelayMs);
+        // Never hold the process open for a cache write.
+        this.timer.unref?.();
+    }
+    /**
+     * Read the cache back. A cache stamped with a DIFFERENT fingerprint is from a
+     * different (or adapted) model, so its vectors are not comparable with this
+     * model's — it is dropped whole rather than mixed in.
+     */
+    hydrate() {
+        if (!this.file || !this.fs.existsSync(this.file))
+            return;
+        let parsed;
+        try {
+            parsed = JSON.parse(this.fs.readFileSync(this.file, "utf8"));
+        }
+        catch {
+            return;
+        }
+        if (!parsed || parsed.fingerprint !== this.fingerprint || !Array.isArray(parsed.vectors))
+            return;
+        for (const row of parsed.vectors) {
+            if (!Array.isArray(row) || typeof row[0] !== "string" || !Array.isArray(row[1]))
+                continue;
+            if (row[1].length !== this.dimensions)
+                continue;
+            this.cache.set(row[0], Float32Array.from(row[1]));
+        }
+    }
+}
+//# sourceMappingURL=evermind-embedder.js.map

package/dist/embedding/evermind-embedder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evermind-embedder.js","sourceRoot":"","sources":["../../src/embedding/evermind-embedder.ts"],"names":[],"mappings":"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"}

package/dist/embedding/index.d.ts

@@ -0,0 +1,38 @@
+/**
+ * embedding — stand up the recall embedder for a headless server.
+ *
+ * Both out-of-process bins (stdio and HTTP) need the SAME decision: is an
+ * embedding model configured, and if so where do its vectors get cached? That
+ * decision lives here once, so the two servers cannot drift into ranking recall
+ * differently from one another.
+ */
+import { type PersistentTextEmbedder } from "./evermind-embedder.js";
+export { createEvermindEmbedder, CachedTextEmbedder } from "./evermind-embedder.js";
+export type { EvermindEmbedderOptions, PersistentTextEmbedder, TextEmbedderLike } from "./evermind-embedder.js";
+/** Absolute path to a `.evermind` package (an `evermind-lm`) to embed recall with. */
+export declare const MODEL_FILE_ENV = "BUILDERFORCE_MEMORY_MODEL";
+/** Absolute path to the tokenizer JSON matching that checkpoint. */
+export declare const TOKENIZER_FILE_ENV = "BUILDERFORCE_MEMORY_TOKENIZER";
+/** Absolute path for the persistent vector cache; defaults beside the snapshot. */
+export declare const VECTOR_CACHE_ENV = "BUILDERFORCE_MEMORY_VECTORS";
+/**
+ * Where vectors are cached by default: beside the memory snapshot, under the same
+ * name. They belong together — the cache is only meaningful for the memories in
+ * that snapshot, and pointing a second store at the same vectors would be a cache
+ * for the wrong corpus.
+ */
+export declare function defaultVectorCacheFile(memoryFile: string): string;
+export interface RecallEmbedderEnv {
+    env?: Record<string, string | undefined>;
+    /** The snapshot path in effect — used to site the default vector cache. */
+    memoryFile: string;
+}
+/**
+ * The embedder this server should rank recall with, or `null` when none is
+ * configured (recall then ranks lexically and says so).
+ *
+ * Opt-in by design: no model path, no model. A memory server must start and serve
+ * recall on a host that has never downloaded a checkpoint.
+ */
+export declare function createRecallEmbedder(opts: RecallEmbedderEnv): Promise<PersistentTextEmbedder | null>;
+//# sourceMappingURL=index.d.ts.map

package/dist/embedding/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/embedding/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAA0B,KAAK,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAE7F,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACpF,YAAY,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAEhH,sFAAsF;AACtF,eAAO,MAAM,cAAc,8BAA8B,CAAC;AAC1D,oEAAoE;AACpE,eAAO,MAAM,kBAAkB,kCAAkC,CAAC;AAClE,mFAAmF;AACnF,eAAO,MAAM,gBAAgB,gCAAgC,CAAC;AAE9D;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEjE;AAED,MAAM,WAAW,iBAAiB;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC,CAS1G"}