@cleocode/core 2026.4.31 → 2026.4.36

package/dist/memory/brain-consolidator.js

@@ -0,0 +1,294 @@
+/**
+ * Brain Consolidator — contradiction detection for the CLEO BRAIN memory system.
+ *
+ * Implements heuristic contradiction detection based on keyword polarity flip.
+ * No LLM required — uses negation markers to identify entries that assert
+ * opposing claims about the same subject.
+ *
+ * When a contradiction is detected:
+ *   1. A 'contradicts' edge is created in brain_page_edges (both directions).
+ *   2. The lower-quality entry's qualityScore is reduced by 0.15.
+ *
+ * All operations are BEST-EFFORT — failures never crash the consolidator.
+ *
+ * @task T549 Wave 3-C
+ * @epic T549
+ */
+import { getBrainDb, getBrainNativeDb } from '../store/brain-sqlite.js';
+import { typedAll } from '../store/typed-query.js';
+// ============================================================================
+// Constants
+// ============================================================================
+/** Minimum number of shared keywords to consider two entries related. */
+const MIN_SHARED_KEYWORDS = 3;
+/**
+ * Negation markers that, when present in one entry but not the other,
+ * indicate a potential contradiction.
+ */
+const NEGATION_MARKERS = [
+    'not',
+    'never',
+    'deprecated',
+    'removed',
+    'replaced',
+    'avoid',
+    'no longer',
+    'do not',
+    "don't",
+    'disabled',
+    'deleted',
+    'dropped',
+    'broken',
+    'invalid',
+    'obsolete',
+    'reverted',
+    'undone',
+    'superseded',
+];
+/** Stop words excluded from keyword extraction (matches brain-lifecycle stop words). */
+const STOP_WORDS = new Set([
+    'the',
+    'a',
+    'an',
+    'is',
+    'are',
+    'was',
+    'were',
+    'be',
+    'been',
+    'being',
+    'have',
+    'has',
+    'had',
+    'do',
+    'does',
+    'did',
+    'will',
+    'would',
+    'could',
+    'should',
+    'may',
+    'might',
+    'shall',
+    'can',
+    'to',
+    'of',
+    'in',
+    'for',
+    'on',
+    'with',
+    'at',
+    'by',
+    'from',
+    'as',
+    'into',
+    'through',
+    'and',
+    'but',
+    'or',
+    'nor',
+    'so',
+    'yet',
+    'this',
+    'that',
+    'these',
+    'those',
+    'it',
+    'its',
+    'not',
+    'no',
+]);
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Extract significant keywords from text for overlap comparison.
+ * Filters stop words and tokens shorter than 4 characters.
+ */
+function extractKeywords(text) {
+    const words = text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s\-_]/g, ' ')
+        .split(/\s+/);
+    const keywords = new Set();
+    for (const w of words) {
+        if (w.length >= 4 && !STOP_WORDS.has(w)) {
+            keywords.add(w);
+        }
+    }
+    return keywords;
+}
+/**
+ * Find negation markers present in the text.
+ */
+function findNegationMarkers(text) {
+    const lower = text.toLowerCase();
+    return NEGATION_MARKERS.filter((marker) => lower.includes(marker));
+}
+/**
+ * Return the intersection of two keyword sets.
+ */
+function keywordIntersection(a, b) {
+    const result = [];
+    for (const w of a) {
+        if (b.has(w))
+            result.push(w);
+    }
+    return result;
+}
+// ============================================================================
+// Main Export
+// ============================================================================
+/**
+ * Detect contradiction pairs across all verified memory entries.
+ *
+ * For each verified entry:
+ *   1. Find entries with >= MIN_SHARED_KEYWORDS shared keywords.
+ *   2. Check for negation markers in one but not the other.
+ *   3. If contradiction detected: create 'contradicts' graph edges.
+ *   4. Lower quality score of the contradicted (lower quality) entry by 0.15.
+ *
+ * Only considers entries where invalid_at IS NULL (currently valid).
+ * Short-circuits after 50 contradiction pairs to limit consolidation cost.
+ *
+ * @param projectRoot - Project root directory for brain.db resolution
+ * @returns List of contradiction pairs found
+ */
+export async function detectContradictions(projectRoot) {
+    await getBrainDb(projectRoot);
+    const nativeDb = getBrainNativeDb();
+    if (!nativeDb)
+        return [];
+    const results = [];
+    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    // Process each table that holds verified entries
+    const tables = [
+        { table: 'brain_observations', textCol: 'narrative' },
+        { table: 'brain_learnings', textCol: 'insight' },
+        { table: 'brain_patterns', textCol: 'pattern' },
+        { table: 'brain_decisions', textCol: 'decision' },
+    ];
+    for (const { table, textCol } of tables) {
+        if (results.length >= 50)
+            break;
+        let entries = [];
+        try {
+            // Only examine verified, valid entries for contradiction scanning
+            entries = typedAll(nativeDb.prepare(`
+          SELECT id, COALESCE(${textCol}, '') AS text, quality_score
+          FROM ${table}
+          WHERE invalid_at IS NULL
+            AND verified = 1
+          LIMIT 200
+        `));
+        }
+        catch {
+            // Table or column may not exist — best-effort
+            continue;
+        }
+        if (entries.length < 2)
+            continue;
+        // Extract keywords for all entries up front
+        const keywordMap = new Map();
+        const negationMap = new Map();
+        for (const entry of entries) {
+            keywordMap.set(entry.id, extractKeywords(entry.text));
+            negationMap.set(entry.id, findNegationMarkers(entry.text));
+        }
+        // Compare all pairs — O(n²) but capped at 200 entries (40k ops max)
+        for (let i = 0; i < entries.length; i++) {
+            if (results.length >= 50)
+                break;
+            const entryA = entries[i];
+            const keywordsA = keywordMap.get(entryA.id);
+            const negationsA = negationMap.get(entryA.id);
+            for (let j = i + 1; j < entries.length; j++) {
+                if (results.length >= 50)
+                    break;
+                const entryB = entries[j];
+                const keywordsB = keywordMap.get(entryB.id);
+                const negationsB = negationMap.get(entryB.id);
+                // Step 1: Need sufficient shared keywords to be "about the same thing"
+                const shared = keywordIntersection(keywordsA, keywordsB);
+                if (shared.length < MIN_SHARED_KEYWORDS)
+                    continue;
+                // Step 2: Check for negation polarity flip — one entry negates the other
+                // A contradiction occurs when one entry has negation markers that the other lacks
+                const negationsOnlyInA = negationsA.filter((m) => !negationsB.includes(m));
+                const negationsOnlyInB = negationsB.filter((m) => !negationsA.includes(m));
+                const negationFlip = negationsOnlyInA.length > 0 || negationsOnlyInB.length > 0;
+                if (!negationFlip)
+                    continue;
+                // Found a contradiction pair
+                const negMarkers = [...negationsOnlyInA, ...negationsOnlyInB];
+                // The contradicted entry is the lower-quality one
+                const qualA = entryA.quality_score ?? 0.5;
+                const qualB = entryB.quality_score ?? 0.5;
+                const contradictedId = qualA <= qualB ? entryA.id : entryB.id;
+                const winningId = contradictedId === entryA.id ? entryB.id : entryA.id;
+                results.push({
+                    entryAId: entryA.id,
+                    entryBId: entryB.id,
+                    contradictedId,
+                    table,
+                    sharedKeywords: shared.slice(0, 10),
+                    negationMarkers: negMarkers.slice(0, 5),
+                });
+                // Step 3: Create 'contradicts' graph edges (best-effort)
+                const nodeA = buildNodeId(table, entryA.id);
+                const nodeB = buildNodeId(table, entryB.id);
+                try {
+                    nativeDb
+                        .prepare(`
+              INSERT OR IGNORE INTO brain_page_edges
+                (from_id, to_id, edge_type, weight, provenance, created_at)
+              VALUES (?, ?, 'contradicts', 0.8, 'consolidation:contradiction', ?)
+            `)
+                        .run(nodeA, nodeB, now);
+                    nativeDb
+                        .prepare(`
+              INSERT OR IGNORE INTO brain_page_edges
+                (from_id, to_id, edge_type, weight, provenance, created_at)
+              VALUES (?, ?, 'contradicts', 0.8, 'consolidation:contradiction', ?)
+            `)
+                        .run(nodeB, nodeA, now);
+                }
+                catch {
+                    /* graph population is best-effort */
+                }
+                // Step 4: Lower quality of the contradicted entry by 0.15
+                try {
+                    nativeDb
+                        .prepare(`
+              UPDATE ${table}
+              SET quality_score = MAX(0.0, COALESCE(quality_score, 0.5) - 0.15),
+                  updated_at = ?
+              WHERE id = ?
+            `)
+                        .run(now, contradictedId);
+                    // Also ensure the winning entry's quality is noted
+                    void winningId; // used above for clarity
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Build the graph node ID for a given table + entry ID combination.
+ * Mirrors the convention used in graph-auto-populate.ts.
+ */
+function buildNodeId(table, entryId) {
+    const typeMap = {
+        brain_observations: 'observation',
+        brain_learnings: 'learning',
+        brain_patterns: 'pattern',
+        brain_decisions: 'decision',
+    };
+    const type = typeMap[table] ?? 'entry';
+    return `${type}:${entryId}`;
+}
+//# sourceMappingURL=brain-consolidator.js.map

package/dist/memory/brain-consolidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-consolidator.js","sourceRoot":"","sources":["../../src/memory/brain-consolidator.ts"],"names":[],"mappings":"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"}

package/dist/memory/brain-embedding.js

@@ -0,0 +1,66 @@
+/**
+ * Brain Embedding System
+ *
+ * Provides text-to-vector embedding for semantic search in brain.db.
+ * Uses a pluggable provider interface — real model integration
+ * (e.g. @huggingface/transformers with all-MiniLM-L6-v2) is separate
+ * from the embedding pipeline. When no provider is set, the system
+ * falls back to FTS5-only search gracefully.
+ *
+ * @epic T5149
+ * @task T5386
+ */
+/** Matches the brain_embeddings vec0 table: FLOAT[384]. */
+export const EMBEDDING_DIMENSIONS = 384;
+let currentProvider = null;
+/**
+ * Register an embedding provider for the brain system.
+ * Validates that the provider's dimensions match the vec0 table.
+ *
+ * @throws Error if provider dimensions do not match EMBEDDING_DIMENSIONS
+ */
+export function setEmbeddingProvider(provider) {
+    if (provider.dimensions !== EMBEDDING_DIMENSIONS) {
+        throw new Error(`Embedding provider dimensions (${provider.dimensions}) do not match vec0 table (${EMBEDDING_DIMENSIONS})`);
+    }
+    currentProvider = provider;
+}
+/** Get the currently registered embedding provider, or null. */
+export function getEmbeddingProvider() {
+    return currentProvider;
+}
+/** Clear the current embedding provider (useful for testing). */
+export function clearEmbeddingProvider() {
+    currentProvider = null;
+}
+/**
+ * Embed text into a float vector using the registered provider.
+ * Returns null when no provider is set or not available (FTS5-only fallback).
+ */
+export async function embedText(text) {
+    if (!currentProvider || !currentProvider.isAvailable())
+        return null;
+    return currentProvider.embed(text);
+}
+/** Check whether embedding is currently available. */
+export function isEmbeddingAvailable() {
+    return currentProvider?.isAvailable() ?? false;
+}
+/**
+ * Initialize the default local embedding provider.
+ *
+ * Loads the LocalEmbeddingProvider dynamically and registers it via
+ * setEmbeddingProvider(). Should be called once at startup when
+ * `brain.embedding.enabled` is true.
+ *
+ * Uses dynamic import to avoid loading the heavy @huggingface/transformers
+ * bundle unless embedding is actually requested.
+ *
+ * @task T136 @epic T134
+ */
+export async function initDefaultProvider() {
+    const { LocalEmbeddingProvider } = await import('./embedding-local.js');
+    const provider = new LocalEmbeddingProvider();
+    setEmbeddingProvider(provider);
+}
+//# sourceMappingURL=brain-embedding.js.map

package/dist/memory/brain-embedding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"brain-embedding.js","sourceRoot":"","sources":["../../src/memory/brain-embedding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAYH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,oBAAoB,GAAG,GAAG,CAAC;AAExC,IAAI,eAAe,GAA6B,IAAI,CAAC;AAErD;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,QAA2B;IAC9D,IAAI,QAAQ,CAAC,UAAU,KAAK,oBAAoB,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CACb,kCAAkC,QAAQ,CAAC,UAAU,8BAA8B,oBAAoB,GAAG,CAC3G,CAAC;IACJ,CAAC;IACD,eAAe,GAAG,QAAQ,CAAC;AAC7B,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,oBAAoB;IAClC,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,sBAAsB;IACpC,eAAe,GAAG,IAAI,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,IAAY;IAC1C,IAAI,CAAC,eAAe,IAAI,CAAC,eAAe,CAAC,WAAW,EAAE;QAAE,OAAO,IAAI,CAAC;IACpE,OAAO,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AACrC,CAAC;AAED,sDAAsD;AACtD,MAAM,UAAU,oBAAoB;IAClC,OAAO,eAAe,EAAE,WAAW,EAAE,IAAI,KAAK,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB;IACvC,MAAM,EAAE,sBAAsB,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;IACxE,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC9C,oBAAoB,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC"}

package/dist/memory/brain-lifecycle.d.ts

@@ -1,5 +1,5 @@
 /**
- * BRAIN lifecycle operations — temporal decay and memory consolidation.
+ * BRAIN lifecycle operations — temporal decay, memory consolidation, and tier promotion.
  *
  * Reduces confidence of stale learnings based on age, following an
  * exponential decay model: new_confidence = confidence * (decayRate ^ daysSinceUpdate).
@@ -7,7 +7,13 @@
  * Consolidation groups old observations by keyword overlap and merges
  * clusters into summary observations, archiving the originals.
  *
- * @task T5394 T5395
+ * Wave 3 additions (T549):
+ * - runTierPromotion — promotes entries through short→medium→long based on citation count,
+ *   age, and verification; soft-evicts stale short-term entries.
+ * - runConsolidation — orchestrates all consolidation steps (dedup, quality recompute,
+ *   tier promotion, contradiction detection, soft eviction, graph strengthening, summaries).
+ *
+ * @task T5394 T5395 T549
  * @epic T5149
  */
 /** Result from applying temporal decay. */
@@ -54,4 +60,79 @@ export declare function consolidateMemories(projectRoot: string, options?: {
     olderThanDays?: number;
     minClusterSize?: number;
 }): Promise<ConsolidationResult>;
+/** A single promoted or evicted entry record. */
+export interface PromotionRecord {
+    id: string;
+    table: string;
+    fromTier: string;
+    toTier: string;
+    reason: string;
+}
+/** Eviction record for soft-evicted entries. */
+export interface EvictionRecord {
+    id: string;
+    table: string;
+    tier: string;
+    reason: string;
+}
+/** Result from runTierPromotion. */
+export interface PromotionResult {
+    promoted: PromotionRecord[];
+    evicted: EvictionRecord[];
+}
+/**
+ * Run tier promotion for all memory tables.
+ *
+ * Promotion rules (per spec §1.1–§1.3):
+ * - short → medium: citationCount >= 3 AND age > 24h AND verified = true
+ *   OR qualityScore >= 0.7 AND verified = true (fast-track)
+ * - medium → long:  citationCount >= 5 AND age > 7 days AND verified = true
+ *
+ * Eviction rules:
+ * - short-term entries older than shortTermEvictionDays (default 7) with no
+ *   promotion eligibility are soft-evicted (invalidAt = now).
+ * - long-term entries are NEVER auto-evicted.
+ *
+ * @param projectRoot - Project root directory for brain.db resolution
+ * @returns Lists of promoted and evicted entries
+ */
+export declare function runTierPromotion(projectRoot: string): Promise<PromotionResult>;
+/** Extended result returned by runConsolidation. */
+export interface RunConsolidationResult {
+    /** Entries merged by dedup pass. */
+    deduplicated: number;
+    /** Entries whose quality score was recomputed. */
+    qualityRecomputed: number;
+    /** Tier promotions applied. */
+    tierPromotions: PromotionResult;
+    /** Contradiction pairs found. */
+    contradictions: number;
+    /** Entries soft-evicted (low quality medium-term). */
+    softEvicted: number;
+    /** Graph edges strengthened. */
+    edgesStrengthened: number;
+    /** Summary nodes generated. */
+    summariesGenerated: number;
+}
+/**
+ * Run the full sleep-time consolidation pipeline.
+ *
+ * This is the "Letta OS sleep-time compute" pattern — consolidation runs
+ * during idle time (after session end), never during active work.
+ *
+ * Steps (in order):
+ *   1. Deduplication — merge entries with >0.85 content similarity
+ *   2. Quality recompute — recalculate scores with current age/citations
+ *   3. Tier promotion — runTierPromotion()
+ *   4. Contradiction detection — from brain-consolidator
+ *   5. Soft eviction — invalidate low-quality medium-term entries
+ *   6. Graph edge strengthening — increment weight on frequently-traversed edges
+ *   7. Summary generation — existing consolidateMemories() for large clusters
+ *
+ * All steps are BEST-EFFORT — any step failure is caught and logged to console.warn.
+ *
+ * @param projectRoot - Project root directory for brain.db resolution
+ * @returns Aggregated counts from each consolidation step
+ */
+export declare function runConsolidation(projectRoot: string): Promise<RunConsolidationResult>;
 //# sourceMappingURL=brain-lifecycle.d.ts.map

package/dist/memory/brain-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brain-lifecycle.d.ts","sourceRoot":"","sources":["../../src/memory/brain-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAOH,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAMD,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAmID;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,mBAAmB,CAAC,CA+G9B"}
+{"version":3,"file":"brain-lifecycle.d.ts","sourceRoot":"","sources":["../../src/memory/brain-lifecycle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,kBAAkB,CACtC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD,OAAO,CAAC,WAAW,CAAC,CAqCtB;AAMD,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAmID;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE;IAAE,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,mBAAmB,CAAC,CA+G9B;AAMD,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gDAAgD;AAChD,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAmKpF;AAMD,oDAAoD;AACpD,MAAM,WAAW,sBAAsB;IACrC,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAC;IACrB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,cAAc,EAAE,eAAe,CAAC;IAChC,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,gCAAgC;IAChC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+BAA+B;IAC/B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAuE3F"}