@seanhogg/builderforce-memory 2026.6.20 → 2026.6.27

package/dist/limbic/LimbicSession.js

@@ -0,0 +1,188 @@
+/**
+ * LimbicSession.ts – high-level facade over the limbic affect model.
+ *
+ * Mirrors {@link MambaSession}: collapses GPU acquisition, model construction,
+ * checkpoint load, and the trainer into a single `LimbicSession.create()` call,
+ * with the same WebGPU-or-CPU-fallback contract. The agent runtime consumes
+ * this through `@seanhogg/builderforce-memory` to run the limbic system on a
+ * self-hosted node (GPU via @webgpu/node when present, CPU otherwise).
+ *
+ *   const limbic = await LimbicSession.create({ gpuAdapter, checkpointBuffer });
+ *   const { delta, reward } = await limbic.step(experienceEmbedding, state);
+ *   await limbic.train(samples, { epochs: 30 });
+ *   const bin = limbic.exportWeights({ fp16: true });
+ */
+import { LimbicModel, LimbicTrainer, LIMBIC_AFFECT_WGSL, createStorageBuffer, createEmptyStorageBuffer, createUniformBuffer, createComputePipeline, createBindGroup, dispatchKernel, readBuffer, } from "@seanhogg/builderforce-memory-engine";
+import { saveToIndexedDB, loadFromIndexedDB } from "../session/persistence.js";
+export class LimbicSession {
+    model;
+    trainer;
+    device;
+    gpuMode;
+    _name;
+    _idbFactory;
+    // GPU step pipeline + buffers, allocated lazily on first GPU step.
+    _pipeline = null;
+    _dimsBuf = null;
+    _paramBufs = null;
+    _paramsDirty = true;
+    constructor(model, trainer, device, gpuMode, name, idbFactory) {
+        this.model = model;
+        this.trainer = trainer;
+        this.device = device;
+        this.gpuMode = gpuMode;
+        this._name = name;
+        this._idbFactory = idbFactory;
+    }
+    static async create(options = {}) {
+        let device = null;
+        let gpuMode = "cpu";
+        if (options.gpuAdapter != null) {
+            try {
+                device = await options.gpuAdapter.requestDevice();
+                gpuMode = "webgpu";
+            }
+            catch {
+                device = null;
+                gpuMode = "cpu";
+            }
+        }
+        else if (typeof navigator !== "undefined" && navigator.gpu) {
+            try {
+                const adapter = await navigator.gpu.requestAdapter({ powerPreference: "high-performance" });
+                if (adapter) {
+                    device = await adapter.requestDevice();
+                    gpuMode = "webgpu";
+                }
+            }
+            catch {
+                device = null;
+            }
+            if (!device && options.allowCpuFallback && typeof navigator !== "undefined" && navigator.gpu) {
+                try {
+                    const fb = await navigator.gpu.requestAdapter({ forceFallbackAdapter: true });
+                    if (fb) {
+                        device = await fb.requestDevice();
+                        gpuMode = "cpu-fallback";
+                    }
+                }
+                catch {
+                    device = null;
+                }
+            }
+        }
+        const model = new LimbicModel({ ...options.modelConfig, seed: options.seed });
+        if (options.checkpointBuffer) {
+            model.loadWeights(options.checkpointBuffer);
+        }
+        const trainer = new LimbicTrainer(model, device);
+        return new LimbicSession(model, trainer, device, gpuMode, options.name ?? "limbic-default", options.idbFactory);
+    }
+    /** One affect step. Uses the GPU kernel when a device is available, else CPU. */
+    async step(input, state, hidden) {
+        const h = hidden ?? this.model.initHidden();
+        if (!this.device)
+            return this.model.forward(input, h, state);
+        return this._stepGpu(input, h, state);
+    }
+    _ensureGpuStep() {
+        const device = this.device;
+        if (!this._pipeline) {
+            this._pipeline = createComputePipeline(device, LIMBIC_AFFECT_WGSL, "affect_step");
+            const { inputDim, hiddenDim, stateDim } = this.model.config;
+            const dims = new ArrayBuffer(16);
+            new Uint32Array(dims).set([inputDim, hiddenDim, stateDim, 0]);
+            this._dimsBuf = createUniformBuffer(device, dims);
+        }
+        if (this._paramsDirty || !this._paramBufs) {
+            this._destroyParamBufs();
+            this._paramBufs = {
+                win: createStorageBuffer(device, this.model.win, false),
+                ws: createStorageBuffer(device, this.model.ws, false),
+                aLogit: createStorageBuffer(device, this.model.aLogit, false),
+                woutState: createStorageBuffer(device, this.model.woutState, false),
+                boutState: createStorageBuffer(device, this.model.boutState, false),
+            };
+            this._paramsDirty = false;
+        }
+        return { pipeline: this._pipeline, params: this._paramBufs, dims: this._dimsBuf };
+    }
+    async _stepGpu(input, hPrev, sPrev) {
+        const device = this.device;
+        const { inputDim, hiddenDim, stateDim } = this.model.config;
+        const { pipeline, params, dims } = this._ensureGpuStep();
+        const xBuf = createStorageBuffer(device, Float32Array.from({ length: inputDim }, (_, i) => input[i] ?? 0), false);
+        const hBuf = createStorageBuffer(device, Float32Array.from({ length: hiddenDim }, (_, j) => hPrev[j] ?? 0), false);
+        const sBuf = createStorageBuffer(device, Float32Array.from({ length: stateDim }, (_, k) => sPrev[k] ?? 0), false);
+        const hOut = createEmptyStorageBuffer(device, hiddenDim * 4, true);
+        const dOut = createEmptyStorageBuffer(device, stateDim * 4, true);
+        const bg = createBindGroup(device, pipeline, [
+            dims,
+            params.win,
+            params.ws,
+            params.aLogit,
+            params.woutState,
+            params.boutState,
+            xBuf,
+            hBuf,
+            sBuf,
+            hOut,
+            dOut,
+        ]);
+        dispatchKernel(device, pipeline, bg, [1, 1, 1]);
+        const hidden = (await readBuffer(device, hOut, hiddenDim * 4)).subarray(0, hiddenDim);
+        const delta = (await readBuffer(device, dOut, stateDim * 4)).subarray(0, stateDim);
+        // Reward head is small — compute on CPU from the GPU-produced hidden state.
+        let reward = this.model.boutReward[0];
+        for (let j = 0; j < hiddenDim; j++)
+            reward += this.model.woutReward[j] * hidden[j];
+        xBuf.destroy();
+        hBuf.destroy();
+        sBuf.destroy();
+        hOut.destroy();
+        dOut.destroy();
+        return { hidden: Float32Array.from(hidden), delta: Float32Array.from(delta), reward };
+    }
+    /** Train the affect model on observed experiences. Marks GPU step buffers dirty. */
+    async train(samples, opts) {
+        const losses = await this.trainer.train(samples, opts);
+        this._paramsDirty = true; // weights changed → GPU step buffers must be re-uploaded
+        return losses;
+    }
+    evaluate(samples) {
+        return this.trainer.evaluate(samples);
+    }
+    exportWeights(opts) {
+        return this.model.exportWeights(opts);
+    }
+    /** Persist weights to IndexedDB under the session name. */
+    async save() {
+        await saveToIndexedDB(`limbic_${this._name}`, this.model.exportWeights({ fp16: true }), this._idbFactory);
+    }
+    /** Load weights from IndexedDB; returns true if a checkpoint was found. */
+    async load() {
+        const buf = await loadFromIndexedDB(`limbic_${this._name}`, this._idbFactory);
+        if (!buf)
+            return false;
+        this.model.loadWeights(buf);
+        this._paramsDirty = true;
+        return true;
+    }
+    _destroyParamBufs() {
+        if (this._paramBufs) {
+            this._paramBufs.win.destroy();
+            this._paramBufs.ws.destroy();
+            this._paramBufs.aLogit.destroy();
+            this._paramBufs.woutState.destroy();
+            this._paramBufs.boutState.destroy();
+            this._paramBufs = null;
+        }
+    }
+    destroy() {
+        this._destroyParamBufs();
+        this._dimsBuf?.destroy();
+        this._dimsBuf = null;
+        this._pipeline = null;
+    }
+}
+//# sourceMappingURL=LimbicSession.js.map

package/dist/limbic/LimbicSession.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory",
-  "version": "2026.6.20",
+  "version": "2026.6.27",
   "description": "BuilderForce Agent Memory — runtime layer. SSM execution, Transformer orchestration, online distillation, and persistent agent memory for BuilderForce.ai agents.",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -49,7 +49,7 @@
   },
   "homepage": "https://github.com/SeanHogg/builderforce-memory/tree/main/packages/memory#readme",
   "peerDependencies": {
-    "@seanhogg/builderforce-memory-engine": "^2026.6.20"
+    "@seanhogg/builderforce-memory-engine": "^2026.6.27"
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
@@ -62,7 +62,7 @@
     "jest": "^29.7.0",
     "ts-jest": "^29.2.0",
     "typescript": "^5.0.0",
-    "@seanhogg/builderforce-memory-engine": "2026.6.20"
+    "@seanhogg/builderforce-memory-engine": "2026.6.27"
   },
   "jest": {
     "preset": "ts-jest/presets/default-esm",

package/src/cognition/EvermindCognition.ts

@@ -0,0 +1,156 @@
+/**
+ * Evermind — Write-Through Cognition engine.
+ *
+ * `commit()` is the model-knowledge analogue of a write-through cache write with
+ * a conflict resolver: Canonicalize (stable subject key) → Recall incumbent →
+ * Evaluate evidence → Reconcile (augment | confirm | supersede | reject) →
+ * write-through. `recall()` is the read side, served through a version-token
+ * cache that invalidates for free whenever knowledge changes.
+ *
+ * This is the layer the append-only knowledge loop skipped: it derives a STABLE
+ * subject key (not a per-run id) and replaces-on-write, so beliefs never drift
+ * into a manual reconciliation step.
+ */
+
+import type {
+    Claim,
+    CognitionFactStore,
+    CommitResult,
+    EvidenceGatherer,
+    EvidenceResult,
+    Verdict,
+} from './types.js';
+
+export interface EvermindCognitionOptions {
+    store: CognitionFactStore;
+    /** Default evidence gatherer used when `commit()` is not given one. */
+    gather?: EvidenceGatherer;
+    /**
+     * Optional embedding-capable runtime (e.g. SSMRuntime) forwarded to the
+     * store's `recallSimilar` so recall sharpens as the model adapts.
+     */
+    runtime?: unknown;
+}
+
+/** Subset of a store that can rank facts by semantic similarity. */
+interface SimilarityCapableStore {
+    recallSimilar(query: string, topK: number, runtime?: unknown): Promise<Array<{ content: string }>>;
+}
+
+function hasRecallSimilar(store: unknown): store is SimilarityCapableStore {
+    return typeof (store as SimilarityCapableStore).recallSimilar === 'function';
+}
+
+export class EvermindCognition {
+    private readonly _store: CognitionFactStore;
+    private readonly _defaultGather?: EvidenceGatherer;
+    private readonly _runtime?: unknown;
+
+    /**
+     * Knowledge-generation token. Bumped on every change to the fact set
+     * (augment / supersede). Doubles as the recall-cache namespace so a write
+     * invalidates cached reads for free — the "invalidate on write" rule applied
+     * to model knowledge.
+     */
+    private _version = 0;
+
+    /**
+     * L1 recall cache, namespaced by `_version`. After any knowledge change the
+     * version moves, so prior-generation entries are never read again (and are
+     * cleared to bound growth) — not an ad-hoc TTL map; a version-token cache.
+     */
+    private readonly _recallCache = new Map<string, string[]>();
+
+    constructor(opts: EvermindCognitionOptions) {
+        this._store = opts.store;
+        this._defaultGather = opts.gather;
+        this._runtime = opts.runtime;
+    }
+
+    /** Current knowledge-generation token. */
+    get version(): number {
+        return this._version;
+    }
+
+    /**
+     * Commit a candidate fact write-through. Evidence decides conflicts; a
+     * supersede replaces the incumbent under the same stable key and invalidates
+     * recall. Never appends a competing belief for the same subject.
+     */
+    async commit(claim: Claim, gather: EvidenceGatherer | undefined = this._defaultGather): Promise<CommitResult> {
+        const incumbent = await this._store.recall(claim.subjectKey);
+        const audit: string[] = [];
+
+        // ── Brand-new subject ────────────────────────────────────────────────
+        if (!incumbent) {
+            if (gather && claim.requireEvidence) {
+                const e = await gather({ claim });
+                audit.push(...e.notes);
+                if (!e.supportsNew) {
+                    return this._result('reject', claim.subjectKey, claim.content, undefined, audit);
+                }
+            }
+            await this._write(claim, claim.importance ?? 0.6);
+            this._bumpVersion();
+            return this._result('augment', claim.subjectKey, claim.content, undefined, audit);
+        }
+
+        // ── Identical incumbent — confirm (refresh confidence, no replace) ────
+        if (incumbent.content === claim.content) {
+            await this._write(claim, Math.min(1, (claim.importance ?? 0.6) + 0.1));
+            return this._result('confirm', claim.subjectKey, claim.content, undefined, audit);
+        }
+
+        // ── Conflict — evidence decides ──────────────────────────────────────
+        const e: EvidenceResult = gather
+            ? await gather({ claim, incumbent: incumbent.content })
+            : { supportsNew: true, notes: ['no evidence gatherer supplied; trusting newer observation'] };
+        audit.push(...e.notes);
+
+        if (e.supportsNew) {
+            await this._write(claim, Math.max(claim.importance ?? 0.6, 0.9));
+            this._bumpVersion();
+            return this._result('supersede', claim.subjectKey, claim.content, incumbent.content, audit);
+        }
+        return this._result('reject', claim.subjectKey, incumbent.content, undefined, audit);
+    }
+
+    /**
+     * Write-through recall: the top-K most relevant facts for `query`, served
+     * from a version-namespaced cache that invalidates on the next knowledge
+     * change. Falls back to an empty set when the store can't rank similarity.
+     */
+    async recall(query: string, topK = 5): Promise<string[]> {
+        const cacheKey = `${this._version}:${topK}:${query}`;
+        const cached = this._recallCache.get(cacheKey);
+        if (cached) return cached;
+
+        const facts = hasRecallSimilar(this._store)
+            ? (await this._store.recallSimilar(query, topK, this._runtime)).map((e) => e.content)
+            : [];
+
+        this._recallCache.set(cacheKey, facts);
+        return facts;
+    }
+
+    // ── internals ────────────────────────────────────────────────────────────
+
+    private async _write(claim: Claim, importance: number): Promise<void> {
+        await this._store.remember(claim.subjectKey, claim.content, { tags: claim.tags, importance });
+    }
+
+    private _bumpVersion(): void {
+        this._version++;
+        this._recallCache.clear();
+    }
+
+    private _result(
+        verdict: Verdict,
+        subjectKey: string,
+        content: string,
+        superseded: string | undefined,
+        evidence: string[],
+    ): CommitResult {
+        return { verdict, subjectKey, content, superseded, evidence, version: this._version };
+    }
+}

package/src/cognition/gatherers.ts

@@ -0,0 +1,40 @@
+/**
+ * Evermind — reusable evidence gatherers.
+ *
+ * Concrete, surface-agnostic evidence rules. The presence rule is the one the
+ * IDE self-correction loop uses (ground a claim by listing the workspace), kept
+ * here so the IDE, the proof harness, and tests share one implementation.
+ */
+
+import type { EvidenceGatherer } from './types.js';
+
+export interface WorkspacePresenceRule {
+    /** Lists the workspace (e.g. the IDE `list_files('.')` control tool). */
+    list: () => Promise<string[]>;
+    /** Entries that MUST be present for the new claim to hold. */
+    mustExist?: string[];
+    /** Entries that MUST be absent for the new claim to hold. */
+    mustBeAbsent?: string[];
+}
+
+/**
+ * Evidence rule: the new claim is supported iff every `mustExist` entry is
+ * present and every `mustBeAbsent` entry is gone from the listing.
+ */
+export function workspacePresenceGatherer(rule: WorkspacePresenceRule): EvidenceGatherer {
+    const mustExist = rule.mustExist ?? [];
+    const mustBeAbsent = rule.mustBeAbsent ?? [];
+    return async () => {
+        const listing = await rule.list();
+        const present = mustExist.filter((d) => listing.includes(d));
+        const absent = mustBeAbsent.filter((d) => !listing.includes(d));
+        const supportsNew = present.length === mustExist.length && absent.length === mustBeAbsent.length;
+        return {
+            supportsNew,
+            notes: [
+                `present: ${present.join(', ') || '—'}`,
+                `absent (as expected): ${absent.join(', ') || '—'}`,
+            ],
+        };
+    };
+}

package/src/cognition/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Evermind — Write-Through Cognition.
+ *
+ * The layer that keeps model knowledge current without a reconciliation step:
+ * stable-subject-key beliefs, evidence-gated conflict resolution, replace-on-write.
+ */
+
+export { EvermindCognition } from './EvermindCognition.js';
+export type { EvermindCognitionOptions } from './EvermindCognition.js';
+export { workspacePresenceGatherer } from './gatherers.js';
+export type { WorkspacePresenceRule } from './gatherers.js';
+export type {
+    Claim,
+    CognitionFactStore,
+    CommitResult,
+    EvidenceContext,
+    EvidenceGatherer,
+    EvidenceResult,
+    Verdict,
+} from './types.js';

package/src/cognition/types.ts

@@ -0,0 +1,88 @@
+/**
+ * Evermind — Write-Through Cognition types.
+ *
+ * The cognition layer is what lets the model's KNOWLEDGE stay current without a
+ * reconciliation step: every incoming fact is evaluated against EVIDENCE and the
+ * incumbent belief, then committed write-through (replace-on-write by a STABLE
+ * subject key) instead of being appended under a fresh per-run key. These types
+ * are intentionally store- and surface-agnostic so the same logic runs in the
+ * IDE, on-prem, cloud, and the browser.
+ */
+
+/** Outcome of evaluating a candidate fact against its incumbent + evidence. */
+export type Verdict =
+    /** No incumbent on this subject — stored as a new belief. */
+    | 'augment'
+    /** Incumbent identical — recency/confidence refreshed, nothing replaced. */
+    | 'confirm'
+    /** Incumbent conflicted and evidence favoured the new fact — replaced. */
+    | 'supersede'
+    /** Incumbent conflicted but evidence did NOT favour the new fact — dropped. */
+    | 'reject';
+
+/**
+ * Minimal write-through fact store the cognition layer needs. `MemoryStore`
+ * satisfies this structurally (no adapter required) — kept narrow so cloud
+ * (Postgres) / browser (IndexedDB) backends can satisfy it too.
+ */
+export interface CognitionFactStore {
+    remember(
+        key: string,
+        content: string,
+        opts?: { tags?: string[]; importance?: number; ttlMs?: number },
+    ): Promise<void>;
+    recall(key: string): Promise<{ content: string } | undefined>;
+    forget(key: string): Promise<void>;
+}
+
+/** A fact asserted about a subject, keyed by a STABLE canonical key. */
+export interface Claim {
+    /**
+     * STABLE canonical key naming the SUBJECT of the fact (e.g. `pkg:ssm-stack`).
+     * This is the anti-drift fix: logically-superseding facts collide on this key
+     * and replace, instead of accumulating under per-run keys.
+     */
+    subjectKey: string;
+    /** The asserted fact content. */
+    content: string;
+    tags?: string[];
+    importance?: number;
+    /**
+     * When true, a brand-new subject is only stored if the gatherer's evidence
+     * supports it (guards against recording unverified first-observations).
+     */
+    requireEvidence?: boolean;
+}
+
+/** The verdict of an evidence probe: does ground truth favour the new claim? */
+export interface EvidenceResult {
+    supportsNew: boolean;
+    /** Audit-readable lines describing what was checked and found. */
+    notes: string[];
+}
+
+export interface EvidenceContext {
+    claim: Claim;
+    /** Incumbent belief content for this subject, when one exists. */
+    incumbent?: string;
+}
+
+/**
+ * Gathers ground-truth evidence for a claim. Injected by the caller because the
+ * evidence source is surface-specific (IDE file tools, cloud DB, HTTP probe…).
+ */
+export type EvidenceGatherer = (ctx: EvidenceContext) => Promise<EvidenceResult>;
+
+/** Result of committing a claim through the cognition pipeline. */
+export interface CommitResult {
+    verdict: Verdict;
+    subjectKey: string;
+    /** The belief now held for this subject (incumbent's content on reject). */
+    content: string;
+    /** Prior content, present only when `verdict === 'supersede'`. */
+    superseded?: string;
+    /** Evidence audit trail. */
+    evidence: string[];
+    /** Knowledge-generation token after this commit (bumps on augment/supersede). */
+    version: number;
+}

package/src/index.ts

@@ -40,6 +40,34 @@ export type {
     Tokenizer,
 } from './session/index.js';
 
+// ── Limbic system (trainable affective dynamics) ──────────────────────────────
+export { LimbicSession } from './limbic/LimbicSession.js';
+export type { LimbicSessionOptions, LimbicGpuMode } from './limbic/LimbicSession.js';
+// Re-export the limbic engine primitives so consumers can use the model/trainer
+// and the region schema directly from @seanhogg/builderforce-memory.
+export {
+    LimbicModel,
+    LimbicTrainer,
+    LIMBIC_DIM,
+    LIMBIC_DIM_NAMES,
+    LIMBIC_STATE_DIM,
+    LIMBIC_BOUNDS,
+    NEUTRAL_STATE,
+    REGION,
+    clampState,
+    neutralState,
+    stateToRecord,
+    recordToState,
+} from '@seanhogg/builderforce-memory-engine';
+export type {
+    LimbicModelConfig,
+    LimbicForward,
+    LimbicSample,
+    LimbicTrainOptions,
+    LimbicDimName,
+    Region,
+} from '@seanhogg/builderforce-memory-engine';
+
 // ── Runtime ───────────────────────────────────────────────────────────────────
 export { SSMRuntime }    from './runtime/SSMRuntime.js';
 export type { SSMRuntimeOptions, GenerateOptions } from './runtime/SSMRuntime.js';
@@ -92,6 +120,20 @@ export type {
     FactType,
 } from './memory/MemoryStore.js';
 
+// ── Cognition (Evermind — Write-Through Cognition) ────────────────────────────
+export { EvermindCognition, workspacePresenceGatherer } from './cognition/index.js';
+export type {
+    EvermindCognitionOptions,
+    WorkspacePresenceRule,
+    Claim,
+    CognitionFactStore,
+    CommitResult,
+    EvidenceContext,
+    EvidenceGatherer,
+    EvidenceResult,
+    Verdict,
+} from './cognition/index.js';
+
 // ── Distillation ──────────────────────────────────────────────────────────────
 export { DistillationEngine } from './distillation/DistillationEngine.js';
 export type {