agent-working-memory 0.10.0 → 0.11.0

package/dist/storage/postgres.js

@@ -274,7 +274,7 @@ export class PostgresEngramStore {
             // ALWAYS the pool, never this.q(): this background flush is fire-and-forget and must
             // not route to a transaction's client (a future caller that logs an activation inside a
             // withTransaction would otherwise collide with the tx's in-flight query on one pg client).
-            await this.pool.query(`INSERT INTO activation_events (id, agent_id, timestamp, context, results_returned, top_score, latency_ms, engram_ids)
+            await this.pool.query(`INSERT INTO activation_events (id, agent_id, timestamp, context, results_returned, top_score, latency_ms, engram_ids)
          VALUES ${values.join(',')}`, params);
         }
         catch {
@@ -321,18 +321,18 @@ export class PostgresEngramStore {
         await this.readyPromise;
         const id = input.id ?? randomUUID();
         const now = new Date().toISOString();
-        await this.q(`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.q(`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
       )`, [
             id,
             input.agentId,
@@ -468,10 +468,10 @@ export class PostgresEngramStore {
     }
     async touchEngram(id) {
         await this.readyPromise;
-        await this.q(`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.q(`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) {
@@ -517,9 +517,9 @@ export class PostgresEngramStore {
     async timeWarp(agentId, ms) {
         await this.readyPromise;
         const seconds = Math.round(ms / 1000);
-        const r1 = await this.q(`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.q(`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]);
         // node-postgres reports the affected-row count as `rowCount` (PGlite called it
         // `affectedRows` — the one result-shape field that differs between the drivers).
@@ -545,13 +545,13 @@ export class PostgresEngramStore {
         // 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.q(`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.q(`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 }));
     }
@@ -570,11 +570,11 @@ export class PostgresEngramStore {
         if (tokens.length === 0)
             return [];
         const websearchQuery = tokens.join(' OR ');
-        const result = await this.q(`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.q(`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)) }));
     }
@@ -588,11 +588,11 @@ export class PostgresEngramStore {
         if (tokens.length === 0)
             return [];
         const websearchQuery = tokens.join(' OR ');
-        const result = await this.q(`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.q(`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)) }));
     }
@@ -673,32 +673,32 @@ export class PostgresEngramStore {
             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.q(sql, params);
         return result.rows.map(rowToEngram);
     }
     async getNextTask(agentId) {
         await this.readyPromise;
-        const result = await this.q(`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.q(`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;
     }
@@ -712,11 +712,11 @@ export class PostgresEngramStore {
     }
     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) {
@@ -749,12 +749,12 @@ export class PostgresEngramStore {
         await this.readyPromise;
         const id = randomUUID();
         const now = new Date().toISOString();
-        await this.q(`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.q(`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)
@@ -776,12 +776,12 @@ export class PostgresEngramStore {
         if (engramIds.length === 0)
             return result;
         await this.readyPromise;
-        const r = await this.q(`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.q(`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) });
@@ -797,7 +797,7 @@ export class PostgresEngramStore {
         if (engramIds.length === 0)
             return result;
         await this.readyPromise;
-        const r = await this.q(`SELECT * FROM associations
+        const r = await this.q(`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);
@@ -837,8 +837,8 @@ export class PostgresEngramStore {
     }
     async getAllAssociations(agentId) {
         await this.readyPromise;
-        const result = await this.q(`SELECT a.* FROM associations a
-       JOIN engrams e ON a.from_engram_id = e.id
+        const result = await this.q(`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);
     }
@@ -847,11 +847,11 @@ export class PostgresEngramStore {
     // ============================================================
     async getEvictionCandidates(agentId, limit) {
         await this.readyPromise;
-        const result = await this.q(`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.q(`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);
     }
@@ -886,7 +886,7 @@ export class PostgresEngramStore {
     }
     async logStagingEvent(event) {
         await this.readyPromise;
-        await this.q(`INSERT INTO staging_events (engram_id, agent_id, action, resonance_score, timestamp, age_ms)
+        await this.q(`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,
@@ -894,18 +894,18 @@ export class PostgresEngramStore {
     }
     async logRetrievalFeedback(activationEventId, engramId, useful, context) {
         await this.readyPromise;
-        await this.q(`INSERT INTO retrieval_feedback (id, activation_event_id, engram_id, useful, context, timestamp)
+        await this.q(`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.q(`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.q(`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);
@@ -914,10 +914,10 @@ export class PostgresEngramStore {
     }
     async getStagingMetrics(agentId) {
         await this.readyPromise;
-        const result = await this.q(`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.q(`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 {
@@ -931,8 +931,8 @@ export class PostgresEngramStore {
         // 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.q(`SELECT latency_ms FROM activation_events
-       WHERE agent_id = $1 AND timestamp > $2
+        const result = await this.q(`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 };
@@ -957,7 +957,7 @@ export class PostgresEngramStore {
         await this.readyPromise;
         const id = randomUUID();
         const now = new Date().toISOString();
-        await this.q(`INSERT INTO episodes (id, agent_id, label, embedding, engram_count, start_time, end_time, created_at)
+        await this.q(`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)
@@ -983,9 +983,9 @@ export class PostgresEngramStore {
     async addEngramToEpisode(engramId, episodeId) {
         await this.readyPromise;
         await this.q(`UPDATE engrams SET episode_id = $1 WHERE id = $2`, [episodeId, engramId]);
-        await this.q(`UPDATE episodes SET
-         engram_count = engram_count + 1,
-         end_time = GREATEST(end_time, $1)
+        await this.q(`UPDATE episodes SET
+         engram_count = engram_count + 1,
+         end_time = GREATEST(end_time, $1)
        WHERE id = $2`, [new Date().toISOString(), episodeId]);
     }
     async getEngramsByEpisode(episodeId) {
@@ -1024,44 +1024,44 @@ export class PostgresEngramStore {
     async updateAutoCheckpointWrite(agentId, engramId) {
         await this.readyPromise;
         const now = new Date().toISOString();
-        await this.q(`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.q(`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.q(`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.q(`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.q(`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.q(`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.q(`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.q(`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]);
     }
     async getCheckpoint(agentId) {
@@ -1094,13 +1094,13 @@ export class PostgresEngramStore {
             await this.q(`UPDATE conscious_state SET last_mini_consolidation_at = $1, updated_at = $1 WHERE agent_id = $2`, [now, agentId]);
         }
         else {
-            await this.q(`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.q(`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]);
         }
     }
@@ -1125,10 +1125,10 @@ export class PostgresEngramStore {
     // ============================================================
     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) {
@@ -1155,10 +1155,10 @@ export class PostgresEngramStore {
     }
     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) {

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAyBA,eAAO,MAAM,OAAO,EAAE,MAAyB,CAAC"}

package/dist/version.js

@@ -0,0 +1,27 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+/**
+ * The running package version, read from package.json at runtime so the number
+ * reported by /health, the startup banner, and the MCP server always matches
+ * the actually-deployed build. Hand-maintained version literals drifted across
+ * releases (a 0.10.0 build was still reporting 0.8.5/0.8.8) — this removes them.
+ */
+function resolveVersion() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // src/version.ts (dev) and dist/version.js (build) both sit one level below
+    // the package root; the ../../ fallback covers a deeper output nesting.
+    for (const rel of ['../package.json', '../../package.json']) {
+        try {
+            const v = JSON.parse(readFileSync(join(here, rel), 'utf8')).version;
+            if (typeof v === 'string' && v)
+                return v;
+        }
+        catch {
+            /* try the next candidate path */
+        }
+    }
+    return '0.0.0';
+}
+export const VERSION = resolveVersion();
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;GAKG;AACH,SAAS,cAAc;IACrB,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,4EAA4E;IAC5E,wEAAwE;IACxE,KAAK,MAAM,GAAG,IAAI,CAAC,iBAAiB,EAAE,oBAAoB,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;YACpE,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC;gBAAE,OAAO,CAAC,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,iCAAiC;QACnC,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAW,cAAc,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-working-memory",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Cognitive memory layer for AI agents — activation-based retrieval, salience filtering, associative connections",
   "type": "module",
   "main": "dist/index.js",
@@ -58,5 +58,13 @@
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CompleteIdeas/agent-working-memory.git"
+  },
+  "homepage": "https://github.com/CompleteIdeas/agent-working-memory#readme",
+  "bugs": {
+    "url": "https://github.com/CompleteIdeas/agent-working-memory/issues"
   }
 }

package/src/adapters/common.ts

@@ -222,7 +222,11 @@ directly — but **DO NOT fall back to markdown files**. Files drift the moment
 you write them; AWM stays current because every agent reads + writes the same store.
 
 ### Lifecycle (always do these, in this order)
-1. **Session start**: call \`memory_restore\` to recover previous context.
+1. **Session start**: call \`memory_restore\` to recover previous context. If it reports the
+   store is empty/new (or recall keeps returning nothing), **warm-start first**: recall the
+   \`onboard a new project\` skill and follow it — or call \`onboard_scan\` on the project's
+   docs/repo, refine the candidates, run \`onboard_questions\`, and save the good ones with
+   \`memory_write\` (canonical). A cold store is nearly useless until it's seeded.
 2. **Starting a task**: call \`memory_task_begin\` (checkpoints + recalls relevant memories).
 3. **During work**: call \`memory_recall\` BEFORE stating any fact, BEFORE searching
    the filesystem, BEFORE making architectural decisions. Recall is ~300ms — cheaper

package/src/api/index.ts

@@ -1,3 +1,3 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-export * from './routes.js';
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+export * from './routes.js';

package/src/api/routes.ts

@@ -49,6 +49,7 @@ import type { TaskStatus, TaskPriority } from '../types/engram.js';
 import type { ConsciousState } from '../types/checkpoint.js';
 import { DEFAULT_AGENT_CONFIG } from '../types/agent.js';
 import { embed, embedBatch } from '../core/embeddings.js';
+import { VERSION } from '../version.js';
 
 export interface MemoryDeps {
   store: EngramStore;
@@ -952,7 +953,7 @@ export function registerRoutes(app: FastifyInstance, deps: MemoryDeps): void {
     const base: Record<string, unknown> = {
       status: 'ok',
       timestamp: new Date().toISOString(),
-      version: '0.8.8',
+      version: VERSION,
       coordination: coordEnabled,
     };
     if (coordEnabled && typeof (deps.store as any).getDb === 'function') {