agent-working-memory 0.10.0 → 0.11.0

package/src/cli.ts

@@ -13,10 +13,12 @@
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
-import { resolve, join, dirname } from 'node:path';
+import { resolve, join, dirname, basename } from 'node:path';
 import { execSync } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { VERSION } from './version.js';
+import { runOnboard, ONBOARD_SKILL } from './onboard/index.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -139,6 +141,9 @@ async function setup() {
   const instructionsAction = adapter.writeInstructions(ctx, skipInstructions);
   const hooksAction = adapter.writeHooks(ctx, skipHooks);
 
+  // Seed the onboarding skill so a cold store can teach the agent how to warm itself.
+  const skillAction = await seedOnboardSkill(ctx.dbPath, ctx.agentId);
+
   console.log(`
 AWM configured for ${adapter.name}${isGlobal ? ' (global)' : ''}
 
@@ -147,6 +152,7 @@ AWM configured for ${adapter.name}${isGlobal ? ' (global)' : ''}
   ${configAction}
   ${instructionsAction}
   ${hooksAction}
+  ${skillAction}
 
 Next steps:
   1. Restart ${adapter.name} to pick up the MCP server
@@ -352,7 +358,7 @@ async function exportMemories() {
     }
 
     const exportData = {
-      version: '0.9.2',
+      version: VERSION,
       exported_at: new Date().toISOString(),
       source_backend: backend,
       agent_filter: agentFilter,
@@ -711,6 +717,72 @@ async function migrateCmd() {
   }
 }
 
+// ─── ONBOARD ──────────────────────────────────────
+
+/**
+ * Seed the onboarding skill as a canonical memory (idempotent). This is what lets
+ * a cold store teach the host agent how to warm-start itself — the agent recalls
+ * the skill and follows it. Best-effort: a seeding failure never fails `awm setup`.
+ */
+async function seedOnboardSkill(dbPath: string, agentId: string): Promise<string> {
+  try {
+    const { store, close } = await openCliStore(dbPath);
+    try {
+      const existing = await store.findActiveMatchByConcept(agentId, ONBOARD_SKILL.concept);
+      if (existing) return 'Onboarding skill: already present';
+      await store.createEngram({
+        agentId, concept: ONBOARD_SKILL.concept, content: ONBOARD_SKILL.content,
+        tags: ONBOARD_SKILL.tags, confidence: 0.9, salience: 0.9, memoryClass: 'canonical',
+      });
+      return 'Onboarding skill: seeded (recall it on a cold store to warm-start)';
+    } finally {
+      await close();
+    }
+  } catch (e: any) {
+    return `Onboarding skill: skipped (${e?.message ?? 'store unavailable'})`;
+  }
+}
+
+function onboardCmd() {
+  const docs: string[] = [];
+  let repo: string | undefined;
+  let project = '';
+  let agentId = '';
+  let purpose: string | undefined;
+  let outDir = resolve(process.cwd(), '.awm');
+
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--repo' && args[i + 1]) repo = args[++i];
+    else if (a === '--project' && args[i + 1]) project = args[++i];
+    else if (a === '--agent' && args[i + 1]) agentId = args[++i];
+    else if (a === '--purpose' && args[i + 1]) purpose = args[++i];
+    else if (a === '--out' && args[i + 1]) outDir = resolve(args[++i]);
+    else if (!a.startsWith('--')) docs.push(a);
+  }
+
+  // Default docs to the repo (or cwd) so a bare `awm onboard --repo .` works.
+  if (docs.length === 0) docs.push(repo ?? process.cwd());
+  if (!project) project = basename(repo ? resolve(repo) : (docs[0] ? resolve(docs[0]) : process.cwd()));
+  if (!agentId) agentId = project;
+
+  const { packPath, reviewPath, count } = runOnboard({ docs, repo, project, agentId, purpose, outDir });
+  console.log(`
+AWM onboard — warm-start pack for "${project}"
+
+  Scanned:   ${docs.join(', ')}${repo ? `  (+repo ${repo})` : ''}
+  Extracted: ${count} candidate memories (agent: ${agentId})
+
+  Review:    ${reviewPath}
+  Pack:      ${packPath}
+
+Next:
+  1. Edit the review file / pack as needed (delete noise, answer the interview questions).
+  2. Load it:  awm import ${packPath} --db <path> --dedupe
+     (embeddings backfill on the first consolidation — recall is warm immediately after)
+`.trimEnd());
+}
+
 // ─── Dispatch ──────────────────────────────────────
 
 switch (command) {
@@ -741,6 +813,9 @@ switch (command) {
   case 'migrate':
     await migrateCmd();
     break;
+  case 'onboard':
+    onboardCmd();
+    break;
   case '--help':
   case '-h':
   case undefined:

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;
+}