@psiclawops/hypermem 0.6.2 → 0.8.0

package/dist/expertise-store.js

@@ -0,0 +1,342 @@
+/**
+ * hypermem Expertise Store
+ *
+ * Stores domain expertise patterns — learned behaviors that make the Nth run
+ * better than the 1st. Two-phase lifecycle:
+ *   1. Observations: raw learnings logged from conversations, pipelines, reviews
+ *   2. Patterns: graduated observations with N≥3 confirming instances
+ *
+ * Patterns are agent-scoped but domain-tagged, enabling cross-agent queries.
+ * Patterns have confidence, frequency tracking, and decay on counter-evidence.
+ */
+function nowIso() {
+    return new Date().toISOString();
+}
+function parseObservationRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        domain: row.domain,
+        context: row.context || null,
+        observationText: row.observation_text,
+        sourceType: row.source_type,
+        sourceRef: row.source_ref || null,
+        createdAt: row.created_at,
+    };
+}
+function parsePatternRow(row) {
+    return {
+        id: row.id,
+        agentId: row.agent_id,
+        domain: row.domain,
+        patternText: row.pattern_text,
+        confidence: row.confidence,
+        frequency: row.frequency,
+        firstSeen: row.first_seen,
+        lastConfirmed: row.last_confirmed,
+        invalidatedAt: row.invalidated_at || null,
+        invalidationReason: row.invalidation_reason || null,
+        decayScore: row.decay_score,
+    };
+}
+// ── Graduation threshold ──
+const DEFAULT_GRADUATION_THRESHOLD = 3;
+export class ExpertiseStore {
+    db;
+    graduationThreshold;
+    constructor(db, graduationThreshold = DEFAULT_GRADUATION_THRESHOLD) {
+        this.db = db;
+        this.graduationThreshold = graduationThreshold;
+    }
+    // ── Observations ──
+    /**
+     * Record a raw observation from any source.
+     */
+    record(agentId, observationText, domain, opts) {
+        const now = nowIso();
+        const result = this.db.prepare(`
+      INSERT INTO expertise_observations
+        (agent_id, domain, context, observation_text, source_type, source_ref, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(agentId, domain, opts?.context || null, observationText, opts?.sourceType || 'conversation', opts?.sourceRef || null, now);
+        const id = Number(result.lastInsertRowid);
+        return {
+            id,
+            agentId,
+            domain,
+            context: opts?.context || null,
+            observationText,
+            sourceType: opts?.sourceType || 'conversation',
+            sourceRef: opts?.sourceRef || null,
+            createdAt: now,
+        };
+    }
+    /**
+     * Get observations for an agent, optionally filtered by domain.
+     */
+    getObservations(agentId, opts) {
+        let sql = 'SELECT * FROM expertise_observations WHERE agent_id = ?';
+        const params = [agentId];
+        if (opts?.domain) {
+            sql += ' AND domain = ?';
+            params.push(opts.domain);
+        }
+        sql += ' ORDER BY created_at DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseObservationRow);
+    }
+    // ── Patterns ──
+    /**
+     * Retrieve active expertise patterns for current work context.
+     * Returns patterns sorted by confidence DESC, frequency DESC.
+     * Excludes invalidated patterns by default.
+     */
+    query(agentId, domain, opts) {
+        let sql = `
+      SELECT * FROM expertise_patterns
+      WHERE agent_id = ? AND domain = ?
+      AND decay_score < 0.8
+    `;
+        const params = [agentId, domain];
+        if (!opts?.includeInvalidated) {
+            sql += ' AND invalidated_at IS NULL';
+        }
+        if (opts?.minConfidence) {
+            sql += ' AND confidence >= ?';
+            params.push(opts.minConfidence);
+        }
+        sql += ' ORDER BY confidence DESC, frequency DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parsePatternRow);
+    }
+    /**
+     * Cross-agent query: get patterns from any agent in a given domain.
+     * Useful for fleet-wide expertise ("what has any agent learned about X?").
+     */
+    queryFleet(domain, opts) {
+        let sql = `
+      SELECT * FROM expertise_patterns
+      WHERE domain = ?
+      AND invalidated_at IS NULL
+      AND decay_score < 0.8
+    `;
+        const params = [domain];
+        if (opts?.minConfidence) {
+            sql += ' AND confidence >= ?';
+            params.push(opts.minConfidence);
+        }
+        sql += ' ORDER BY confidence DESC, frequency DESC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parsePatternRow);
+    }
+    /**
+     * Graduate an observation to a pattern.
+     *
+     * If a similar pattern already exists (same agent, domain, and pattern text prefix match),
+     * increments its frequency and updates lastConfirmed instead of creating a duplicate.
+     *
+     * Auto-graduation happens when an observation has N≥graduationThreshold confirming
+     * evidence links. Can also be called manually.
+     */
+    graduate(agentId, observationId, opts) {
+        // Get the observation
+        const obsRow = this.db.prepare('SELECT * FROM expertise_observations WHERE id = ? AND agent_id = ?').get(observationId, agentId);
+        if (!obsRow)
+            return null;
+        const obs = parseObservationRow(obsRow);
+        const patternText = opts?.patternText || obs.observationText;
+        const confidence = opts?.confidence || 0.7;
+        const now = nowIso();
+        // Check for existing similar pattern (same domain, prefix match)
+        const prefix = patternText.slice(0, 80);
+        const existing = this.db.prepare(`
+      SELECT * FROM expertise_patterns
+      WHERE agent_id = ? AND domain = ? AND pattern_text LIKE ?
+      AND invalidated_at IS NULL
+      LIMIT 1
+    `).get(agentId, obs.domain, `${prefix}%`);
+        if (existing) {
+            // Increment frequency and update
+            this.db.prepare(`
+        UPDATE expertise_patterns
+        SET frequency = frequency + 1,
+            confidence = MAX(confidence, ?),
+            last_confirmed = ?,
+            decay_score = MAX(decay_score - 0.1, 0)
+        WHERE id = ?
+      `).run(confidence, now, existing.id);
+            // Link evidence
+            this.db.prepare(`
+        INSERT INTO expertise_evidence (observation_id, pattern_id, relationship, created_at)
+        VALUES (?, ?, 'confirms', ?)
+      `).run(observationId, existing.id, now);
+            // Return updated pattern
+            const updated = this.db.prepare('SELECT * FROM expertise_patterns WHERE id = ?')
+                .get(existing.id);
+            return parsePatternRow(updated);
+        }
+        // Create new pattern
+        const result = this.db.prepare(`
+      INSERT INTO expertise_patterns
+        (agent_id, domain, pattern_text, confidence, frequency, first_seen, last_confirmed, decay_score)
+      VALUES (?, ?, ?, ?, 1, ?, ?, 0.0)
+    `).run(agentId, obs.domain, patternText, confidence, now, now);
+        const patternId = Number(result.lastInsertRowid);
+        // Link the graduating observation as evidence
+        this.db.prepare(`
+      INSERT INTO expertise_evidence (observation_id, pattern_id, relationship, created_at)
+      VALUES (?, ?, 'confirms', ?)
+    `).run(observationId, patternId, now);
+        return {
+            id: patternId,
+            agentId,
+            domain: obs.domain,
+            patternText,
+            confidence,
+            frequency: 1,
+            firstSeen: now,
+            lastConfirmed: now,
+            invalidatedAt: null,
+            invalidationReason: null,
+            decayScore: 0,
+        };
+    }
+    /**
+     * Record evidence linking an observation to a pattern.
+     * If this pushes a pattern's contradicting evidence past threshold,
+     * auto-invalidates the pattern.
+     */
+    addEvidence(observationId, patternId, relationship) {
+        const now = nowIso();
+        this.db.prepare(`
+      INSERT INTO expertise_evidence (observation_id, pattern_id, relationship, created_at)
+      VALUES (?, ?, ?, ?)
+    `).run(observationId, patternId, relationship, now);
+        if (relationship === 'confirms') {
+            // Boost the pattern
+            this.db.prepare(`
+        UPDATE expertise_patterns
+        SET frequency = frequency + 1,
+            last_confirmed = ?,
+            decay_score = MAX(decay_score - 0.05, 0)
+        WHERE id = ?
+      `).run(now, patternId);
+        }
+        else {
+            // Contradicting: increase decay, check if should invalidate
+            this.db.prepare(`
+        UPDATE expertise_patterns
+        SET decay_score = MIN(decay_score + 0.2, 1.0)
+        WHERE id = ?
+      `).run(patternId);
+            // Count contradictions vs confirmations
+            const counts = this.db.prepare(`
+        SELECT relationship, COUNT(*) as cnt
+        FROM expertise_evidence
+        WHERE pattern_id = ?
+        GROUP BY relationship
+      `).all(patternId);
+            const confirms = counts.find(c => c.relationship === 'confirms')?.cnt ?? 0;
+            const contradicts = counts.find(c => c.relationship === 'contradicts')?.cnt ?? 0;
+            // Auto-invalidate if contradictions exceed confirmations
+            if (contradicts > confirms) {
+                this.invalidate(patternId, 'auto: contradicting evidence exceeded confirmations');
+            }
+        }
+    }
+    /**
+     * Check if any observations are ready for auto-graduation.
+     * An observation graduates when it has N≥threshold confirming evidence links.
+     * Returns the number of newly graduated patterns.
+     */
+    autoGraduate(agentId) {
+        // Find observations with enough confirming evidence that aren't already patterns
+        const candidates = this.db.prepare(`
+      SELECT e.observation_id, COUNT(*) as confirm_count
+      FROM expertise_evidence e
+      JOIN expertise_observations o ON o.id = e.observation_id
+      WHERE o.agent_id = ?
+      AND e.relationship = 'confirms'
+      AND e.observation_id NOT IN (
+        SELECT DISTINCT e2.observation_id FROM expertise_evidence e2
+        JOIN expertise_patterns p ON p.id = e2.pattern_id
+        WHERE p.agent_id = ?
+      )
+      GROUP BY e.observation_id
+      HAVING COUNT(*) >= ?
+    `).all(agentId, agentId, this.graduationThreshold);
+        let graduated = 0;
+        for (const candidate of candidates) {
+            const result = this.graduate(agentId, candidate.observation_id);
+            if (result)
+                graduated++;
+        }
+        return graduated;
+    }
+    /**
+     * Mark a pattern as invalidated.
+     */
+    invalidate(patternId, reason) {
+        const now = nowIso();
+        const result = this.db.prepare(`
+      UPDATE expertise_patterns
+      SET invalidated_at = ?, invalidation_reason = ?, updated_at = ?
+      WHERE id = ? AND invalidated_at IS NULL
+    `).run(now, reason, now, patternId);
+        return result.changes > 0;
+    }
+    /**
+     * List all active patterns for an agent, optionally filtered by domain.
+     */
+    list(agentId, opts) {
+        let sql = 'SELECT * FROM expertise_patterns WHERE agent_id = ?';
+        const params = [agentId];
+        if (opts?.domain) {
+            sql += ' AND domain = ?';
+            params.push(opts.domain);
+        }
+        if (!opts?.includeInvalidated) {
+            sql += ' AND invalidated_at IS NULL';
+        }
+        sql += ' ORDER BY confidence DESC, frequency DESC';
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parsePatternRow);
+    }
+    /**
+     * Decay all patterns by a fixed rate. Similar to fact decay.
+     */
+    decayPatterns(agentId, decayRate = 0.005) {
+        const result = this.db.prepare(`
+      UPDATE expertise_patterns
+      SET decay_score = MIN(decay_score + ?, 1.0)
+      WHERE agent_id = ? AND decay_score < 1.0 AND invalidated_at IS NULL
+    `).run(decayRate, agentId);
+        return result.changes;
+    }
+    /**
+     * Get pattern and observation counts for an agent.
+     */
+    getStats(agentId) {
+        const obs = this.db.prepare('SELECT COUNT(*) as count FROM expertise_observations WHERE agent_id = ?').get(agentId);
+        const active = this.db.prepare('SELECT COUNT(*) as count FROM expertise_patterns WHERE agent_id = ? AND invalidated_at IS NULL').get(agentId);
+        const invalidated = this.db.prepare('SELECT COUNT(*) as count FROM expertise_patterns WHERE agent_id = ? AND invalidated_at IS NOT NULL').get(agentId);
+        return {
+            observations: obs.count,
+            activePatterns: active.count,
+            invalidatedPatterns: invalidated.count,
+        };
+    }
+}
+//# sourceMappingURL=expertise-store.js.map

package/dist/fact-store.d.ts

@@ -71,5 +71,20 @@ export declare class FactStore {
      * Get fact count for an agent.
      */
     getFactCount(agentId: string): number;
+    /**
+     * Get facts that were valid at a specific point in time.
+     * Returns facts where valid_from <= dateMs AND (invalid_at IS NULL OR invalid_at > dateMs).
+     * This enables "what was true on date X?" queries (Zep-competitive).
+     */
+    getFactsValidAt(agentId: string, dateMs: number, opts?: {
+        domain?: string;
+        limit?: number;
+    }): Fact[];
+    /**
+     * Mark a fact as invalid at a specific time (or now).
+     * Unlike supersede, this doesn't require a replacement fact.
+     * Used by contradiction detection to mark stale facts.
+     */
+    invalidateFact(factId: number, atDate?: string): boolean;
 }
 //# sourceMappingURL=fact-store.d.ts.map

package/dist/fact-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fact-store.d.ts","sourceRoot":"","sources":["../src/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA2BlD,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,OAAO,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,IAAI;IA4EP;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,IAAI,EAAE;IAkCT;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,EAAE;IAoCV;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAY7D;;;;;;OAMG;IACH,yBAAyB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,MAAM,GAAG,IAAI;IA0BhB;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM;IAU7D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAanC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAMtC"}
+{"version":3,"file":"fact-store.d.ts","sourceRoot":"","sources":["../src/fact-store.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AA6BlD,qBAAa,SAAS;IACR,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,YAAY;IAE7C;;OAEG;IACH,OAAO,CACL,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,GACA,IAAI;IA+EP;;OAEG;IACH,cAAc,CACZ,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,KAAK,CAAC,EAAE,SAAS,CAAC;QAClB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,GACA,IAAI,EAAE;IAkCT;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAChC,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GAAG,IAAI,EAAE;IAoCV;;;;;;OAMG;IACH,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO;IAY7D;;;;;;OAMG;IACH,yBAAyB,CACvB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GACzB,MAAM,GAAG,IAAI;IA0BhB;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,MAAM;IAU7D;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAanC;;OAEG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAOrC;;;;OAIG;IACH,eAAe,CACb,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QACL,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,GACA,IAAI,EAAE;IA4BT;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO;CAUzD"}

package/dist/fact-store.js

@@ -26,6 +26,8 @@ function parseFactRow(row) {
         expiresAt: row.expires_at || null,
         supersededBy: row.superseded_by || null,
         decayScore: row.decay_score,
+        validFrom: row.valid_from || null,
+        invalidAt: row.invalid_at || null,
     };
 }
 export class FactStore {
@@ -66,9 +68,9 @@ export class FactStore {
         const result = this.db.prepare(`
       INSERT INTO facts (agent_id, scope, domain, content, confidence,
         visibility, source_type, source_session_key, source_ref,
-        created_at, updated_at, expires_at, decay_score)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0.0)
-    `).run(agentId, scope, opts?.domain || null, content, opts?.confidence || 1.0, resolvedVisibility, opts?.sourceType || 'conversation', opts?.sourceSessionKey || null, opts?.sourceRef || null, now, now, opts?.expiresAt || null);
+        created_at, updated_at, expires_at, decay_score, valid_from)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0.0, ?)
+    `).run(agentId, scope, opts?.domain || null, content, opts?.confidence || 1.0, resolvedVisibility, opts?.sourceType || 'conversation', opts?.sourceSessionKey || null, opts?.sourceRef || null, now, now, opts?.expiresAt || null, now);
         const id = Number(result.lastInsertRowid);
         return {
             id,
@@ -86,6 +88,8 @@ export class FactStore {
             expiresAt: opts?.expiresAt || null,
             supersededBy: null,
             decayScore: 0,
+            validFrom: now,
+            invalidAt: null,
         };
     }
     /**
@@ -166,10 +170,10 @@ export class FactStore {
         const result = this.db
             .prepare(`
         UPDATE facts
-        SET superseded_by = ?, updated_at = ?
+        SET superseded_by = ?, invalid_at = ?, updated_at = ?
         WHERE id = ? AND superseded_by IS NULL
       `)
-            .run(newFactId, now, oldFactId);
+            .run(newFactId, now, now, oldFactId);
         return result.changes > 0;
     }
     /**
@@ -232,5 +236,48 @@ export class FactStore {
         const row = this.db.prepare('SELECT COUNT(*) AS count FROM facts WHERE agent_id = ?').get(agentId);
         return row.count;
     }
+    /**
+     * Get facts that were valid at a specific point in time.
+     * Returns facts where valid_from <= dateMs AND (invalid_at IS NULL OR invalid_at > dateMs).
+     * This enables "what was true on date X?" queries (Zep-competitive).
+     */
+    getFactsValidAt(agentId, dateMs, opts) {
+        const dateIso = new Date(dateMs).toISOString();
+        let sql = `
+      SELECT * FROM facts
+      WHERE agent_id = ?
+      AND (valid_from IS NULL OR valid_from <= ?)
+      AND (invalid_at IS NULL OR invalid_at > ?)
+      AND superseded_by IS NULL
+      AND decay_score < 0.8
+    `;
+        const params = [agentId, dateIso, dateIso];
+        if (opts?.domain) {
+            sql += ' AND domain = ?';
+            params.push(opts.domain);
+        }
+        sql += ' ORDER BY confidence DESC, decay_score ASC';
+        if (opts?.limit) {
+            sql += ' LIMIT ?';
+            params.push(opts.limit);
+        }
+        const rows = this.db.prepare(sql).all(...params);
+        return rows.map(parseFactRow);
+    }
+    /**
+     * Mark a fact as invalid at a specific time (or now).
+     * Unlike supersede, this doesn't require a replacement fact.
+     * Used by contradiction detection to mark stale facts.
+     */
+    invalidateFact(factId, atDate) {
+        const invalidAt = atDate || new Date().toISOString();
+        const result = this.db
+            .prepare(`
+        UPDATE facts SET invalid_at = ?, updated_at = ?
+        WHERE id = ? AND invalid_at IS NULL
+      `)
+            .run(invalidAt, invalidAt, factId);
+        return result.changes > 0;
+    }
 }
 //# sourceMappingURL=fact-store.js.map

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * @module @psiclawops/hypermem
  *
  * Architecture:
- *   L1: Redis       — hot session working memory
+ *   L1: CacheLayer  — SQLite `:memory:` hot session working memory
  *   L2: messages.db — per-agent conversation log (rotatable)
  *   L3: vectors.db  — per-agent semantic search index (reconstructable)
  *   L4: library.db  — fleet-wide structured knowledge (crown jewel)
@@ -13,6 +13,8 @@ export { ENGINE_VERSION, MIN_NODE_VERSION, MIN_REDIS_VERSION, SQLITE_VEC_VERSION
 export { DatabaseManager } from './db.js';
 export type { DatabaseManagerConfig } from './db.js';
 export { MessageStore } from './message-store.js';
+export { ToolArtifactStore } from './tool-artifact-store.js';
+export type { ToolArtifactRecord, PutToolArtifactInput } from './tool-artifact-store.js';
 export { FactStore } from './fact-store.js';
 export { KnowledgeStore } from './knowledge-store.js';
 export type { LinkType } from './knowledge-store.js';
@@ -25,10 +27,12 @@ export type { FleetAgent, FleetOrg, AgentCapability } from './fleet-store.js';
 export { SystemStore } from './system-store.js';
 export type { SystemState, SystemEvent } from './system-store.js';
 export { WorkStore } from './work-store.js';
-export { ensureContextSchema, getActiveContext, getOrCreateActiveContext, updateContextHead, archiveContext, rotateSessionContext } from './context-store.js';
+export { ensureContextSchema, getActiveContext, getOrCreateActiveContext, updateContextHead, archiveContext, rotateSessionContext, getContextById, getArchivedContexts, getArchivedContext, getContextLineage, getForkChildren } from './context-store.js';
 export type { Context } from './context-store.js';
 export type { WorkItem, WorkEvent, WorkStatus } from './work-store.js';
 export { DesiredStateStore } from './desired-state-store.js';
+export { ExpertiseStore } from './expertise-store.js';
+export type { ExpertiseObservation, ExpertisePattern, ExpertiseEvidence } from './expertise-store.js';
 export { evictStaleContent, DEFAULT_EVICTION_CONFIG } from './image-eviction.js';
 export type { ImageEvictionConfig, EvictionStats, EvictionResult } from './image-eviction.js';
 export { KnowledgeGraph } from './knowledge-graph.js';
@@ -38,7 +42,12 @@ export type { RateLimiterConfig, Priority } from './rate-limiter.js';
 export type { DesiredStateEntry, ConfigEvent, DriftStatus } from './desired-state-store.js';
 export type { ModelState } from './cache.js';
 export { CacheLayer } from './cache.js';
-export { Compositor, type CompositorDeps, applyToolGradientToWindow, canPersistReshapedHistory, OPENCLAW_BOOTSTRAP_FILES } from './compositor.js';
+export { TRIM_SOFT_TARGET, TRIM_GROWTH_THRESHOLD, TRIM_HEADROOM_FRACTION, TRIM_BUDGET_POLICY, resolveTrimBudgets, } from './budget-policy.js';
+export { DEGRADATION_REASONS, DEGRADATION_LIMITS, isDegradationReason, isReplayState, formatToolChainStub, parseToolChainStub, isToolChainStub, formatArtifactRef, parseArtifactRef, isArtifactRef, formatReplayMarker, parseReplayMarker, isReplayMarker, isDegradedContent, } from './degradation.js';
+export type { DegradationReason, ToolChainStub, ArtifactRef, ReplayMarker, ReplayState, DegradationEvent, } from './degradation.js';
+export { REPLAY_RECOVERY_POLICY, decideReplayRecovery, isColdRedisReplay, isReplayRecovered, } from './replay-recovery.js';
+export type { ReplayRecoveryInputs, ReplayRecoveryDecision } from './replay-recovery.js';
+export { Compositor, type CompositorDeps, applyToolGradientToWindow, canPersistReshapedHistory, OPENCLAW_BOOTSTRAP_FILES, resolveToolChainEjections, type ToolChainEjectionResult } from './compositor.js';
 export { type CollectionTrigger, TRIGGER_REGISTRY, TRIGGER_REGISTRY_VERSION, TRIGGER_REGISTRY_HASH, DEFAULT_TRIGGERS, matchTriggers, } from './trigger-registry.js';
 export { ensureCompactionFenceSchema, updateCompactionFence, getCompactionFence, getCompactionEligibility, getCompactableMessages, } from './compaction-fence.js';
 export type { CompactionFence, CompactionEligibility } from './compaction-fence.js';
@@ -51,6 +60,8 @@ export { VectorStore, generateEmbeddings } from './vector-store.js';
 export type { EmbeddingConfig, VectorSearchResult, VectorIndexStats } from './vector-store.js';
 export { hybridSearch, buildFtsQuery } from './hybrid-retrieval.js';
 export type { HybridSearchResult, HybridSearchOptions } from './hybrid-retrieval.js';
+export { ContradictionDetector } from './contradiction-detector.js';
+export type { ContradictionCandidate, ContradictionResult, ContradictionDetectorConfig } from './contradiction-detector.js';
 export { DocChunkStore } from './doc-chunk-store.js';
 export type { DocChunkRow, ChunkQuery, IndexResult as DocIndexResult } from './doc-chunk-store.js';
 export { WorkspaceSeeder, seedWorkspace } from './seed.js';
@@ -71,7 +82,7 @@ export type { LintResult } from './knowledge-lint.js';
 export { buildSpawnContext } from './spawn-context.js';
 export type { SpawnContextOptions, SpawnContext } from './spawn-context.js';
 export { runNoiseSweep, runToolDecay, type NoiseSweepResult, type ToolDecayResult } from './proactive-pass.js';
-export type { NeutralMessage, NeutralToolCall, NeutralToolResult, StoredMessage, MessageRole, ProviderMessage, Conversation, Fact, Topic, Knowledge, Episode, ComposeRequest, ComposeResult, ComposeDiagnostics, SlotTokenCounts, SessionSlots, SessionMeta, HyperMemConfig, RedisConfig, CompositorConfig, IndexerConfig, ChannelType, ConversationStatus, FactScope, TopicStatus, EpisodeType, MemoryVisibility, CrossAgentQuery, AgentIdentity, SessionCursor, RecentTurn, } from './types.js';
+export type { NeutralMessage, NeutralToolCall, NeutralToolResult, StoredMessage, MessageRole, ProviderMessage, Conversation, Fact, Topic, Knowledge, Episode, ComposeRequest, ComposeResult, ComposeDiagnostics, SlotTokenCounts, SessionSlots, SessionMeta, HyperMemConfig, RedisConfig, CompositorConfig, IndexerConfig, ChannelType, ConversationStatus, FactScope, TopicStatus, EpisodeType, MemoryVisibility, CrossAgentQuery, AgentIdentity, SessionCursor, RecentTurn, ExpertiseSourceType, EvidenceRelationship, ArchivedMiningQuery, ArchivedMiningResult, MultiContextMiningOptions, } from './types.js';
 export type { ProviderType } from './provider-translator.js';
 export { classifyContentType, signalWeight, isSignalBearing, SIGNAL_WEIGHT } from './content-type-classifier.js';
 export type { ContentType, ContentTypeResult } from './content-type-classifier.js';
@@ -89,19 +100,34 @@ import { type EntityType, type KnowledgeLink, type GraphNode, type TraversalResu
 import { type DesiredStateEntry, type DriftStatus } from './desired-state-store.js';
 import { CacheLayer } from './cache.js';
 import { Compositor } from './compositor.js';
+import { type Context } from './context-store.js';
 import { VectorStore, type VectorSearchResult, type VectorIndexStats } from './vector-store.js';
 import { type DocChunkRow, type ChunkQuery, type IndexResult } from './doc-chunk-store.js';
 import { type SeedOptions, type SeedResult } from './seed.js';
 import { type DocChunk } from './doc-chunker.js';
-import type { HyperMemConfig, ComposeRequest, ComposeResult, NeutralMessage, StoredMessage, Conversation, ChannelType } from './types.js';
+import type { HyperMemConfig, ComposeRequest, ComposeResult, NeutralMessage, StoredMessage, Conversation, ChannelType, ArchivedMiningQuery, ArchivedMiningResult, MultiContextMiningOptions } from './types.js';
 import { type OrgRegistry } from './cross-agent.js';
+export interface StartupFleetSeedOptions {
+    workspaceRoots?: string[];
+    includeMessageDbAgents?: boolean;
+    hydrateCache?: boolean;
+}
+export interface StartupFleetSeedResult {
+    discovered: number;
+    inserted: number;
+    updated: number;
+    skipped: number;
+    orgsCreated: number;
+    hydratedAgents: number;
+    hydratedSummary: boolean;
+}
 /**
  * hypermem — the main API facade.
  *
  * Usage:
  *   const hm = await hypermem.create({ dataDir: '~/.openclaw/hypermem' });
- *   await hm.record('agent1', 'agent:agent1:webchat:main', userMsg);
- *   const result = await hm.compose({ agentId: 'agent1', sessionKey: '...', ... });
+ *   await hm.record('alice', 'agent:alice:webchat:main', userMsg);
+ *   const result = await hm.compose({ agentId: 'alice', sessionKey: '...', ... });
  */
 export declare class HyperMem {
     readonly dbManager: DatabaseManager;
@@ -145,6 +171,38 @@ export declare class HyperMem {
      * Compose context for an LLM call.
      */
     compose(request: ComposeRequest): Promise<ComposeResult>;
+    /**
+     * Persist a full tool result payload and return the durable record.
+     * Used by the plugin wave-guard to capture payloads before stubbing the
+     * transcript. Dedupes by content hash within the (agentId, sessionKey)
+     * scope — identical payloads bump ref_count on the existing row.
+     */
+    recordToolArtifact(agentId: string, sessionKey: string, input: Omit<import('./tool-artifact-store.js').PutToolArtifactInput, 'agentId' | 'sessionKey'>): Promise<import('./tool-artifact-store.js').ToolArtifactRecord>;
+    /** Fetch a tool artifact by id. Returns null if unknown. */
+    getToolArtifact(agentId: string, artifactId: string): Promise<import('./tool-artifact-store.js').ToolArtifactRecord | null>;
+    /** List tool artifacts for a specific turn. */
+    listToolArtifactsByTurn(agentId: string, sessionKey: string, turnId: string): Promise<import('./tool-artifact-store.js').ToolArtifactRecord[]>;
+    /**
+     * List archived or forked contexts for an agent.
+     *
+     * operator-safe enumeration path. This is the approved archived-context
+     * listing surface. Active composition remains separate.
+     */
+    listArchivedContexts(agentId: string, opts?: {
+        sessionKey?: string;
+        limit?: number;
+    }): Context[];
+    /**
+     * Mine a single archived or forked context through the archived-mining
+     * surface. This does not widen active composition.
+     */
+    mineArchivedContext(agentId: string, query: ArchivedMiningQuery): ArchivedMiningResult<StoredMessage[]>;
+    /**
+     * Mine multiple archived or forked contexts through the capped archived-
+     * mining surface. This does not expose raw DAG helpers and does not widen
+     * active composition.
+     */
+    mineArchivedContexts(agentId: string, contextIds: number[], opts?: MultiContextMiningOptions): ArchivedMiningResult<StoredMessage[]>[];
     /**
      * Warm a session from SQLite into Redis.
      */
@@ -155,7 +213,7 @@ export declare class HyperMem {
     /**
      * Recompute the Redis hot history view from SQLite and re-apply tool gradient.
      */
-    refreshRedisGradient(agentId: string, sessionKey: string, tokenBudget?: number): Promise<void>;
+    refreshRedisGradient(agentId: string, sessionKey: string, tokenBudget?: number, historyDepth?: number): Promise<void>;
     /**
      * Full-text search across all messages for an agent.
      */
@@ -618,6 +676,14 @@ export declare class HyperMem {
         agentId?: string;
         collection?: string;
     }): import("./doc-chunk-store.js").DocSourceRow[];
+    /**
+     * Seed fleet agents from known workspace identity files and existing
+     * message-db agent directories, then optionally hydrate the Redis fleet cache.
+     *
+     * The sweep is idempotent: existing rows are only updated when startup-discovered
+     * values differ, so repeated boots do not duplicate or churn fleet rows.
+     */
+    seedFleetAgentsOnStartup(opts?: StartupFleetSeedOptions): Promise<StartupFleetSeedResult>;
     /**
      * Hydrate the Redis fleet cache from library.db.
      * Call on gateway startup to warm the cache for dashboard queries.