agent-working-memory 0.5.5 → 0.6.0

package/dist/storage/sqlite.js

@@ -25,121 +25,147 @@ export class EngramStore {
         this.db = new Database(dbPath);
         this.db.pragma('journal_mode = WAL');
         this.db.pragma('foreign_keys = ON');
+        this.db.pragma('busy_timeout = 5000');
+        this.db.pragma('synchronous = NORMAL');
         this.init();
     }
+    /** Expose the raw database handle for the coordination module. */
+    getDb() {
+        return this.db;
+    }
+    /** Run PRAGMA quick_check and return true if DB is healthy. */
+    integrityCheck() {
+        try {
+            const rows = this.db.pragma('quick_check');
+            const result = rows[0]?.quick_check ?? 'unknown';
+            return { ok: result === 'ok', result };
+        }
+        catch (err) {
+            return { ok: false, result: err.message };
+        }
+    }
+    /** Hot backup using SQLite backup API. Returns the backup path. */
+    backup(destPath) {
+        this.db.backup(destPath);
+    }
+    /** Flush WAL to main database file. */
+    walCheckpoint() {
+        this.db.pragma('wal_checkpoint(TRUNCATE)');
+    }
     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 '[]'
-      );
-
-      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 {
@@ -153,10 +179,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)');
         }
@@ -165,35 +191,42 @@ 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 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 {
             this.db.exec(`ALTER TABLE conscious_state ADD COLUMN consolidation_cycle_count INTEGER NOT NULL DEFAULT 0`);
         }
         catch { /* column already exists */ }
+        // Migration: add memory_type column if missing
+        try {
+            this.db.prepare('SELECT memory_type FROM engrams LIMIT 0').get();
+        }
+        catch {
+            this.db.exec(`ALTER TABLE engrams ADD COLUMN memory_type TEXT NOT NULL DEFAULT 'unclassified'`);
+        }
     }
     // --- Engram CRUD ---
     createEngram(input) {
@@ -202,12 +235,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)
-      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);
+        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)
+      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');
         return this.getEngram(id);
     }
     getEngram(id) {
@@ -226,9 +259,21 @@ export class EngramStore {
         }
         return this.db.prepare(query).all(...params).map(r => this.rowToEngram(r));
     }
+    /**
+     * Touch an engram: increment access count, update last_accessed, and
+     * nudge confidence upward. Each retrieval is weak evidence the memory
+     * is useful — bounded so only explicit feedback can push confidence
+     * above 0.85. Diminishing returns: first accesses matter most.
+     *
+     * 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 = ? 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) {
@@ -242,8 +287,8 @@ export class EngramStore {
         this.db.prepare('UPDATE engrams SET embedding = ? WHERE id = ?').run(blob, id);
     }
     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);
     }
     deleteEngram(id) {
@@ -258,20 +303,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;
@@ -296,12 +341,12 @@ export class EngramStore {
         if (!sanitized)
             return [];
         try {
-            const rows = this.db.prepare(`
-        SELECT e.*, rank FROM engrams e
-        JOIN engrams_fts ON e.rowid = engrams_fts.rowid
-        WHERE engrams_fts MATCH ? AND e.agent_id = ? AND e.retracted = 0
-        ORDER BY rank
-        LIMIT ?
+            const rows = this.db.prepare(`
+        SELECT e.*, rank FROM engrams e
+        JOIN engrams_fts ON e.rowid = engrams_fts.rowid
+        WHERE engrams_fts MATCH ? AND e.agent_id = ? AND e.retracted = 0
+        ORDER BY rank
+        LIMIT ?
       `).all(sanitized, agentId, limit);
             return rows.map(r => ({
                 engram: this.rowToEngram(r),
@@ -381,14 +426,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));
     }
@@ -396,20 +441,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;
     }
@@ -432,15 +477,18 @@ export class EngramStore {
     updateMemoryClass(id, memoryClass) {
         this.db.prepare('UPDATE engrams SET memory_class = ? WHERE id = ?').run(memoryClass, id);
     }
+    updateTags(id, tags) {
+        this.db.prepare('UPDATE engrams SET tags = ? WHERE id = ?').run(JSON.stringify(tags), id);
+    }
     // --- Associations ---
     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);
     }
@@ -468,22 +516,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));
     }
@@ -498,8 +546,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))
@@ -507,53 +555,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 };
@@ -594,6 +642,7 @@ export class EngramStore {
             tags: JSON.parse(row.tags),
             episodeId: row.episode_id ?? null,
             memoryClass: (row.memory_class ?? 'working'),
+            memoryType: (row.memory_type ?? 'unclassified'),
             supersededBy: row.superseded_by ?? null,
             supersedes: row.supersedes ?? null,
             taskStatus: row.task_status ?? null,
@@ -621,9 +670,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);
     }
@@ -638,19 +687,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) {
@@ -701,49 +750,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);
     }
     getCheckpoint(agentId) {
@@ -770,20 +819,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);
         }
     }