agent-working-memory 0.8.8 → 0.9.0

package/src/engine/connections.ts

@@ -28,6 +28,50 @@ import type { Engram } from '../types/index.js';
 
 const COLD_START_THRESHOLD = Number(process.env.AWM_CONNECTION_COLD_START_THRESHOLD ?? 10);
 
+/**
+ * R1 — broaden edge FORMATION beyond high-cosine semantic links.
+ *
+ * The semantic `activate` path only links engrams at ≥0.7 cosine, so two facts
+ * that share an entity but are lexically/semantically distant ("my main project
+ * is Atlas" vs "Atlas's codename is Magpie") never get an edge — starving the
+ * graph walk / spreading activation of exactly the bridges multi-hop needs.
+ *
+ * When enabled, after the semantic pass we also form *entity co-occurrence*
+ * edges: extract proper-noun entities from the engram, find other engrams that
+ * literally mention the same entity (BM25 + substring re-check for precision),
+ * and link them at a LOWER weight than semantic edges. Recall-only by design —
+ * the edges feed candidate generation; the reranker still makes the final cut.
+ *
+ * Default-OFF (gate per docs/awm-improvement-register.md). Set
+ * `AWM_BROAD_EDGES=1` to enable.
+ */
+const BROAD_EDGES = process.env.AWM_BROAD_EDGES === '1';
+/** Max entity-co-occurrence edges formed per engram (on top of semantic). */
+const MAX_ENTITY_EDGES = Number(process.env.AWM_BROAD_EDGES_MAX ?? 6);
+/** Proper-noun entity extraction — mirrors auto-tagger's `entity:` pattern. */
+const ENTITY_RE = /\b([A-Z][a-z]{2,}(?:\s+[A-Z][a-z]+)*)\b/g;
+/** Common capitalized words that are not useful entity bridges. */
+const ENTITY_STOPWORDS = new Set([
+  'The', 'This', 'That', 'These', 'Those', 'There', 'Then', 'They', 'Them',
+  'And', 'But', 'For', 'With', 'From', 'Into', 'When', 'What', 'Where', 'Which',
+  'While', 'Who', 'Why', 'How', 'Also', 'After', 'Before', 'Because', 'Should',
+  'Would', 'Could', 'Will', 'Was', 'Were', 'Has', 'Have', 'Had', 'Not', 'Now',
+  'New', 'One', 'Two', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday',
+  'Saturday', 'Sunday', 'January', 'February', 'March', 'April', 'June', 'July',
+  'August', 'September', 'October', 'November', 'December',
+]);
+
+function extractEntities(text: string): string[] {
+  const out = new Set<string>();
+  for (const m of text.matchAll(ENTITY_RE)) {
+    const name = m[1].trim();
+    if (name.length < 3 || name.length > 40) continue;
+    if (ENTITY_STOPWORDS.has(name)) continue;
+    out.add(name);
+  }
+  return [...out];
+}
+
 export class ConnectionEngine {
   private store: EngramStore;
   private engine: ActivationEngine;
@@ -130,6 +174,7 @@ export class ConnectionEngine {
       limit: 5,
       minScore: this.threshold,
       internal: true,
+      spread: false, // edge discovery must not recurse through R2 spreading
     });
 
     // Filter out self and already-connected engrams
@@ -157,6 +202,55 @@ export class ConnectionEngine {
         result.score,
         'connection'
       );
+      existingIds.add(result.engram.id);
+    }
+
+    if (BROAD_EDGES) {
+      await this.formEntityEdges(engram, existingIds);
+    }
+  }
+
+  /**
+   * R1 — form entity co-occurrence edges (default-off, `AWM_BROAD_EDGES=1`).
+   *
+   * Extract proper-noun entities from the engram, find other engrams that
+   * literally mention the same entity, and link them at a lower weight than
+   * the semantic edges above. The BM25 candidate is re-checked with a
+   * case-insensitive substring match so a coincidental capitalized word
+   * doesn't create a spurious edge (precision guard); edge weight scales with
+   * the number of shared entities but stays below the 0.7 semantic floor so
+   * semantic links still dominate the graph walk.
+   */
+  private async formEntityEdges(engram: Engram, existingIds: Set<string>): Promise<void> {
+    const entities = extractEntities(`${engram.concept} ${engram.content}`);
+    if (entities.length === 0) return;
+
+    // Gather candidates that match any of the engram's entities (BM25 OR).
+    const query = entities.slice(0, 6).join(' ');
+    const candidates = await this.store.searchBM25(engram.agentId, query, 20);
+    const lowerEntities = entities.map(e => e.toLowerCase());
+
+    // Rank candidates by how many of our entities they literally contain.
+    const scored: Array<{ id: string; engram: Engram; shared: number }> = [];
+    for (const cand of candidates) {
+      if (cand.id === engram.id) continue;
+      if (existingIds.has(cand.id)) continue;
+      if (cand.stage !== 'active') continue;
+      const candText = `${cand.concept} ${cand.content}`.toLowerCase();
+      let shared = 0;
+      for (const ent of lowerEntities) {
+        if (candText.includes(ent)) shared++;
+      }
+      if (shared > 0) scored.push({ id: cand.id, engram: cand, shared });
+    }
+
+    scored.sort((a, b) => b.shared - a.shared);
+    for (const { id, shared } of scored.slice(0, MAX_ENTITY_EDGES)) {
+      // Below the 0.7 semantic floor; more shared entities → stronger edge.
+      const weight = Math.min(0.6, 0.4 + 0.1 * shared);
+      await this.store.upsertAssociation(engram.id, id, weight, 'connection');
+      await this.store.upsertAssociation(id, engram.id, weight, 'connection');
+      existingIds.add(id);
     }
   }
 }

package/src/engine/consolidation-scheduler.ts

@@ -1,242 +1,242 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Consolidation Scheduler - sleep-only consolidation (AWM 0.8.x).
- *
- * Two triggers, both modeled on biological sleep (offline consolidation, not in-band):
- *
- *   1. Cron - fires at a configured time (default: 0 3 * * * = 3 AM local time).
- *      Configurable via AWM_CONSOLIDATION_CRON env var.
- *
- *   2. Quiescence - fires when ALL active agents have been idle >30 min.
- *      "Truly asleep" - no agent is currently writing or recalling.
- *
- * Kill switch: AWM_DISABLE_SCHEDULER=1 skips both triggers. Manual
- * consolidation via POST /system/consolidate still works.
- *
- * Removed in 2.0: in-band idle/volume/time/precision triggers that fired
- * during active hours and blocked HTTP.
- *
- * Tick granularity: 1 minute (sufficient for cron-at-the-minute precision
- * and quiescence checks at human timescales).
- */
-
-import type { IEngramStore as EngramStore } from '../storage/store.js';
-import type { ConsolidationEngine } from './consolidation.js';
-
-const TICK_INTERVAL_MS = 60_000;             // Check every 60s
-const QUIESCENCE_THRESHOLD_MS = 30 * 60_000; // 30 minutes
-const DEFAULT_CRON = '0 3 * * *';            // 3 AM local time daily
-
-// --- Cron matcher (hand-rolled, minute-granularity) ---
-
-/**
- * Parse a single cron field into a Set of valid integer values.
- * Supports: wildcard, literal value, range A-B, list A,B,C, step A-B/N.
- */
-function parseCronField(field: string, min: number, max: number): Set<number> {
-  const result = new Set<number>();
-  for (const part of field.split(',')) {
-    // Handle step: <range>/N
-    const stepMatch = part.match(/^(.+?)\/(\d+)$/);
-    if (stepMatch) {
-      const range = stepMatch[1];
-      const step = parseInt(stepMatch[2], 10);
-      if (step <= 0) continue;
-      const [lo, hi] = range === '*'
-        ? [min, max]
-        : range.includes('-')
-          ? range.split('-').map(n => parseInt(n, 10)) as [number, number]
-          : [parseInt(range, 10), max];
-      for (let n = lo; n <= hi; n += step) {
-        if (n >= min && n <= max) result.add(n);
-      }
-      continue;
-    }
-    // Range: A-B
-    if (part.includes('-')) {
-      const [lo, hi] = part.split('-').map(n => parseInt(n, 10));
-      for (let n = lo; n <= hi; n++) {
-        if (n >= min && n <= max) result.add(n);
-      }
-      continue;
-    }
-    // Wildcard
-    if (part === '*') {
-      for (let n = min; n <= max; n++) result.add(n);
-      continue;
-    }
-    // Single value
-    const n = parseInt(part, 10);
-    if (!Number.isNaN(n) && n >= min && n <= max) result.add(n);
-  }
-  return result;
-}
-
-/**
- * Return true if `now` matches the cron expression at minute granularity.
- * Format: "minute hour dayOfMonth month dayOfWeek" (5 fields, space-separated).
- * Day-of-week: 0-6 (0 = Sunday). 7 is also accepted as Sunday alias.
- */
-export function cronMatches(now: Date, expr: string): boolean {
-  const fields = expr.trim().split(/\s+/);
-  if (fields.length !== 5) return false;
-
-  const minutes = parseCronField(fields[0], 0, 59);
-  const hours = parseCronField(fields[1], 0, 23);
-  const daysOfMonth = parseCronField(fields[2], 1, 31);
-  const months = parseCronField(fields[3], 1, 12);
-  const daysOfWeekRaw = parseCronField(fields[4], 0, 7);
-  // Normalize: 7 == 0 (Sunday)
-  const daysOfWeek = new Set<number>();
-  for (const d of daysOfWeekRaw) daysOfWeek.add(d === 7 ? 0 : d);
-
-  return (
-    minutes.has(now.getMinutes()) &&
-    hours.has(now.getHours()) &&
-    daysOfMonth.has(now.getDate()) &&
-    months.has(now.getMonth() + 1) &&
-    daysOfWeek.has(now.getDay())
-  );
-}
-
-// --- Scheduler ---
-
-export class ConsolidationScheduler {
-  private timer: ReturnType<typeof setInterval> | null = null;
-  private running = false;
-  private readonly cronExpr: string;
-  private readonly disabled: boolean;
-  private lastCronTriggeredMinute: string | null = null;
-
-  constructor(
-    private store: EngramStore,
-    private consolidationEngine: ConsolidationEngine,
-  ) {
-    this.cronExpr = process.env.AWM_CONSOLIDATION_CRON ?? DEFAULT_CRON;
-    this.disabled = process.env.AWM_DISABLE_SCHEDULER === '1' || process.env.AWM_DISABLE_SCHEDULER === 'true';
-  }
-
-  start(): void {
-    if (this.timer) return;
-    if (this.disabled) {
-      console.log('ConsolidationScheduler disabled (AWM_DISABLE_SCHEDULER=1)');
-      return;
-    }
-    this.timer = setInterval(() => this.tick(), TICK_INTERVAL_MS);
-    console.log(`ConsolidationScheduler started - cron='${this.cronExpr}', quiescence-gate=${QUIESCENCE_THRESHOLD_MS / 60_000}min`);
-  }
-
-  stop(): void {
-    if (this.timer) {
-      clearInterval(this.timer);
-      this.timer = null;
-    }
-    console.log('ConsolidationScheduler stopped');
-  }
-
-  /** True if the scheduler is currently running a consolidation cycle. */
-  isRunning(): boolean {
-    return this.running;
-  }
-
-  /** True if the scheduler's automatic triggers are disabled (kill switch). */
-  isDisabled(): boolean {
-    return this.disabled;
-  }
-
-  /**
-   * Mini-consolidation - lightweight, called from restore path.
-   * Only runs replay + strengthen (phases 1-2), skips heavy phases.
-   */
-  async runMiniConsolidation(agentId: string): Promise<void> {
-    if (this.running) return;
-    this.running = true;
-    try {
-      console.log(`[scheduler] mini-consolidation for ${agentId}`);
-      await this.consolidationEngine.consolidate(agentId);
-      await this.store.markConsolidation(agentId, true);
-    } catch (err) {
-      console.error(`[scheduler] mini-consolidation failed for ${agentId}:`, err);
-    } finally {
-      this.running = false;
-    }
-  }
-
-  /**
-   * Tick handler - checks both triggers. Cron first (planned), then quiescence (opportunistic).
-   * Fires consolidation for at most one agent per tick to avoid overload.
-   */
-  private async tick(): Promise<void> {
-    if (this.running) return;
-    const now = new Date();
-
-    // Trigger 1: cron
-    if (cronMatches(now, this.cronExpr)) {
-      const minuteKey = `${now.getFullYear()}-${now.getMonth()}-${now.getDate()}T${now.getHours()}:${now.getMinutes()}`;
-      if (this.lastCronTriggeredMinute !== minuteKey) {
-        this.lastCronTriggeredMinute = minuteKey;
-        const agent = await this.pickAgent();
-        if (agent) {
-          this.runFullConsolidation(agent.agentId, `cron (${this.cronExpr})`);
-          return;
-        }
-      }
-    }
-
-    // Trigger 2: quiescence
-    if (await this.isQuiescent(now)) {
-      const agent = await this.pickAgent();
-      if (agent) {
-        this.runFullConsolidation(agent.agentId, `quiescence (>${QUIESCENCE_THRESHOLD_MS / 60_000}min idle, all agents)`);
-        return;
-      }
-    }
-  }
-
-  /**
-   * Pick the agent that benefits most from consolidation:
-   * highest writeCount since last consolidation, tie-break by oldest consolidation.
-   */
-  private async pickAgent(): Promise<{ agentId: string } | null> {
-    const agents = await this.store.getActiveAgents();
-    if (agents.length === 0) return null;
-    const sorted = [...agents].sort((a, b) => {
-      if (b.writeCount !== a.writeCount) return b.writeCount - a.writeCount;
-      const aT = a.lastConsolidationAt?.getTime() ?? 0;
-      const bT = b.lastConsolidationAt?.getTime() ?? 0;
-      return aT - bT;
-    });
-    return sorted[0];
-  }
-
-  /**
-   * Quiescence check: ALL active agents must have lastActivityAt > threshold ago.
-   * `lastActivityAt` is updated on both writes and recalls so this captures both.
-   * If no active agents, the system is trivially quiescent.
-   */
-  private async isQuiescent(now: Date): Promise<boolean> {
-    const agents = await this.store.getActiveAgents();
-    if (agents.length === 0) return true;
-    const nowMs = now.getTime();
-    for (const agent of agents) {
-      const idleMs = nowMs - agent.lastActivityAt.getTime();
-      if (idleMs < QUIESCENCE_THRESHOLD_MS) return false;
-    }
-    return true;
-  }
-
-  private async runFullConsolidation(agentId: string, reason: string): Promise<void> {
-    this.running = true;
-    try {
-      console.log(`[scheduler] full consolidation for ${agentId} - trigger: ${reason}`);
-      const result = await this.consolidationEngine.consolidate(agentId);
-      await this.store.markConsolidation(agentId, false);
-      console.log(`[scheduler] consolidation done: ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
-    } catch (err) {
-      console.error(`[scheduler] consolidation failed for ${agentId}:`, err);
-    } finally {
-      this.running = false;
-    }
-  }
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Consolidation Scheduler - sleep-only consolidation (AWM 0.8.x).
+ *
+ * Two triggers, both modeled on biological sleep (offline consolidation, not in-band):
+ *
+ *   1. Cron - fires at a configured time (default: 0 3 * * * = 3 AM local time).
+ *      Configurable via AWM_CONSOLIDATION_CRON env var.
+ *
+ *   2. Quiescence - fires when ALL active agents have been idle >30 min.
+ *      "Truly asleep" - no agent is currently writing or recalling.
+ *
+ * Kill switch: AWM_DISABLE_SCHEDULER=1 skips both triggers. Manual
+ * consolidation via POST /system/consolidate still works.
+ *
+ * Removed in 2.0: in-band idle/volume/time/precision triggers that fired
+ * during active hours and blocked HTTP.
+ *
+ * Tick granularity: 1 minute (sufficient for cron-at-the-minute precision
+ * and quiescence checks at human timescales).
+ */
+
+import type { IEngramStore as EngramStore } from '../storage/store.js';
+import type { ConsolidationEngine } from './consolidation.js';
+
+const TICK_INTERVAL_MS = 60_000;             // Check every 60s
+const QUIESCENCE_THRESHOLD_MS = 30 * 60_000; // 30 minutes
+const DEFAULT_CRON = '0 3 * * *';            // 3 AM local time daily
+
+// --- Cron matcher (hand-rolled, minute-granularity) ---
+
+/**
+ * Parse a single cron field into a Set of valid integer values.
+ * Supports: wildcard, literal value, range A-B, list A,B,C, step A-B/N.
+ */
+function parseCronField(field: string, min: number, max: number): Set<number> {
+  const result = new Set<number>();
+  for (const part of field.split(',')) {
+    // Handle step: <range>/N
+    const stepMatch = part.match(/^(.+?)\/(\d+)$/);
+    if (stepMatch) {
+      const range = stepMatch[1];
+      const step = parseInt(stepMatch[2], 10);
+      if (step <= 0) continue;
+      const [lo, hi] = range === '*'
+        ? [min, max]
+        : range.includes('-')
+          ? range.split('-').map(n => parseInt(n, 10)) as [number, number]
+          : [parseInt(range, 10), max];
+      for (let n = lo; n <= hi; n += step) {
+        if (n >= min && n <= max) result.add(n);
+      }
+      continue;
+    }
+    // Range: A-B
+    if (part.includes('-')) {
+      const [lo, hi] = part.split('-').map(n => parseInt(n, 10));
+      for (let n = lo; n <= hi; n++) {
+        if (n >= min && n <= max) result.add(n);
+      }
+      continue;
+    }
+    // Wildcard
+    if (part === '*') {
+      for (let n = min; n <= max; n++) result.add(n);
+      continue;
+    }
+    // Single value
+    const n = parseInt(part, 10);
+    if (!Number.isNaN(n) && n >= min && n <= max) result.add(n);
+  }
+  return result;
+}
+
+/**
+ * Return true if `now` matches the cron expression at minute granularity.
+ * Format: "minute hour dayOfMonth month dayOfWeek" (5 fields, space-separated).
+ * Day-of-week: 0-6 (0 = Sunday). 7 is also accepted as Sunday alias.
+ */
+export function cronMatches(now: Date, expr: string): boolean {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length !== 5) return false;
+
+  const minutes = parseCronField(fields[0], 0, 59);
+  const hours = parseCronField(fields[1], 0, 23);
+  const daysOfMonth = parseCronField(fields[2], 1, 31);
+  const months = parseCronField(fields[3], 1, 12);
+  const daysOfWeekRaw = parseCronField(fields[4], 0, 7);
+  // Normalize: 7 == 0 (Sunday)
+  const daysOfWeek = new Set<number>();
+  for (const d of daysOfWeekRaw) daysOfWeek.add(d === 7 ? 0 : d);
+
+  return (
+    minutes.has(now.getMinutes()) &&
+    hours.has(now.getHours()) &&
+    daysOfMonth.has(now.getDate()) &&
+    months.has(now.getMonth() + 1) &&
+    daysOfWeek.has(now.getDay())
+  );
+}
+
+// --- Scheduler ---
+
+export class ConsolidationScheduler {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private running = false;
+  private readonly cronExpr: string;
+  private readonly disabled: boolean;
+  private lastCronTriggeredMinute: string | null = null;
+
+  constructor(
+    private store: EngramStore,
+    private consolidationEngine: ConsolidationEngine,
+  ) {
+    this.cronExpr = process.env.AWM_CONSOLIDATION_CRON ?? DEFAULT_CRON;
+    this.disabled = process.env.AWM_DISABLE_SCHEDULER === '1' || process.env.AWM_DISABLE_SCHEDULER === 'true';
+  }
+
+  start(): void {
+    if (this.timer) return;
+    if (this.disabled) {
+      console.log('ConsolidationScheduler disabled (AWM_DISABLE_SCHEDULER=1)');
+      return;
+    }
+    this.timer = setInterval(() => this.tick(), TICK_INTERVAL_MS);
+    console.log(`ConsolidationScheduler started - cron='${this.cronExpr}', quiescence-gate=${QUIESCENCE_THRESHOLD_MS / 60_000}min`);
+  }
+
+  stop(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    console.log('ConsolidationScheduler stopped');
+  }
+
+  /** True if the scheduler is currently running a consolidation cycle. */
+  isRunning(): boolean {
+    return this.running;
+  }
+
+  /** True if the scheduler's automatic triggers are disabled (kill switch). */
+  isDisabled(): boolean {
+    return this.disabled;
+  }
+
+  /**
+   * Mini-consolidation - lightweight, called from restore path.
+   * Only runs replay + strengthen (phases 1-2), skips heavy phases.
+   */
+  async runMiniConsolidation(agentId: string): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    try {
+      console.log(`[scheduler] mini-consolidation for ${agentId}`);
+      await this.consolidationEngine.consolidate(agentId);
+      await this.store.markConsolidation(agentId, true);
+    } catch (err) {
+      console.error(`[scheduler] mini-consolidation failed for ${agentId}:`, err);
+    } finally {
+      this.running = false;
+    }
+  }
+
+  /**
+   * Tick handler - checks both triggers. Cron first (planned), then quiescence (opportunistic).
+   * Fires consolidation for at most one agent per tick to avoid overload.
+   */
+  private async tick(): Promise<void> {
+    if (this.running) return;
+    const now = new Date();
+
+    // Trigger 1: cron
+    if (cronMatches(now, this.cronExpr)) {
+      const minuteKey = `${now.getFullYear()}-${now.getMonth()}-${now.getDate()}T${now.getHours()}:${now.getMinutes()}`;
+      if (this.lastCronTriggeredMinute !== minuteKey) {
+        this.lastCronTriggeredMinute = minuteKey;
+        const agent = await this.pickAgent();
+        if (agent) {
+          this.runFullConsolidation(agent.agentId, `cron (${this.cronExpr})`);
+          return;
+        }
+      }
+    }
+
+    // Trigger 2: quiescence
+    if (await this.isQuiescent(now)) {
+      const agent = await this.pickAgent();
+      if (agent) {
+        this.runFullConsolidation(agent.agentId, `quiescence (>${QUIESCENCE_THRESHOLD_MS / 60_000}min idle, all agents)`);
+        return;
+      }
+    }
+  }
+
+  /**
+   * Pick the agent that benefits most from consolidation:
+   * highest writeCount since last consolidation, tie-break by oldest consolidation.
+   */
+  private async pickAgent(): Promise<{ agentId: string } | null> {
+    const agents = await this.store.getActiveAgents();
+    if (agents.length === 0) return null;
+    const sorted = [...agents].sort((a, b) => {
+      if (b.writeCount !== a.writeCount) return b.writeCount - a.writeCount;
+      const aT = a.lastConsolidationAt?.getTime() ?? 0;
+      const bT = b.lastConsolidationAt?.getTime() ?? 0;
+      return aT - bT;
+    });
+    return sorted[0];
+  }
+
+  /**
+   * Quiescence check: ALL active agents must have lastActivityAt > threshold ago.
+   * `lastActivityAt` is updated on both writes and recalls so this captures both.
+   * If no active agents, the system is trivially quiescent.
+   */
+  private async isQuiescent(now: Date): Promise<boolean> {
+    const agents = await this.store.getActiveAgents();
+    if (agents.length === 0) return true;
+    const nowMs = now.getTime();
+    for (const agent of agents) {
+      const idleMs = nowMs - agent.lastActivityAt.getTime();
+      if (idleMs < QUIESCENCE_THRESHOLD_MS) return false;
+    }
+    return true;
+  }
+
+  private async runFullConsolidation(agentId: string, reason: string): Promise<void> {
+    this.running = true;
+    try {
+      console.log(`[scheduler] full consolidation for ${agentId} - trigger: ${reason}`);
+      const result = await this.consolidationEngine.consolidate(agentId);
+      await this.store.markConsolidation(agentId, false);
+      console.log(`[scheduler] consolidation done: ${result.edgesStrengthened} strengthened, ${result.memoriesForgotten} forgotten`);
+    } catch (err) {
+      console.error(`[scheduler] consolidation failed for ${agentId}:`, err);
+    } finally {
+      this.running = false;
+    }
+  }
+}