@seanhogg/builderforce-memory-engine 2026.10.1 → 2026.10.3

package/src/experience/index.ts

@@ -21,6 +21,7 @@ export type {
   RunStepLog,
   Run,
   Adaptation,
+  CuratedOut,
 } from './types.js';
 export { newExperienceId } from './types.js';
 export { isIrreversibleLabel, elementLabel, needsApproval } from './approval.js';
@@ -32,4 +33,4 @@ export type { ExperienceDocument } from './corpus.js';
 export { experienceOverview } from './overview.js';
 export type { ExperienceOverview, ExperienceRegion, ExperienceEvent, ExperienceDay, OverviewOptions } from './overview.js';
 export { EXPERIENCE_SCHEMA, MAX_RUNS, MAX_ADAPTATIONS, emptySnapshot, parseSnapshot, InMemoryExperienceStore } from './store.js';
-export type { ExperienceSnapshot, ExperienceStore } from './store.js';
+export type { ExperienceSnapshot, ExperienceStore, CurationRecord } from './store.js';

package/src/experience/store.ts

@@ -7,7 +7,7 @@
  * is the reference implementation, and `ExperienceSnapshot` is the one serialized shape,
  * so a store on one runtime can be read by another.
  */
-import type { Adaptation, Episode, EpisodeSummary, Run, RunStepLog, Skill } from './types.js';
+import type { Adaptation, CuratedOut, Episode, EpisodeSummary, Run, RunStepLog, Skill } from './types.js';
 
 export const EXPERIENCE_SCHEMA = 'evermind.experience/1';
 /** Runs kept, newest first — the audit trail is recent history, not an archive. */
@@ -29,6 +29,18 @@ export interface ExperienceSnapshot {
   learned: Record<string, number>;
   /** Every adaptation's measurements, newest first (capped at {@link MAX_ADAPTATIONS}). */
   adaptations: Adaptation[];
+  /**
+   * Procedures curation left out, by id, until they are learned, forgotten or judged
+   * again — so a later curation skips them instead of re-embedding each one.
+   */
+  curated: Record<string, CuratedOut>;
+}
+
+/** What one curation call decided: the procedures it left out, and the ones it kept. */
+export interface CurationRecord {
+  dropped: Record<string, CuratedOut>;
+  /** Ids curation kept this time — any earlier verdict on them is cleared. */
+  kept: string[];
 }
 
 export interface ExperienceStore {
@@ -56,13 +68,20 @@ export interface ExperienceStore {
    */
   recordAdaptation(adaptation: Adaptation): Promise<void>;
 
+  /**
+   * Record one curation's verdicts: each dropped procedure is stored as `curated_out`
+   * (replacing an earlier verdict), each kept one loses any earlier verdict. Learning
+   * or forgetting a procedure also clears its verdict.
+   */
+  recordCuration(curation: CurationRecord): Promise<void>;
+
   snapshot(): Promise<ExperienceSnapshot>;
   /** Delete every episode, skill and run. */
   clear(): Promise<void>;
 }
 
 export function emptySnapshot(): ExperienceSnapshot {
-  return { schema: EXPERIENCE_SCHEMA, episodes: [], skills: [], runs: [], learned: {}, adaptations: [] };
+  return { schema: EXPERIENCE_SCHEMA, episodes: [], skills: [], runs: [], learned: {}, adaptations: [], curated: {} };
 }
 
 /** Parse a snapshot, tolerating a missing or foreign file as empty. */
@@ -77,6 +96,8 @@ export function parseSnapshot(raw: unknown): ExperienceSnapshot {
     learned: s.learned && typeof s.learned === 'object' && !Array.isArray(s.learned) ? s.learned : {},
     // Optional within schema 1: snapshots written before the history existed have none.
     adaptations: Array.isArray(s.adaptations) ? s.adaptations : [],
+    // Optional within schema 1 too: written from 2026.10.3.
+    curated: s.curated && typeof s.curated === 'object' && !Array.isArray(s.curated) ? s.curated : {},
   };
 }
 
@@ -130,6 +151,7 @@ export class InMemoryExperienceStore implements ExperienceStore {
   async deleteEpisode(id: string): Promise<boolean> {
     const ok = InMemoryExperienceStore.remove(this.data.episodes, id);
     delete this.data.learned[id];
+    delete this.data.curated[id];
     if (ok) await this.changed();
     return ok;
   }
@@ -147,6 +169,7 @@ export class InMemoryExperienceStore implements ExperienceStore {
   async deleteSkill(id: string): Promise<boolean> {
     const ok = InMemoryExperienceStore.remove(this.data.skills, id);
     delete this.data.learned[id];
+    delete this.data.curated[id];
     if (ok) await this.changed();
     return ok;
   }
@@ -172,12 +195,21 @@ export class InMemoryExperienceStore implements ExperienceStore {
   }
 
   async recordAdaptation(adaptation: Adaptation): Promise<void> {
-    for (const id of adaptation.learned) this.data.learned[id] = adaptation.index;
+    for (const id of adaptation.learned) {
+      this.data.learned[id] = adaptation.index;
+      delete this.data.curated[id];
+    }
     this.data.adaptations.unshift(adaptation);
     this.data.adaptations.length = Math.min(this.data.adaptations.length, MAX_ADAPTATIONS);
     await this.changed();
   }
 
+  async recordCuration(curation: CurationRecord): Promise<void> {
+    for (const id of curation.kept) delete this.data.curated[id];
+    Object.assign(this.data.curated, curation.dropped);
+    await this.changed();
+  }
+
   async snapshot(): Promise<ExperienceSnapshot> {
     return structuredClone(this.data);
   }

package/src/experience/types.ts

@@ -154,6 +154,25 @@ export interface Adaptation {
   at: number;
 }
 
+/**
+ * A procedure curation left out of an adaptation, kept so a later curation does not
+ * re-embed and re-judge it while the verdict still stands: a `duplicate` stands while
+ * the procedure it repeats (`of`) is learned by the loaded model; a `low-quality` one
+ * while its finished-run count is still `runs` (new runs are new evidence). An
+ * `excluded` one is recorded but always reconsidered — exclusion is the caller's call.
+ */
+export interface CuratedOut {
+  status: 'curated_out';
+  reason: 'duplicate' | 'low-quality' | 'excluded';
+  /** `duplicate`: the id of the procedure it repeats. */
+  of?: string;
+  /** Similarity (duplicate) or P(high) (low-quality). */
+  score?: number;
+  /** Finished runs of the procedure when it was judged. */
+  runs: number;
+  at: number;
+}
+
 /** A short random id — unique enough for one person's store. */
 export function newExperienceId(): string {
   const bytes = new Uint8Array(8);

package/src/index.ts

@@ -43,6 +43,7 @@ export {
     buildDeltaLearnPayload,
     decodeDeltaPayload,
     deltaUnusableReason,
+    deltaTargetMismatch,
     MAX_DELTA_B64_CHARS,
     mergeCheckpointDiffs,
     mergeCheckpointDiffsGated,
@@ -63,6 +64,7 @@ export type {
     AdaptTokenizer,
     DeltaLearnPayload,
     DeltaParseResult,
+    DeltaParseOptions,
     MergeResult,
     GatedMergeResult,
     MergeGateOptions,

package/src/kernels/weight_update.ts

@@ -35,6 +35,12 @@ struct AdamParams {
 // v     (N,)   – second moment
 @group(0) @binding(4) var<storage, read_write> v_state  : array<f32>;
 
+// NaN or ±Inf, read from the IEEE-754 exponent bits (all ones) — immune to a
+// compiler that assumes finite floats and folds "x != x" away.
+fn non_finite(x : f32) -> bool {
+    return (bitcast<u32>(x) & 0x7f800000u) == 0x7f800000u;
+}
+
 // Dispatch: (ceil(N / 256), 1, 1)
 @compute @workgroup_size(256, 1, 1)
 fn adamw_update(
@@ -49,6 +55,12 @@ fn adamw_update(
     // Moment updates
     let m_new = adam.beta1 * m_state[i] + (1.0 - adam.beta1) * g;
     let v_new = adam.beta2 * v_state[i] + (1.0 - adam.beta2) * g * g;
+
+    // Non-finite gradient (or moments that overflowed): skip this element ENTIRELY —
+    // m, v and the weight keep their values. Storing a NaN moment and dropping only
+    // the step froze the weight forever (every later step read the NaN back).
+    // Mirrors adamwUpdateInPlace (optim/adamw.ts), which counts the skips.
+    if (non_finite(g) || non_finite(m_new) || non_finite(v_new)) { return; }
     m_state[i] = m_new;
     v_state[i] = v_new;
 

package/src/limbic/limbic_model.ts

@@ -28,6 +28,7 @@
  * (experience, state) → affect pair is close to an independent regression.
  */
 
+import { sigmoid } from "../training/cpu_ops.js";
 import { SeededRng } from "../utils/rng.js";
 import { quantizeFp16, dequantizeFp16 } from "../utils/quantization.js";
 import { LIMBIC_STATE_DIM } from "./regions.js";
@@ -86,10 +87,6 @@ const MAGIC = 0x4c4d4243; // "LMBC"
 /** Fixed default init seed — reproducible byte-identical cold start across machines. */
 export const DEFAULT_LIMBIC_SEED = 0x11b1c5ee;
 
-function sigmoid(x: number): number {
-  return 1 / (1 + Math.exp(-x));
-}
-
 export class LimbicModel {
   readonly config: Required<Omit<LimbicModelConfig, "seed">>;
 

package/src/limbic/limbic_trainer.ts

@@ -1,91 +1,91 @@
-/**
- * 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 — through the shared {@link HeadTrainer} (`ml/head_trainer.ts`),
- * which runs the optimiser step on the GPU via WEIGHT_UPDATE_WGSL when a device is
- * supplied and on a numerically-equivalent CPU AdamW otherwise. This file is only
- * the limbic registration: the head adapter and the public trainer surface.
- *
- * 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 { HeadTrainer, type HeadTrainOptions, type TrainableHead } from "../ml/head_trainer.js";
-import type { LimbicModel, LimbicParam } 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;
-}
-
-/** The limbic trainer's options are the shared head trainer's. */
-export type LimbicTrainOptions = HeadTrainOptions;
-
-/**
- * The limbic model as a {@link TrainableHead}. 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.
- */
-export function limbicHead(model: LimbicModel): TrainableHead<LimbicSample> {
-  return {
-    parameters: (): LimbicParam[] => model.parameters(),
-    gradients: (): LimbicParam[] => model.gradients(),
-    zeroGrad: () => model.zeroGrad(),
-    accumulate: (s) =>
-      model.backwardStep(s.input, model.initHidden(), s.state, s.deltaTarget, s.reward).loss,
-    loss: (s) => {
-      const { rewardWeight } = model.config;
-      const f = model.forward(s.input, 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;
-      return loss;
-    },
-  };
-}
-
-/** Thin registration of the limbic head over the shared {@link HeadTrainer}. */
-export class LimbicTrainer {
-  readonly model: LimbicModel;
-  readonly device: GPUDevice | null;
-  private readonly _trainer: HeadTrainer<LimbicSample>;
-
-  constructor(model: LimbicModel, device: GPUDevice | null = null) {
-    this.model = model;
-    this.device = device;
-    this._trainer = new HeadTrainer(limbicHead(model), device, "LimbicTrainer");
-  }
-
-  /** Whether the optimiser step runs on the GPU. */
-  get gpuTraining(): boolean {
-    return this._trainer.gpuTraining;
-  }
-
-  /**
-   * Train on a batch of samples for `epochs` passes. Returns the per-epoch mean
-   * loss (monotonically decreasing on a learnable mapping).
-   */
-  train(samples: LimbicSample[], opts: LimbicTrainOptions = {}): Promise<number[]> {
-    return this._trainer.train(samples, opts);
-  }
-
-  /** Mean MSE loss over samples (no weight update). Hidden resets per sample. */
-  evaluate(samples: LimbicSample[]): number {
-    return this._trainer.evaluate(samples);
-  }
-}
+/**
+ * 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 — through the shared {@link HeadTrainer} (`ml/head_trainer.ts`),
+ * which runs the optimiser step on the GPU via WEIGHT_UPDATE_WGSL when a device is
+ * supplied and on a numerically-equivalent CPU AdamW otherwise. This file is only
+ * the limbic registration: the head adapter and the public trainer surface.
+ *
+ * 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 { HeadTrainer, type HeadTrainOptions, type TrainableHead } from "../ml/head_trainer.js";
+import type { LimbicModel, LimbicParam } 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;
+}
+
+/** The limbic trainer's options are the shared head trainer's. */
+export type LimbicTrainOptions = HeadTrainOptions;
+
+/**
+ * The limbic model as a {@link TrainableHead}. 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.
+ */
+export function limbicHead(model: LimbicModel): TrainableHead<LimbicSample> {
+  return {
+    parameters: (): LimbicParam[] => model.parameters(),
+    gradients: (): LimbicParam[] => model.gradients(),
+    zeroGrad: () => model.zeroGrad(),
+    accumulate: (s) =>
+      model.backwardStep(s.input, model.initHidden(), s.state, s.deltaTarget, s.reward).loss,
+    loss: (s) => {
+      const { rewardWeight } = model.config;
+      const f = model.forward(s.input, 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;
+      return loss;
+    },
+  };
+}
+
+/** Thin registration of the limbic head over the shared {@link HeadTrainer}. */
+export class LimbicTrainer {
+  readonly model: LimbicModel;
+  readonly device: GPUDevice | null;
+  private readonly _trainer: HeadTrainer<LimbicSample>;
+
+  constructor(model: LimbicModel, device: GPUDevice | null = null) {
+    this.model = model;
+    this.device = device;
+    this._trainer = new HeadTrainer(limbicHead(model), device, "LimbicTrainer");
+  }
+
+  /** Whether the optimiser step runs on the GPU. */
+  get gpuTraining(): boolean {
+    return this._trainer.gpuTraining;
+  }
+
+  /**
+   * Train on a batch of samples for `epochs` passes. Returns the per-epoch mean
+   * loss (monotonically decreasing on a learnable mapping).
+   */
+  train(samples: LimbicSample[], opts: LimbicTrainOptions = {}): Promise<number[]> {
+    return this._trainer.train(samples, opts);
+  }
+
+  /** Mean MSE loss over samples (no weight update). Hidden resets per sample. */
+  evaluate(samples: LimbicSample[]): number {
+    return this._trainer.evaluate(samples);
+  }
+}

package/src/ml/classical/anomaly_composite.ts

@@ -0,0 +1,46 @@
+/**
+ * ml/classical/anomaly_composite.ts — robust z and EWMA as ONE anomaly engine.
+ *
+ * Two detectors, one answer: robust z (median/MAD over the whole history — "far
+ * from normal") and EWMA (the recent trend — "drifting away from lately"). The
+ * score is the larger of the two normalised scores, so either one can flag. It is
+ * one engine because it is one fitted thing: a task that lists it gets back exactly
+ * what it stores under `local:classical:anomaly-composite`.
+ */
+import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
+import { EwmaModel, fitEwma, type EwmaOptions } from "./ewma.js";
+import { anomalyConfidence, fitRobustZ, RobustZModel, type RobustZOptions } from "./robust_z.js";
+
+export interface AnomalyCompositeOptions {
+  robustZ?: RobustZOptions;
+  ewma?: EwmaOptions;
+}
+
+export class AnomalyCompositeModel implements MlPredictor {
+  constructor(
+    readonly population: RobustZModel,
+    readonly trend: EwmaModel,
+  ) {}
+
+  /** Per feature, per detector: z / threshold (≥ 1 = out of range). */
+  featureScores(x: ArrayLike<number>): { population: number; trend: number }[] {
+    const pz = this.population.zScores(x);
+    const tz = this.trend.zScores(x);
+    return pz.map((z, i) => ({ population: z / this.population.threshold, trend: tz[i]! / this.trend.threshold }));
+  }
+
+  /** Fold a finished, non-anomalous observation into the trend. */
+  observe(x: ArrayLike<number>): void {
+    this.trend.update(x);
+  }
+
+  predict(x: Float32Array): MlPrediction {
+    const score = Math.max(this.population.predict(x).scores[0]!, this.trend.predict(x).scores[0]!);
+    return { scores: [score], confidence: anomalyConfidence(score) };
+  }
+}
+
+/** Fit both detectors on a chronological history (feature vectors, oldest first). */
+export function fitAnomalyComposite(samples: readonly MlSample[], opts: AnomalyCompositeOptions = {}): AnomalyCompositeModel {
+  return new AnomalyCompositeModel(fitRobustZ(samples, opts.robustZ), fitEwma(samples, opts.ewma));
+}

package/src/ml/classical/ewma.ts

@@ -5,10 +5,12 @@
  * Per feature, over the history IN ORDER: diff = x − μ; μ += α·diff;
  * σ² = (1 − α)(σ² + α·diff²). A new point scores z = |x − μ| / σ against the
  * state BEFORE it is folded in. Prediction: `scores[0] = max_i z_i / threshold`.
+ * σ is floored like robust z's scale: a fraction of |μ|, and `minScale` in absolute
+ * units — σ² starts at 0, so a constant history would otherwise flag any change.
  */
 import type { MlPrediction, MlPredictor, MlSample } from "../types.js";
 import { featureDim } from "./math.js";
-import { anomalyConfidence } from "./robust_z.js";
+import { anomalyConfidence, minScaleAt, type MinScale } from "./robust_z.js";
 
 export interface EwmaOptions {
   /** Smoothing factor in (0, 1]. Default 0.3. */
@@ -17,6 +19,8 @@ export interface EwmaOptions {
   threshold?: number;
   /** Smallest σ per feature, as a fraction of |μ| (plus 1e-9). Default 0.01. */
   minScaleFraction?: number;
+  /** Smallest σ in absolute feature units, one or per feature. Default 0 (see `RobustZOptions.minScale`). */
+  minScale?: MinScale;
 }
 
 export class EwmaModel implements MlPredictor {
@@ -26,13 +30,14 @@ export class EwmaModel implements MlPredictor {
     readonly alpha: number,
     readonly threshold: number,
     readonly minScaleFraction: number,
+    readonly minScale: MinScale = 0,
   ) {
     if (!(alpha > 0 && alpha <= 1)) throw new Error(`EwmaModel: alpha must be in (0, 1] (got ${alpha})`);
   }
 
   zScores(x: ArrayLike<number>): number[] {
     return Array.from(this.mean, (m, i) => {
-      const sd = Math.max(Math.sqrt(this.variance[i]!), this.minScaleFraction * Math.abs(m) + 1e-9);
+      const sd = Math.max(Math.sqrt(this.variance[i]!), this.minScaleFraction * Math.abs(m) + 1e-9, minScaleAt(this.minScale, i));
       return Math.abs((x[i] ?? 0) - m) / sd;
     });
   }
@@ -62,6 +67,7 @@ export function fitEwma(samples: readonly MlSample[], opts: EwmaOptions = {}): E
     opts.alpha ?? 0.3,
     opts.threshold ?? 3,
     opts.minScaleFraction ?? 0.01,
+    opts.minScale ?? 0,
   );
   for (let i = 1; i < samples.length; i++) model.update(samples[i]!.x);
   return model;