agent-working-memory 0.17.0 → 0.19.0

package/dist/storage/sqlite.js

@@ -37,6 +37,21 @@ export class EngramStore {
         this.db.pragma('busy_timeout = 5000');
         this.db.pragma('synchronous = NORMAL');
         this.db.pragma('wal_autocheckpoint = 1000');
+        // Page cache and mmap (0.19). Until now the store ran on SQLite's 2 MB default
+        // page cache against a ~270 MB file, so the BM25 and association-stats
+        // phases of a recall paid page faults on every query: 42 ms / 14 ms at p50
+        // but 156 ms / 167 ms at p95 in the 2026-10-19 profile. 64 MB of cache
+        // holds the hot FTS and association pages; mmap lets reads come straight
+        // from the OS file cache without a copy. Both are per-connection settings
+        // with no effect on results; mmap is safe with WAL and multiple processes.
+        // AWM_SQLITE_CACHE_MB / AWM_SQLITE_MMAP_MB override (0 = SQLite default).
+        const cacheMb = Number(process.env.AWM_SQLITE_CACHE_MB ?? 64);
+        const mmapMb = Number(process.env.AWM_SQLITE_MMAP_MB ?? 256);
+        if (Number.isFinite(cacheMb) && cacheMb > 0)
+            this.db.pragma(`cache_size = ${-Math.round(cacheMb * 1024)}`);
+        if (Number.isFinite(mmapMb) && mmapMb > 0)
+            this.db.pragma(`mmap_size = ${Math.round(mmapMb * 1024 * 1024)}`);
+        this.db.pragma('temp_store = MEMORY');
         this.init();
         this.startWalCheckpointTimer();
     }
@@ -154,123 +169,123 @@ 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);
-      -- Serves getTopAccessedTags: the recall path's pronoun branch needs the ten
-      -- most-accessed engrams, and without this it filters then sorts the whole
-      -- agent partition on every query containing "it", "this" or "that".
-      CREATE INDEX IF NOT EXISTS idx_engrams_access ON engrams(agent_id, stage, access_count DESC);
-
-      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);
+      -- Serves getTopAccessedTags: the recall path's pronoun branch needs the ten
+      -- most-accessed engrams, and without this it filters then sorts the whole
+      -- agent partition on every query containing "it", "this" or "that".
+      CREATE INDEX IF NOT EXISTS idx_engrams_access ON engrams(agent_id, stage, access_count DESC);
+
+      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 {
@@ -284,10 +299,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)');
         }
@@ -296,10 +311,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)
@@ -311,49 +326,57 @@ export class EngramStore {
         }
         // 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
-      );
+        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;
+            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: stage-transition timestamp (A-4, 2026-10-12). Additive, nullable,
+        // no backfill — null means "never transitioned", so readers fall back to created_at.
+        try {
+            this.db.prepare('SELECT stage_changed_at FROM engrams LIMIT 0').get();
+        }
+        catch {
+            this.db.exec(`ALTER TABLE engrams ADD COLUMN stage_changed_at 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 {
@@ -374,7 +397,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
@@ -393,12 +416,12 @@ 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, origin_class, writer_session, recipe_id, valid_from, valid_to)
-      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, 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)
@@ -578,11 +601,11 @@ export class EngramStore {
     getTopAccessedTags(agentIds, topN, stage = 'active') {
         if (agentIds.length === 0 || topN <= 0)
             return [];
-        const stmt = this.db.prepare(`
-      SELECT tags, access_count AS accessCount, id FROM engrams
-      WHERE agent_id = ? AND stage = ? AND retracted = 0
-      ORDER BY access_count DESC, id
-      LIMIT ?
+        const stmt = this.db.prepare(`
+      SELECT tags, access_count AS accessCount, id FROM engrams
+      WHERE agent_id = ? AND stage = ? AND retracted = 0
+      ORDER BY access_count DESC, id
+      LIMIT ?
     `);
         const rows = [];
         for (const agentId of agentIds) {
@@ -620,15 +643,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),
@@ -667,16 +690,22 @@ 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);
     }
+    /**
+     * Move an engram to a new stage, recording WHEN. The timestamp is written here
+     * rather than at the six consolidation call sites so a future transition cannot
+     * forget it; see `Engram.stageChangedAt` for why the column exists.
+     */
     updateStage(id, stage) {
-        this.db.prepare('UPDATE engrams SET stage = ? WHERE id = ?').run(stage, id);
+        this.db.prepare('UPDATE engrams SET stage = ?, stage_changed_at = ? WHERE id = ?')
+            .run(stage, new Date().toISOString(), id);
         this.cacheUpdateStage(id, stage);
     }
     /**
@@ -702,13 +731,35 @@ 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);
     }
+    /**
+     * Delete an engram and everything that points at it.
+     *
+     * `associations` cascades (its FKs declare ON DELETE CASCADE), but
+     * `retrieval_feedback`, `entity_mentions` and `staging_events` carry a bare
+     * `engram_id TEXT` with no foreign key, so deleting an engram used to strand their
+     * rows. Measured on the live store 2026-10-12: **571 orphaned retrieval_feedback
+     * rows and 3 orphaned entity_mentions**, present in the pre-purge backup too, so
+     * they accumulated over time rather than in one incident. Inert for recall, but
+     * they corrupt any join that assumes referential integrity — including the
+     * feedback-weighted scoring channel's own counts.
+     *
+     * One transaction, so a crash cannot leave the half-deleted state this is fixing.
+     * `activation_events` is deliberately NOT touched: its `engram_ids` is a JSON array
+     * describing a recall that really happened, and editing history to remove one id
+     * would falsify the event rather than tidy it.
+     */
     deleteEngram(id) {
-        this.db.prepare('DELETE FROM engrams WHERE id = ?').run(id);
+        this.db.transaction(() => {
+            this.db.prepare('DELETE FROM retrieval_feedback WHERE engram_id = ?').run(id);
+            this.db.prepare('DELETE FROM entity_mentions WHERE engram_id = ?').run(id);
+            this.db.prepare('DELETE FROM staging_events WHERE engram_id = ?').run(id);
+            this.db.prepare('DELETE FROM engrams WHERE id = ?').run(id);
+        })();
         this.cacheRemove(id);
     }
     /**
@@ -720,20 +771,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;
@@ -812,15 +863,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),
@@ -940,14 +991,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));
     }
@@ -955,20 +1006,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;
     }
@@ -990,11 +1041,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) {
@@ -1029,11 +1080,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);
     }
@@ -1073,12 +1124,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 });
@@ -1109,7 +1160,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);
@@ -1148,22 +1199,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));
     }
@@ -1178,8 +1229,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))
@@ -1187,53 +1238,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, p50LatencyMs: 0, p90LatencyMs: 0, p95LatencyMs: 0 };
@@ -1258,11 +1309,11 @@ export class EngramStore {
      */
     getLinkedFeedbackStats(agentId, windowHours = 24 * 7) {
         const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
-        const row = this.db.prepare(`
-      SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = 1 THEN 1 END) AS useful
-      FROM retrieval_feedback rf
-      JOIN activation_events ae ON ae.id = rf.activation_event_id
-      WHERE ae.agent_id = ? AND rf.timestamp > ?
+        const row = this.db.prepare(`
+      SELECT COUNT(*) AS total, COUNT(CASE WHEN rf.useful = 1 THEN 1 END) AS useful
+      FROM retrieval_feedback rf
+      JOIN activation_events ae ON ae.id = rf.activation_event_id
+      WHERE ae.agent_id = ? AND rf.timestamp > ?
     `).get(agentId, since);
         return { total: row.total, useful: row.useful };
     }
@@ -1308,6 +1359,7 @@ export class EngramStore {
             recipeId: row.recipe_id ?? null,
             validFrom: row.valid_from ?? null,
             validTo: row.valid_to ?? null,
+            stageChangedAt: row.stage_changed_at ?? null,
         };
     }
     rowToAssociation(row) {
@@ -1330,9 +1382,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);
     }
@@ -1347,19 +1399,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) {
@@ -1410,49 +1462,49 @@ 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). */
@@ -1469,10 +1521,10 @@ export class EngramStore {
         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 ?
+        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);
     }
@@ -1514,20 +1566,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);
         }
     }
@@ -1598,10 +1650,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,
@@ -1641,10 +1693,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,
@@ -1712,11 +1764,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 = [];