agent-working-memory 0.8.7 → 0.9.0

package/src/coordination/circuit-breaker.ts

@@ -1,83 +1,83 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Per-worker CircuitBreaker for the coordination control layer.
- * Prevents chronically-stale workers from poisoning the assignment queue.
- * Part of AWM 0.8.1 — additive, no breaking changes.
- *
- * States:
- *   closed    — normal operation
- *   open      — worker blocked after FAILURE_THRESHOLD consecutive failures
- *   half_open — probe window (30s after open), allows one assignment attempt
- */
-
-import type Database from 'better-sqlite3';
-
-export type CircuitState = 'closed' | 'open' | 'half_open';
-
-const FAILURE_THRESHOLD = 5;
-const HALF_OPEN_DELAY_MS = 30_000;
-
-/** Record a worker failure. Opens the circuit when consecutive failures hit the threshold. */
-export function recordFailure(db: Database.Database, agentId: string): void {
-  db.prepare(`
-    INSERT INTO coord_circuit_state (agent_id, consecutive_failures, last_transition_at)
-    VALUES (?, 1, datetime('now'))
-    ON CONFLICT(agent_id) DO UPDATE SET
-      consecutive_failures = consecutive_failures + 1,
-      state = CASE
-        WHEN consecutive_failures + 1 >= ${FAILURE_THRESHOLD} THEN 'open'
-        ELSE state
-      END,
-      opened_at = CASE
-        WHEN consecutive_failures + 1 >= ${FAILURE_THRESHOLD} AND (state != 'open' OR opened_at IS NULL)
-        THEN datetime('now')
-        ELSE opened_at
-      END,
-      last_transition_at = datetime('now')
-  `).run(agentId);
-}
-
-/** Record a worker success. Resets to closed regardless of prior state. */
-export function recordSuccess(db: Database.Database, agentId: string): void {
-  db.prepare(`
-    INSERT INTO coord_circuit_state (agent_id, state, consecutive_failures, last_transition_at)
-    VALUES (?, 'closed', 0, datetime('now'))
-    ON CONFLICT(agent_id) DO UPDATE SET
-      state = 'closed',
-      consecutive_failures = 0,
-      opened_at = NULL,
-      last_transition_at = datetime('now')
-  `).run(agentId);
-}
-
-/**
- * Get current circuit state for a worker.
- * If the circuit has been open for >30s, auto-transitions to half_open.
- */
-export function getState(db: Database.Database, agentId: string): CircuitState {
-  const row = db.prepare(
-    `SELECT state, opened_at FROM coord_circuit_state WHERE agent_id = ?`
-  ).get(agentId) as { state: string; opened_at: string | null } | undefined;
-
-  if (!row || row.state === 'closed') return 'closed';
-  if (row.state === 'half_open') return 'half_open';
-
-  // open — check if half-open window has elapsed
-  if (row.state === 'open' && row.opened_at) {
-    const openedAt = new Date(row.opened_at.endsWith('Z') ? row.opened_at : row.opened_at + 'Z').getTime();
-    if (Date.now() - openedAt > HALF_OPEN_DELAY_MS) {
-      db.prepare(
-        `UPDATE coord_circuit_state SET state = 'half_open', last_transition_at = datetime('now') WHERE agent_id = ?`
-      ).run(agentId);
-      return 'half_open';
-    }
-  }
-
-  return 'open';
-}
-
-/** Returns true when the worker is eligible to receive an assignment. */
-export function isAvailable(db: Database.Database, agentId: string): boolean {
-  return getState(db, agentId) !== 'open';
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Per-worker CircuitBreaker for the coordination control layer.
+ * Prevents chronically-stale workers from poisoning the assignment queue.
+ * Part of AWM 0.8.1 — additive, no breaking changes.
+ *
+ * States:
+ *   closed    — normal operation
+ *   open      — worker blocked after FAILURE_THRESHOLD consecutive failures
+ *   half_open — probe window (30s after open), allows one assignment attempt
+ */
+
+import type Database from 'better-sqlite3';
+
+export type CircuitState = 'closed' | 'open' | 'half_open';
+
+const FAILURE_THRESHOLD = 5;
+const HALF_OPEN_DELAY_MS = 30_000;
+
+/** Record a worker failure. Opens the circuit when consecutive failures hit the threshold. */
+export function recordFailure(db: Database.Database, agentId: string): void {
+  db.prepare(`
+    INSERT INTO coord_circuit_state (agent_id, consecutive_failures, last_transition_at)
+    VALUES (?, 1, datetime('now'))
+    ON CONFLICT(agent_id) DO UPDATE SET
+      consecutive_failures = consecutive_failures + 1,
+      state = CASE
+        WHEN consecutive_failures + 1 >= ${FAILURE_THRESHOLD} THEN 'open'
+        ELSE state
+      END,
+      opened_at = CASE
+        WHEN consecutive_failures + 1 >= ${FAILURE_THRESHOLD} AND (state != 'open' OR opened_at IS NULL)
+        THEN datetime('now')
+        ELSE opened_at
+      END,
+      last_transition_at = datetime('now')
+  `).run(agentId);
+}
+
+/** Record a worker success. Resets to closed regardless of prior state. */
+export function recordSuccess(db: Database.Database, agentId: string): void {
+  db.prepare(`
+    INSERT INTO coord_circuit_state (agent_id, state, consecutive_failures, last_transition_at)
+    VALUES (?, 'closed', 0, datetime('now'))
+    ON CONFLICT(agent_id) DO UPDATE SET
+      state = 'closed',
+      consecutive_failures = 0,
+      opened_at = NULL,
+      last_transition_at = datetime('now')
+  `).run(agentId);
+}
+
+/**
+ * Get current circuit state for a worker.
+ * If the circuit has been open for >30s, auto-transitions to half_open.
+ */
+export function getState(db: Database.Database, agentId: string): CircuitState {
+  const row = db.prepare(
+    `SELECT state, opened_at FROM coord_circuit_state WHERE agent_id = ?`
+  ).get(agentId) as { state: string; opened_at: string | null } | undefined;
+
+  if (!row || row.state === 'closed') return 'closed';
+  if (row.state === 'half_open') return 'half_open';
+
+  // open — check if half-open window has elapsed
+  if (row.state === 'open' && row.opened_at) {
+    const openedAt = new Date(row.opened_at.endsWith('Z') ? row.opened_at : row.opened_at + 'Z').getTime();
+    if (Date.now() - openedAt > HALF_OPEN_DELAY_MS) {
+      db.prepare(
+        `UPDATE coord_circuit_state SET state = 'half_open', last_transition_at = datetime('now') WHERE agent_id = ?`
+      ).run(agentId);
+      return 'half_open';
+    }
+  }
+
+  return 'open';
+}
+
+/** Returns true when the worker is eligible to receive an assignment. */
+export function isAvailable(db: Database.Database, agentId: string): boolean {
+  return getState(db, agentId) !== 'open';
+}

package/src/coordination/failure-modes.ts

@@ -1,50 +1,50 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * FailureMode taxonomy and mutation-hint map for the coordination control layer.
- * Part of AWM 0.8.1 — additive, no breaking changes.
- */
-
-export enum FailureMode {
-  AGENT_STALE    = 'agent_stale',
-  TIMEOUT        = 'timeout',
-  OUTPUT_INVALID = 'output_invalid',
-  TEST_FAIL      = 'test_fail',
-  LINT_FAIL      = 'lint_fail',
-  MERGE_CONFLICT = 'merge_conflict',
-  UNKNOWN        = 'unknown',
-}
-
-/** Classify a failure result string into one of the known modes. */
-export function classifyFailure(result: string | null): FailureMode {
-  if (!result) return FailureMode.UNKNOWN;
-  const r = result.toLowerCase();
-  if (r.includes('stale') || r.includes('disconnected')) return FailureMode.AGENT_STALE;
-  if (r.includes('timeout') || r.includes('timed out'))  return FailureMode.TIMEOUT;
-  if (r.includes('json') || r.includes('schema') || r.includes('parse')) return FailureMode.OUTPUT_INVALID;
-  if (r.includes('test fail') || r.includes('vitest') || r.includes('jest')) return FailureMode.TEST_FAIL;
-  if (r.includes('lint') || r.includes('eslint') || r.includes('typecheck')) return FailureMode.LINT_FAIL;
-  if (r.includes('conflict'))                             return FailureMode.MERGE_CONFLICT;
-  return FailureMode.UNKNOWN;
-}
-
-/**
- * Corrective guidance injected into the task description on retry.
- * Each hint is written in the vocabulary the next worker will read.
- */
-export const MUTATION_HINTS: Record<FailureMode, string> = {
-  [FailureMode.AGENT_STALE]:
-    'Previous worker disconnected before completion. Resume from last known state; check git status before re-running destructive commands.',
-  [FailureMode.TIMEOUT]:
-    'Previous attempt timed out. Break work into smaller commits; report progress every 5 minutes.',
-  [FailureMode.OUTPUT_INVALID]:
-    'Previous output failed validation. Return a single fenced code block; verify JSON parses before submitting.',
-  [FailureMode.TEST_FAIL]:
-    'Previous attempt left tests failing. Run vitest before completion; do NOT mark complete if any test fails.',
-  [FailureMode.LINT_FAIL]:
-    'Previous attempt had lint/typecheck errors. Run pnpm typecheck and pnpm lint before completion.',
-  [FailureMode.MERGE_CONFLICT]:
-    'Previous attempt left merge conflicts unresolved. git pull --rebase, resolve, then re-attempt.',
-  [FailureMode.UNKNOWN]:
-    'Previous attempt failed for an unclassified reason. Investigate the prior result before re-running.',
-};
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * FailureMode taxonomy and mutation-hint map for the coordination control layer.
+ * Part of AWM 0.8.1 — additive, no breaking changes.
+ */
+
+export enum FailureMode {
+  AGENT_STALE    = 'agent_stale',
+  TIMEOUT        = 'timeout',
+  OUTPUT_INVALID = 'output_invalid',
+  TEST_FAIL      = 'test_fail',
+  LINT_FAIL      = 'lint_fail',
+  MERGE_CONFLICT = 'merge_conflict',
+  UNKNOWN        = 'unknown',
+}
+
+/** Classify a failure result string into one of the known modes. */
+export function classifyFailure(result: string | null): FailureMode {
+  if (!result) return FailureMode.UNKNOWN;
+  const r = result.toLowerCase();
+  if (r.includes('stale') || r.includes('disconnected')) return FailureMode.AGENT_STALE;
+  if (r.includes('timeout') || r.includes('timed out'))  return FailureMode.TIMEOUT;
+  if (r.includes('json') || r.includes('schema') || r.includes('parse')) return FailureMode.OUTPUT_INVALID;
+  if (r.includes('test fail') || r.includes('vitest') || r.includes('jest')) return FailureMode.TEST_FAIL;
+  if (r.includes('lint') || r.includes('eslint') || r.includes('typecheck')) return FailureMode.LINT_FAIL;
+  if (r.includes('conflict'))                             return FailureMode.MERGE_CONFLICT;
+  return FailureMode.UNKNOWN;
+}
+
+/**
+ * Corrective guidance injected into the task description on retry.
+ * Each hint is written in the vocabulary the next worker will read.
+ */
+export const MUTATION_HINTS: Record<FailureMode, string> = {
+  [FailureMode.AGENT_STALE]:
+    'Previous worker disconnected before completion. Resume from last known state; check git status before re-running destructive commands.',
+  [FailureMode.TIMEOUT]:
+    'Previous attempt timed out. Break work into smaller commits; report progress every 5 minutes.',
+  [FailureMode.OUTPUT_INVALID]:
+    'Previous output failed validation. Return a single fenced code block; verify JSON parses before submitting.',
+  [FailureMode.TEST_FAIL]:
+    'Previous attempt left tests failing. Run vitest before completion; do NOT mark complete if any test fails.',
+  [FailureMode.LINT_FAIL]:
+    'Previous attempt had lint/typecheck errors. Run pnpm typecheck and pnpm lint before completion.',
+  [FailureMode.MERGE_CONFLICT]:
+    'Previous attempt left merge conflicts unresolved. git pull --rebase, resolve, then re-attempt.',
+  [FailureMode.UNKNOWN]:
+    'Previous attempt failed for an unclassified reason. Investigate the prior result before re-running.',
+};

package/src/core/decay.ts

@@ -1,63 +1,63 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * ACT-R Base-Level Activation
- *
- * Based on Anderson's ACT-R cognitive architecture (1993).
- * Memories that are accessed more recently and more frequently
- * have higher activation — a well-established model of human memory.
- *
- * Formula: B(M) = ln(n + 1) - d * ln(ageDays / (n + 1))
- *
- * Where:
- *   n = access count
- *   d = decay exponent (default 0.5)
- *   ageDays = age of memory in days
- */
-
-export function baseLevelActivation(
-  accessCount: number,
-  ageDays: number,
-  decayExponent: number = 0.5
-): number {
-  const n = Math.max(accessCount, 0);
-  const age = Math.max(ageDays, 0.001); // Avoid log(0)
-  return Math.log(n + 1) - decayExponent * Math.log(age / (n + 1));
-}
-
-/**
- * Softplus — smooth approximation of ReLU.
- * Used to keep activation scores positive without hard clipping.
- */
-export function softplus(x: number): number {
-  return Math.log(1 + Math.exp(x));
-}
-
-/**
- * Composite activation score combining content match, temporal decay,
- * Hebbian boost, and confidence.
- *
- * Score = contentMatch * softplus(B(M) + scale * hebbianBoost) * confidence
- */
-export function compositeScore(params: {
-  contentMatch: number;
-  accessCount: number;
-  ageDays: number;
-  hebbianBoost: number;
-  confidence: number;
-  decayExponent?: number;
-  hebbianScale?: number;
-}): number {
-  const {
-    contentMatch,
-    accessCount,
-    ageDays,
-    hebbianBoost,
-    confidence,
-    decayExponent = 0.5,
-    hebbianScale = 1.0,
-  } = params;
-
-  const bm = baseLevelActivation(accessCount, ageDays, decayExponent);
-  return contentMatch * softplus(bm + hebbianScale * hebbianBoost) * confidence;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ACT-R Base-Level Activation
+ *
+ * Based on Anderson's ACT-R cognitive architecture (1993).
+ * Memories that are accessed more recently and more frequently
+ * have higher activation — a well-established model of human memory.
+ *
+ * Formula: B(M) = ln(n + 1) - d * ln(ageDays / (n + 1))
+ *
+ * Where:
+ *   n = access count
+ *   d = decay exponent (default 0.5)
+ *   ageDays = age of memory in days
+ */
+
+export function baseLevelActivation(
+  accessCount: number,
+  ageDays: number,
+  decayExponent: number = 0.5
+): number {
+  const n = Math.max(accessCount, 0);
+  const age = Math.max(ageDays, 0.001); // Avoid log(0)
+  return Math.log(n + 1) - decayExponent * Math.log(age / (n + 1));
+}
+
+/**
+ * Softplus — smooth approximation of ReLU.
+ * Used to keep activation scores positive without hard clipping.
+ */
+export function softplus(x: number): number {
+  return Math.log(1 + Math.exp(x));
+}
+
+/**
+ * Composite activation score combining content match, temporal decay,
+ * Hebbian boost, and confidence.
+ *
+ * Score = contentMatch * softplus(B(M) + scale * hebbianBoost) * confidence
+ */
+export function compositeScore(params: {
+  contentMatch: number;
+  accessCount: number;
+  ageDays: number;
+  hebbianBoost: number;
+  confidence: number;
+  decayExponent?: number;
+  hebbianScale?: number;
+}): number {
+  const {
+    contentMatch,
+    accessCount,
+    ageDays,
+    hebbianBoost,
+    confidence,
+    decayExponent = 0.5,
+    hebbianScale = 1.0,
+  } = params;
+
+  const bm = baseLevelActivation(accessCount, ageDays, decayExponent);
+  return contentMatch * softplus(bm + hebbianScale * hebbianBoost) * confidence;
+}

package/src/core/embeddings.ts

@@ -1,110 +1,110 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Embedding Engine - vector embeddings via the ML worker pool.
- *
- * Default model: bge-small-en-v1.5 (384 dimensions, ~90MB, MTEB retrieval-optimized).
- * Configurable via AWM_EMBED_MODEL env var.
- *
- * AWM 0.8.x: inference dispatches through ml-worker.ts. The worker_threads
- * path was planned but reverted to in-process because onnxruntime-node's
- * native bindings store V8 handles that don't cross isolate boundaries
- * safely — see ml-worker.ts for the full status. The dispatch abstraction
- * is preserved for a future child_process or HTTP sidecar pool.
- * `AWM_ML_INPROCESS=1` is honored as a no-op (in-process is now the default).
- *
- * NOTE: Changing the model invalidates existing embeddings.
- * Set AWM_EMBED_MODEL=Xenova/all-MiniLM-L6-v2 for backward compatibility.
- */
-
-import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
-import { dispatchEmbed, registerInProcessHandlers } from './ml-worker.js';
-
-const MODEL_ID = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
-const DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
-const POOLING = (process.env.AWM_EMBED_POOLING ?? 'mean') as 'cls' | 'mean';
-
-// --- In-process fallback (used by tests and crash recovery) ---
-
-let inProcessInstance: FeatureExtractionPipeline | null = null;
-let inProcessInitPromise: Promise<FeatureExtractionPipeline> | null = null;
-
-async function loadInProcess(): Promise<FeatureExtractionPipeline> {
-  if (inProcessInstance) return inProcessInstance;
-  if (inProcessInitPromise) return inProcessInitPromise;
-  inProcessInitPromise = pipeline('feature-extraction', MODEL_ID, { dtype: 'fp32' }).then(pipe => {
-    inProcessInstance = pipe;
-    console.log(`Embedding model loaded in-process: ${MODEL_ID} (${DIMENSIONS}d)`);
-    return pipe;
-  });
-  return inProcessInitPromise;
-}
-
-async function inProcessEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]> {
-  const { texts, pooling, dimensions } = args;
-  if (texts.length === 0) return [];
-  const embedder = await loadInProcess();
-  const result = await embedder(texts, { pooling, normalize: true });
-  const data = result.data as Float32Array;
-  const vectors: number[][] = [];
-  for (let i = 0; i < texts.length; i++) {
-    vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
-  }
-  return vectors;
-}
-
-// Register the in-process handler with the pool (used in test mode and as fallback)
-registerInProcessHandlers({ embed: inProcessEmbed });
-
-// --- Public API ---
-
-/**
- * Get or initialize the embedding pipeline (singleton).
- * Kept for backwards compat — returns the in-process pipeline only.
- * Most consumers should use embed() / embedBatch() which dispatch
- * to the worker pool by default.
- */
-export async function getEmbedder(): Promise<FeatureExtractionPipeline> {
-  return loadInProcess();
-}
-
-/**
- * Generate an embedding vector for a text string.
- * Dispatches to the worker pool (or in-process fallback).
- */
-export async function embed(text: string): Promise<number[]> {
-  const vectors = await dispatchEmbed({ texts: [text], pooling: POOLING, dimensions: DIMENSIONS });
-  return vectors[0] ?? new Array(DIMENSIONS).fill(0);
-}
-
-/**
- * Generate embeddings for multiple texts in a batch.
- * More efficient than calling embed() in a loop — the worker batches the
- * tokenization + forward pass.
- */
-export async function embedBatch(texts: string[]): Promise<number[][]> {
-  if (texts.length === 0) return [];
-  return dispatchEmbed({ texts, pooling: POOLING, dimensions: DIMENSIONS });
-}
-
-/** Get the current embedding model ID (for version tracking in stored embeddings) */
-export function getModelId(): string {
-  return MODEL_ID;
-}
-
-/**
- * Cosine similarity between two normalized vectors.
- * Since vectors are pre-normalized, this is just the dot product.
- */
-export function cosineSimilarity(a: number[], b: number[]): number {
-  if (a.length !== b.length || a.length === 0) return 0;
-  let dot = 0;
-  for (let i = 0; i < a.length; i++) {
-    dot += a[i] * b[i];
-  }
-  // Clamp to [-1, 1] to handle floating point drift
-  return Math.max(-1, Math.min(1, dot));
-}
-
-/** Vector dimensions for this model */
-export const EMBEDDING_DIMENSIONS = DIMENSIONS;
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Embedding Engine - vector embeddings via the ML worker pool.
+ *
+ * Default model: bge-small-en-v1.5 (384 dimensions, ~90MB, MTEB retrieval-optimized).
+ * Configurable via AWM_EMBED_MODEL env var.
+ *
+ * AWM 0.8.x: inference dispatches through ml-worker.ts. The worker_threads
+ * path was planned but reverted to in-process because onnxruntime-node's
+ * native bindings store V8 handles that don't cross isolate boundaries
+ * safely — see ml-worker.ts for the full status. The dispatch abstraction
+ * is preserved for a future child_process or HTTP sidecar pool.
+ * `AWM_ML_INPROCESS=1` is honored as a no-op (in-process is now the default).
+ *
+ * NOTE: Changing the model invalidates existing embeddings.
+ * Set AWM_EMBED_MODEL=Xenova/all-MiniLM-L6-v2 for backward compatibility.
+ */
+
+import { pipeline, type FeatureExtractionPipeline } from '@huggingface/transformers';
+import { dispatchEmbed, registerInProcessHandlers } from './ml-worker.js';
+
+const MODEL_ID = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
+const DIMENSIONS = parseInt(process.env.AWM_EMBED_DIMS ?? '384', 10);
+const POOLING = (process.env.AWM_EMBED_POOLING ?? 'mean') as 'cls' | 'mean';
+
+// --- In-process fallback (used by tests and crash recovery) ---
+
+let inProcessInstance: FeatureExtractionPipeline | null = null;
+let inProcessInitPromise: Promise<FeatureExtractionPipeline> | null = null;
+
+async function loadInProcess(): Promise<FeatureExtractionPipeline> {
+  if (inProcessInstance) return inProcessInstance;
+  if (inProcessInitPromise) return inProcessInitPromise;
+  inProcessInitPromise = pipeline('feature-extraction', MODEL_ID, { dtype: 'fp32' }).then(pipe => {
+    inProcessInstance = pipe;
+    console.log(`Embedding model loaded in-process: ${MODEL_ID} (${DIMENSIONS}d)`);
+    return pipe;
+  });
+  return inProcessInitPromise;
+}
+
+async function inProcessEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]> {
+  const { texts, pooling, dimensions } = args;
+  if (texts.length === 0) return [];
+  const embedder = await loadInProcess();
+  const result = await embedder(texts, { pooling, normalize: true });
+  const data = result.data as Float32Array;
+  const vectors: number[][] = [];
+  for (let i = 0; i < texts.length; i++) {
+    vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
+  }
+  return vectors;
+}
+
+// Register the in-process handler with the pool (used in test mode and as fallback)
+registerInProcessHandlers({ embed: inProcessEmbed });
+
+// --- Public API ---
+
+/**
+ * Get or initialize the embedding pipeline (singleton).
+ * Kept for backwards compat — returns the in-process pipeline only.
+ * Most consumers should use embed() / embedBatch() which dispatch
+ * to the worker pool by default.
+ */
+export async function getEmbedder(): Promise<FeatureExtractionPipeline> {
+  return loadInProcess();
+}
+
+/**
+ * Generate an embedding vector for a text string.
+ * Dispatches to the worker pool (or in-process fallback).
+ */
+export async function embed(text: string): Promise<number[]> {
+  const vectors = await dispatchEmbed({ texts: [text], pooling: POOLING, dimensions: DIMENSIONS });
+  return vectors[0] ?? new Array(DIMENSIONS).fill(0);
+}
+
+/**
+ * Generate embeddings for multiple texts in a batch.
+ * More efficient than calling embed() in a loop — the worker batches the
+ * tokenization + forward pass.
+ */
+export async function embedBatch(texts: string[]): Promise<number[][]> {
+  if (texts.length === 0) return [];
+  return dispatchEmbed({ texts, pooling: POOLING, dimensions: DIMENSIONS });
+}
+
+/** Get the current embedding model ID (for version tracking in stored embeddings) */
+export function getModelId(): string {
+  return MODEL_ID;
+}
+
+/**
+ * Cosine similarity between two normalized vectors.
+ * Since vectors are pre-normalized, this is just the dot product.
+ */
+export function cosineSimilarity(a: number[], b: number[]): number {
+  if (a.length !== b.length || a.length === 0) return 0;
+  let dot = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+  }
+  // Clamp to [-1, 1] to handle floating point drift
+  return Math.max(-1, Math.min(1, dot));
+}
+
+/** Vector dimensions for this model */
+export const EMBEDDING_DIMENSIONS = DIMENSIONS;

package/src/core/index.ts

@@ -1,5 +1,5 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-export * from './decay.js';
-export * from './hebbian.js';
-export * from './salience.js';
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+export * from './decay.js';
+export * from './hebbian.js';
+export * from './salience.js';