agent-working-memory 0.11.0 → 0.12.3

package/dist/storage/sqlite.js

@@ -154,119 +154,119 @@ export class EngramStore {
         }
     }
     init() {
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS engrams (
-        id TEXT PRIMARY KEY,
-        agent_id TEXT NOT NULL,
-        concept TEXT NOT NULL,
-        content TEXT NOT NULL,
-        embedding BLOB,
-        confidence REAL NOT NULL DEFAULT 0.5,
-        salience REAL NOT NULL DEFAULT 0.5,
-        access_count INTEGER NOT NULL DEFAULT 0,
-        last_accessed TEXT NOT NULL,
-        created_at TEXT NOT NULL,
-        salience_features TEXT NOT NULL DEFAULT '{}',
-        reason_codes TEXT NOT NULL DEFAULT '[]',
-        stage TEXT NOT NULL DEFAULT 'active',
-        ttl INTEGER,
-        retracted INTEGER NOT NULL DEFAULT 0,
-        retracted_by TEXT,
-        retracted_at TEXT,
-        tags TEXT NOT NULL DEFAULT '[]',
-        memory_type TEXT NOT NULL DEFAULT 'unclassified'
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_engrams_agent ON engrams(agent_id);
-      CREATE INDEX IF NOT EXISTS idx_engrams_stage ON engrams(agent_id, stage);
-      CREATE INDEX IF NOT EXISTS idx_engrams_concept ON engrams(concept);
-      CREATE INDEX IF NOT EXISTS idx_engrams_retracted ON engrams(agent_id, retracted);
-
-      CREATE TABLE IF NOT EXISTS associations (
-        id TEXT PRIMARY KEY,
-        from_engram_id TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
-        to_engram_id TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
-        weight REAL NOT NULL DEFAULT 0.1,
-        confidence REAL NOT NULL DEFAULT 0.5,
-        type TEXT NOT NULL DEFAULT 'hebbian',
-        activation_count INTEGER NOT NULL DEFAULT 0,
-        created_at TEXT NOT NULL,
-        last_activated TEXT NOT NULL
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_assoc_from ON associations(from_engram_id);
-      CREATE INDEX IF NOT EXISTS idx_assoc_to ON associations(to_engram_id);
-      CREATE UNIQUE INDEX IF NOT EXISTS idx_assoc_pair ON associations(from_engram_id, to_engram_id);
-
-      CREATE TABLE IF NOT EXISTS agents (
-        id TEXT PRIMARY KEY,
-        name TEXT NOT NULL,
-        created_at TEXT NOT NULL,
-        config TEXT NOT NULL DEFAULT '{}'
-      );
-
-      -- FTS5 for full-text search (BM25 ranking built in)
-      CREATE VIRTUAL TABLE IF NOT EXISTS engrams_fts USING fts5(
-        concept, content, tags,
-        content=engrams,
-        content_rowid=rowid
-      );
-
-      -- Triggers to keep FTS in sync
-      CREATE TRIGGER IF NOT EXISTS engrams_ai AFTER INSERT ON engrams BEGIN
-        INSERT INTO engrams_fts(rowid, concept, content, tags) VALUES (new.rowid, new.concept, new.content, new.tags);
-      END;
-      CREATE TRIGGER IF NOT EXISTS engrams_ad AFTER DELETE ON engrams BEGIN
-        INSERT INTO engrams_fts(engrams_fts, rowid, concept, content, tags) VALUES('delete', old.rowid, old.concept, old.content, old.tags);
-      END;
-      CREATE TRIGGER IF NOT EXISTS engrams_au AFTER UPDATE ON engrams BEGIN
-        INSERT INTO engrams_fts(engrams_fts, rowid, concept, content, tags) VALUES('delete', old.rowid, old.concept, old.content, old.tags);
-        INSERT INTO engrams_fts(rowid, concept, content, tags) VALUES (new.rowid, new.concept, new.content, new.tags);
-      END;
-
-      -- Eval event logs
-      CREATE TABLE IF NOT EXISTS activation_events (
-        id TEXT PRIMARY KEY,
-        agent_id TEXT NOT NULL,
-        timestamp TEXT NOT NULL,
-        context TEXT NOT NULL,
-        results_returned INTEGER NOT NULL,
-        top_score REAL,
-        latency_ms REAL NOT NULL,
-        engram_ids TEXT NOT NULL DEFAULT '[]'
-      );
-
-      CREATE TABLE IF NOT EXISTS staging_events (
-        engram_id TEXT NOT NULL,
-        agent_id TEXT NOT NULL,
-        action TEXT NOT NULL,
-        resonance_score REAL,
-        timestamp TEXT NOT NULL,
-        age_ms INTEGER NOT NULL
-      );
-
-      CREATE TABLE IF NOT EXISTS retrieval_feedback (
-        id TEXT PRIMARY KEY,
-        activation_event_id TEXT,
-        engram_id TEXT NOT NULL,
-        useful INTEGER NOT NULL,
-        context TEXT,
-        timestamp TEXT NOT NULL
-      );
-
-      CREATE TABLE IF NOT EXISTS episodes (
-        id TEXT PRIMARY KEY,
-        agent_id TEXT NOT NULL,
-        label TEXT NOT NULL,
-        embedding BLOB,
-        engram_count INTEGER NOT NULL DEFAULT 0,
-        start_time TEXT NOT NULL,
-        end_time TEXT NOT NULL,
-        created_at TEXT NOT NULL
-      );
-
-      CREATE INDEX IF NOT EXISTS idx_episodes_agent ON episodes(agent_id);
-      CREATE INDEX IF NOT EXISTS idx_episodes_time ON episodes(agent_id, end_time);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS engrams (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        concept TEXT NOT NULL,
+        content TEXT NOT NULL,
+        embedding BLOB,
+        confidence REAL NOT NULL DEFAULT 0.5,
+        salience REAL NOT NULL DEFAULT 0.5,
+        access_count INTEGER NOT NULL DEFAULT 0,
+        last_accessed TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        salience_features TEXT NOT NULL DEFAULT '{}',
+        reason_codes TEXT NOT NULL DEFAULT '[]',
+        stage TEXT NOT NULL DEFAULT 'active',
+        ttl INTEGER,
+        retracted INTEGER NOT NULL DEFAULT 0,
+        retracted_by TEXT,
+        retracted_at TEXT,
+        tags TEXT NOT NULL DEFAULT '[]',
+        memory_type TEXT NOT NULL DEFAULT 'unclassified'
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_engrams_agent ON engrams(agent_id);
+      CREATE INDEX IF NOT EXISTS idx_engrams_stage ON engrams(agent_id, stage);
+      CREATE INDEX IF NOT EXISTS idx_engrams_concept ON engrams(concept);
+      CREATE INDEX IF NOT EXISTS idx_engrams_retracted ON engrams(agent_id, retracted);
+
+      CREATE TABLE IF NOT EXISTS associations (
+        id TEXT PRIMARY KEY,
+        from_engram_id TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
+        to_engram_id TEXT NOT NULL REFERENCES engrams(id) ON DELETE CASCADE,
+        weight REAL NOT NULL DEFAULT 0.1,
+        confidence REAL NOT NULL DEFAULT 0.5,
+        type TEXT NOT NULL DEFAULT 'hebbian',
+        activation_count INTEGER NOT NULL DEFAULT 0,
+        created_at TEXT NOT NULL,
+        last_activated TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_assoc_from ON associations(from_engram_id);
+      CREATE INDEX IF NOT EXISTS idx_assoc_to ON associations(to_engram_id);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_assoc_pair ON associations(from_engram_id, to_engram_id);
+
+      CREATE TABLE IF NOT EXISTS agents (
+        id TEXT PRIMARY KEY,
+        name TEXT NOT NULL,
+        created_at TEXT NOT NULL,
+        config TEXT NOT NULL DEFAULT '{}'
+      );
+
+      -- FTS5 for full-text search (BM25 ranking built in)
+      CREATE VIRTUAL TABLE IF NOT EXISTS engrams_fts USING fts5(
+        concept, content, tags,
+        content=engrams,
+        content_rowid=rowid
+      );
+
+      -- Triggers to keep FTS in sync
+      CREATE TRIGGER IF NOT EXISTS engrams_ai AFTER INSERT ON engrams BEGIN
+        INSERT INTO engrams_fts(rowid, concept, content, tags) VALUES (new.rowid, new.concept, new.content, new.tags);
+      END;
+      CREATE TRIGGER IF NOT EXISTS engrams_ad AFTER DELETE ON engrams BEGIN
+        INSERT INTO engrams_fts(engrams_fts, rowid, concept, content, tags) VALUES('delete', old.rowid, old.concept, old.content, old.tags);
+      END;
+      CREATE TRIGGER IF NOT EXISTS engrams_au AFTER UPDATE ON engrams BEGIN
+        INSERT INTO engrams_fts(engrams_fts, rowid, concept, content, tags) VALUES('delete', old.rowid, old.concept, old.content, old.tags);
+        INSERT INTO engrams_fts(rowid, concept, content, tags) VALUES (new.rowid, new.concept, new.content, new.tags);
+      END;
+
+      -- Eval event logs
+      CREATE TABLE IF NOT EXISTS activation_events (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        timestamp TEXT NOT NULL,
+        context TEXT NOT NULL,
+        results_returned INTEGER NOT NULL,
+        top_score REAL,
+        latency_ms REAL NOT NULL,
+        engram_ids TEXT NOT NULL DEFAULT '[]'
+      );
+
+      CREATE TABLE IF NOT EXISTS staging_events (
+        engram_id TEXT NOT NULL,
+        agent_id TEXT NOT NULL,
+        action TEXT NOT NULL,
+        resonance_score REAL,
+        timestamp TEXT NOT NULL,
+        age_ms INTEGER NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS retrieval_feedback (
+        id TEXT PRIMARY KEY,
+        activation_event_id TEXT,
+        engram_id TEXT NOT NULL,
+        useful INTEGER NOT NULL,
+        context TEXT,
+        timestamp TEXT NOT NULL
+      );
+
+      CREATE TABLE IF NOT EXISTS episodes (
+        id TEXT PRIMARY KEY,
+        agent_id TEXT NOT NULL,
+        label TEXT NOT NULL,
+        embedding BLOB,
+        engram_count INTEGER NOT NULL DEFAULT 0,
+        start_time TEXT NOT NULL,
+        end_time TEXT NOT NULL,
+        created_at TEXT NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_episodes_agent ON episodes(agent_id);
+      CREATE INDEX IF NOT EXISTS idx_episodes_time ON episodes(agent_id, end_time);
     `);
         // Migration: add episode_id column if missing
         try {
@@ -280,10 +280,10 @@ export class EngramStore {
             this.db.prepare('SELECT task_status FROM engrams LIMIT 0').get();
         }
         catch {
-            this.db.exec(`
-        ALTER TABLE engrams ADD COLUMN task_status TEXT;
-        ALTER TABLE engrams ADD COLUMN task_priority TEXT;
-        ALTER TABLE engrams ADD COLUMN blocked_by TEXT;
+            this.db.exec(`
+        ALTER TABLE engrams ADD COLUMN task_status TEXT;
+        ALTER TABLE engrams ADD COLUMN task_priority TEXT;
+        ALTER TABLE engrams ADD COLUMN blocked_by TEXT;
       `);
             this.db.exec('CREATE INDEX IF NOT EXISTS idx_engrams_task ON engrams(agent_id, task_status)');
         }
@@ -292,10 +292,10 @@ export class EngramStore {
             this.db.prepare('SELECT memory_class FROM engrams LIMIT 0').get();
         }
         catch {
-            this.db.exec(`
-        ALTER TABLE engrams ADD COLUMN memory_class TEXT NOT NULL DEFAULT 'working';
-        ALTER TABLE engrams ADD COLUMN superseded_by TEXT;
-        ALTER TABLE engrams ADD COLUMN supersedes TEXT;
+            this.db.exec(`
+        ALTER TABLE engrams ADD COLUMN memory_class TEXT NOT NULL DEFAULT 'working';
+        ALTER TABLE engrams ADD COLUMN superseded_by TEXT;
+        ALTER TABLE engrams ADD COLUMN supersedes TEXT;
       `);
         }
         // Migration: add embedding_model for version tracking (prevents drift on model change)
@@ -305,23 +305,51 @@ export class EngramStore {
         catch {
             this.db.exec(`ALTER TABLE engrams ADD COLUMN embedding_model TEXT`);
         }
+        // Entity inverted index + alias table (D9, 2026-07-30) — write-time
+        // bookkeeping only; retrieval unchanged until D11. Idempotent CREATEs.
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS entity_mentions (
+        entity    TEXT NOT NULL,
+        engram_id TEXT NOT NULL,
+        agent_id  TEXT NOT NULL,
+        PRIMARY KEY (entity, engram_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_entity_mentions_agent ON entity_mentions(agent_id, entity);
+      CREATE TABLE IF NOT EXISTS entity_aliases (
+        alias  TEXT PRIMARY KEY,
+        entity TEXT NOT NULL
+      );
+    `);
+        // Migration: memory-spine provenance + temporal validity (D5/D8, 2026-07-30)
+        try {
+            this.db.prepare('SELECT origin_class FROM engrams LIMIT 0').get();
+        }
+        catch {
+            this.db.exec(`
+        ALTER TABLE engrams ADD COLUMN origin_class TEXT;
+        ALTER TABLE engrams ADD COLUMN writer_session TEXT;
+        ALTER TABLE engrams ADD COLUMN recipe_id TEXT;
+        ALTER TABLE engrams ADD COLUMN valid_from TEXT;
+        ALTER TABLE engrams ADD COLUMN valid_to TEXT;
+      `);
+        }
         // Migration: add conscious_state table for checkpointing
-        this.db.exec(`
-      CREATE TABLE IF NOT EXISTS conscious_state (
-        agent_id TEXT PRIMARY KEY,
-        last_write_id TEXT,
-        last_recall_context TEXT,
-        last_recall_ids TEXT NOT NULL DEFAULT '[]',
-        last_activity_at TEXT NOT NULL DEFAULT (datetime('now')),
-        write_count_since_consolidation INTEGER NOT NULL DEFAULT 0,
-        recall_count_since_consolidation INTEGER NOT NULL DEFAULT 0,
-        execution_state TEXT,
-        checkpoint_at TEXT,
-        last_consolidation_at TEXT,
-        last_mini_consolidation_at TEXT,
-        consolidation_cycle_count INTEGER NOT NULL DEFAULT 0,
-        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
-      )
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS conscious_state (
+        agent_id TEXT PRIMARY KEY,
+        last_write_id TEXT,
+        last_recall_context TEXT,
+        last_recall_ids TEXT NOT NULL DEFAULT '[]',
+        last_activity_at TEXT NOT NULL DEFAULT (datetime('now')),
+        write_count_since_consolidation INTEGER NOT NULL DEFAULT 0,
+        recall_count_since_consolidation INTEGER NOT NULL DEFAULT 0,
+        execution_state TEXT,
+        checkpoint_at TEXT,
+        last_consolidation_at TEXT,
+        last_mini_consolidation_at TEXT,
+        consolidation_cycle_count INTEGER NOT NULL DEFAULT 0,
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
     `);
         // Migration: add consolidation_cycle_count if missing (existing DBs)
         try {
@@ -342,7 +370,7 @@ export class EngramStore {
         }
         catch {
             this.db.exec(`ALTER TABLE engrams ADD COLUMN sequence INTEGER`);
-            this.db.exec(`CREATE INDEX IF NOT EXISTS idx_engrams_agent_sequence
+            this.db.exec(`CREATE INDEX IF NOT EXISTS idx_engrams_agent_sequence
          ON engrams(agent_id, sequence) WHERE sequence IS NOT NULL`);
         }
         // Migration (0.8 Cluster A): references_json column for typed cross-record
@@ -361,14 +389,14 @@ export class EngramStore {
         const embeddingBlob = input.embedding
             ? Buffer.from(new Float32Array(input.embedding).buffer)
             : null;
-        this.db.prepare(`
-      INSERT INTO engrams (id, agent_id, concept, content, embedding, confidence, salience,
-        access_count, last_accessed, created_at, salience_features, reason_codes, stage, tags, episode_id,
-        ttl, memory_class, supersedes, task_status, task_priority, blocked_by, memory_type,
-        sequence, references_json)
-      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        this.db.prepare(`
+      INSERT INTO engrams (id, agent_id, concept, content, embedding, confidence, salience,
+        access_count, last_accessed, created_at, salience_features, reason_codes, stage, tags, episode_id,
+        ttl, memory_class, supersedes, task_status, task_priority, blocked_by, memory_type,
+        sequence, references_json, origin_class, writer_session, recipe_id, valid_from, valid_to)
+      VALUES (?, ?, ?, ?, ?, ?, ?, 0, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
     `).run(id, input.agentId, input.concept, input.content, embeddingBlob, input.confidence ?? 0.5, input.salience ?? 0.5, now, now, JSON.stringify(input.salienceFeatures ?? DEFAULT_SALIENCE_FEATURES), JSON.stringify(input.reasonCodes ?? []), JSON.stringify(input.tags ?? []), input.episodeId ?? null, input.ttl ?? null, input.memoryClass ?? 'working', input.supersedes ?? null, input.taskStatus ?? null, input.taskPriority ?? null, input.blockedBy ?? null, input.memoryType ?? 'unclassified', input.sequence ?? null, input.references && input.references.length > 0
-            ? JSON.stringify(input.references) : null);
+            ? JSON.stringify(input.references) : null, input.originClass ?? null, input.writerSession ?? null, input.recipeId ?? null, input.validFrom ?? null, input.validTo ?? null);
         // Add to slim cache (skip if not yet populated — first slim fetch will load it)
         if (this.slimCachePopulated) {
             this.cacheAdd({
@@ -536,15 +564,15 @@ export class EngramStore {
         try {
             const placeholders = agentIds.map(() => '?').join(',');
             const innerLimit = Math.max(limit * 5, 50);
-            const rows = this.db.prepare(`
-        WITH top_fts AS (
-          SELECT rowid, rank FROM engrams_fts WHERE engrams_fts MATCH ? ORDER BY rank LIMIT ?
-        )
-        SELECT e.*, top_fts.rank FROM top_fts
-        JOIN engrams e ON e.rowid = top_fts.rowid
-        WHERE e.agent_id IN (${placeholders}) AND e.retracted = 0
-        ORDER BY top_fts.rank
-        LIMIT ?
+            const rows = this.db.prepare(`
+        WITH top_fts AS (
+          SELECT rowid, rank FROM engrams_fts WHERE engrams_fts MATCH ? ORDER BY rank LIMIT ?
+        )
+        SELECT e.*, top_fts.rank FROM top_fts
+        JOIN engrams e ON e.rowid = top_fts.rowid
+        WHERE e.agent_id IN (${placeholders}) AND e.retracted = 0
+        ORDER BY top_fts.rank
+        LIMIT ?
       `).all(sanitized, innerLimit, ...agentIds, limit);
             return rows.map(r => ({
                 engram: this.rowToEngram(r),
@@ -583,12 +611,12 @@ export class EngramStore {
      * Boost: +0.02 per access, scaled by 1/sqrt(accessCount+1), capped at 0.85.
      */
     touchEngram(id) {
-        this.db.prepare(`
-      UPDATE engrams
-      SET access_count = access_count + 1,
-          last_accessed = ?,
-          confidence = MIN(0.85, confidence + 0.02 / (1.0 + sqrt(access_count)))
-      WHERE id = ?
+        this.db.prepare(`
+      UPDATE engrams
+      SET access_count = access_count + 1,
+          last_accessed = ?,
+          confidence = MIN(0.85, confidence + 0.02 / (1.0 + sqrt(access_count)))
+      WHERE id = ?
     `).run(new Date().toISOString(), id);
     }
     updateStage(id, stage) {
@@ -618,8 +646,8 @@ export class EngramStore {
         this.cacheUpdateEmbedding(id, embedding);
     }
     retractEngram(id, retractedBy) {
-        this.db.prepare(`
-      UPDATE engrams SET retracted = 1, retracted_by = ?, retracted_at = ? WHERE id = ?
+        this.db.prepare(`
+      UPDATE engrams SET retracted = 1, retracted_by = ?, retracted_at = ? WHERE id = ?
     `).run(retractedBy, new Date().toISOString(), id);
         this.cacheRetract(id);
     }
@@ -636,20 +664,20 @@ export class EngramStore {
         let count = 0;
         const shiftSec = Math.round(ms / 1000);
         // Shift engram timestamps
-        const r1 = this.db.prepare(`
-      UPDATE engrams SET
-        created_at = datetime(created_at, '-${shiftSec} seconds'),
-        last_accessed = datetime(last_accessed, '-${shiftSec} seconds')
-      WHERE agent_id = ?
+        const r1 = this.db.prepare(`
+      UPDATE engrams SET
+        created_at = datetime(created_at, '-${shiftSec} seconds'),
+        last_accessed = datetime(last_accessed, '-${shiftSec} seconds')
+      WHERE agent_id = ?
     `).run(agentId);
         count += r1.changes;
         // Shift association timestamps
-        const r2 = this.db.prepare(`
-      UPDATE associations SET
-        created_at = datetime(created_at, '-${shiftSec} seconds'),
-        last_activated = datetime(last_activated, '-${shiftSec} seconds')
-      WHERE from_engram_id IN (SELECT id FROM engrams WHERE agent_id = ?)
-         OR to_engram_id IN (SELECT id FROM engrams WHERE agent_id = ?)
+        const r2 = this.db.prepare(`
+      UPDATE associations SET
+        created_at = datetime(created_at, '-${shiftSec} seconds'),
+        last_activated = datetime(last_activated, '-${shiftSec} seconds')
+      WHERE from_engram_id IN (SELECT id FROM engrams WHERE agent_id = ?)
+         OR to_engram_id IN (SELECT id FROM engrams WHERE agent_id = ?)
     `).run(agentId, agentId);
         count += r2.changes;
         return count;
@@ -728,15 +756,15 @@ export class EngramStore {
         // dominant, low retracted rate).
         try {
             const innerLimit = Math.max(limit * 5, 50);
-            const rows = this.db.prepare(`
-        WITH top_fts AS (
-          SELECT rowid, rank FROM engrams_fts WHERE engrams_fts MATCH ? ORDER BY rank LIMIT ?
-        )
-        SELECT e.*, top_fts.rank FROM top_fts
-        JOIN engrams e ON e.rowid = top_fts.rowid
-        WHERE e.agent_id = ? AND e.retracted = 0
-        ORDER BY top_fts.rank
-        LIMIT ?
+            const rows = this.db.prepare(`
+        WITH top_fts AS (
+          SELECT rowid, rank FROM engrams_fts WHERE engrams_fts MATCH ? ORDER BY rank LIMIT ?
+        )
+        SELECT e.*, top_fts.rank FROM top_fts
+        JOIN engrams e ON e.rowid = top_fts.rowid
+        WHERE e.agent_id = ? AND e.retracted = 0
+        ORDER BY top_fts.rank
+        LIMIT ?
       `).all(sanitized, innerLimit, agentId, limit);
             return rows.map(r => ({
                 engram: this.rowToEngram(r),
@@ -851,14 +879,14 @@ export class EngramStore {
             sql += ' AND task_status = ?';
             params.push(status);
         }
-        sql += ` ORDER BY
-      CASE task_priority
-        WHEN 'urgent' THEN 0
-        WHEN 'high' THEN 1
-        WHEN 'medium' THEN 2
-        WHEN 'low' THEN 3
-        ELSE 4
-      END,
+        sql += ` ORDER BY
+      CASE task_priority
+        WHEN 'urgent' THEN 0
+        WHEN 'high' THEN 1
+        WHEN 'medium' THEN 2
+        WHEN 'low' THEN 3
+        ELSE 4
+      END,
       created_at DESC`;
         return this.db.prepare(sql).all(...params).map(r => this.rowToEngram(r));
     }
@@ -866,20 +894,20 @@ export class EngramStore {
      * Get the next actionable task — highest priority that's not blocked or done.
      */
     getNextTask(agentId) {
-        const row = this.db.prepare(`
-      SELECT * FROM engrams
-      WHERE agent_id = ? AND task_status IN ('open', 'in_progress') AND retracted = 0
-      ORDER BY
-        CASE task_status WHEN 'in_progress' THEN 0 ELSE 1 END,
-        CASE task_priority
-          WHEN 'urgent' THEN 0
-          WHEN 'high' THEN 1
-          WHEN 'medium' THEN 2
-          WHEN 'low' THEN 3
-          ELSE 4
-        END,
-        created_at ASC
-      LIMIT 1
+        const row = this.db.prepare(`
+      SELECT * FROM engrams
+      WHERE agent_id = ? AND task_status IN ('open', 'in_progress') AND retracted = 0
+      ORDER BY
+        CASE task_status WHEN 'in_progress' THEN 0 ELSE 1 END,
+        CASE task_priority
+          WHEN 'urgent' THEN 0
+          WHEN 'high' THEN 1
+          WHEN 'medium' THEN 2
+          WHEN 'low' THEN 3
+          ELSE 4
+        END,
+        created_at ASC
+      LIMIT 1
     `).get(agentId);
         return row ? this.rowToEngram(row) : null;
     }
@@ -901,11 +929,11 @@ export class EngramStore {
      * Returns null if no match.
      */
     findActiveMatchByConcept(agentId, concept, requiredTags) {
-        let sql = `SELECT * FROM engrams
-               WHERE agent_id = ?
-               AND LOWER(TRIM(concept)) = LOWER(TRIM(?))
-               AND stage = 'active'
-               AND retracted = 0
+        let sql = `SELECT * FROM engrams
+               WHERE agent_id = ?
+               AND LOWER(TRIM(concept)) = LOWER(TRIM(?))
+               AND stage = 'active'
+               AND retracted = 0
                AND superseded_by IS NULL`;
         const params = [agentId, concept];
         if (requiredTags && requiredTags.length > 0) {
@@ -935,11 +963,11 @@ export class EngramStore {
     upsertAssociation(fromId, toId, weight, type = 'hebbian', confidence = 0.5) {
         const now = new Date().toISOString();
         const id = randomUUID();
-        this.db.prepare(`
-      INSERT INTO associations (id, from_engram_id, to_engram_id, weight, confidence, type, activation_count, created_at, last_activated)
-      VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)
-      ON CONFLICT(from_engram_id, to_engram_id) DO UPDATE SET
-        weight = ?, confidence = ?, last_activated = ?, activation_count = activation_count + 1
+        this.db.prepare(`
+      INSERT INTO associations (id, from_engram_id, to_engram_id, weight, confidence, type, activation_count, created_at, last_activated)
+      VALUES (?, ?, ?, ?, ?, ?, 0, ?, ?)
+      ON CONFLICT(from_engram_id, to_engram_id) DO UPDATE SET
+        weight = ?, confidence = ?, last_activated = ?, activation_count = activation_count + 1
     `).run(id, fromId, toId, weight, confidence, type, now, now, weight, confidence, now);
         return this.getAssociation(fromId, toId);
     }
@@ -979,12 +1007,12 @@ export class EngramStore {
             // associations under both their from and to engram. Self-loops would be
             // double-counted, but they're rare in practice and the prior code handled them
             // identically.
-            const rows = this.db.prepare(`SELECT id, SUM(cnt) AS count, SUM(sw) AS sum_weight FROM (
-           SELECT from_engram_id AS id, 1 AS cnt, weight AS sw FROM associations WHERE from_engram_id IN (${placeholders})
-           UNION ALL
-           SELECT to_engram_id AS id, 1 AS cnt, weight AS sw FROM associations WHERE to_engram_id IN (${placeholders})
-         )
-         WHERE id IN (${placeholders})
+            const rows = this.db.prepare(`SELECT id, SUM(cnt) AS count, SUM(sw) AS sum_weight FROM (
+           SELECT from_engram_id AS id, 1 AS cnt, weight AS sw FROM associations WHERE from_engram_id IN (${placeholders})
+           UNION ALL
+           SELECT to_engram_id AS id, 1 AS cnt, weight AS sw FROM associations WHERE to_engram_id IN (${placeholders})
+         )
+         WHERE id IN (${placeholders})
          GROUP BY id`).all(...chunk, ...chunk, ...chunk);
             for (const r of rows) {
                 result.set(r.id, { count: r.count, sumWeight: r.sum_weight });
@@ -1015,7 +1043,7 @@ export class EngramStore {
         for (let i = 0; i < engramIds.length; i += CHUNK) {
             const chunk = engramIds.slice(i, i + CHUNK);
             const placeholders = chunk.map(() => '?').join(',');
-            const rows = this.db.prepare(`SELECT * FROM associations
+            const rows = this.db.prepare(`SELECT * FROM associations
          WHERE from_engram_id IN (${placeholders}) OR to_engram_id IN (${placeholders})`).all(...chunk, ...chunk);
             for (const r of rows) {
                 const a = this.rowToAssociation(r);
@@ -1054,22 +1082,22 @@ export class EngramStore {
         this.db.prepare('DELETE FROM associations WHERE id = ?').run(id);
     }
     getAllAssociations(agentId) {
-        const rows = this.db.prepare(`
-      SELECT a.* FROM associations a
-      JOIN engrams e ON a.from_engram_id = e.id
-      WHERE e.agent_id = ?
+        const rows = this.db.prepare(`
+      SELECT a.* FROM associations a
+      JOIN engrams e ON a.from_engram_id = e.id
+      WHERE e.agent_id = ?
     `).all(agentId);
         return rows.map(r => this.rowToAssociation(r));
     }
     // --- Eviction ---
     getEvictionCandidates(agentId, limit) {
         // Lowest combined score: low salience + low access + low confidence + oldest
-        const rows = this.db.prepare(`
-      SELECT * FROM engrams
-      WHERE agent_id = ? AND stage = 'active' AND retracted = 0
-      ORDER BY (salience * 0.3 + confidence * 0.3 + (CAST(access_count AS REAL) / (access_count + 5)) * 0.2 +
-        (1.0 / (1.0 + (julianday('now') - julianday(last_accessed)))) * 0.2) ASC
-      LIMIT ?
+        const rows = this.db.prepare(`
+      SELECT * FROM engrams
+      WHERE agent_id = ? AND stage = 'active' AND retracted = 0
+      ORDER BY (salience * 0.3 + confidence * 0.3 + (CAST(access_count AS REAL) / (access_count + 5)) * 0.2 +
+        (1.0 / (1.0 + (julianday('now') - julianday(last_accessed)))) * 0.2) ASC
+      LIMIT ?
     `).all(agentId, limit);
         return rows.map(r => this.rowToEngram(r));
     }
@@ -1084,8 +1112,8 @@ export class EngramStore {
     // --- Staging buffer ---
     getExpiredStaging() {
         const now = Date.now();
-        const rows = this.db.prepare(`
-      SELECT * FROM engrams WHERE stage = 'staging' AND ttl IS NOT NULL
+        const rows = this.db.prepare(`
+      SELECT * FROM engrams WHERE stage = 'staging' AND ttl IS NOT NULL
     `).all();
         return rows
             .map(r => this.rowToEngram(r))
@@ -1093,53 +1121,53 @@ export class EngramStore {
     }
     // --- Eval event logging ---
     logActivationEvent(event) {
-        this.db.prepare(`
-      INSERT INTO activation_events (id, agent_id, timestamp, context, results_returned, top_score, latency_ms, engram_ids)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        this.db.prepare(`
+      INSERT INTO activation_events (id, agent_id, timestamp, context, results_returned, top_score, latency_ms, engram_ids)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
     `).run(event.id, event.agentId, event.timestamp.toISOString(), event.context, event.resultsReturned, event.topScore, event.latencyMs, JSON.stringify(event.engramIds));
     }
     logStagingEvent(event) {
-        this.db.prepare(`
-      INSERT INTO staging_events (engram_id, agent_id, action, resonance_score, timestamp, age_ms)
-      VALUES (?, ?, ?, ?, ?, ?)
+        this.db.prepare(`
+      INSERT INTO staging_events (engram_id, agent_id, action, resonance_score, timestamp, age_ms)
+      VALUES (?, ?, ?, ?, ?, ?)
     `).run(event.engramId, event.agentId, event.action, event.resonanceScore, event.timestamp.toISOString(), event.ageMs);
     }
     logRetrievalFeedback(activationEventId, engramId, useful, context) {
-        this.db.prepare(`
-      INSERT INTO retrieval_feedback (id, activation_event_id, engram_id, useful, context, timestamp)
-      VALUES (?, ?, ?, ?, ?, ?)
+        this.db.prepare(`
+      INSERT INTO retrieval_feedback (id, activation_event_id, engram_id, useful, context, timestamp)
+      VALUES (?, ?, ?, ?, ?, ?)
     `).run(randomUUID(), activationEventId, engramId, useful ? 1 : 0, context, new Date().toISOString());
     }
     // --- Eval metrics queries ---
     getRetrievalPrecision(agentId, windowHours = 24) {
         const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
-        const row = this.db.prepare(`
-      SELECT
-        COUNT(CASE WHEN useful = 1 THEN 1 END) as useful_count,
-        COUNT(*) as total_count
-      FROM retrieval_feedback rf
-      LEFT JOIN activation_events ae ON rf.activation_event_id = ae.id
-      JOIN engrams e ON rf.engram_id = e.id
-      WHERE e.agent_id = ? AND rf.timestamp > ?
+        const row = this.db.prepare(`
+      SELECT
+        COUNT(CASE WHEN useful = 1 THEN 1 END) as useful_count,
+        COUNT(*) as total_count
+      FROM retrieval_feedback rf
+      LEFT JOIN activation_events ae ON rf.activation_event_id = ae.id
+      JOIN engrams e ON rf.engram_id = e.id
+      WHERE e.agent_id = ? AND rf.timestamp > ?
     `).get(agentId, since);
         return row.total_count > 0 ? row.useful_count / row.total_count : 0;
     }
     getStagingMetrics(agentId) {
-        const row = this.db.prepare(`
-      SELECT
-        COUNT(CASE WHEN action = 'promoted' THEN 1 END) as promoted,
-        COUNT(CASE WHEN action = 'discarded' THEN 1 END) as discarded,
-        COUNT(CASE WHEN action = 'expired' THEN 1 END) as expired
-      FROM staging_events WHERE agent_id = ?
+        const row = this.db.prepare(`
+      SELECT
+        COUNT(CASE WHEN action = 'promoted' THEN 1 END) as promoted,
+        COUNT(CASE WHEN action = 'discarded' THEN 1 END) as discarded,
+        COUNT(CASE WHEN action = 'expired' THEN 1 END) as expired
+      FROM staging_events WHERE agent_id = ?
     `).get(agentId);
         return { promoted: row.promoted, discarded: row.discarded, expired: row.expired };
     }
     getActivationStats(agentId, windowHours = 24) {
         const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
-        const rows = this.db.prepare(`
-      SELECT latency_ms FROM activation_events
-      WHERE agent_id = ? AND timestamp > ?
-      ORDER BY latency_ms ASC
+        const rows = this.db.prepare(`
+      SELECT latency_ms FROM activation_events
+      WHERE agent_id = ? AND timestamp > ?
+      ORDER BY latency_ms ASC
     `).all(agentId, since);
         if (rows.length === 0)
             return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
@@ -1188,6 +1216,11 @@ export class EngramStore {
             blockedBy: row.blocked_by ?? null,
             sequence: row.sequence == null ? null : Number(row.sequence),
             references: row.references_json ? JSON.parse(row.references_json) : null,
+            originClass: row.origin_class ?? null,
+            writerSession: row.writer_session ?? null,
+            recipeId: row.recipe_id ?? null,
+            validFrom: row.valid_from ?? null,
+            validTo: row.valid_to ?? null,
         };
     }
     rowToAssociation(row) {
@@ -1210,9 +1243,9 @@ export class EngramStore {
         const embeddingBlob = input.embedding
             ? Buffer.from(new Float32Array(input.embedding).buffer)
             : null;
-        this.db.prepare(`
-      INSERT INTO episodes (id, agent_id, label, embedding, engram_count, start_time, end_time, created_at)
-      VALUES (?, ?, ?, ?, 0, ?, ?, ?)
+        this.db.prepare(`
+      INSERT INTO episodes (id, agent_id, label, embedding, engram_count, start_time, end_time, created_at)
+      VALUES (?, ?, ?, ?, 0, ?, ?, ?)
     `).run(id, input.agentId, input.label, embeddingBlob, now, now, now);
         return this.getEpisode(id);
     }
@@ -1227,19 +1260,19 @@ export class EngramStore {
     getActiveEpisode(agentId, windowMs = 3600_000) {
         // Find most recent episode that ended within the time window
         const cutoff = new Date(Date.now() - windowMs).toISOString();
-        const row = this.db.prepare(`
-      SELECT * FROM episodes WHERE agent_id = ? AND end_time > ?
-      ORDER BY end_time DESC LIMIT 1
+        const row = this.db.prepare(`
+      SELECT * FROM episodes WHERE agent_id = ? AND end_time > ?
+      ORDER BY end_time DESC LIMIT 1
     `).get(agentId, cutoff);
         return row ? this.rowToEpisode(row) : null;
     }
     addEngramToEpisode(engramId, episodeId) {
         this.db.prepare('UPDATE engrams SET episode_id = ? WHERE id = ?').run(episodeId, engramId);
-        this.db.prepare(`
-      UPDATE episodes SET
-        engram_count = engram_count + 1,
-        end_time = MAX(end_time, ?)
-      WHERE id = ?
+        this.db.prepare(`
+      UPDATE episodes SET
+        engram_count = engram_count + 1,
+        end_time = MAX(end_time, ?)
+      WHERE id = ?
     `).run(new Date().toISOString(), episodeId);
     }
     getEngramsByEpisode(episodeId) {
@@ -1290,51 +1323,86 @@ export class EngramStore {
     // --- Checkpointing ---
     updateAutoCheckpointWrite(agentId, engramId) {
         const now = new Date().toISOString();
-        this.db.prepare(`
-      INSERT INTO conscious_state (agent_id, last_write_id, last_activity_at, write_count_since_consolidation, updated_at)
-      VALUES (?, ?, ?, 1, ?)
-      ON CONFLICT(agent_id) DO UPDATE SET
-        last_write_id = excluded.last_write_id,
-        last_activity_at = excluded.last_activity_at,
-        write_count_since_consolidation = write_count_since_consolidation + 1,
-        updated_at = excluded.updated_at
+        this.db.prepare(`
+      INSERT INTO conscious_state (agent_id, last_write_id, last_activity_at, write_count_since_consolidation, updated_at)
+      VALUES (?, ?, ?, 1, ?)
+      ON CONFLICT(agent_id) DO UPDATE SET
+        last_write_id = excluded.last_write_id,
+        last_activity_at = excluded.last_activity_at,
+        write_count_since_consolidation = write_count_since_consolidation + 1,
+        updated_at = excluded.updated_at
     `).run(agentId, engramId, now, now);
     }
     updateAutoCheckpointRecall(agentId, context, engramIds) {
         const now = new Date().toISOString();
-        this.db.prepare(`
-      INSERT INTO conscious_state (agent_id, last_recall_context, last_recall_ids, last_activity_at, recall_count_since_consolidation, updated_at)
-      VALUES (?, ?, ?, ?, 1, ?)
-      ON CONFLICT(agent_id) DO UPDATE SET
-        last_recall_context = excluded.last_recall_context,
-        last_recall_ids = excluded.last_recall_ids,
-        last_activity_at = excluded.last_activity_at,
-        recall_count_since_consolidation = recall_count_since_consolidation + 1,
-        updated_at = excluded.updated_at
+        this.db.prepare(`
+      INSERT INTO conscious_state (agent_id, last_recall_context, last_recall_ids, last_activity_at, recall_count_since_consolidation, updated_at)
+      VALUES (?, ?, ?, ?, 1, ?)
+      ON CONFLICT(agent_id) DO UPDATE SET
+        last_recall_context = excluded.last_recall_context,
+        last_recall_ids = excluded.last_recall_ids,
+        last_activity_at = excluded.last_activity_at,
+        recall_count_since_consolidation = recall_count_since_consolidation + 1,
+        updated_at = excluded.updated_at
     `).run(agentId, context, JSON.stringify(engramIds), now, now);
     }
     touchActivity(agentId) {
         const now = new Date().toISOString();
-        this.db.prepare(`
-      INSERT INTO conscious_state (agent_id, last_activity_at, updated_at)
-      VALUES (?, ?, ?)
-      ON CONFLICT(agent_id) DO UPDATE SET
-        last_activity_at = excluded.last_activity_at,
-        updated_at = excluded.updated_at
+        this.db.prepare(`
+      INSERT INTO conscious_state (agent_id, last_activity_at, updated_at)
+      VALUES (?, ?, ?)
+      ON CONFLICT(agent_id) DO UPDATE SET
+        last_activity_at = excluded.last_activity_at,
+        updated_at = excluded.updated_at
     `).run(agentId, now, now);
     }
     saveCheckpoint(agentId, state) {
         const now = new Date().toISOString();
-        this.db.prepare(`
-      INSERT INTO conscious_state (agent_id, execution_state, checkpoint_at, last_activity_at, updated_at)
-      VALUES (?, ?, ?, ?, ?)
-      ON CONFLICT(agent_id) DO UPDATE SET
-        execution_state = excluded.execution_state,
-        checkpoint_at = excluded.checkpoint_at,
-        last_activity_at = excluded.last_activity_at,
-        updated_at = excluded.updated_at
+        this.db.prepare(`
+      INSERT INTO conscious_state (agent_id, execution_state, checkpoint_at, last_activity_at, updated_at)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(agent_id) DO UPDATE SET
+        execution_state = excluded.execution_state,
+        checkpoint_at = excluded.checkpoint_at,
+        last_activity_at = excluded.last_activity_at,
+        updated_at = excluded.updated_at
     `).run(agentId, JSON.stringify(state), now, now, now);
     }
+    /** Record entity mentions for an engram (D9 inverted index; idempotent). */
+    recordEntityMentions(engramId, agentId, entities) {
+        if (!entities || entities.length === 0)
+            return;
+        const stmt = this.db.prepare('INSERT OR IGNORE INTO entity_mentions (entity, engram_id, agent_id) VALUES (?, ?, ?)');
+        for (const entity of entities)
+            stmt.run(entity, engramId, agentId);
+    }
+    /** Indexed entities whose normalized key:value — or a registered alias — contains the term
+     *  (D11 query-side lookup). Alias matches resolve to their target entity. */
+    searchEntities(term, limit = 8) {
+        const t = term.toLowerCase().replace(/[%_]/g, '');
+        if (!t)
+            return [];
+        const rows = this.db.prepare(`
+      SELECT DISTINCT entity FROM (
+        SELECT entity FROM entity_mentions WHERE entity LIKE ?
+        UNION SELECT entity FROM entity_aliases WHERE alias LIKE ?
+      ) LIMIT ?`).all(`%${t}%`, `%${t}%`, limit);
+        return rows.map(r => r.entity);
+    }
+    /** Engram ids mentioning an entity (alias-resolved), optionally agent-scoped. */
+    getEngramIdsByEntity(entity, agentId) {
+        const resolved = this.db.prepare('SELECT entity FROM entity_aliases WHERE alias = ?')
+            .get(entity.toLowerCase())?.entity ?? entity.toLowerCase();
+        const rows = agentId
+            ? this.db.prepare('SELECT engram_id FROM entity_mentions WHERE entity = ? AND agent_id = ?').all(resolved, agentId)
+            : this.db.prepare('SELECT engram_id FROM entity_mentions WHERE entity = ?').all(resolved);
+        return rows.map(r => r.engram_id);
+    }
+    /** Distinct agent ids present in this store (D3 whoami; includes all stages). */
+    listAgentIds() {
+        const rows = this.db.prepare('SELECT DISTINCT agent_id FROM engrams ORDER BY agent_id').all();
+        return rows.map(r => r.agent_id);
+    }
     getCheckpoint(agentId) {
         const row = this.db.prepare('SELECT * FROM conscious_state WHERE agent_id = ?').get(agentId);
         if (!row)
@@ -1359,20 +1427,20 @@ export class EngramStore {
     markConsolidation(agentId, mini) {
         const now = new Date().toISOString();
         if (mini) {
-            this.db.prepare(`
-        UPDATE conscious_state SET last_mini_consolidation_at = ?, updated_at = ? WHERE agent_id = ?
+            this.db.prepare(`
+        UPDATE conscious_state SET last_mini_consolidation_at = ?, updated_at = ? WHERE agent_id = ?
       `).run(now, now, agentId);
         }
         else {
-            this.db.prepare(`
-        UPDATE conscious_state SET
-          last_consolidation_at = ?,
-          last_mini_consolidation_at = ?,
-          write_count_since_consolidation = 0,
-          recall_count_since_consolidation = 0,
-          consolidation_cycle_count = consolidation_cycle_count + 1,
-          updated_at = ?
-        WHERE agent_id = ?
+            this.db.prepare(`
+        UPDATE conscious_state SET
+          last_consolidation_at = ?,
+          last_mini_consolidation_at = ?,
+          write_count_since_consolidation = 0,
+          recall_count_since_consolidation = 0,
+          consolidation_cycle_count = consolidation_cycle_count + 1,
+          updated_at = ?
+        WHERE agent_id = ?
       `).run(now, now, now, agentId);
         }
     }
@@ -1443,10 +1511,10 @@ export class EngramStore {
      * sequence are excluded (they have no story-time anchor).
      */
     getLatestByTag(opts) {
-        let sql = `SELECT * FROM engrams
-               WHERE agent_id = ?
-               AND retracted = ?
-               AND stage = 'active'
+        let sql = `SELECT * FROM engrams
+               WHERE agent_id = ?
+               AND retracted = ?
+               AND stage = 'active'
                AND tags LIKE ?`;
         const params = [
             opts.agentId,
@@ -1486,10 +1554,10 @@ export class EngramStore {
      */
     getTopBy(opts) {
         // Build the base query inline (mirrors search() but adds the topBy sort).
-        let sql = `SELECT * FROM engrams
-               WHERE agent_id = ?
-               AND retracted = ?
-               AND stage = 'active'
+        let sql = `SELECT * FROM engrams
+               WHERE agent_id = ?
+               AND retracted = ?
+               AND stage = 'active'
                AND tags LIKE ?`;
         const params = [
             opts.agentId,
@@ -1557,11 +1625,11 @@ export class EngramStore {
         // Find candidate referencing engrams. LIKE-filter first to narrow,
         // then JSON.parse each candidate's references_json to verify the
         // matchEngramId and type. Cheap enough at NovelForge's scale.
-        const candidates = this.db.prepare(`SELECT id, references_json, created_at FROM engrams
-       WHERE agent_id = ?
-       AND retracted = 0
-       AND stage = 'active'
-       AND references_json IS NOT NULL
+        const candidates = this.db.prepare(`SELECT id, references_json, created_at FROM engrams
+       WHERE agent_id = ?
+       AND retracted = 0
+       AND stage = 'active'
+       AND references_json IS NOT NULL
        AND references_json LIKE ?`).all(target.agentId, `%"${targetEngramId}"%`);
         const terminalTypes = new Set(['resolves', 'subverts', 'abandons']);
         const resolvingEvents = [];