@seanhogg/builderforce-memory-engine 2026.9.28 → 2026.9.29

package/src/experience/store.ts

@@ -0,0 +1,188 @@
+/**
+ * experience/store.ts — the persistence port for experience, and its snapshot format.
+ *
+ * The engine does no I/O (checkpoints are `ArrayBuffer`s the host stores); experience
+ * follows the same rule. `ExperienceStore` is the port every host implements over its own
+ * storage — a JSON file on disk (memory-mcp), IndexedDB, a KV. `InMemoryExperienceStore`
+ * 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';
+
+export const EXPERIENCE_SCHEMA = 'evermind.experience/1';
+/** Runs kept, newest first — the audit trail is recent history, not an archive. */
+export const MAX_RUNS = 500;
+/** Adaptations kept, newest first — enough history to chart how learning went. */
+export const MAX_ADAPTATIONS = 200;
+
+export interface ExperienceSnapshot {
+  schema: typeof EXPERIENCE_SCHEMA;
+  episodes: Episode[];
+  skills: Skill[];
+  runs: Run[];
+  /**
+   * Which episodes and skills the local Evermind has been adapted on, and by which
+   * adaptation (the N of the model's `+expN` version) — so training reads each
+   * procedure once, and a model rolled back to an earlier N re-learns what the
+   * discarded versions had learned.
+   */
+  learned: Record<string, number>;
+  /** Every adaptation's measurements, newest first (capped at {@link MAX_ADAPTATIONS}). */
+  adaptations: Adaptation[];
+}
+
+export interface ExperienceStore {
+  putEpisode(episode: Episode): Promise<void>;
+  getEpisode(id: string): Promise<Episode | undefined>;
+  listEpisodes(): Promise<EpisodeSummary[]>;
+  /** Forget a demonstration. Skills compiled from it keep working — they carry their own steps. */
+  deleteEpisode(id: string): Promise<boolean>;
+
+  putSkill(skill: Skill): Promise<void>;
+  getSkill(id: string): Promise<Skill | undefined>;
+  listSkills(): Promise<Skill[]>;
+  deleteSkill(id: string): Promise<boolean>;
+
+  putRun(run: Run): Promise<void>;
+  /** Append one audit line to a run; false when the run is unknown. */
+  appendRunStep(runId: string, step: RunStepLog): Promise<boolean>;
+  getRun(id: string): Promise<Run | undefined>;
+  listRuns(limit: number): Promise<Run[]>;
+
+  /**
+   * Record one adaptation: its items join the learned ledger under its index (the
+   * model's `+expN`) and its measurements join the history — one write, so the ledger
+   * and the chart can never disagree.
+   */
+  recordAdaptation(adaptation: Adaptation): 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: [] };
+}
+
+/** Parse a snapshot, tolerating a missing or foreign file as empty. */
+export function parseSnapshot(raw: unknown): ExperienceSnapshot {
+  const s = raw as Partial<ExperienceSnapshot> | null;
+  if (!s || s.schema !== EXPERIENCE_SCHEMA) return emptySnapshot();
+  return {
+    schema: EXPERIENCE_SCHEMA,
+    episodes: Array.isArray(s.episodes) ? s.episodes : [],
+    skills: Array.isArray(s.skills) ? s.skills : [],
+    runs: Array.isArray(s.runs) ? s.runs : [],
+    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 : [],
+  };
+}
+
+function summary(e: Episode): EpisodeSummary {
+  return { id: e.id, name: e.name, program: e.program, startedAt: e.startedAt, steps: e.steps.length };
+}
+
+/**
+ * The reference store: the snapshot held in memory. Hosts that persist wrap it and
+ * write `snapshot()` after each change (see `onChange`).
+ */
+export class InMemoryExperienceStore implements ExperienceStore {
+  private data: ExperienceSnapshot;
+
+  constructor(initial?: ExperienceSnapshot, private readonly onChange?: (s: ExperienceSnapshot) => void | Promise<void>) {
+    this.data = initial ? parseSnapshot(initial) : emptySnapshot();
+  }
+
+  /** Replace the contents (a host re-reading its file after another process wrote it). */
+  load(snapshot: ExperienceSnapshot): void {
+    this.data = parseSnapshot(snapshot);
+  }
+
+  private async changed(): Promise<void> {
+    await this.onChange?.(this.data);
+  }
+
+  private static upsert<T extends { id: string }>(list: T[], item: T): void {
+    const i = list.findIndex((x) => x.id === item.id);
+    if (i >= 0) list[i] = item;
+    else list.push(item);
+  }
+
+  private static remove<T extends { id: string }>(list: T[], id: string): boolean {
+    const i = list.findIndex((x) => x.id === id);
+    if (i < 0) return false;
+    list.splice(i, 1);
+    return true;
+  }
+
+  async putEpisode(episode: Episode): Promise<void> {
+    InMemoryExperienceStore.upsert(this.data.episodes, episode);
+    await this.changed();
+  }
+  async getEpisode(id: string): Promise<Episode | undefined> {
+    return this.data.episodes.find((e) => e.id === id);
+  }
+  async listEpisodes(): Promise<EpisodeSummary[]> {
+    return [...this.data.episodes].sort((a, b) => b.startedAt - a.startedAt).map(summary);
+  }
+  async deleteEpisode(id: string): Promise<boolean> {
+    const ok = InMemoryExperienceStore.remove(this.data.episodes, id);
+    delete this.data.learned[id];
+    if (ok) await this.changed();
+    return ok;
+  }
+
+  async putSkill(skill: Skill): Promise<void> {
+    InMemoryExperienceStore.upsert(this.data.skills, skill);
+    await this.changed();
+  }
+  async getSkill(id: string): Promise<Skill | undefined> {
+    return this.data.skills.find((s) => s.id === id);
+  }
+  async listSkills(): Promise<Skill[]> {
+    return [...this.data.skills].sort((a, b) => b.createdAt - a.createdAt);
+  }
+  async deleteSkill(id: string): Promise<boolean> {
+    const ok = InMemoryExperienceStore.remove(this.data.skills, id);
+    delete this.data.learned[id];
+    if (ok) await this.changed();
+    return ok;
+  }
+
+  async putRun(run: Run): Promise<void> {
+    InMemoryExperienceStore.upsert(this.data.runs, run);
+    this.data.runs.sort((a, b) => b.startedAt - a.startedAt);
+    this.data.runs.length = Math.min(this.data.runs.length, MAX_RUNS);
+    await this.changed();
+  }
+  async appendRunStep(runId: string, step: RunStepLog): Promise<boolean> {
+    const run = this.data.runs.find((r) => r.id === runId);
+    if (!run) return false;
+    run.steps.push(step);
+    await this.changed();
+    return true;
+  }
+  async getRun(id: string): Promise<Run | undefined> {
+    return this.data.runs.find((r) => r.id === id);
+  }
+  async listRuns(limit: number): Promise<Run[]> {
+    return this.data.runs.slice(0, Math.max(0, limit));
+  }
+
+  async recordAdaptation(adaptation: Adaptation): Promise<void> {
+    for (const id of adaptation.learned) this.data.learned[id] = adaptation.index;
+    this.data.adaptations.unshift(adaptation);
+    this.data.adaptations.length = Math.min(this.data.adaptations.length, MAX_ADAPTATIONS);
+    await this.changed();
+  }
+
+  async snapshot(): Promise<ExperienceSnapshot> {
+    return structuredClone(this.data);
+  }
+  async clear(): Promise<void> {
+    this.data = emptySnapshot();
+    await this.changed();
+  }
+}

package/src/experience/trainOnce.ts

@@ -0,0 +1,85 @@
+/**
+ * experience/trainOnce.ts — Train Once: one reviewed demonstration becomes a skill that
+ * runs again with new values.
+ *
+ * Deterministic, local, no model call. Every value the person typed becomes a named
+ * parameter (named after the field it went into), every secret field a secret parameter,
+ * and every irreversible click an approval gate. The review edits decide what stays.
+ */
+import { elementLabel, needsApproval } from './approval.js';
+import { newExperienceId, type Episode, type Skill, type SkillAction, type SkillParam, type SkillStep } from './types.js';
+
+/** What the person changed in review, keyed by recorded step id. */
+export interface ReviewEdits {
+  /** The skill's name (defaults to the episode's). */
+  name?: string | null;
+  /** Steps left out of the skill. */
+  removed?: string[];
+  /** Typed values kept exactly as recorded instead of asked for each run. */
+  fixed?: string[];
+  /** Approval gate per step, where the person overrode the default. */
+  approvals?: Record<string, boolean>;
+  /** Parameter names the person chose, per step. */
+  paramNames?: Record<string, string>;
+}
+
+export function trainOnce(episode: Episode, edits: ReviewEdits = {}, now: number = Date.now()): Skill {
+  const removed = new Set(edits.removed ?? []);
+  const fixed = new Set(edits.fixed ?? []);
+  const params: SkillParam[] = [];
+  const steps: SkillStep[] = [];
+  for (const rec of episode.steps) {
+    if (removed.has(rec.id)) continue;
+    const a = rec.action;
+    let action: SkillAction;
+    if (a.kind === 'setValue') {
+      if (!a.secret && fixed.has(rec.id)) {
+        action = { kind: 'setValue', target: a.target, value: { from: 'literal', text: a.value } };
+      } else {
+        const chosen = slug(edits.paramNames?.[rec.id] ?? '');
+        const base = chosen || slug(elementLabel(a.target)) || 'value';
+        const name = uniqueName(params, base);
+        params.push({ name, label: elementLabel(a.target), default: a.secret ? null : a.value, secret: !!a.secret });
+        action = { kind: 'setValue', target: a.target, value: { from: 'param', name } };
+      }
+    } else {
+      action = a;
+    }
+    steps.push({
+      id: rec.id,
+      action,
+      requiresApproval: edits.approvals?.[rec.id] ?? needsApproval(a),
+      screenshot: rec.screenshot ?? null,
+    });
+  }
+  return {
+    id: newExperienceId(),
+    name: edits.name?.trim() || episode.name,
+    program: episode.program,
+    args: [...episode.args],
+    params,
+    steps,
+    sourceEpisode: episode.id,
+    createdAt: now,
+    routine: null,
+  };
+}
+
+/** `Invoice Amount (USD)` → `invoice_amount_usd`. Letters in any script survive. */
+export function slug(label: string): string {
+  return label
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean)
+    .join('_')
+    .slice(0, 40)
+    .replace(/_+$/, '');
+}
+
+function uniqueName(params: SkillParam[], base: string): string {
+  if (!params.some((p) => p.name === base)) return base;
+  for (let i = 2; ; i++) {
+    const n = `${base}_${i}`;
+    if (!params.some((p) => p.name === n)) return n;
+  }
+}

package/src/experience/types.ts

@@ -0,0 +1,162 @@
+/**
+ * experience/types.ts — what Evermind has DONE, as opposed to what it knows.
+ *
+ * Facts live in `@seanhogg/builderforce-memory` (MemoryStore / EvermindCognition) and
+ * weights in the model; this is the third kind of learned item: experience.
+ *   - an **Episode** is one demonstration — a person doing a task in a program, recorded
+ *     as semantic steps (the UI element acted on and the value set, never raw keystrokes);
+ *   - a **Skill** is what Train Once compiles from an episode — a procedure that runs
+ *     again with new values, with approval gates on irreversible steps;
+ *   - a **Run** is one execution of a skill, with its step-by-step audit trail.
+ *
+ * Plain data, JSON-shaped (camelCase, actions tagged by `kind`), so any recorder — the
+ * native Windows UI Automation one in Synapse included — produces it and any runtime
+ * persists it. Timestamps are epoch milliseconds.
+ */
+
+/** A UI element, identified the way the platform's accessibility API sees it. */
+export interface ElementRef {
+  name: string;
+  automationId: string;
+  /** `Button`, `Edit`, `MenuItem`, … */
+  controlType: string;
+  className: string;
+  /** The top-level window the element sits in. */
+  windowTitle: string;
+  processName: string;
+  /** Where it was acted on, relative to the window's top-left — the replay fallback. */
+  relX: number;
+  relY: number;
+}
+
+/** One thing the person did. A secret field records that it was filled, never the value. */
+export type Action =
+  | { kind: 'click'; target: ElementRef }
+  | { kind: 'setValue'; target: ElementRef; value: string; secret?: boolean }
+  | { kind: 'keys'; keys: string; target?: ElementRef | null };
+
+export interface RecordedStep {
+  id: string;
+  /** Milliseconds since the recording started. */
+  atMs: number;
+  action: Action;
+  /** Screenshot file name inside the episode's folder, if one was taken. */
+  screenshot?: string | null;
+}
+
+export interface Episode {
+  id: string;
+  name: string;
+  program: string;
+  args: string[];
+  startedAt: number;
+  endedAt?: number | null;
+  steps: RecordedStep[];
+}
+
+export interface EpisodeSummary {
+  id: string;
+  name: string;
+  program: string;
+  startedAt: number;
+  steps: number;
+}
+
+/** A value a skill asks for at run time. */
+export interface SkillParam {
+  /** Stable key, e.g. `amount`. */
+  name: string;
+  /** What the field was called where it was typed, e.g. `Amount`. */
+  label: string;
+  /** The value from the demonstration; never set for a secret. */
+  default?: string | null;
+  secret: boolean;
+}
+
+export type SkillValue = { from: 'param'; name: string } | { from: 'literal'; text: string };
+
+export type SkillAction =
+  | { kind: 'click'; target: ElementRef }
+  | { kind: 'setValue'; target: ElementRef; value: SkillValue }
+  | { kind: 'keys'; keys: string; target?: ElementRef | null };
+
+export interface SkillStep {
+  id: string;
+  action: SkillAction;
+  /** Pause and ask the person before this step. */
+  requiresApproval: boolean;
+  screenshot?: string | null;
+}
+
+/** When a skill runs by itself. Local time of day for `day`. */
+export type Schedule = { every: 'minutes'; minutes: number } | { every: 'day'; hour: number; minute: number };
+
+/** A skill's routine: at most one per skill, so it lives on the skill. */
+export interface SkillRoutine {
+  schedule: Schedule;
+  /** Values for the non-secret parameters; secrets come from the host's vault. */
+  values: Record<string, string>;
+  enabled: boolean;
+  lastRunAt?: number | null;
+}
+
+export interface Skill {
+  id: string;
+  name: string;
+  program: string;
+  args: string[];
+  params: SkillParam[];
+  steps: SkillStep[];
+  sourceEpisode: string;
+  createdAt: number;
+  routine?: SkillRoutine | null;
+}
+
+export type RunStatus = 'running' | 'succeeded' | 'failed' | 'stopped' | 'denied';
+
+export type StepOutcome = 'ok' | 'fallback' | 'failed' | 'approved' | 'denied';
+
+/** One line of a run's audit trail. A step can have two (approved, then ok). */
+export interface RunStepLog {
+  idx: number;
+  stepId: string;
+  outcome: StepOutcome;
+  detail?: string | null;
+  at: number;
+}
+
+export interface Run {
+  id: string;
+  skillId: string;
+  skillName: string;
+  /** `manual` or `routine`. */
+  trigger: string;
+  status: RunStatus;
+  startedAt: number;
+  endedAt?: number | null;
+  error?: string | null;
+  steps: RunStepLog[];
+}
+
+/**
+ * One adaptation of the private model on experience: what it learned and how the fit
+ * went. Measured when the adaptation ran, never estimated afterwards.
+ */
+export interface Adaptation {
+  /** N of the `+expN` version this adaptation wrote. */
+  index: number;
+  version: string;
+  /** Episode and skill ids it learned. */
+  learned: string[];
+  passes: number;
+  /** Mean fit loss over the passes. */
+  loss: number;
+  at: number;
+}
+
+/** A short random id — unique enough for one person's store. */
+export function newExperienceId(): string {
+  const bytes = new Uint8Array(8);
+  globalThis.crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}

package/src/index.ts

@@ -35,7 +35,9 @@ export type {
 // ── Evermind (the .evermind artifact + the shared learning pipeline) ───────────
 export {
     EvermindModelPackage,
+    PACKAGE_HEADER_BYTES,
     adaptAndDiff,
+    adaptPackage,
     EVERMIND_ADAPT_MAX_CHARS,
     parseDeltaLearnPayload,
     buildDeltaLearnPayload,
@@ -53,6 +55,7 @@ export type {
     PackageMeta,
     ValidationResult,
     AdaptResult,
+    AdaptedPackage,
     AdaptOptions,
     AdaptTokenizer,
     DeltaLearnPayload,
@@ -363,3 +366,8 @@ export type {
 } from './limbic/index.js';
 
 export { LIMBIC_AFFECT_WGSL } from './kernels/limbic_affect.js';
+
+
+// ── Experience (demonstrations, Train Once skills, runs) ─────────────────────
+
+export * from './experience/index.js';