agent-working-memory 0.8.5 → 0.8.7

package/dist/storage/pglite.js

@@ -184,7 +184,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 {
@@ -222,18 +222,18 @@ 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
+      ) 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,
@@ -362,10 +362,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) {
@@ -411,9 +411,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.
@@ -439,13 +439,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 }));
     }
@@ -464,11 +464,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)) }));
     }
@@ -482,11 +482,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)) }));
     }
@@ -567,32 +567,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;
     }
@@ -606,11 +606,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) {
@@ -643,12 +643,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)
@@ -670,12 +670,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) });
@@ -691,7 +691,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);
@@ -731,8 +731,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);
     }
@@ -741,11 +741,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);
     }
@@ -780,7 +780,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,
@@ -788,18 +788,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);
@@ -808,10 +808,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 {
@@ -825,8 +825,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 };
@@ -851,7 +851,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)
@@ -877,9 +877,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) {
@@ -918,44 +918,44 @@ 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]);
     }
     async getCheckpoint(agentId) {
@@ -988,13 +988,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]);
         }
     }
@@ -1019,10 +1019,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) {
@@ -1049,10 +1049,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) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-working-memory",
-  "version": "0.8.5",
-  "description": "Cognitive memory layer for AI agents — activation-based retrieval, salience filtering, associative connections",
+  "version": "0.8.7",
+  "description": "Cognitive memory layer for AI agents — activation-based retrieval, salience filtering, associative connections",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
@@ -31,7 +31,7 @@
     "test:all": "vitest run && tsx tests/mcp-smoke.ts"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "license": "Apache-2.0",
   "files": [
@@ -45,6 +45,7 @@
     "@electric-sql/pglite": "^0.4.6",
     "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@toon-format/toon": "^2.3.0",
     "better-sqlite3": "^12.6.2",
     "fastify": "^5.8.2",
     "zod": "^4.3.6"

package/src/adapters/common.ts

@@ -352,6 +352,33 @@ When it isn't:
   return nothing, the memory probably isn't there — read the code instead of
   burning more recalls.
 
+### Recall tuning (0.8.x — opt-in parameters for higher-quality recall)
+Default \`memory_recall\` is tuned for the common case. The 0.8.x recall pipeline
+exposes four opt-in parameters that change the cost/quality tradeoff. Use them
+when the default doesn't match what you actually need.
+
+- **\`granularity: 'compact'\`** — every result carries a 200-char \`summary\`
+  field with a query-aware snippet (the densest window of query terms in the
+  content). Use this when you expect to scan 5+ results to find one — saves
+  ~70% of recall output tokens. The full content stays available in
+  \`engram.content\` if you want to drill into a specific result.
+- **\`granularity: 'auto'\`** — confidence-adaptive. If the top result is a clear
+  winner, it gets a longer summary while the rest are compact. If confidence
+  is uniform across results, everything is compact. Use when you don't know
+  in advance whether one result will dominate.
+- **\`require_confidence: 0.10 | 0.25 | 0.40\`** — opt-in abstention. AWM
+  returns \`[]\` instead of low-confidence noise. Use when you're about to ACT
+  on the recalled fact (grounding a decision, citing the memory verbatim,
+  contradicting a prior assumption). Thresholds: \`0.10\` strict — only abstain
+  on garbage; \`0.25\` balanced; \`0.40\` aggressive — prefer "I don't know"
+  over "best of bad." When abstention fires (empty result), treat it as a
+  signal — either the memory genuinely isn't there (read the code) or your
+  query missed (reformulate). Don't retry without the threshold.
+- **\`workspace: "<name>"\`** — hive-mode recall across all agents in the
+  workspace. Use when other agents may have written canonical knowledge you
+  need. Default is agent-scoped (your own memories only). Can also be set
+  globally via the \`AWM_WORKSPACE\` env var.
+
 ### Keep memory fresh
 - After recalling a memory, if you observe the real state is different → call
   \`memory_supersede\` immediately with the corrected version.
@@ -362,6 +389,24 @@ When it isn't:
   drifts out of date. The system relies on you to keep it current. This is the #1
   failure mode.**
 
+### Content fade — write-and-forget is safe (0.8.x)
+Un-recalled engrams gradually fade their content while preserving cue pathways
+(concept + tags + embedding stay intact). This is Paper 1 — storage
+degradation. Practical implications:
+
+- **Don't manually purge memories** to "save space." The system already
+  compresses unused content. Old memories stay findable via cue match even
+  when their body has decayed.
+- **Don't over-pin with \`memory_class: canonical\`** to fight fade. Canonical
+  only changes salience gating at write time, not fade behavior. Fade
+  affects un-recalled engrams of any class.
+- **Recall keeps content alive.** Every recall touches the engram and resets
+  its fade clock. Frequently-recalled memories stay full-fidelity automatically.
+- **Supersede is the right tool for stale facts.** When you observe a memory
+  is outdated, call \`memory_supersede\` — the new version inherits the old
+  one's coherent associations (counter-narrative replacement, 0.8.x) so cue
+  pathways carry forward to the replacement.
+
 ### Example — good vs bad memory_write
 
 **BAD** (no prefix tags, vague concept, can't be recalled by future queries):
@@ -392,19 +437,74 @@ memory_write(
 - AWM is shared across all agents in real time. When any agent writes or supersedes a
   memory, every other agent can recall it immediately.
 
+### Output compression (token efficiency, output-only)
+When a tool returns a LARGE STRUCTURED result you need to keep in context — a JSON
+array of records, query rows, a log dump, an API response — pass it through
+\`compress_output\` first. It re-encodes the data as TOON (a compact, lossless,
+schema-aware tabular form of JSON), cutting ~50-65% of the tokens at no
+comprehension cost. This is output-only: it never changes the data or your memories.
+- Use it on big STRUCTURED outputs, not on prose. Prose is returned unchanged —
+  for trimming memory prose, use recall \`granularity: 'compact'\` instead.
+- It returns a \`ref\`; call \`retrieve_original(ref)\` if you later need the exact
+  verbatim source (e.g. to hand it to another tool unchanged).
+- Don't bother for small outputs — it only compresses when the saving is worthwhile
+  and falls back to plain JSON if TOON wouldn't reproduce the data exactly.
+
+### Backend (SQLite vs PGlite, 0.8.x)
+AWM ships two storage backends. The installer picks SQLite by default; both
+are functionally equivalent for cognitive workloads, but differ in operational
+guarantees:
+
+- **SQLite** (default) — embedded, **multi-process safe** via WAL mode. Best
+  for single-machine setups and MCP scenarios where multiple Claude Code
+  sessions may open the same database concurrently.
+- **PGlite** — embedded Postgres (WASM) with pgvector. **Single-process only**
+  — two MCP processes against the same \`memory-pglite/\` directory will
+  abort the second. Pick via \`AWM_STORE_BACKEND=pglite\` and
+  \`AWM_DB_PATH=path/to/memory-pglite\`.
+- **Auto-detect** — if \`AWM_DB_PATH\` points to a directory that already
+  exists, AWM detects PGlite; a file → SQLite. No explicit
+  \`AWM_STORE_BACKEND\` needed when an existing DB is present.
+
+For the comparison table (recall quality parity, BM25 vs \`ts_rank_cd\`,
+multi-process guarantees), see \`docs/pglite-feature-parity.md\`.
+
 ### Diagnostics / escape hatches (env vars, only if you know why)
-The 0.7.6→0.7.14 work cut recall latency from 11s to ~300ms. Each optimization
-is gated by an env-var so it can be disabled for A/B testing if a regression
-appears in your workload:
+The 0.7.6→0.7.14 work cut recall latency from 11s to ~300ms. The 0.8.x work
+added the write-path rewrite (per-write 300+ ms → under 10ms) and PGlite
+parity tuning. Each optimization is gated by an env-var so it can be disabled
+for A/B testing if a regression appears in your workload:
 
-- \`AWM_DISABLE_POOL_FILTER=1\` (0.7.7+) — disables the candidate pool reduction
+Recall pipeline (0.7.x):
+- \`AWM_DISABLE_POOL_FILTER=1\` — disables the candidate pool reduction
   pre-filter in recall. Reverts to scoring all active candidates.
-- \`AWM_DISABLE_SLIM_CACHE=1\` (0.7.10+) — disables the in-memory slim cache.
+- \`AWM_DISABLE_SLIM_CACHE=1\` — disables the in-memory slim cache.
   Reverts to per-recall SQL fetch + Buffer→Float32Array conversion.
-- \`AWM_DISABLE_RERANK_SKIP=1\` (0.7.10+) — disables the cross-encoder skip on
+- \`AWM_DISABLE_RERANK_SKIP=1\` — disables the cross-encoder skip on
   clear-winner queries. Forces every recall through the reranker.
-- \`AWM_DISABLE_EXPANSION_CACHE=1\` (0.7.11+) — disables the query expansion
-  skip heuristic + LRU cache. Forces every recall through flan-t5-small.
+- \`AWM_DISABLE_EXPANSION_CACHE=1\` — disables the query expansion skip
+  heuristic + LRU cache. Forces every recall through flan-t5-small.
+
+Write pipeline + lifecycle (0.8.x):
+- \`AWM_REINFORCE_MAX_CONTENT_LEN=1500\` — max chars an engram's content
+  can grow to via merge-on-reinforce (drop-oldest on overflow). Higher =
+  preserves more reinforced detail; lower = leaner recall output.
+- \`AWM_REINFORCE_MERGE_CONTENT=0\` — disable content merge on reinforce.
+  Reverts to pre-0.8.5 behavior (discard new content, only bump confidence).
+- \`AWM_NOVELTY_EMBED=0\` — disable the cosine channel in novelty
+  computation. BM25-only fallback. Reverts to pre-0.8.5 novelty.
+- \`AWM_GRANULARITY_COMPACT_LEN=200\` — char budget for query-aware snippet
+  in \`granularity: 'compact'\` mode.
+- \`AWM_GRANULARITY_FULL_LEN=1000\` — char budget for the top result in
+  \`granularity: 'auto'\` mode when there's a clear winner.
+
+PGlite backend (0.8.x):
+- \`AWM_PGLITE_BM25_M=1\` — multiplier on PGlite \`ts_rank_cd\` to calibrate
+  against SQLite FTS5 BM25 distribution. M=1 (default) is passthrough;
+  higher M boosts PGlite scores at the cost of recall-ranking precision
+  (see CHANGELOG 0.8.5 follow-up).
+- \`AWM_IVFFLAT_PROBES=5\` — pgvector ivfflat probes per query. Higher =
+  more accurate, slower.
 
 In production, leave these all unset. Use only when diagnosing a suspected
 recall-quality regression.

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

@@ -952,7 +952,7 @@ export function registerRoutes(app: FastifyInstance, deps: MemoryDeps): void {
     const base: Record<string, unknown> = {
       status: 'ok',
       timestamp: new Date().toISOString(),
-      version: '0.8.5',
+      version: '0.8.7',
       coordination: coordEnabled,
     };
     if (coordEnabled && typeof (deps.store as any).getDb === 'function') {