@seanhogg/builderforce-memory-mcp 2026.9.28 → 2026.9.30

package/src/bin/stdio.ts

@@ -23,6 +23,10 @@
  *   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).
+ *   BUILDERFORCE_MEMORY_EXPERIENCE '1' to expose the experience tools (episodes, Train
+ *                                 Once skills, runs, experience_train). Kept beside the
+ *                                 snapshot in experience.json + episodes/; trains the
+ *                                 BUILDERFORCE_MEMORY_MODEL package.
  *
  * 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.
@@ -30,6 +34,7 @@
 
 import { createLocalMemoryStoreBackend } from "../backends/memory-store.js";
 import { createRecallEmbedder } from "../embedding/index.js";
+import { createExperienceHost } from "../experience/host.js";
 import { resolveMemoryFile } from "../install/server-spec.js";
 import { runStdio } from "../transports/stdio.js";
 
@@ -49,4 +54,6 @@ await runStdio(backend, {
     // exposed when an API key is present; URL defaults to the public gateway.
     gatewayUrl: process.env["BUILDERFORCE_GATEWAY_URL"] ?? "https://api.builderforce.ai",
     gatewayApiKey: process.env["BUILDERFORCE_API_KEY"],
+    // Null unless BUILDERFORCE_MEMORY_EXPERIENCE=1 — Synapse's opt-in.
+    experience: await createExperienceHost({ memoryFile }),
 });

package/src/dynamic-import.ts

@@ -0,0 +1,12 @@
+/**
+ * Load a module by name at run time without the bundler or tsc resolving it.
+ *
+ * The optional peers (the memory runtime, the engine, fake-indexeddb, the Claude
+ * Agent SDK) and Node builtins are reached through this, so a consumer that never
+ * takes those paths — a browser bundle, a custom backend, the HTTP thin client —
+ * never has to install or ship them.
+ */
+export function dynamicImport(m: string): Promise<unknown> {
+    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
+    return new Function("m", "return import(m)")(m) as Promise<unknown>;
+}

package/src/embedding/evermind-embedder.ts

@@ -21,6 +21,9 @@
  * absent file (drop it and recompute — a cache is never the source of truth).
  */
 
+import { dynamicImport } from "../dynamic-import.js";
+import { loadEvermindPackage } from "../model/evermind-package.js";
+
 /** The seam `MemoryStore.recallRanked(query, k, runtime)` consumes. */
 export interface TextEmbedderLike {
     embed(text: string): Promise<Float32Array>;
@@ -66,25 +69,8 @@ export interface EvermindEmbedderOptions {
     flushDelayMs?: number;
 }
 
-/** Minimal structural view of the optional engine package. */
-interface EmbedEngine {
-    EvermindModelPackage: {
-        fromBlob(blob: ArrayBuffer): {
-            manifest: { modelType?: string; tokenizerFormat?: string };
-            loadLM(): unknown;
-            /** Present on engines that support the embedded-tokenizer section. */
-            loadTokenizer?(): { encode(t: string): number[] } | null;
-        };
-    };
-    BPETokenizer: {
-        new (): { loadFromSpec(spec: unknown): void; loadHuggingFace(spec: unknown): void; encode(t: string): number[] };
-    };
-    EvermindTextEmbedder: new (model: unknown, codec: unknown) => TextEmbedderLike;
-}
-
 type FsLike = {
     readFileSync(path: string, enc: "utf8"): string;
-    readFileSync(path: string): Uint8Array;
     writeFileSync(path: string, data: string): void;
     existsSync(path: string): boolean;
 };
@@ -100,24 +86,6 @@ interface VectorCacheFile {
     vectors: Array<[string, number[]]>;
 }
 
-/** Indirect import so the optional engine peer is never statically resolved. */
-function dynamicImport(m: string): Promise<unknown> {
-    // eslint-disable-next-line @typescript-eslint/no-implied-eval, no-new-func
-    return new Function("m", "return import(m)")(m) as Promise<unknown>;
-}
-
-/**
- * Load the tokenizer spec from `file`, accepting either `BPETokenizer.toObject()`
- * output or a Hugging Face `tokenizer.json`.
- */
-function loadCodec(engine: EmbedEngine, fs: FsLike, file: string): { encode(t: string): number[] } {
-    const spec = JSON.parse(fs.readFileSync(file, "utf8")) as { vocab?: unknown; merges?: unknown; model?: unknown };
-    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.
@@ -132,32 +100,14 @@ export async function createEvermindEmbedder(
     opts: EvermindEmbedderOptions,
 ): Promise<PersistentTextEmbedder | null> {
     try {
-        const engine = (await dynamicImport("@seanhogg/builderforce-memory-engine")) as Partial<EmbedEngine>;
-        if (!engine?.EvermindModelPackage || !engine.BPETokenizer || !engine.EvermindTextEmbedder) return null;
-
-        const fs = (await dynamicImport("node:fs")) as FsLike;
-        if (!fs.existsSync(opts.modelFile)) return null;
-
-        const bytes = fs.readFileSync(opts.modelFile);
-        const blob = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
-        const pkg = (engine as EmbedEngine).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: { encode(t: string): number[] };
-        if (embedded) {
-            codec = embedded;
-        } else {
-            const tokenizerFile = opts.tokenizerFile ?? `${opts.modelFile}.tokenizer.json`;
-            if (!fs.existsSync(tokenizerFile)) return null;
-            codec = loadCodec(engine as EmbedEngine, fs, tokenizerFile);
-        }
-        const inner = new (engine as EmbedEngine).EvermindTextEmbedder(pkg.loadLM(), codec);
-        return new CachedTextEmbedder(inner, fs, opts);
+        const loaded = await loadEvermindPackage(opts.modelFile, opts.tokenizerFile);
+        if (!loaded) return null;
+        const engine = (await dynamicImport("@seanhogg/builderforce-memory-engine")) as {
+            EvermindTextEmbedder?: new (model: unknown, codec: unknown) => TextEmbedderLike;
+        };
+        if (!engine?.EvermindTextEmbedder) return null;
+        const inner = new engine.EvermindTextEmbedder(loaded.pkg.loadLM(), loaded.codec);
+        return new CachedTextEmbedder(inner, loaded.fs, opts);
     } catch {
         // Any failure to stand the model up is a degrade, not a fault.
         return null;

package/src/experience/file-store.ts

@@ -0,0 +1,143 @@
+/**
+ * The engine's experience store, made durable on disk.
+ *
+ * The engine owns experience — the types, Train Once, the snapshot format and the
+ * reference `InMemoryExperienceStore`. This host adds only what a pure package
+ * cannot: the snapshot lives in `experience.json` beside `memory.json`, shared by
+ * every process on the machine the same way memories are (one {@link SharedJsonFile}
+ * implementation, so the freshness check and the loop guard are the memory store's),
+ * and each episode's screenshots live in `episodes/<id>/`, removed when it is forgotten.
+ */
+
+import type {
+    Adaptation,
+    Episode,
+    EpisodeSummary,
+    ExperienceSnapshot,
+    ExperienceStore,
+    InMemoryExperienceStore,
+    Run,
+    RunStepLog,
+    Skill,
+} from "@seanhogg/builderforce-memory-engine";
+import type { SharedJsonFile } from "../persistence/shared-json-file.js";
+
+/** The filesystem calls the store makes besides the snapshot's own. */
+export interface EpisodeFolders {
+    /**
+     * Delete one episode's screenshot folder, if it exists. Only ever called with a safe
+     * id. Forgetting everything calls this once per KNOWN episode — never a recursive
+     * delete of the parent, which sits beside a user-chosen memory file.
+     */
+    remove(episodeId: string): void;
+}
+
+/** Episode ids are also folder names — anything that could leave the folder is refused. */
+export function isSafeExperienceId(id: string): boolean {
+    return /^[A-Za-z0-9_-]{1,64}$/.test(id);
+}
+
+export class FileExperienceStore implements ExperienceStore {
+    constructor(
+        private readonly inner: InMemoryExperienceStore,
+        private readonly file: SharedJsonFile,
+        private readonly parse: (raw: unknown) => ExperienceSnapshot,
+        private readonly folders: EpisodeFolders,
+    ) {}
+
+    /**
+     * Absorb the file when another process rewrote it. Also the boot hydration. A file
+     * that does not parse is left unabsorbed (a half-written snapshot): the store keeps
+     * what it has and the next call looks again.
+     */
+    private fresh(): void {
+        const changed = this.file.readIfChanged();
+        if (!changed) return;
+        let raw: unknown;
+        try {
+            raw = JSON.parse(changed.text);
+        } catch {
+            return;
+        }
+        const snapshot = this.parse(raw);
+        // A snapshot in a schema this server does not know (a newer writer) parses to
+        // empty — absorbing it would let the next write destroy it. Refuse instead.
+        const schema = (raw as { schema?: unknown } | null)?.schema;
+        if (typeof schema === "string" && schema !== snapshot.schema) {
+            throw new Error(
+                `${this.file.path} is in schema "${schema}", which this server cannot read (it writes "${snapshot.schema}"). Upgrade the memory server; the file was left untouched.`,
+            );
+        }
+        this.inner.load(snapshot);
+        changed.accept();
+    }
+
+    async putEpisode(episode: Episode): Promise<void> {
+        this.fresh();
+        await this.inner.putEpisode(episode);
+    }
+    async getEpisode(id: string): Promise<Episode | undefined> {
+        this.fresh();
+        return this.inner.getEpisode(id);
+    }
+    async listEpisodes(): Promise<EpisodeSummary[]> {
+        this.fresh();
+        return this.inner.listEpisodes();
+    }
+    async deleteEpisode(id: string): Promise<boolean> {
+        this.fresh();
+        const ok = await this.inner.deleteEpisode(id);
+        if (isSafeExperienceId(id)) this.folders.remove(id);
+        return ok;
+    }
+
+    async putSkill(skill: Skill): Promise<void> {
+        this.fresh();
+        await this.inner.putSkill(skill);
+    }
+    async getSkill(id: string): Promise<Skill | undefined> {
+        this.fresh();
+        return this.inner.getSkill(id);
+    }
+    async listSkills(): Promise<Skill[]> {
+        this.fresh();
+        return this.inner.listSkills();
+    }
+    async deleteSkill(id: string): Promise<boolean> {
+        this.fresh();
+        return this.inner.deleteSkill(id);
+    }
+
+    async putRun(run: Run): Promise<void> {
+        this.fresh();
+        await this.inner.putRun(run);
+    }
+    async appendRunStep(runId: string, step: RunStepLog): Promise<boolean> {
+        this.fresh();
+        return this.inner.appendRunStep(runId, step);
+    }
+    async getRun(id: string): Promise<Run | undefined> {
+        this.fresh();
+        return this.inner.getRun(id);
+    }
+    async listRuns(limit: number): Promise<Run[]> {
+        this.fresh();
+        return this.inner.listRuns(limit);
+    }
+
+    async recordAdaptation(adaptation: Adaptation): Promise<void> {
+        this.fresh();
+        await this.inner.recordAdaptation(adaptation);
+    }
+
+    async snapshot(): Promise<ExperienceSnapshot> {
+        this.fresh();
+        return this.inner.snapshot();
+    }
+    async clear(): Promise<void> {
+        this.fresh();
+        const known = (await this.inner.snapshot()).episodes.map((e) => e.id).filter(isSafeExperienceId);
+        await this.inner.clear();
+        for (const id of known) this.folders.remove(id);
+    }
+}

package/src/experience/host.ts

@@ -0,0 +1,113 @@
+/**
+ * Stand up experience for a headless server: the engine, the durable store and the
+ * private model it trains — or nothing, when experience is not switched on.
+ *
+ * Opt-in by design, like the Synapse feature it serves: a plain memory server (the
+ * one every coding agent installs) never pays for experience tools in its tool list.
+ */
+
+import type {
+    ExperienceStore,
+    InMemoryExperienceStore,
+    ExperienceSnapshot,
+    dueSkills,
+    experienceOverview,
+    newExperienceId,
+    trainOnce,
+} from "@seanhogg/builderforce-memory-engine";
+import { dynamicImport } from "../dynamic-import.js";
+import { MODEL_FILE_ENV, TOKENIZER_FILE_ENV } from "../embedding/index.js";
+import { loadEvermindPackage, readEvermindVersion, type LoadedEvermind } from "../model/evermind-package.js";
+import { SharedJsonFile, type SharedFileFs } from "../persistence/shared-json-file.js";
+import { FileExperienceStore } from "./file-store.js";
+import type { TrainEngine } from "./train.js";
+
+/** '1' turns the experience tools on. */
+export const EXPERIENCE_ENV = "BUILDERFORCE_MEMORY_EXPERIENCE";
+
+/** The engine surface experience uses, passed around so the peer stays optional. */
+export interface ExperienceEngine extends TrainEngine {
+    trainOnce: typeof trainOnce;
+    dueSkills: typeof dueSkills;
+    newExperienceId: typeof newExperienceId;
+    experienceOverview: typeof experienceOverview;
+}
+
+export interface ExperienceHost {
+    store: ExperienceStore;
+    engine: ExperienceEngine;
+    /** The memory snapshot experience sits beside (the facts). */
+    memoryFile: string;
+    /** The experience snapshot file. */
+    file: string;
+    /** Where each episode's screenshots go: `<episodesDir>/<episodeId>/`. */
+    episodesDir: string;
+    /** The private model experience trains, when one is configured. */
+    modelFile?: string;
+    /** Load the model fresh from disk (training rewrites it, so it is never cached). */
+    loadModel(): Promise<LoadedEvermind | null>;
+    /** The model's version from its manifest alone, or null without a readable one. */
+    modelVersion(): Promise<string | null>;
+}
+
+type HostFs = SharedFileFs & {
+    mkdirSync(path: string, opts: { recursive: boolean }): void;
+    rmSync(path: string, opts: { recursive: boolean; force: boolean }): void;
+};
+type HostPath = { dirname(p: string): string; join(...p: string[]): string };
+
+export interface ExperienceHostOptions {
+    env?: Record<string, string | undefined>;
+    /** The memory snapshot in effect — experience lives beside it. */
+    memoryFile: string;
+}
+
+/**
+ * The experience host, or `null` when experience is off or the engine peer is
+ * absent. Never throws: a memory server must start without it.
+ */
+export async function createExperienceHost(opts: ExperienceHostOptions): Promise<ExperienceHost | null> {
+    const env = opts.env ?? process.env;
+    if (env[EXPERIENCE_ENV] !== "1") return null;
+    try {
+        const engine = (await dynamicImport("@seanhogg/builderforce-memory-engine")) as Partial<
+            ExperienceEngine & {
+                InMemoryExperienceStore: new (
+                    initial?: ExperienceSnapshot,
+                    onChange?: (s: ExperienceSnapshot) => void,
+                ) => InMemoryExperienceStore;
+                parseSnapshot: (raw: unknown) => ExperienceSnapshot;
+            }
+        >;
+        if (!engine?.InMemoryExperienceStore || !engine.parseSnapshot || !engine.trainOnce || !engine.adaptPackage) return null;
+
+        const fs = (await dynamicImport("node:fs")) as HostFs;
+        const path = (await dynamicImport("node:path")) as HostPath;
+        const dir = path.dirname(opts.memoryFile);
+        const file = path.join(dir, "experience.json");
+        const episodesDir = path.join(dir, "episodes");
+        fs.mkdirSync(episodesDir, { recursive: true });
+
+        const shared = new SharedJsonFile(file, fs);
+        const inner = new engine.InMemoryExperienceStore(undefined, (s) => shared.write(JSON.stringify(s, null, 2)));
+        const store = new FileExperienceStore(inner, shared, engine.parseSnapshot, {
+            remove: (id) => fs.rmSync(path.join(episodesDir, id), { recursive: true, force: true }),
+        });
+        const modelFile = env[MODEL_FILE_ENV] || undefined;
+        const tokenizerFile = env[TOKENIZER_FILE_ENV] || undefined;
+        const loadModel = async () => (modelFile ? loadEvermindPackage(modelFile, tokenizerFile) : null);
+        const modelVersion = async () => (modelFile ? readEvermindVersion(modelFile) : null);
+        return {
+            store,
+            engine: engine as ExperienceEngine,
+            memoryFile: opts.memoryFile,
+            file,
+            episodesDir,
+            modelFile,
+            loadModel,
+            modelVersion,
+        };
+    } catch {
+        return null;
+    }
+}