agent-working-memory 0.10.0 → 0.12.0

package/dist/storage/pglite.js

@@ -92,6 +92,11 @@ function rowToEngram(row) {
         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,
     };
 }
 function rowToAssociation(row) {
@@ -185,7 +190,7 @@ export class PGliteEngramStore {
             params.push(e.id, e.agentId, e.timestamp.toISOString(), e.context, e.resultsReturned, e.topScore, e.latencyMs, JSON.stringify(e.engramIds));
         }
         try {
-            await this.db.query(`INSERT INTO activation_events (id, agent_id, timestamp, context, results_returned, top_score, latency_ms, engram_ids)
+            await this.db.query(`INSERT INTO activation_events (id, agent_id, timestamp, context, results_returned, top_score, latency_ms, engram_ids)
          VALUES ${values.join(',')}`, params);
         }
         catch {
@@ -223,18 +228,20 @@ export class PGliteEngramStore {
         await this.readyPromise;
         const id = input.id ?? randomUUID();
         const now = new Date().toISOString();
-        await this.db.query(`INSERT INTO engrams (
-        id, agent_id, concept, content, embedding, embedding_model,
-        confidence, salience, access_count, last_accessed, created_at,
-        salience_features, reason_codes, stage, ttl, retracted,
-        tags, memory_type, memory_class, supersedes, episode_id,
-        task_status, task_priority, blocked_by, sequence, references_json
-      ) VALUES (
-        $1, $2, $3, $4, $5::vector, $6,
-        $7, $8, 0, $9, $10,
-        $11, $12, 'active', $13, FALSE,
-        $14, $15, $16, $17, $18,
-        $19, $20, $21, $22, $23
+        await this.db.query(`INSERT INTO engrams (
+        id, agent_id, concept, content, embedding, embedding_model,
+        confidence, salience, access_count, last_accessed, created_at,
+        salience_features, reason_codes, stage, ttl, retracted,
+        tags, memory_type, memory_class, supersedes, episode_id,
+        task_status, task_priority, blocked_by, sequence, references_json,
+        origin_class, writer_session, recipe_id, valid_from, valid_to
+      ) VALUES (
+        $1, $2, $3, $4, $5::vector, $6,
+        $7, $8, 0, $9, $10,
+        $11, $12, 'active', $13, FALSE,
+        $14, $15, $16, $17, $18,
+        $19, $20, $21, $22, $23,
+        $24, $25, $26, $27, $28
       )`, [
             id,
             input.agentId,
@@ -259,6 +266,11 @@ export class PGliteEngramStore {
             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,
         ]);
         const row = await this.getEngram(id);
         if (!row)
@@ -370,10 +382,10 @@ export class PGliteEngramStore {
     }
     async touchEngram(id) {
         await this.readyPromise;
-        await this.db.query(`UPDATE engrams
-       SET access_count = access_count + 1,
-           last_accessed = $1,
-           confidence = LEAST(0.85, confidence + 0.02 / (1.0 + sqrt(access_count::float)))
+        await this.db.query(`UPDATE engrams
+       SET access_count = access_count + 1,
+           last_accessed = $1,
+           confidence = LEAST(0.85, confidence + 0.02 / (1.0 + sqrt(access_count::float)))
        WHERE id = $2`, [new Date().toISOString(), id]);
     }
     async updateStage(id, stage) {
@@ -419,9 +431,9 @@ export class PGliteEngramStore {
     async timeWarp(agentId, ms) {
         await this.readyPromise;
         const seconds = Math.round(ms / 1000);
-        const r1 = await this.db.query(`UPDATE engrams SET
-         created_at = to_char(($1::timestamptz - interval '1 second' * $2), 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
-         last_accessed = to_char(($3::timestamptz - interval '1 second' * $2), 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')
+        const r1 = await this.db.query(`UPDATE engrams SET
+         created_at = to_char(($1::timestamptz - interval '1 second' * $2), 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"'),
+         last_accessed = to_char(($3::timestamptz - interval '1 second' * $2), 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')
        WHERE agent_id = $4`, ['now', seconds, 'now', agentId]);
         // Simpler: just update with relative arithmetic on stored ISO strings.
         // PGlite doesn't support all date ops cleanly; fall through to JS-side calculation.
@@ -447,13 +459,13 @@ export class PGliteEngramStore {
         // Restrict to active + fading. Faded engrams (Paper 1: storage degradation)
         // retain their embedding so they still participate in semantic recall, even
         // though their content has been trimmed. Excludes staging/consolidated/archived.
-        const result = await this.db.query(`SELECT *, (embedding <=> $2::vector) AS distance
-       FROM engrams
-       WHERE agent_id = $1
-         AND embedding IS NOT NULL
-         AND retracted = FALSE
-         AND stage IN ('active', 'fading')
-       ORDER BY distance ASC
+        const result = await this.db.query(`SELECT *, (embedding <=> $2::vector) AS distance
+       FROM engrams
+       WHERE agent_id = $1
+         AND embedding IS NOT NULL
+         AND retracted = FALSE
+         AND stage IN ('active', 'fading')
+       ORDER BY distance ASC
        LIMIT $3`, [agentId, vectorToLiteral(vec), limit]);
         return result.rows.map((r) => ({ engram: rowToEngram(r), distance: r.distance }));
     }
@@ -472,11 +484,11 @@ export class PGliteEngramStore {
         if (tokens.length === 0)
             return [];
         const websearchQuery = tokens.join(' OR ');
-        const result = await this.db.query(`SELECT *, ts_rank_cd(fts, websearch_to_tsquery('english', $2)) AS rank
-       FROM engrams
-       WHERE agent_id = $1 AND retracted = FALSE
-         AND fts @@ websearch_to_tsquery('english', $2)
-       ORDER BY rank DESC
+        const result = await this.db.query(`SELECT *, ts_rank_cd(fts, websearch_to_tsquery('english', $2)) AS rank
+       FROM engrams
+       WHERE agent_id = $1 AND retracted = FALSE
+         AND fts @@ websearch_to_tsquery('english', $2)
+       ORDER BY rank DESC
        LIMIT $3`, [agentId, websearchQuery, limit]);
         return result.rows.map((r) => ({ engram: rowToEngram(r), bm25Score: calibrateBm25(Number(r.rank)) }));
     }
@@ -490,11 +502,11 @@ export class PGliteEngramStore {
         if (tokens.length === 0)
             return [];
         const websearchQuery = tokens.join(' OR ');
-        const result = await this.db.query(`SELECT *, ts_rank_cd(fts, websearch_to_tsquery('english', $2)) AS rank
-       FROM engrams
-       WHERE agent_id = ANY($1::text[]) AND retracted = FALSE
-         AND fts @@ websearch_to_tsquery('english', $2)
-       ORDER BY rank DESC
+        const result = await this.db.query(`SELECT *, ts_rank_cd(fts, websearch_to_tsquery('english', $2)) AS rank
+       FROM engrams
+       WHERE agent_id = ANY($1::text[]) AND retracted = FALSE
+         AND fts @@ websearch_to_tsquery('english', $2)
+       ORDER BY rank DESC
        LIMIT $3`, [agentIds, websearchQuery, limit]);
         return result.rows.map((r) => ({ engram: rowToEngram(r), bm25Score: calibrateBm25(Number(r.rank)) }));
     }
@@ -575,32 +587,32 @@ export class PGliteEngramStore {
             sql += ` AND task_status = $${params.length + 1}`;
             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`;
         const result = await this.db.query(sql, params);
         return result.rows.map(rowToEngram);
     }
     async getNextTask(agentId) {
         await this.readyPromise;
-        const result = await this.db.query(`SELECT * FROM engrams
-       WHERE agent_id = $1 AND task_status IN ('open', 'in_progress') AND retracted = FALSE
-       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
+        const result = await this.db.query(`SELECT * FROM engrams
+       WHERE agent_id = $1 AND task_status IN ('open', 'in_progress') AND retracted = FALSE
+       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`, [agentId]);
         return result.rows.length > 0 ? rowToEngram(result.rows[0]) : null;
     }
@@ -614,11 +626,11 @@ export class PGliteEngramStore {
     }
     async findActiveMatchByConcept(agentId, concept, requiredTags) {
         await this.readyPromise;
-        let sql = `SELECT * FROM engrams
-               WHERE agent_id = $1
-                 AND LOWER(TRIM(concept)) = LOWER(TRIM($2))
-                 AND stage = 'active'
-                 AND retracted = FALSE
+        let sql = `SELECT * FROM engrams
+               WHERE agent_id = $1
+                 AND LOWER(TRIM(concept)) = LOWER(TRIM($2))
+                 AND stage = 'active'
+                 AND retracted = FALSE
                  AND superseded_by IS NULL`;
         const params = [agentId, concept];
         if (requiredTags && requiredTags.length > 0) {
@@ -651,12 +663,12 @@ export class PGliteEngramStore {
         await this.readyPromise;
         const id = randomUUID();
         const now = new Date().toISOString();
-        await this.db.query(`INSERT INTO associations (id, from_engram_id, to_engram_id, weight, confidence, type, activation_count, created_at, last_activated)
-       VALUES ($1, $2, $3, $4, $5, $6, 0, $7, $7)
-       ON CONFLICT (from_engram_id, to_engram_id) DO UPDATE SET
-         weight = EXCLUDED.weight,
-         confidence = EXCLUDED.confidence,
-         last_activated = EXCLUDED.last_activated,
+        await this.db.query(`INSERT INTO associations (id, from_engram_id, to_engram_id, weight, confidence, type, activation_count, created_at, last_activated)
+       VALUES ($1, $2, $3, $4, $5, $6, 0, $7, $7)
+       ON CONFLICT (from_engram_id, to_engram_id) DO UPDATE SET
+         weight = EXCLUDED.weight,
+         confidence = EXCLUDED.confidence,
+         last_activated = EXCLUDED.last_activated,
          activation_count = associations.activation_count + 1`, [id, fromId, toId, weight, confidence, type, now]);
         const assoc = await this.getAssociation(fromId, toId);
         if (!assoc)
@@ -678,12 +690,12 @@ export class PGliteEngramStore {
         if (engramIds.length === 0)
             return result;
         await this.readyPromise;
-        const r = await this.db.query(`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 = ANY($1::text[])
-         UNION ALL
-         SELECT to_engram_id   AS id, 1 AS cnt, weight AS sw FROM associations WHERE to_engram_id   = ANY($1::text[])
-       ) t
-       WHERE id = ANY($1::text[])
+        const r = await this.db.query(`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 = ANY($1::text[])
+         UNION ALL
+         SELECT to_engram_id   AS id, 1 AS cnt, weight AS sw FROM associations WHERE to_engram_id   = ANY($1::text[])
+       ) t
+       WHERE id = ANY($1::text[])
        GROUP BY id`, [engramIds]);
         for (const row of r.rows) {
             result.set(row.id, { count: Number(row.count), sumWeight: Number(row.sum_weight) });
@@ -699,7 +711,7 @@ export class PGliteEngramStore {
         if (engramIds.length === 0)
             return result;
         await this.readyPromise;
-        const r = await this.db.query(`SELECT * FROM associations
+        const r = await this.db.query(`SELECT * FROM associations
        WHERE from_engram_id = ANY($1::text[]) OR to_engram_id = ANY($1::text[])`, [engramIds]);
         for (const row of r.rows) {
             const a = rowToAssociation(row);
@@ -739,8 +751,8 @@ export class PGliteEngramStore {
     }
     async getAllAssociations(agentId) {
         await this.readyPromise;
-        const result = await this.db.query(`SELECT a.* FROM associations a
-       JOIN engrams e ON a.from_engram_id = e.id
+        const result = await this.db.query(`SELECT a.* FROM associations a
+       JOIN engrams e ON a.from_engram_id = e.id
        WHERE e.agent_id = $1`, [agentId]);
         return result.rows.map(rowToAssociation);
     }
@@ -749,11 +761,11 @@ export class PGliteEngramStore {
     // ============================================================
     async getEvictionCandidates(agentId, limit) {
         await this.readyPromise;
-        const result = await this.db.query(`SELECT * FROM engrams
-       WHERE agent_id = $1 AND stage = 'active' AND retracted = FALSE
-       ORDER BY (salience * 0.3 + confidence * 0.3
-                 + (access_count::float / (access_count + 5)) * 0.2
-                 + (1.0 / (1.0 + EXTRACT(EPOCH FROM (now() - last_accessed::timestamptz)) / 86400.0)) * 0.2) ASC
+        const result = await this.db.query(`SELECT * FROM engrams
+       WHERE agent_id = $1 AND stage = 'active' AND retracted = FALSE
+       ORDER BY (salience * 0.3 + confidence * 0.3
+                 + (access_count::float / (access_count + 5)) * 0.2
+                 + (1.0 / (1.0 + EXTRACT(EPOCH FROM (now() - last_accessed::timestamptz)) / 86400.0)) * 0.2) ASC
        LIMIT $2`, [agentId, limit]);
         return result.rows.map(rowToEngram);
     }
@@ -788,7 +800,7 @@ export class PGliteEngramStore {
     }
     async logStagingEvent(event) {
         await this.readyPromise;
-        await this.db.query(`INSERT INTO staging_events (engram_id, agent_id, action, resonance_score, timestamp, age_ms)
+        await this.db.query(`INSERT INTO staging_events (engram_id, agent_id, action, resonance_score, timestamp, age_ms)
        VALUES ($1, $2, $3, $4, $5, $6)`, [
             event.engramId, event.agentId, event.action,
             event.resonanceScore, event.timestamp.toISOString(), event.ageMs,
@@ -796,18 +808,18 @@ export class PGliteEngramStore {
     }
     async logRetrievalFeedback(activationEventId, engramId, useful, context) {
         await this.readyPromise;
-        await this.db.query(`INSERT INTO retrieval_feedback (id, activation_event_id, engram_id, useful, context, timestamp)
+        await this.db.query(`INSERT INTO retrieval_feedback (id, activation_event_id, engram_id, useful, context, timestamp)
        VALUES ($1, $2, $3, $4, $5, $6)`, [randomUUID(), activationEventId, engramId, useful, context, new Date().toISOString()]);
     }
     async getRetrievalPrecision(agentId, windowHours = 24) {
         await this.readyPromise;
         const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
-        const result = await this.db.query(`SELECT
-         COUNT(CASE WHEN useful = TRUE 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
+        const result = await this.db.query(`SELECT
+         COUNT(CASE WHEN useful = TRUE 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 = $1 AND rf.timestamp > $2`, [agentId, since]);
         const row = result.rows[0];
         const total = Number(row?.total_count ?? 0);
@@ -816,10 +828,10 @@ export class PGliteEngramStore {
     }
     async getStagingMetrics(agentId) {
         await this.readyPromise;
-        const result = await this.db.query(`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
+        const result = await this.db.query(`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 = $1`, [agentId]);
         const row = result.rows[0] ?? { promoted: 0, discarded: 0, expired: 0 };
         return {
@@ -833,8 +845,8 @@ export class PGliteEngramStore {
         // Flush any buffered activation events so stats reflect the latest writes.
         await this.flushActivationEvents();
         const since = new Date(Date.now() - windowHours * 3600_000).toISOString();
-        const result = await this.db.query(`SELECT latency_ms FROM activation_events
-       WHERE agent_id = $1 AND timestamp > $2
+        const result = await this.db.query(`SELECT latency_ms FROM activation_events
+       WHERE agent_id = $1 AND timestamp > $2
        ORDER BY latency_ms ASC`, [agentId, since]);
         if (result.rows.length === 0)
             return { count: 0, avgLatencyMs: 0, p95LatencyMs: 0 };
@@ -859,7 +871,7 @@ export class PGliteEngramStore {
         await this.readyPromise;
         const id = randomUUID();
         const now = new Date().toISOString();
-        await this.db.query(`INSERT INTO episodes (id, agent_id, label, embedding, engram_count, start_time, end_time, created_at)
+        await this.db.query(`INSERT INTO episodes (id, agent_id, label, embedding, engram_count, start_time, end_time, created_at)
        VALUES ($1, $2, $3, $4::vector, 0, $5, $5, $5)`, [id, input.agentId, input.label, vectorToLiteral(input.embedding ?? null), now]);
         const ep = await this.getEpisode(id);
         if (!ep)
@@ -885,9 +897,9 @@ export class PGliteEngramStore {
     async addEngramToEpisode(engramId, episodeId) {
         await this.readyPromise;
         await this.db.query(`UPDATE engrams SET episode_id = $1 WHERE id = $2`, [episodeId, engramId]);
-        await this.db.query(`UPDATE episodes SET
-         engram_count = engram_count + 1,
-         end_time = GREATEST(end_time, $1)
+        await this.db.query(`UPDATE episodes SET
+         engram_count = engram_count + 1,
+         end_time = GREATEST(end_time, $1)
        WHERE id = $2`, [new Date().toISOString(), episodeId]);
     }
     async getEngramsByEpisode(episodeId) {
@@ -926,46 +938,76 @@ export class PGliteEngramStore {
     async updateAutoCheckpointWrite(agentId, engramId) {
         await this.readyPromise;
         const now = new Date().toISOString();
-        await this.db.query(`INSERT INTO conscious_state (agent_id, last_write_id, last_activity_at, write_count_since_consolidation, updated_at)
-       VALUES ($1, $2, $3, 1, $3)
-       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 = conscious_state.write_count_since_consolidation + 1,
+        await this.db.query(`INSERT INTO conscious_state (agent_id, last_write_id, last_activity_at, write_count_since_consolidation, updated_at)
+       VALUES ($1, $2, $3, 1, $3)
+       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 = conscious_state.write_count_since_consolidation + 1,
          updated_at = EXCLUDED.updated_at`, [agentId, engramId, now]);
     }
     async updateAutoCheckpointRecall(agentId, context, engramIds) {
         await this.readyPromise;
         const now = new Date().toISOString();
-        await this.db.query(`INSERT INTO conscious_state (agent_id, last_recall_context, last_recall_ids, last_activity_at, recall_count_since_consolidation, updated_at)
-       VALUES ($1, $2, $3, $4, 1, $4)
-       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 = conscious_state.recall_count_since_consolidation + 1,
+        await this.db.query(`INSERT INTO conscious_state (agent_id, last_recall_context, last_recall_ids, last_activity_at, recall_count_since_consolidation, updated_at)
+       VALUES ($1, $2, $3, $4, 1, $4)
+       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 = conscious_state.recall_count_since_consolidation + 1,
          updated_at = EXCLUDED.updated_at`, [agentId, context, JSON.stringify(engramIds), now]);
     }
     async touchActivity(agentId) {
         await this.readyPromise;
         const now = new Date().toISOString();
-        await this.db.query(`INSERT INTO conscious_state (agent_id, last_activity_at, updated_at)
-       VALUES ($1, $2, $2)
-       ON CONFLICT(agent_id) DO UPDATE SET
-         last_activity_at = EXCLUDED.last_activity_at,
+        await this.db.query(`INSERT INTO conscious_state (agent_id, last_activity_at, updated_at)
+       VALUES ($1, $2, $2)
+       ON CONFLICT(agent_id) DO UPDATE SET
+         last_activity_at = EXCLUDED.last_activity_at,
          updated_at = EXCLUDED.updated_at`, [agentId, now]);
     }
     async saveCheckpoint(agentId, state) {
         await this.readyPromise;
         const now = new Date().toISOString();
-        await this.db.query(`INSERT INTO conscious_state (agent_id, execution_state, checkpoint_at, last_activity_at, updated_at)
-       VALUES ($1, $2, $3, $3, $3)
-       ON CONFLICT(agent_id) DO UPDATE SET
-         execution_state = EXCLUDED.execution_state,
-         checkpoint_at = EXCLUDED.checkpoint_at,
-         last_activity_at = EXCLUDED.last_activity_at,
+        await this.db.query(`INSERT INTO conscious_state (agent_id, execution_state, checkpoint_at, last_activity_at, updated_at)
+       VALUES ($1, $2, $3, $3, $3)
+       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`, [agentId, JSON.stringify(state), now]);
     }
+    /** Distinct agent ids present in this store (D3 whoami; includes all stages). */
+    async listAgentIds() {
+        const res = await this.db.query('SELECT DISTINCT agent_id FROM engrams ORDER BY agent_id');
+        return res.rows.map(r => r.agent_id);
+    }
+    async recordEntityMentions(engramId, agentId, entities) {
+        if (!entities || entities.length === 0)
+            return;
+        for (const entity of entities) {
+            await this.db.query('INSERT INTO entity_mentions (entity, engram_id, agent_id) VALUES ($1, $2, $3) ON CONFLICT DO NOTHING', [entity, engramId, agentId]);
+        }
+    }
+    async searchEntities(term, limit = 8) {
+        const t = term.toLowerCase().replace(/[%_]/g, '');
+        if (!t)
+            return [];
+        const res = await this.db.query(`SELECT DISTINCT entity FROM (
+         SELECT entity FROM entity_mentions WHERE entity LIKE $1
+         UNION SELECT entity FROM entity_aliases WHERE alias LIKE $1
+       ) u LIMIT $2`, [`%${t}%`, limit]);
+        return res.rows.map(r => r.entity);
+    }
+    async getEngramIdsByEntity(entity, agentId) {
+        const alias = await this.db.query('SELECT entity FROM entity_aliases WHERE alias = $1', [entity.toLowerCase()]);
+        const resolved = alias.rows[0]?.entity ?? entity.toLowerCase();
+        const res = agentId
+            ? await this.db.query('SELECT engram_id FROM entity_mentions WHERE entity = $1 AND agent_id = $2', [resolved, agentId])
+            : await this.db.query('SELECT engram_id FROM entity_mentions WHERE entity = $1', [resolved]);
+        return res.rows.map(r => r.engram_id);
+    }
     async getCheckpoint(agentId) {
         await this.readyPromise;
         const result = await this.db.query(`SELECT * FROM conscious_state WHERE agent_id = $1`, [agentId]);
@@ -996,13 +1038,13 @@ export class PGliteEngramStore {
             await this.db.query(`UPDATE conscious_state SET last_mini_consolidation_at = $1, updated_at = $1 WHERE agent_id = $2`, [now, agentId]);
         }
         else {
-            await this.db.query(`UPDATE conscious_state SET
-           last_consolidation_at = $1,
-           last_mini_consolidation_at = $1,
-           write_count_since_consolidation = 0,
-           recall_count_since_consolidation = 0,
-           consolidation_cycle_count = consolidation_cycle_count + 1,
-           updated_at = $1
+            await this.db.query(`UPDATE conscious_state SET
+           last_consolidation_at = $1,
+           last_mini_consolidation_at = $1,
+           write_count_since_consolidation = 0,
+           recall_count_since_consolidation = 0,
+           consolidation_cycle_count = consolidation_cycle_count + 1,
+           updated_at = $1
          WHERE agent_id = $2`, [now, agentId]);
         }
     }
@@ -1027,10 +1069,10 @@ export class PGliteEngramStore {
     // ============================================================
     async getLatestByTag(opts) {
         await this.readyPromise;
-        let sql = `SELECT * FROM engrams
-               WHERE agent_id = $1
-                 AND retracted = $2
-                 AND stage = 'active'
+        let sql = `SELECT * FROM engrams
+               WHERE agent_id = $1
+                 AND retracted = $2
+                 AND stage = 'active'
                  AND tags LIKE $3`;
         const params = [opts.agentId, opts.retracted ?? false, `%"${opts.tagKeyPrefix}%`];
         if (opts.scopeTagsAll && opts.scopeTagsAll.length > 0) {
@@ -1057,10 +1099,10 @@ export class PGliteEngramStore {
     }
     async getTopBy(opts) {
         await this.readyPromise;
-        let sql = `SELECT * FROM engrams
-               WHERE agent_id = $1
-                 AND retracted = $2
-                 AND stage = 'active'
+        let sql = `SELECT * FROM engrams
+               WHERE agent_id = $1
+                 AND retracted = $2
+                 AND stage = 'active'
                  AND tags LIKE $3`;
         const params = [opts.agentId, opts.retracted ?? false, `%"${opts.sortField}%`];
         if (opts.filterTagsAll && opts.filterTagsAll.length > 0) {