@seanhogg/builderforce-memory 2026.6.34 → 2026.6.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.6.34",
+  "version": "2026.6.39",
   "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, hybrid RAG retrieval, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -53,7 +53,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.6.34"
+    "@seanhogg/builderforce-memory-engine": "^2026.6.39"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -67,7 +67,7 @@
     "ts-jest": "^29.2.0",
     "typescript": "^6.0.3",
     "@typescript/native-preview": "7.0.0-dev.20260627.2",
-    "@seanhogg/builderforce-memory-engine": "2026.6.34"
+    "@seanhogg/builderforce-memory-engine": "2026.6.39"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",
@@ -85,6 +85,7 @@
             "strict": false,
             "esModuleInterop": true,
             "skipLibCheck": true,
+            "rootDir": "..",
             "types": [
               "@webgpu/types",
               "jest"
@@ -94,19 +95,21 @@
       ]
     },
     "moduleNameMapper": {
+      "^@seanhogg/builderforce-memory-engine$": "<rootDir>/../memory-engine/src/index.ts",
       "^(\\.{1,2}/.*)\\.js$": "$1"
     },
     "collectCoverageFrom": [
       "src/**/*.ts",
       "!src/**/index.ts",
-      "!src/session/**"
+      "!src/session/**",
+      "!src/limbic/LimbicSession.ts"
     ],
     "coverageThreshold": {
       "global": {
-        "branches": 100,
-        "functions": 100,
-        "lines": 100,
-        "statements": 100
+        "statements": 90,
+        "branches": 85,
+        "functions": 95,
+        "lines": 92
       }
     }
   },

package/src/index.ts

@@ -217,9 +217,12 @@ export {
     BUILTIN_STEPS,
     AGENTIC_SEVEN_LAYER,
     TRAIN_LLM,
+    TEACH_CODE,
     WORKFLOW_TEMPLATES,
     getTemplate,
     cloneTemplate,
+    analyzeCode,
+    runJsCases,
 } from './workflow/index.js';
 export type {
     WorkflowConfig,
@@ -228,6 +231,9 @@ export type {
     StepFactory,
     WorkflowValidationError,
     RunWorkflowOptions,
+    CodeAnalysis,
+    CodeCase,
+    CodeEvalResult,
 } from './workflow/index.js';
 
 // ── Publish (ship an engine model export to HF / local folder) ──────────────────

package/src/limbic/LimbicSession.ts

@@ -24,10 +24,15 @@ import {
   createBindGroup,
   dispatchKernel,
   readBuffer,
+  personalitySetpoint,
+  clampState,
+  neutralState,
+  LIMBIC_STATE_DIM,
   type LimbicModelConfig,
   type LimbicForward,
   type LimbicSample,
   type LimbicTrainOptions,
+  type PersonalityTraits,
 } from "@seanhogg/builderforce-memory-engine";
 
 import { saveToIndexedDB, loadFromIndexedDB } from "../session/persistence.js";
@@ -49,6 +54,18 @@ export interface LimbicSessionOptions {
   modelConfig?: Partial<LimbicModelConfig>;
   /** Deterministic init seed. */
   seed?: number;
+  /**
+   * The agent's static personality traits (0..100). Mapped to the resting affective
+   * SETPOINT the learned dynamics ride on top of, so training + relaxation happen
+   * around the personality baseline instead of neutral ("personality = setpoints,
+   * limbic = dynamics"). Ignored when {@link personalitySetpoint} is given.
+   */
+  personalityTraits?: PersonalityTraits;
+  /**
+   * An explicit 8-dim resting setpoint (e.g. one already derived by the runtime's
+   * `deriveLimbicSetpoints`). Overrides {@link personalityTraits}. Clamped to bounds.
+   */
+  personalitySetpoint?: ArrayLike<number>;
 }
 
 interface StepBuffers {
@@ -64,6 +81,11 @@ export class LimbicSession {
   readonly trainer: LimbicTrainer;
   readonly device: GPUDevice | null;
   readonly gpuMode: LimbicGpuMode;
+  /** The personality-conditioned resting setpoint (8-dim). NEUTRAL when no
+   *  personality was supplied. The homeostatic baseline the learned dynamics
+   *  settle toward — see {@link baselineState}. Mutable via {@link setSetpoint} so a
+   *  long-lived service can re-point it when the active personas change. */
+  setpoint: Float32Array;
   private readonly _name: string;
   private readonly _idbFactory: IDBFactory | undefined;
 
@@ -80,6 +102,7 @@ export class LimbicSession {
     gpuMode: LimbicGpuMode,
     name: string,
     idbFactory: IDBFactory | undefined,
+    setpoint: Float32Array,
   ) {
     this.model = model;
     this.trainer = trainer;
@@ -87,6 +110,32 @@ export class LimbicSession {
     this.gpuMode = gpuMode;
     this._name = name;
     this._idbFactory = idbFactory;
+    this.setpoint = setpoint;
+  }
+
+  /**
+   * A fresh copy of the personality-conditioned resting state. Seed training-sample
+   * states and initial affect from this so the learned dynamics move AROUND the
+   * agent's personality baseline rather than a fixed neutral. NEUTRAL when the
+   * session was created with no personality.
+   */
+  baselineState(): Float32Array {
+    return Float32Array.from(this.setpoint);
+  }
+
+  /**
+   * Re-point the resting setpoint after construction — e.g. a long-lived service
+   * recomputing it when the active personas change. An explicit 8-dim vector wins;
+   * else the traits are mapped; else neutral. Clamped to bounds.
+   */
+  setSetpoint(traits?: PersonalityTraits, explicit?: ArrayLike<number>): void {
+    if (explicit && explicit.length >= LIMBIC_STATE_DIM) {
+      this.setpoint = clampState(Float32Array.from(explicit));
+    } else if (traits) {
+      this.setpoint = personalitySetpoint(traits);
+    } else {
+      this.setpoint = neutralState();
+    }
   }
 
   static async create(options: LimbicSessionOptions = {}): Promise<LimbicSession> {
@@ -129,7 +178,18 @@ export class LimbicSession {
       model.loadWeights(options.checkpointBuffer);
     }
     const trainer = new LimbicTrainer(model, device);
-    return new LimbicSession(model, trainer, device, gpuMode, options.name ?? "limbic-default", options.idbFactory);
+    // Resolve the resting setpoint: an explicit 8-dim vector wins; else map the
+    // personality traits; else neutral. This is where the STATIC personality enters
+    // the (dynamic, trainable) limbic system.
+    let setpoint: Float32Array;
+    if (options.personalitySetpoint && options.personalitySetpoint.length >= LIMBIC_STATE_DIM) {
+      setpoint = clampState(Float32Array.from(options.personalitySetpoint));
+    } else if (options.personalityTraits) {
+      setpoint = personalitySetpoint(options.personalityTraits);
+    } else {
+      setpoint = neutralState();
+    }
+    return new LimbicSession(model, trainer, device, gpuMode, options.name ?? "limbic-default", options.idbFactory, setpoint);
   }
 
   /** One affect step. Uses the GPU kernel when a device is available, else CPU. */

package/src/memory/MemoryStore.ts

@@ -10,7 +10,7 @@
 
 import { SSMError } from '../errors/SSMError.js';
 import { tokenize, jaccardSimilarity } from '../similarity/index.js';
-import { hybridRetrieve, denseSearch, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
+import { hybridRetrieve, denseSearch, HnswIndex, type RetrievalCandidate, type HybridRetrieveOptions } from '../retrieval/index.js';
 
 export type FactType = 'text' | 'json' | 'number' | 'boolean';
 
@@ -116,6 +116,20 @@ export class MemoryStore {
     private _sweepTimer: ReturnType<typeof setInterval> | null = null;
     /** Content → L2-normalised embedding cache, used by recallSimilar. */
     private readonly _embedCache = new Map<string, Float32Array>();
+    /** Runtime whose embeddings populate `_embedCache`; a change invalidates it. */
+    private _embedRuntime: unknown = null;
+
+    // ── Persistent dense index (EVM-1b) ────────────────────────────────────────
+    // Fact embeddings keyed by `${key}@${seq}` so an EDIT (seq bump) is a new key
+    // and an unchanged fact is never re-embedded. The HNSW index is derived from
+    // these vectors and reused across recalls until the fact set changes — so
+    // steady-state recall is O(1) query-embed + O(log N) search, not O(N) embed.
+    private readonly _denseVectors = new Map<string, Float32Array>();
+    private _denseIndex: HnswIndex | null = null;
+    /** Signature of the fact set the current index was built from. */
+    private _denseSig = '';
+    /** Identity of the runtime whose embeddings populated the vectors. */
+    private _denseRuntime: unknown = null;
 
     constructor(opts: MemoryStoreOptions = {}) {
         this._dbName     = opts.dbName     ?? 'ssmjs';
@@ -321,19 +335,16 @@ export class MemoryStore {
         if (runtime != null && typeof runtime.embed === 'function') {
             const queryVec = await this._embedWithCache(runtime, query);
             if (queryVec) {
-                const items: Array<{ id: string; vector: Float32Array }> = [];
-                const byKey = new Map<string, MemoryEntry>();
-                let embeddedAll = true;
-                for (const entry of all) {
-                    const entryVec = await this._embedWithCache(runtime, entry.content);
-                    if (!entryVec) { embeddedAll = false; break; }
-                    items.push({ id: entry.key, vector: entryVec });
-                    byKey.set(entry.key, entry);
-                }
-                if (embeddedAll) {
-                    // EVM-1: exact scan under the threshold, HNSW ANN above it.
-                    const hits = denseSearch(queryVec, items, topK, this._annThreshold);
-                    return hits.map(h => byKey.get(h.id)).filter((e): e is MemoryEntry => !!e);
+                // EVM-1b: sync the persistent vector store + index (embeds only the
+                // delta), then query it — no per-call re-embed of every fact.
+                const synced = await this._syncDense(runtime, all);
+                if (synced) {
+                    const hits = synced.index
+                        // EVM-1: above the threshold, query the persistent HNSW (O(log N)).
+                        ? synced.index.search(queryVec, topK)
+                        // Below it, an exact scan over the (already-embedded) vectors.
+                        : denseSearch(queryVec, synced.items, topK, this._annThreshold);
+                    return hits.map(h => synced.byKey.get(h.id)).filter((e): e is MemoryEntry => !!e);
                 }
             }
             // Any failure falls through to the Jaccard path below.
@@ -392,6 +403,12 @@ export class MemoryStore {
      * unavailable so callers can fall back to lexical similarity.
      */
     private async _embedWithCache(runtime: SSMRuntimeRef, text: string): Promise<Float32Array | null> {
+        // Embeddings are model-specific: if the runtime instance changed, the cached
+        // vectors are from a different model and must be dropped. (EVM-1b)
+        if (runtime !== this._embedRuntime) {
+            this._embedCache.clear();
+            this._embedRuntime = runtime;
+        }
         const cached = this._embedCache.get(text);
         if (cached) {
             // LRU touch: re-insert so this entry becomes most-recently-used. (EVM-8)
@@ -418,6 +435,68 @@ export class MemoryStore {
         return null;
     }
 
+    /**
+     * Synchronise the persistent dense vector store + HNSW index to `all` (EVM-1b).
+     * Embeds ONLY new/changed facts (keyed by `key@seq`), prunes removed ones, and
+     * rebuilds the index only when the fact set actually changed — so a read-heavy
+     * workload reuses both the embeddings and the index across recalls. Returns
+     * `null` (caller falls back to lexical) if any embedding is unavailable, or
+     * resets everything when the runtime identity changes (embeddings are
+     * model-specific).
+     */
+    private async _syncDense(
+        runtime: SSMRuntimeRef,
+        all: MemoryEntry[],
+    ): Promise<{ byKey: Map<string, MemoryEntry>; items: Array<{ id: string; vector: Float32Array }>; index: HnswIndex | null } | null> {
+        if (runtime !== this._denseRuntime) {
+            this._denseVectors.clear();
+            this._denseIndex = null;
+            this._denseSig = '';
+            this._denseRuntime = runtime;
+        }
+
+        const vkeyOf = (e: MemoryEntry): string => `${e.key}@${e.seq ?? 0}`;
+        const currentVkeys = new Set<string>();
+        let sig = `${all.length}`;
+        for (const e of all) { const k = vkeyOf(e); currentVkeys.add(k); sig += '|' + k; }
+
+        const byKey = new Map<string, MemoryEntry>();
+        const items: Array<{ id: string; vector: Float32Array }> = [];
+        for (const entry of all) {
+            const vk = vkeyOf(entry);
+            let vec = this._denseVectors.get(vk);
+            if (!vec) {
+                const v = await this._embedWithCache(runtime, entry.content);
+                if (!v) return null; // embedding failed → lexical fallback
+                vec = v;
+                this._denseVectors.set(vk, vec);
+            }
+            items.push({ id: entry.key, vector: vec });
+            byKey.set(entry.key, entry);
+        }
+
+        // Drop vectors for facts that are gone or were edited (stale vkeys).
+        if (this._denseVectors.size > currentVkeys.size) {
+            for (const k of this._denseVectors.keys()) {
+                if (!currentVkeys.has(k)) this._denseVectors.delete(k);
+            }
+        }
+
+        // Maintain the ANN index only above the threshold; (re)build it only when
+        // the fact set changed (no embedding involved — purely in-memory).
+        if (all.length >= this._annThreshold) {
+            if (sig !== this._denseSig || this._denseIndex === null) {
+                const index = new HnswIndex();
+                for (const it of items) index.add(it.id, it.vector);
+                this._denseIndex = index;
+            }
+        } else {
+            this._denseIndex = null;
+        }
+        this._denseSig = sig;
+        return { byKey, items, index: this._denseIndex };
+    }
+
     /**
      * Hard-deletes all entries whose TTL has expired.
      * @returns The number of entries deleted.
@@ -451,6 +530,11 @@ export class MemoryStore {
     /** Deletes all facts. Does not affect saved weights. */
     async clear(): Promise<void> {
         const db = await this._open();
+        // Drop the persistent dense index/vectors too (EVM-1b) — they describe a
+        // fact set that no longer exists.
+        this._denseVectors.clear();
+        this._denseIndex = null;
+        this._denseSig = '';
 
         const tx = db.transaction(FACTS_STORE, 'readwrite');
         return requestToPromise(tx.objectStore(FACTS_STORE).clear(), 'Failed to clear facts', () => undefined);

package/src/session/session.ts

@@ -12,6 +12,8 @@ import {
     BPETokenizer,
     HybridMambaModel,
     MambaTrainer,
+    diffCheckpoints,
+    applyCheckpointDiff,
     type HybridMambaModelConfig,
     type LayerSpec,
     type LayerType,
@@ -172,12 +174,21 @@ export interface SaveOptions {
     storage?  : StorageTarget;  // Default: 'indexedDB'
     filename? : string;         // Used by 'download' and 'fileSystem'. Default: '<name>.bin'
     key?      : string;         // IndexedDB key override. Default: session name
+    /**
+     * Base checkpoint to diff against (EVM-6b). When provided, save persists only
+     * a sparse DELTA vs this base (online adapt() I/O win) instead of the full
+     * model. Reload with `load({ deltaBase })`. Must be an f32 checkpoint of the
+     * same config (e.g. a prior `await session.export()` / saved buffer).
+     */
+    deltaBase?: ArrayBuffer;
 }
 
 export interface LoadOptions {
     storage?  : StorageTarget;  // Default: 'indexedDB'
     url?      : string;         // Used when storage is 'url'
     key?      : string;         // IndexedDB key override. Default: session name
+    /** Base checkpoint to reconstruct a delta saved with `save({ deltaBase })`. (EVM-6b) */
+    deltaBase?: ArrayBuffer;
 }
 
 export type CreateStage = 'gpu' | 'tokenizer' | 'model' | 'weights';
@@ -552,7 +563,12 @@ export class MambaSession {
         const key      = options.key      ?? this._name;
         const filename = options.filename ?? `${this._name}.bin`;
 
-        const buffer = await this._model.exportWeights();
+        // EVM-6b: when a base is supplied, persist only the sparse delta vs it
+        // (f32 both sides) — an online adapt() then writes kilobytes, not the
+        // whole model. Otherwise write the full checkpoint as before.
+        const buffer = options.deltaBase
+            ? diffCheckpoints(options.deltaBase, await this._model.exportWeights({ fp16: false }))
+            : await this._model.exportWeights();
 
         switch (storage) {
             case 'indexedDB':
@@ -608,6 +624,12 @@ export class MambaSession {
 
         if (buffer == null) return false;
 
+        // EVM-6b: a delta saved with `save({ deltaBase })` is reconstructed against
+        // the same base before loading.
+        if (options.deltaBase) {
+            buffer = applyCheckpointDiff(options.deltaBase, buffer);
+        }
+
         try {
             await this._model.loadWeights(buffer);
         } catch (err) {

package/src/workflow/code-eval.ts

@@ -0,0 +1,143 @@
+/**
+ * workflow/code-eval.ts — dependency-free code-validity + execution-reward checks.
+ *
+ * These power the code-specific BUILD diagnostics that grade what Evermind's
+ * generator produces when we teach it to program:
+ *   • {@link analyzeCode}  — structural validity (balanced delimiters/strings) +
+ *                            an optional JS parse. The portable "does this look
+ *                            like valid code" gate.
+ *   • {@link runJsCases}   — execution-grounded reward: run generated JS against
+ *                            test cases and score the pass-rate. Code's signal is
+ *                            that it RUNS — this turns that into a number.
+ *
+ * Both are zero-dependency (no AST library) so they run in the same WebGPU/TS
+ * runtime as the rest of the engine. Execution uses the `Function` constructor —
+ * a heuristic reward sandbox, NOT a security boundary; only feed it code from a
+ * trusted teacher / the model under training.
+ */
+
+const OPEN: Record<string, string> = { ")": "(", "]": "[", "}": "{" };
+
+export interface CodeAnalysis {
+  /** 0..1 structural-validity score (1 = delimiters and strings all balanced). */
+  score: number;
+  /** True when every bracket/brace/paren and string literal closes cleanly. */
+  balanced: boolean;
+  /** For language="js": whether the source parses (Function constructor). undefined otherwise. */
+  jsParse?: boolean;
+}
+
+/**
+ * Score how structurally valid `code` is: walk the source tracking string state
+ * (so brackets inside strings are ignored) and a delimiter stack. A clean parse
+ * scores 1; each unmatched/mismatched delimiter or unterminated string lowers it.
+ */
+export function analyzeCode(code: string, language = "js"): CodeAnalysis {
+  const stack: string[] = [];
+  let mismatches = 0;
+  let delims = 0;
+  let inString: string | null = null; // the opening quote char, or null
+  let escaped = false;
+
+  for (let i = 0; i < code.length; i++) {
+    const ch = code[i]!;
+    if (inString) {
+      if (escaped) { escaped = false; continue; }
+      if (ch === "\\") { escaped = true; continue; }
+      if (ch === inString) inString = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") { inString = ch; continue; }
+    if (ch === "(" || ch === "[" || ch === "{") { stack.push(ch); delims++; continue; }
+    if (ch === ")" || ch === "]" || ch === "}") {
+      delims++;
+      if (stack.pop() !== OPEN[ch]) mismatches++;
+    }
+  }
+  // Anything left open is an unmatched delimiter; an open string is one more fault.
+  mismatches += stack.length;
+  const faults = mismatches + (inString ? 1 : 0);
+  const denom = Math.max(1, delims + (inString ? 1 : 0));
+  const balanced = faults === 0;
+  const score = balanced ? 1 : Math.max(0, 1 - faults / denom);
+
+  const analysis: CodeAnalysis = { score, balanced };
+  if (language === "js" || language === "ts" || language === "javascript" || language === "typescript") {
+    analysis.jsParse = jsParses(code);
+  }
+  return analysis;
+}
+
+/** True when `code` parses as JS (Function constructor parses but does not run). */
+function jsParses(code: string): boolean {
+  try {
+    // eslint-disable-next-line no-new-func
+    new Function(code);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export interface CodeCase {
+  /** An expression to evaluate after the code is loaded, e.g. "add(2, 3)". */
+  call: string;
+  /** The expected result (deep-equal compared). */
+  expect: unknown;
+}
+
+export interface CodeEvalResult {
+  passed: number;
+  total: number;
+  /** passed / total (0 when there are no cases). */
+  passRate: number;
+  /** A whole-program error (e.g. syntax error) that failed every case, if any. */
+  error?: string;
+}
+
+/**
+ * Load `code` (which defines functions) and evaluate each case's `call`
+ * expression, comparing the result to `expect`. A syntax error in `code` fails
+ * every case. Per-case runtime errors fail only that case.
+ *
+ * NOTE: heuristic reward sandbox, not a security boundary — see file header.
+ */
+export function runJsCases(code: string, cases: CodeCase[]): CodeEvalResult {
+  const total = cases.length;
+  if (total === 0) return { passed: 0, total: 0, passRate: 0 };
+
+  let passed = 0;
+  for (const c of cases) {
+    try {
+      // Code defines functions (hoisted); the trailing return evaluates the call.
+      // eslint-disable-next-line no-new-func
+      const fn = new Function(`${code}\n;return (${c.call});`);
+      const actual = fn();
+      if (deepEqual(actual, c.expect)) passed++;
+    } catch (err) {
+      // A syntax error throws at construction for ALL cases — report it once.
+      if (err instanceof SyntaxError) {
+        return { passed: 0, total, passRate: 0, error: err.message };
+      }
+      // Runtime error → this case simply fails.
+    }
+  }
+  return { passed, total, passRate: passed / total };
+}
+
+/** Structural deep equality good enough for JSON-shaped test expectations. */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null) return false;
+  if (typeof a !== "object") return Object.is(a, b);
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => deepEqual(v, b[i]));
+  }
+  const ao = a as Record<string, unknown>;
+  const bo = b as Record<string, unknown>;
+  const ak = Object.keys(ao);
+  const bk = Object.keys(bo);
+  if (ak.length !== bk.length) return false;
+  return ak.every((k) => deepEqual(ao[k], bo[k]));
+}

package/src/workflow/index.ts

@@ -6,14 +6,22 @@
 
 export type { WorkflowConfig, WorkflowStepConfig, StepTypeInfo, StepFactory } from "./types.js";
 export { StepTypeRegistry, createDefaultRegistry, defaultStepRegistry } from "./registry.js";
-export { BUILTIN_STEPS } from "./steps.js";
+export { BUILTIN_STEPS, selectBestCandidate, stripCodeFences } from "./steps.js";
 export {
   AGENTIC_SEVEN_LAYER,
   TRAIN_LLM,
+  TEACH_CODE,
   WORKFLOW_TEMPLATES,
   getTemplate,
   cloneTemplate,
 } from "./templates.js";
+export {
+  analyzeCode,
+  runJsCases,
+  type CodeAnalysis,
+  type CodeCase,
+  type CodeEvalResult,
+} from "./code-eval.js";
 export {
   compileWorkflow,
   validateWorkflow,