@seanhogg/builderforce-memory-engine 2026.6.19 → 2026.6.27

package/dist/limbic/limbic_trainer.d.ts

@@ -0,0 +1,62 @@
+/**
+ * limbic_trainer.ts – LimbicTrainer: gradient-based training for the LimbicModel.
+ *
+ * Trains the affect head to predict affect deltas and reward from
+ * (experience embedding, current state) pairs, using full-batch gradient
+ * descent with AdamW. When a GPUDevice is supplied the optimiser step runs on
+ * the GPU via the shared WEIGHT_UPDATE_WGSL kernel (real WebGPU training); with
+ * no device it uses a numerically-equivalent CPU AdamW so training works
+ * everywhere (CI, Node without @webgpu/node, etc.).
+ *
+ * The objective is MSE (regression), not the cross-entropy used by the
+ * language-model {@link MambaTrainer} — a limbic experience has continuous
+ * targets, not a next-token distribution.
+ */
+import type { LimbicModel } from "./limbic_model.js";
+/** One training example: an experience and the affect change it should produce. */
+export interface LimbicSample {
+    /** Experience embedding (length = model.inputDim). */
+    input: ArrayLike<number>;
+    /** Affective state at the time of the experience (length = model.stateDim). */
+    state: ArrayLike<number>;
+    /** Observed affect delta target in (-1, 1) per state dim (length = model.stateDim). */
+    deltaTarget: ArrayLike<number>;
+    /** Observed scalar reward for the experience. */
+    reward: number;
+}
+export interface LimbicTrainOptions {
+    learningRate?: number;
+    epochs?: number;
+    weightDecay?: number;
+    beta1?: number;
+    beta2?: number;
+    eps?: number;
+    /** Max global gradient L2 norm before the optimiser step. Default 1.0. */
+    maxGradNorm?: number;
+    onEpochEnd?: ((epoch: number, loss: number) => void) | null;
+}
+export declare class LimbicTrainer {
+    readonly model: LimbicModel;
+    readonly device: GPUDevice | null;
+    private _moments;
+    private _step;
+    private readonly _adamwPipeline;
+    constructor(model: LimbicModel, device?: GPUDevice | null);
+    /** Whether the optimiser step runs on the GPU. */
+    get gpuTraining(): boolean;
+    private _initMoments;
+    /**
+     * Train on a batch of samples for `epochs` passes. Returns the per-epoch mean
+     * loss (monotonically decreasing on a learnable mapping). Full-batch: grads
+     * accumulate across the whole sequence (recurrent hidden carried, reset per
+     * epoch), are averaged, clipped, then applied once per epoch.
+     */
+    train(samples: LimbicSample[], opts?: LimbicTrainOptions): Promise<number[]>;
+    /** Mean MSE loss over samples (no weight update). Hidden resets per sample. */
+    evaluate(samples: LimbicSample[]): number;
+    private _clipGradients;
+    private _adamwStepCpu;
+    /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
+    private _adamwStepGpu;
+}
+//# sourceMappingURL=limbic_trainer.d.ts.map

package/dist/limbic/limbic_trainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limbic_trainer.d.ts","sourceRoot":"","sources":["../../src/limbic/limbic_trainer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAYH,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,mBAAmB,CAAC;AAElE,mFAAmF;AACnF,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzB,+EAA+E;IAC/E,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IACzB,uFAAuF;IACvF,WAAW,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;IAC/B,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CAC7D;AAuBD,qBAAa,aAAa;IACxB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4B;gBAE/C,KAAK,EAAE,WAAW,EAAE,MAAM,GAAE,SAAS,GAAG,IAAW;IAQ/D,kDAAkD;IAClD,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,OAAO,CAAC,YAAY;IAQpB;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA6DtF,+EAA+E;IAC/E,QAAQ,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,MAAM;IAkBzC,OAAO,CAAC,cAAc;IAUtB,OAAO,CAAC,aAAa;IAqBrB,mFAAmF;YACrE,aAAa;CAkC5B"}

package/dist/limbic/limbic_trainer.js

@@ -0,0 +1,172 @@
+/**
+ * limbic_trainer.ts – LimbicTrainer: gradient-based training for the LimbicModel.
+ *
+ * Trains the affect head to predict affect deltas and reward from
+ * (experience embedding, current state) pairs, using full-batch gradient
+ * descent with AdamW. When a GPUDevice is supplied the optimiser step runs on
+ * the GPU via the shared WEIGHT_UPDATE_WGSL kernel (real WebGPU training); with
+ * no device it uses a numerically-equivalent CPU AdamW so training works
+ * everywhere (CI, Node without @webgpu/node, etc.).
+ *
+ * The objective is MSE (regression), not the cross-entropy used by the
+ * language-model {@link MambaTrainer} — a limbic experience has continuous
+ * targets, not a next-token distribution.
+ */
+import { createUniformBuffer, createStorageBuffer, createComputePipeline, createBindGroup, dispatchKernel, readBuffer, cdiv, } from "../utils/gpu_utils.js";
+import { WEIGHT_UPDATE_WGSL } from "../kernels/weight_update.js";
+function packAdamParams(numElements, lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t) {
+    const buf = new ArrayBuffer(32);
+    new Uint32Array(buf, 0, 1).set([numElements]);
+    new Float32Array(buf, 4, 7).set([lr, beta1, beta2, eps, weightDecay, beta1_t, beta2_t]);
+    return buf;
+}
+export class LimbicTrainer {
+    model;
+    device;
+    _moments = null;
+    _step = 0;
+    _adamwPipeline;
+    constructor(model, device = null) {
+        this.model = model;
+        this.device = device;
+        this._adamwPipeline = device
+            ? createComputePipeline(device, WEIGHT_UPDATE_WGSL, "adamw_update")
+            : null;
+    }
+    /** Whether the optimiser step runs on the GPU. */
+    get gpuTraining() {
+        return this.device != null && this._adamwPipeline != null;
+    }
+    _initMoments() {
+        if (this._moments)
+            return;
+        this._moments = this.model.parameters().map((p) => ({
+            m: new Float32Array(p.numel),
+            v: new Float32Array(p.numel),
+        }));
+    }
+    /**
+     * Train on a batch of samples for `epochs` passes. Returns the per-epoch mean
+     * loss (monotonically decreasing on a learnable mapping). Full-batch: grads
+     * accumulate across the whole sequence (recurrent hidden carried, reset per
+     * epoch), are averaged, clipped, then applied once per epoch.
+     */
+    async train(samples, opts = {}) {
+        if (samples.length === 0)
+            throw new Error("LimbicTrainer.train: no samples");
+        const { learningRate = 0.05, epochs = 50, weightDecay = 0.0, beta1 = 0.9, beta2 = 0.999, eps = 1e-8, maxGradNorm = 1.0, onEpochEnd = null, } = opts;
+        this._initMoments();
+        const losses = [];
+        for (let epoch = 0; epoch < epochs; epoch++) {
+            this.model.zeroGrad();
+            let epochLoss = 0;
+            // Each sample is one experience appraisal: cross-experience memory flows
+            // through the affective state `s` (fed back by the runtime), not through
+            // the hidden scratch `h`, so the hidden state resets per sample. This also
+            // makes BPTT(1) exact — there is no truncated carry.
+            for (const s of samples) {
+                const { loss } = this.model.backwardStep(s.input, this.model.initHidden(), s.state, s.deltaTarget, s.reward);
+                epochLoss += loss;
+            }
+            // Average gradients over the batch.
+            const grads = this.model.gradients();
+            const invN = 1 / samples.length;
+            for (const g of grads) {
+                for (let i = 0; i < g.data.length; i++)
+                    g.data[i] *= invN;
+            }
+            this._clipGradients(grads, maxGradNorm);
+            this._step++;
+            const beta1_t = Math.pow(beta1, this._step);
+            const beta2_t = Math.pow(beta2, this._step);
+            const hp = { learningRate, weightDecay, beta1, beta2, eps, beta1_t, beta2_t };
+            if (this.gpuTraining) {
+                await this._adamwStepGpu(grads, hp);
+            }
+            else {
+                this._adamwStepCpu(grads, hp);
+            }
+            const avg = epochLoss / samples.length;
+            losses.push(avg);
+            if (onEpochEnd)
+                onEpochEnd(epoch + 1, avg);
+        }
+        return losses;
+    }
+    /** Mean MSE loss over samples (no weight update). Hidden resets per sample. */
+    evaluate(samples) {
+        if (samples.length === 0)
+            return 0;
+        let total = 0;
+        const { rewardWeight } = this.model.config;
+        for (const s of samples) {
+            const f = this.model.forward(s.input, this.model.initHidden(), s.state);
+            let loss = 0;
+            for (let k = 0; k < f.delta.length; k++) {
+                const d = f.delta[k] - (s.deltaTarget[k] ?? 0);
+                loss += 0.5 * d * d;
+            }
+            const rd = f.reward - s.reward;
+            loss += 0.5 * rewardWeight * rd * rd;
+            total += loss;
+        }
+        return total / samples.length;
+    }
+    _clipGradients(grads, maxNorm) {
+        let normSq = 0;
+        for (const g of grads)
+            for (let i = 0; i < g.data.length; i++)
+                normSq += g.data[i] * g.data[i];
+        const norm = Math.sqrt(normSq);
+        if (norm > maxNorm && norm > 0) {
+            const scale = maxNorm / norm;
+            for (const g of grads)
+                for (let i = 0; i < g.data.length; i++)
+                    g.data[i] *= scale;
+        }
+    }
+    _adamwStepCpu(grads, hp) {
+        const params = this.model.parameters();
+        const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
+        for (let pi = 0; pi < params.length; pi++) {
+            const p = params[pi].data;
+            const g = grads[pi].data;
+            const mom = this._moments[pi];
+            for (let i = 0; i < p.length; i++) {
+                const gi = g[i];
+                mom.m[i] = beta1 * mom.m[i] + (1 - beta1) * gi;
+                mom.v[i] = beta2 * mom.v[i] + (1 - beta2) * gi * gi;
+                const mHat = mom.m[i] / (1 - beta1_t);
+                const vHat = mom.v[i] / (1 - beta2_t);
+                p[i] = p[i] * (1 - lr * wd) - (lr * mHat) / (Math.sqrt(vHat) + eps);
+            }
+        }
+    }
+    /** AdamW on the GPU via the shared WEIGHT_UPDATE_WGSL kernel. Awaited per step. */
+    async _adamwStepGpu(grads, hp) {
+        const device = this.device;
+        const pipeline = this._adamwPipeline;
+        const params = this.model.parameters();
+        const { learningRate: lr, weightDecay: wd, beta1, beta2, eps, beta1_t, beta2_t } = hp;
+        for (let pi = 0; pi < params.length; pi++) {
+            const p = params[pi];
+            const mom = this._moments[pi];
+            const paramBuf = createStorageBuffer(device, p.data, true);
+            const gradBuf = createStorageBuffer(device, grads[pi].data, false);
+            const mBuf = createStorageBuffer(device, mom.m, true);
+            const vBuf = createStorageBuffer(device, mom.v, true);
+            const uni = createUniformBuffer(device, packAdamParams(p.numel, lr, beta1, beta2, eps, wd, beta1_t, beta2_t));
+            const bg = createBindGroup(device, pipeline, [uni, paramBuf, gradBuf, mBuf, vBuf]);
+            dispatchKernel(device, pipeline, bg, [cdiv(p.numel, 256), 1, 1]);
+            p.data.set((await readBuffer(device, paramBuf, p.numel * 4)).subarray(0, p.numel));
+            mom.m.set((await readBuffer(device, mBuf, p.numel * 4)).subarray(0, p.numel));
+            mom.v.set((await readBuffer(device, vBuf, p.numel * 4)).subarray(0, p.numel));
+            paramBuf.destroy();
+            gradBuf.destroy();
+            mBuf.destroy();
+            vBuf.destroy();
+            uni.destroy();
+        }
+    }
+}
+//# sourceMappingURL=limbic_trainer.js.map

package/dist/limbic/limbic_trainer.js.map

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

package/dist/limbic/regions.d.ts

@@ -0,0 +1,79 @@
+/**
+ * regions.ts – Limbic-system region map and affective state schema.
+ *
+ * The limbic model is the *dynamic* affective/motivational layer that rides on
+ * top of the (static) psychometric personality. Where the hippocampus
+ * (HybridMambaModel + MemoryStore) holds *what the agent knows*, the limbic
+ * model holds *how the agent currently feels and what it is driven toward* —
+ * and learns the dynamics of that, in WebGPU, from experience.
+ *
+ * This file is the single source of truth for the affective state vector that
+ * every other limbic module (model, trainer, runtime service) indexes into.
+ * Keep the dimension ids in sync with the runtime compiler in
+ * `agent-runtime/src/builderforce/limbic.ts` — the two are coupled solely by
+ * these string ids and the {@link LIMBIC_DIM} indices.
+ *
+ * Region → state mapping (mirrors the labelled diagram):
+ *   • Amygdala      → salience / threat appraisal → drives valence + arousal
+ *   • Hypothalamus  → homeostatic drives (curiosity, caution, effort, social)
+ *   • Thalamus      → attention gate (how much incoming signal is admitted)
+ *   • Basal ganglia → action selection bias (explore vs. exploit)
+ *   • Hippocampus   → reused (existing SSM memory); feeds the experience input
+ */
+/** The five modelled limbic regions. Hippocampus is reused, not re-modelled. */
+export declare const REGION: {
+    readonly amygdala: "amygdala";
+    readonly hypothalamus: "hypothalamus";
+    readonly thalamus: "thalamus";
+    readonly basalGanglia: "basal_ganglia";
+    readonly hippocampus: "hippocampus";
+};
+export type Region = (typeof REGION)[keyof typeof REGION];
+/**
+ * Canonical indices into the affective state vector. The vector is a dense
+ * Float32Array of length {@link LIMBIC_STATE_DIM}. Core affect (valence,
+ * arousal) is the 2D summary; the remaining dims are the per-region drives the
+ * agent's behaviour is modulated by.
+ */
+export declare const LIMBIC_DIM: {
+    /** Core affect — pleasantness. Range [-1, +1] (negative .. positive). */
+    readonly valence: 0;
+    /** Core affect — activation. Range [0, 1] (calm .. activated). */
+    readonly arousal: 1;
+    /** Hypothalamus drive — appetite for novelty/exploration. Range [0, 1]. */
+    readonly driveCuriosity: 2;
+    /** Hypothalamus drive — appetite for safety/guardrails. Range [0, 1]. */
+    readonly driveCaution: 3;
+    /** Hypothalamus drive — available energy. Range [0, 1] (fatigued .. fresh). */
+    readonly driveEffort: 4;
+    /** Hypothalamus drive — appetite for communication/collaboration. Range [0, 1]. */
+    readonly driveSocial: 5;
+    /** Thalamus — attention gain on incoming signal. Range [0, 1]. */
+    readonly attention: 6;
+    /** Basal ganglia — explore(1) vs. exploit(0) action-selection bias. Range [0, 1]. */
+    readonly exploration: 7;
+};
+export type LimbicDimName = keyof typeof LIMBIC_DIM;
+/** Length of the affective state vector. */
+export declare const LIMBIC_STATE_DIM = 8;
+/** Ordered dim names, index-aligned with {@link LIMBIC_DIM}. */
+export declare const LIMBIC_DIM_NAMES: LimbicDimName[];
+/** Inclusive [min, max] bounds per state dim, index-aligned. Valence is signed. */
+export declare const LIMBIC_BOUNDS: ReadonlyArray<readonly [number, number]>;
+/**
+ * Neutral resting state — the default homeostatic setpoint before personality
+ * pulls it anywhere. Calm, mildly positive, balanced drives, full attention,
+ * slightly exploit-biased.
+ */
+export declare const NEUTRAL_STATE: ReadonlyArray<number>;
+/** Clamp a single state dim to its bounds. */
+export declare function clampDim(index: number, value: number): number;
+/** Clamp a whole state vector in place and return it. */
+export declare function clampState(state: Float32Array): Float32Array;
+/** A fresh neutral state vector. */
+export declare function neutralState(): Float32Array;
+/** Build a labelled record from a dense state vector (for logging / transport). */
+export declare function stateToRecord(state: ArrayLike<number>): Record<LimbicDimName, number>;
+/** Build a dense state vector from a (possibly partial) labelled record. */
+export declare function recordToState(rec: Partial<Record<LimbicDimName, number>>): Float32Array;
+//# sourceMappingURL=regions.d.ts.map

package/dist/limbic/regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"regions.d.ts","sourceRoot":"","sources":["../../src/limbic/regions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,gFAAgF;AAChF,eAAO,MAAM,MAAM;;;;;;CAMT,CAAC;AACX,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,MAAM,CAAC,CAAC,MAAM,OAAO,MAAM,CAAC,CAAC;AAE1D;;;;;GAKG;AACH,eAAO,MAAM,UAAU;IACrB,yEAAyE;;IAEzE,kEAAkE;;IAElE,2EAA2E;;IAE3E,yEAAyE;;IAEzE,+EAA+E;;IAE/E,mFAAmF;;IAEnF,kEAAkE;;IAElE,qFAAqF;;CAE7E,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,UAAU,CAAC;AAEpD,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,gEAAgE;AAChE,eAAO,MAAM,gBAAgB,EAAE,aAAa,EAS3C,CAAC;AAEF,mFAAmF;AACnF,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CASlE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,aAAa,EAAE,aAAa,CAAC,MAAM,CAS/C,CAAC;AAEF,8CAA8C;AAC9C,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAK7D;AAED,yDAAyD;AACzD,wBAAgB,UAAU,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAK5D;AAED,oCAAoC;AACpC,wBAAgB,YAAY,IAAI,YAAY,CAE3C;AAED,mFAAmF;AACnF,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAMrF;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC,GAAG,YAAY,CAOvF"}

package/dist/limbic/regions.js

@@ -0,0 +1,132 @@
+/**
+ * regions.ts – Limbic-system region map and affective state schema.
+ *
+ * The limbic model is the *dynamic* affective/motivational layer that rides on
+ * top of the (static) psychometric personality. Where the hippocampus
+ * (HybridMambaModel + MemoryStore) holds *what the agent knows*, the limbic
+ * model holds *how the agent currently feels and what it is driven toward* —
+ * and learns the dynamics of that, in WebGPU, from experience.
+ *
+ * This file is the single source of truth for the affective state vector that
+ * every other limbic module (model, trainer, runtime service) indexes into.
+ * Keep the dimension ids in sync with the runtime compiler in
+ * `agent-runtime/src/builderforce/limbic.ts` — the two are coupled solely by
+ * these string ids and the {@link LIMBIC_DIM} indices.
+ *
+ * Region → state mapping (mirrors the labelled diagram):
+ *   • Amygdala      → salience / threat appraisal → drives valence + arousal
+ *   • Hypothalamus  → homeostatic drives (curiosity, caution, effort, social)
+ *   • Thalamus      → attention gate (how much incoming signal is admitted)
+ *   • Basal ganglia → action selection bias (explore vs. exploit)
+ *   • Hippocampus   → reused (existing SSM memory); feeds the experience input
+ */
+/** The five modelled limbic regions. Hippocampus is reused, not re-modelled. */
+export const REGION = {
+    amygdala: "amygdala",
+    hypothalamus: "hypothalamus",
+    thalamus: "thalamus",
+    basalGanglia: "basal_ganglia",
+    hippocampus: "hippocampus",
+};
+/**
+ * Canonical indices into the affective state vector. The vector is a dense
+ * Float32Array of length {@link LIMBIC_STATE_DIM}. Core affect (valence,
+ * arousal) is the 2D summary; the remaining dims are the per-region drives the
+ * agent's behaviour is modulated by.
+ */
+export const LIMBIC_DIM = {
+    /** Core affect — pleasantness. Range [-1, +1] (negative .. positive). */
+    valence: 0,
+    /** Core affect — activation. Range [0, 1] (calm .. activated). */
+    arousal: 1,
+    /** Hypothalamus drive — appetite for novelty/exploration. Range [0, 1]. */
+    driveCuriosity: 2,
+    /** Hypothalamus drive — appetite for safety/guardrails. Range [0, 1]. */
+    driveCaution: 3,
+    /** Hypothalamus drive — available energy. Range [0, 1] (fatigued .. fresh). */
+    driveEffort: 4,
+    /** Hypothalamus drive — appetite for communication/collaboration. Range [0, 1]. */
+    driveSocial: 5,
+    /** Thalamus — attention gain on incoming signal. Range [0, 1]. */
+    attention: 6,
+    /** Basal ganglia — explore(1) vs. exploit(0) action-selection bias. Range [0, 1]. */
+    exploration: 7,
+};
+/** Length of the affective state vector. */
+export const LIMBIC_STATE_DIM = 8;
+/** Ordered dim names, index-aligned with {@link LIMBIC_DIM}. */
+export const LIMBIC_DIM_NAMES = [
+    "valence",
+    "arousal",
+    "driveCuriosity",
+    "driveCaution",
+    "driveEffort",
+    "driveSocial",
+    "attention",
+    "exploration",
+];
+/** Inclusive [min, max] bounds per state dim, index-aligned. Valence is signed. */
+export const LIMBIC_BOUNDS = [
+    [-1, 1], // valence
+    [0, 1], // arousal
+    [0, 1], // driveCuriosity
+    [0, 1], // driveCaution
+    [0, 1], // driveEffort
+    [0, 1], // driveSocial
+    [0, 1], // attention
+    [0, 1], // exploration
+];
+/**
+ * Neutral resting state — the default homeostatic setpoint before personality
+ * pulls it anywhere. Calm, mildly positive, balanced drives, full attention,
+ * slightly exploit-biased.
+ */
+export const NEUTRAL_STATE = [
+    0.0, // valence
+    0.2, // arousal
+    0.5, // driveCuriosity
+    0.5, // driveCaution
+    0.8, // driveEffort
+    0.5, // driveSocial
+    0.7, // attention
+    0.5, // exploration (centred → resting state is behaviourally inert)
+];
+/** Clamp a single state dim to its bounds. */
+export function clampDim(index, value) {
+    const b = LIMBIC_BOUNDS[index];
+    if (!b)
+        return value;
+    if (Number.isNaN(value))
+        return b[0];
+    return Math.max(b[0], Math.min(b[1], value));
+}
+/** Clamp a whole state vector in place and return it. */
+export function clampState(state) {
+    for (let i = 0; i < state.length && i < LIMBIC_STATE_DIM; i++) {
+        state[i] = clampDim(i, state[i]);
+    }
+    return state;
+}
+/** A fresh neutral state vector. */
+export function neutralState() {
+    return Float32Array.from(NEUTRAL_STATE);
+}
+/** Build a labelled record from a dense state vector (for logging / transport). */
+export function stateToRecord(state) {
+    const out = {};
+    for (let i = 0; i < LIMBIC_DIM_NAMES.length; i++) {
+        out[LIMBIC_DIM_NAMES[i]] = state[i] ?? 0;
+    }
+    return out;
+}
+/** Build a dense state vector from a (possibly partial) labelled record. */
+export function recordToState(rec) {
+    const s = neutralState();
+    for (let i = 0; i < LIMBIC_DIM_NAMES.length; i++) {
+        const v = rec[LIMBIC_DIM_NAMES[i]];
+        if (typeof v === "number" && !Number.isNaN(v))
+            s[i] = clampDim(i, v);
+    }
+    return s;
+}
+//# sourceMappingURL=regions.js.map

package/dist/limbic/regions.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seanhogg/builderforce-memory-engine",
-  "version": "2026.6.19",
+  "version": "2026.6.27",
   "description": "BuilderForce Agent Memory — engine layer. TypeScript/WGSL Mamba SSM kernels, model blocks, autograd, training, and BPE tokenizer (zero runtime deps, WebGPU-native).",
   "main": "dist/index.js",
   "module": "dist/index.js",

package/src/index.ts

@@ -108,6 +108,37 @@ export { COMPLEX_SSD_FORWARD_WGSL, COMPLEX_SSD_BACKWARD_WGSL }
 export { ATTENTION_FORWARD_WGSL, ATTENTION_BACKWARD_WGSL, SOFTMAX_WGSL }
     from './kernels/attention.js';
 
+// ── Limbic system (trainable affective dynamics) ──────────────────────────────
+
+export {
+    REGION,
+    LIMBIC_DIM,
+    LIMBIC_DIM_NAMES,
+    LIMBIC_STATE_DIM,
+    LIMBIC_BOUNDS,
+    NEUTRAL_STATE,
+    clampDim,
+    clampState,
+    neutralState,
+    stateToRecord,
+    recordToState,
+    LimbicModel,
+    DEFAULT_LIMBIC_CONFIG,
+    DEFAULT_LIMBIC_SEED,
+    LimbicTrainer,
+} from './limbic/index.js';
+export type {
+    Region,
+    LimbicDimName,
+    LimbicModelConfig,
+    LimbicForward,
+    LimbicParam,
+    LimbicSample,
+    LimbicTrainOptions,
+} from './limbic/index.js';
+
+export { LIMBIC_AFFECT_WGSL } from './kernels/limbic_affect.js';
+
 // ── Version ───────────────────────────────────────────────────────────────────
 
 export const VERSION     = '2.0.0';

package/src/kernels/limbic_affect.ts

@@ -0,0 +1,74 @@
+// Limbic Affect WGSL Kernel
+//
+// One forward step of the limbic model's recurrent affect core, run on the GPU.
+// Given the previous hidden state, previous affective state, and an experience
+// embedding, it produces the next hidden state and a bounded affect *delta*.
+//
+// This mirrors the CPU reference in limbic/limbic_model.ts exactly (same math):
+//   pre[j]  = Σ_i Win[j,i]·x[i] + Σ_k Ws[j,k]·s[k]
+//   a[j]    = sigmoid(A[j])                       // per-channel recurrence gate
+//   h'[j]   = a[j]·h[j] + (1-a[j])·tanh(pre[j])   // SSM-style leak/input
+//   Δ[k]    = tanh( Σ_j Wout[k,j]·h'[j] + b[k] )  // bounded affect change
+//
+// hidden_dim is assumed ≤ 64 (the limbic head is tiny — the heavy lifting is in
+// the hippocampus SSM that produces the experience embedding). Reward is NOT
+// computed here: it is only needed during training, which runs the CPU backward
+// path; the per-turn inference step only needs Δ and the next hidden state.
+
+export const LIMBIC_AFFECT_WGSL: string = /* wgsl */ `
+
+struct Dims {
+    input_dim  : u32,
+    hidden_dim : u32,
+    state_dim  : u32,
+    _pad       : u32,
+};
+
+@group(0) @binding(0)  var<uniform>             dims        : Dims;
+@group(0) @binding(1)  var<storage, read>       win         : array<f32>;  // hidden*input
+@group(0) @binding(2)  var<storage, read>       ws          : array<f32>;  // hidden*state
+@group(0) @binding(3)  var<storage, read>       a_logit     : array<f32>;  // hidden
+@group(0) @binding(4)  var<storage, read>       wout_state  : array<f32>;  // state*hidden
+@group(0) @binding(5)  var<storage, read>       bout_state  : array<f32>;  // state
+@group(0) @binding(6)  var<storage, read>       x_in        : array<f32>;  // input
+@group(0) @binding(7)  var<storage, read>       h_prev      : array<f32>;  // hidden
+@group(0) @binding(8)  var<storage, read>       s_prev      : array<f32>;  // state
+@group(0) @binding(9)  var<storage, read_write> h_out       : array<f32>;  // hidden
+@group(0) @binding(10) var<storage, read_write> delta_out   : array<f32>;  // state
+
+var<workgroup> hbuf : array<f32, 64>;
+
+// Single-workgroup dispatch: (1, 1, 1) with workgroup_size 64.
+@compute @workgroup_size(64, 1, 1)
+fn affect_step(
+    @builtin(local_invocation_id) lid : vec3<u32>,
+) {
+    let j = lid.x;
+
+    // Pass 1: recurrent hidden update (one thread per hidden channel).
+    if (j < dims.hidden_dim) {
+        var pre : f32 = 0.0;
+        for (var i : u32 = 0u; i < dims.input_dim; i = i + 1u) {
+            pre = pre + win[j * dims.input_dim + i] * x_in[i];
+        }
+        for (var k : u32 = 0u; k < dims.state_dim; k = k + 1u) {
+            pre = pre + ws[j * dims.state_dim + k] * s_prev[k];
+        }
+        let a  = 1.0 / (1.0 + exp(-a_logit[j]));
+        let hn = a * h_prev[j] + (1.0 - a) * tanh(pre);
+        hbuf[j]  = hn;
+        h_out[j] = hn;
+    }
+
+    workgroupBarrier();
+
+    // Pass 2: bounded affect delta (one thread per state dim).
+    if (j < dims.state_dim) {
+        var acc : f32 = bout_state[j];
+        for (var m : u32 = 0u; m < dims.hidden_dim; m = m + 1u) {
+            acc = acc + wout_state[j * dims.hidden_dim + m] * hbuf[m];
+        }
+        delta_out[j] = tanh(acc);
+    }
+}
+`;

package/src/limbic/index.ts

@@ -0,0 +1,28 @@
+/**
+ * Limbic system – trainable affective/motivational dynamics for agents.
+ *
+ * The dynamic counterpart to the (static) psychometric personality: where
+ * personality sets the homeostatic setpoints, the limbic model learns — in
+ * WebGPU — how an agent's affective state moves in response to experience.
+ */
+
+export {
+  REGION,
+  LIMBIC_DIM,
+  LIMBIC_DIM_NAMES,
+  LIMBIC_STATE_DIM,
+  LIMBIC_BOUNDS,
+  NEUTRAL_STATE,
+  clampDim,
+  clampState,
+  neutralState,
+  stateToRecord,
+  recordToState,
+} from "./regions.js";
+export type { Region, LimbicDimName } from "./regions.js";
+
+export { LimbicModel, DEFAULT_LIMBIC_CONFIG, DEFAULT_LIMBIC_SEED } from "./limbic_model.js";
+export type { LimbicModelConfig, LimbicForward, LimbicParam } from "./limbic_model.js";
+
+export { LimbicTrainer } from "./limbic_trainer.js";
+export type { LimbicSample, LimbicTrainOptions } from "./limbic_trainer.js";