@cleocode/core 2026.4.37 → 2026.4.39

package/dist/memory/quality-feedback.js

@@ -0,0 +1,449 @@
+/**
+ * Memory Quality Feedback Loop — BRAIN self-improvement system.
+ *
+ * Closes the retrieval→usage→outcome loop so that memory quality scores
+ * reflect real-world utility, not just insert-time heuristics.
+ *
+ * Three operations:
+ *
+ * 1. trackMemoryUsage — record whether a retrieved memory was actually used
+ *    by an agent after task completion.
+ *
+ * 2. correlateOutcomes — scan the retrieval log, join against task outcomes,
+ *    and apply quality adjustments:
+ *      - Memory retrieved before a successful task completion: +0.05
+ *      - Memory retrieved before a failed task: -0.05
+ *      - Memory never retrieved in 30 days: flagged for pruning
+ *
+ * 3. getMemoryQualityReport — dashboard metrics over the entire brain.db.
+ *
+ * Schema addition: brain_usage_log (entry_id, task_id, used, outcome, created_at).
+ * The table is self-healing — created on first access.
+ *
+ * @task T555
+ */
+import { typedAll } from '../store/typed-query.js';
+// ============================================================================
+// Internal: schema bootstrap
+// ============================================================================
+/**
+ * Ensure brain_usage_log exists. Safe to call multiple times — uses
+ * CREATE TABLE IF NOT EXISTS. Returns silently on error (best-effort).
+ */
+async function ensureUsageLogTable(projectRoot) {
+    const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+    const nativeDb = getBrainNativeDb();
+    if (!nativeDb)
+        return;
+    try {
+        nativeDb
+            .prepare(`CREATE TABLE IF NOT EXISTS brain_usage_log (
+          id         INTEGER PRIMARY KEY AUTOINCREMENT,
+          entry_id   TEXT    NOT NULL,
+          task_id    TEXT,
+          used       INTEGER NOT NULL DEFAULT 0,
+          outcome    TEXT    NOT NULL DEFAULT 'unknown',
+          created_at TEXT    NOT NULL DEFAULT (datetime('now'))
+        )`)
+            .run();
+        // Index to speed up correlateOutcomes JOIN on entry_id.
+        nativeDb
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_brain_usage_log_entry_id
+         ON brain_usage_log(entry_id)`)
+            .run();
+        // Index to speed up pruning scan (entries never retrieved).
+        nativeDb
+            .prepare(`CREATE INDEX IF NOT EXISTS idx_brain_usage_log_task_id
+         ON brain_usage_log(task_id)`)
+            .run();
+    }
+    catch {
+        // best-effort: DDL failures are non-fatal
+    }
+}
+/**
+ * Ensure prune_candidate column exists on all typed brain tables.
+ * Added lazily so existing schemas are not broken.
+ */
+async function ensurePruneCandidateColumn(projectRoot) {
+    const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+    const nativeDb = getBrainNativeDb();
+    if (!nativeDb)
+        return;
+    const tables = [
+        'brain_decisions',
+        'brain_patterns',
+        'brain_learnings',
+        'brain_observations',
+    ];
+    for (const tbl of tables) {
+        try {
+            nativeDb.prepare(`ALTER TABLE ${tbl} ADD COLUMN prune_candidate INTEGER DEFAULT 0`).run();
+        }
+        catch {
+            // Column already exists — silently continue
+        }
+    }
+}
+// ============================================================================
+// 1. trackMemoryUsage
+// ============================================================================
+/**
+ * Record whether a retrieved memory entry was actually used by an agent.
+ *
+ * Call this after task completion, once the agent has decided which retrieved
+ * entries were referenced. Inserts a row into brain_usage_log; the
+ * correlateOutcomes pass will read these rows to adjust quality scores.
+ *
+ * @param projectRoot - Project root directory
+ * @param memoryId    - The brain entry ID (e.g. "O-...", "D-...", "P-...")
+ * @param used        - Whether the agent actually used this entry
+ * @param taskId      - Optional task ID for outcome correlation
+ * @param outcome     - Optional task outcome; defaults to 'unknown' until correlated
+ */
+export async function trackMemoryUsage(projectRoot, memoryId, used, taskId, outcome = 'unknown') {
+    if (!memoryId?.trim())
+        return;
+    await ensureUsageLogTable(projectRoot);
+    const { getBrainNativeDb } = await import('../store/brain-sqlite.js');
+    const nativeDb = getBrainNativeDb();
+    if (!nativeDb)
+        return;
+    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+    try {
+        nativeDb
+            .prepare(`INSERT INTO brain_usage_log (entry_id, task_id, used, outcome, created_at)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(memoryId, taskId ?? null, used ? 1 : 0, outcome, now);
+    }
+    catch {
+        // best-effort
+    }
+}
+// ============================================================================
+// 2. correlateOutcomes
+// ============================================================================
+/**
+ * Resolve the table name for a brain entry based on its ID prefix.
+ */
+function tableForId(id) {
+    if (id.startsWith('D-') || /^D\d/.test(id))
+        return 'brain_decisions';
+    if (id.startsWith('P-') || /^P\d/.test(id))
+        return 'brain_patterns';
+    if (id.startsWith('L-') || /^L\d/.test(id))
+        return 'brain_learnings';
+    if (id.startsWith('O-') || id.startsWith('CM-') || /^O/.test(id))
+        return 'brain_observations';
+    return null;
+}
+/**
+ * Apply a quality delta (+0.05 or -0.05) to a brain entry, clamped to [0.0, 1.0].
+ */
+function applyQualityDelta(nativeDb, table, id, delta, now) {
+    if (!nativeDb)
+        return;
+    try {
+        nativeDb
+            .prepare(`UPDATE ${table}
+         SET quality_score = MAX(0.0, MIN(1.0, COALESCE(quality_score, 0.5) + ?)),
+             updated_at    = ?
+         WHERE id = ?`)
+            .run(delta, now, id);
+    }
+    catch {
+        // best-effort: column may differ in older schemas
+    }
+}
+/**
+ * Analyse the retrieval log and usage log against task outcomes, then
+ * adjust quality scores to reflect real-world utility.
+ *
+ * Algorithm:
+ *   1. Read brain_usage_log where outcome != 'unknown' — these are rows
+ *      already tagged with a definitive outcome.
+ *   2. For success rows: boost quality_score by +0.05 for each entry used.
+ *   3. For failure rows: penalise quality_score by -0.05 for each entry used.
+ *   4. Flag entries whose citation_count = 0 AND last retrieval (if any) is
+ *      older than 30 days as prune candidates.
+ *
+ * This is designed to be idempotent — running it twice on the same data
+ * applies the delta twice (small, intentional drift toward ground truth).
+ * Callers should schedule it once per session end or per task batch.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Summary of changes made
+ */
+export async function correlateOutcomes(projectRoot) {
+    await ensureUsageLogTable(projectRoot);
+    await ensurePruneCandidateColumn(projectRoot);
+    const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+    const nativeDb = getBrainNativeDb();
+    const ranAt = new Date().toISOString();
+    if (!nativeDb) {
+        return { boosted: 0, penalized: 0, flaggedForPruning: 0, ranAt };
+    }
+    const now = ranAt.replace('T', ' ').slice(0, 19);
+    let boosted = 0;
+    let penalized = 0;
+    // Aggregate: for each (entry_id, outcome) pair sum the 'used' flags so we
+    // do a single UPDATE per entry rather than one per log row.
+    let usageRows = [];
+    try {
+        usageRows = typedAll(nativeDb.prepare(`SELECT entry_id, outcome, SUM(used) AS used_count
+         FROM brain_usage_log
+         WHERE outcome IN ('success', 'failure')
+         GROUP BY entry_id, outcome`));
+    }
+    catch {
+        // brain_usage_log may not exist yet on this DB — treat as empty
+        usageRows = [];
+    }
+    for (const row of usageRows) {
+        const table = tableForId(row.entry_id);
+        if (!table)
+            continue;
+        if (row.outcome === 'success' && row.used_count > 0) {
+            applyQualityDelta(nativeDb, table, row.entry_id, 0.05, now);
+            boosted++;
+        }
+        else if (row.outcome === 'failure' && row.used_count > 0) {
+            applyQualityDelta(nativeDb, table, row.entry_id, -0.05, now);
+            penalized++;
+        }
+    }
+    // ---- Step 2: flag stale entries for pruning ----
+    const cutoffDate = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)
+        .toISOString()
+        .replace('T', ' ')
+        .slice(0, 19);
+    let flaggedForPruning = 0;
+    const pruneTargetTables = [
+        { table: 'brain_decisions', dateCol: 'created_at' },
+        { table: 'brain_patterns', dateCol: 'extracted_at' },
+        { table: 'brain_learnings', dateCol: 'created_at' },
+        { table: 'brain_observations', dateCol: 'created_at' },
+    ];
+    for (const { table, dateCol } of pruneTargetTables) {
+        try {
+            // Entries with zero citation_count whose creation date is older than 30 days.
+            const result = nativeDb
+                .prepare(`UPDATE ${table}
+           SET prune_candidate = 1
+           WHERE COALESCE(citation_count, 0) = 0
+             AND ${dateCol} < ?`)
+                .run(cutoffDate);
+            flaggedForPruning += result.changes ?? 0;
+        }
+        catch {
+            // best-effort
+        }
+    }
+    return { boosted, penalized, flaggedForPruning, ranAt };
+}
+// ============================================================================
+// 3. getMemoryQualityReport
+// ============================================================================
+/**
+ * Return dashboard-level quality metrics for the BRAIN memory system.
+ *
+ * Aggregates across all four typed tables (decisions, patterns, learnings,
+ * observations) and the retrieval log to produce a single report object.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Quality metrics report
+ */
+export async function getMemoryQualityReport(projectRoot) {
+    await ensureUsageLogTable(projectRoot);
+    const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+    const nativeDb = getBrainNativeDb();
+    const emptyReport = {
+        totalRetrievals: 0,
+        uniqueEntriesRetrieved: 0,
+        usageRate: 0,
+        topRetrieved: [],
+        neverRetrieved: [],
+        qualityDistribution: { low: 0, medium: 0, high: 0 },
+        tierDistribution: { short: 0, medium: 0, long: 0, unknown: 0 },
+        noiseRatio: 0,
+    };
+    if (!nativeDb)
+        return emptyReport;
+    let totalRetrievals = 0;
+    let uniqueEntriesRetrieved = 0;
+    try {
+        const logCount = typedAll(nativeDb.prepare('SELECT COUNT(*) AS cnt FROM brain_retrieval_log'));
+        totalRetrievals = logCount[0]?.cnt ?? 0;
+        const uniqueCount = typedAll(nativeDb.prepare(`SELECT COUNT(DISTINCT value) AS cnt
+         FROM brain_retrieval_log,
+              json_each('["' || replace(entry_ids, ',', '","') || '"]')`));
+        uniqueEntriesRetrieved = uniqueCount[0]?.cnt ?? 0;
+    }
+    catch {
+        // brain_retrieval_log not yet created — harmless
+    }
+    // ---- Usage rate ----
+    let usageRate = 0;
+    try {
+        const totalUsage = typedAll(nativeDb.prepare('SELECT COUNT(*) AS cnt FROM brain_usage_log'));
+        const usedCount = typedAll(nativeDb.prepare('SELECT COUNT(*) AS cnt FROM brain_usage_log WHERE used = 1'));
+        const total = totalUsage[0]?.cnt ?? 0;
+        const used = usedCount[0]?.cnt ?? 0;
+        usageRate = total > 0 ? used / total : 0;
+    }
+    catch {
+        // brain_usage_log not yet created
+    }
+    const topRetrieved = [];
+    try {
+        const rows = typedAll(nativeDb.prepare(`SELECT id,
+                'decision' AS type,
+                decision    AS title,
+                COALESCE(citation_count, 0) AS citation_count
+         FROM brain_decisions
+         UNION ALL
+         SELECT id,
+                'pattern'  AS type,
+                pattern     AS title,
+                COALESCE(citation_count, 0) AS citation_count
+         FROM brain_patterns
+         UNION ALL
+         SELECT id,
+                'learning' AS type,
+                insight     AS title,
+                COALESCE(citation_count, 0) AS citation_count
+         FROM brain_learnings
+         UNION ALL
+         SELECT id,
+                'observation' AS type,
+                title         AS title,
+                COALESCE(citation_count, 0) AS citation_count
+         FROM brain_observations
+         ORDER BY citation_count DESC
+         LIMIT 10`));
+        for (const r of rows) {
+            topRetrieved.push({
+                id: r.id,
+                type: r.type,
+                title: String(r.title ?? '').slice(0, 120),
+                citationCount: r.citation_count,
+            });
+        }
+    }
+    catch {
+        // best-effort
+    }
+    const neverRetrieved = [];
+    try {
+        const rows = typedAll(nativeDb.prepare(`SELECT id,
+                'decision' AS type,
+                decision    AS title,
+                COALESCE(quality_score, 0.5) AS quality_score
+         FROM brain_decisions
+         WHERE COALESCE(citation_count, 0) = 0
+         UNION ALL
+         SELECT id,
+                'pattern'  AS type,
+                pattern     AS title,
+                COALESCE(quality_score, 0.5) AS quality_score
+         FROM brain_patterns
+         WHERE COALESCE(citation_count, 0) = 0
+         UNION ALL
+         SELECT id,
+                'learning' AS type,
+                insight     AS title,
+                COALESCE(quality_score, 0.5) AS quality_score
+         FROM brain_learnings
+         WHERE COALESCE(citation_count, 0) = 0
+         UNION ALL
+         SELECT id,
+                'observation' AS type,
+                title         AS title,
+                COALESCE(quality_score, 0.5) AS quality_score
+         FROM brain_observations
+         WHERE COALESCE(citation_count, 0) = 0
+         ORDER BY quality_score ASC
+         LIMIT 10`));
+        for (const r of rows) {
+            neverRetrieved.push({
+                id: r.id,
+                type: r.type,
+                title: String(r.title ?? '').slice(0, 120),
+                qualityScore: r.quality_score,
+            });
+        }
+    }
+    catch {
+        // best-effort
+    }
+    let qualityDistribution = { low: 0, medium: 0, high: 0 };
+    try {
+        const rows = typedAll(nativeDb.prepare(`SELECT
+           SUM(CASE WHEN qs < 0.3 THEN 1 ELSE 0 END)               AS low,
+           SUM(CASE WHEN qs >= 0.3 AND qs <= 0.6 THEN 1 ELSE 0 END) AS medium,
+           SUM(CASE WHEN qs > 0.6 THEN 1 ELSE 0 END)               AS high
+         FROM (
+           SELECT COALESCE(quality_score, 0.5) AS qs FROM brain_decisions
+           UNION ALL
+           SELECT COALESCE(quality_score, 0.5) AS qs FROM brain_patterns
+           UNION ALL
+           SELECT COALESCE(quality_score, 0.5) AS qs FROM brain_learnings
+           UNION ALL
+           SELECT COALESCE(quality_score, 0.5) AS qs FROM brain_observations
+         )`));
+        if (rows[0]) {
+            qualityDistribution = {
+                low: rows[0].low ?? 0,
+                medium: rows[0].medium ?? 0,
+                high: rows[0].high ?? 0,
+            };
+        }
+    }
+    catch {
+        // best-effort
+    }
+    const tierDistribution = { short: 0, medium: 0, long: 0, unknown: 0 };
+    try {
+        const rows = typedAll(nativeDb.prepare(`SELECT memory_tier AS tier, COUNT(*) AS cnt
+         FROM (
+           SELECT memory_tier FROM brain_decisions
+           UNION ALL
+           SELECT memory_tier FROM brain_patterns
+           UNION ALL
+           SELECT memory_tier FROM brain_learnings
+           UNION ALL
+           SELECT memory_tier FROM brain_observations
+         )
+         GROUP BY memory_tier`));
+        for (const r of rows) {
+            const tier = r.tier?.toLowerCase() ?? 'unknown';
+            if (tier === 'short' || tier === 'medium' || tier === 'long') {
+                tierDistribution[tier] += r.cnt;
+            }
+            else {
+                tierDistribution.unknown += r.cnt;
+            }
+        }
+    }
+    catch {
+        // memory_tier column may not exist on older schemas
+    }
+    // ---- Noise ratio ----
+    const totalEntries = qualityDistribution.low + qualityDistribution.medium + qualityDistribution.high;
+    const noiseRatio = totalEntries > 0 ? qualityDistribution.low / totalEntries : 0;
+    return {
+        totalRetrievals,
+        uniqueEntriesRetrieved,
+        usageRate,
+        topRetrieved,
+        neverRetrieved,
+        qualityDistribution,
+        tierDistribution,
+        noiseRatio,
+    };
+}
+//# sourceMappingURL=quality-feedback.js.map

package/dist/memory/quality-feedback.js.map

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

package/dist/memory/sleep-consolidation.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Sleep-Time Consolidation — LLM-driven background memory hygiene for CLEO BRAIN.
+ *
+ * Implements the "sleep-time compute" pattern inspired by Letta OS: after a
+ * session ends, a cheap LLM pass runs in the background to:
+ *   1. Merge near-duplicate entries (embedding similarity > 0.85)
+ *   2. Prune short-tier stale entries with low quality (7d old, quality < 0.4)
+ *   3. Synthesize frequently-cited learnings into higher-quality patterns
+ *   4. Extract cross-cutting insights from clusters of related observations
+ *
+ * All LLM calls use `claude-haiku-4-5-20251001` (cheapest available model).
+ * No API key = silent no-op for LLM steps; structural steps still run.
+ * All errors are caught and logged — nothing here may block session end.
+ *
+ * ## Configuration
+ *
+ * Add to `config.json` under `brain.sleepConsolidation`:
+ * ```json
+ * {
+ *   "brain": {
+ *     "sleepConsolidation": {
+ *       "enabled": true
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @task T555
+ * @epic T549
+ * @see packages/core/src/memory/observer-reflector.ts (Observer/Reflector pattern)
+ * @see packages/core/src/memory/brain-lifecycle.ts (runConsolidation)
+ */
+/** Count of changes from the merge-duplicates step. */
+export interface MergeDuplicatesResult {
+    /** Number of duplicate entries merged (soft-evicted clones). */
+    merged: number;
+    /** Number of LLM merge decisions made. */
+    llmDecisions: number;
+}
+/** Count of changes from the prune-stale step. */
+export interface PruneStaleResult {
+    /** Number of entries soft-evicted. */
+    pruned: number;
+    /** Number of entries the LLM decided to preserve. */
+    preserved: number;
+}
+/** Count of changes from the strengthen-patterns step. */
+export interface StrengthenPatternsResult {
+    /** Number of high-citation learnings synthesized. */
+    synthesized: number;
+    /** Number of new patterns generated. */
+    patternsGenerated: number;
+}
+/** Count of changes from the generate-insights step. */
+export interface GenerateInsightsResult {
+    /** Number of observation clusters processed. */
+    clustersProcessed: number;
+    /** Number of new insight observations stored. */
+    insightsStored: number;
+}
+/** Aggregated result from the full sleep consolidation run. */
+export interface SleepConsolidationResult {
+    /** Whether the run was enabled and fully attempted. */
+    ran: boolean;
+    /** Step 1: merge duplicates. */
+    mergeDuplicates: MergeDuplicatesResult;
+    /** Step 2: prune stale entries. */
+    pruneStale: PruneStaleResult;
+    /** Step 3: strengthen frequently-cited patterns. */
+    strengthenPatterns: StrengthenPatternsResult;
+    /** Step 4: generate cross-cutting insights. */
+    generateInsights: GenerateInsightsResult;
+}
+/** Sleep consolidation configuration resolved from config.json. */
+export interface SleepConsolidationConfig {
+    enabled: boolean;
+}
+/**
+ * Run the full sleep-time consolidation pipeline for CLEO BRAIN.
+ *
+ * This is the main entry point for LLM-driven background memory hygiene.
+ * It is designed to run after session end (via setImmediate) and must never
+ * throw — all errors are caught and logged.
+ *
+ * Steps (in order):
+ *   1. Merge duplicates — embedding-similarity-based dedup with LLM confirmation
+ *   2. Prune stale — evict low-quality short-tier entries; LLM may preserve some
+ *   3. Strengthen patterns — synthesize frequently-cited learnings into patterns
+ *   4. Generate insights — extract cross-cutting insights from observation clusters
+ *
+ * Graceful degradation: when no Anthropic API key is available, LLM steps
+ * silently skip their LLM call and fall back to structural heuristics.
+ *
+ * @param projectRoot - Project root directory for brain.db resolution.
+ * @returns Aggregated result counts from each step.
+ */
+export declare function runSleepConsolidation(projectRoot: string): Promise<SleepConsolidationResult>;
+//# sourceMappingURL=sleep-consolidation.d.ts.map

package/dist/memory/sleep-consolidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sleep-consolidation.d.ts","sourceRoot":"","sources":["../../src/memory/sleep-consolidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA0EH,uDAAuD;AACvD,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAgB;IAC/B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,0DAA0D;AAC1D,MAAM,WAAW,wBAAwB;IACvC,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wDAAwD;AACxD,MAAM,WAAW,sBAAsB;IACrC,gDAAgD;IAChD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,+DAA+D;AAC/D,MAAM,WAAW,wBAAwB;IACvC,uDAAuD;IACvD,GAAG,EAAE,OAAO,CAAC;IACb,gCAAgC;IAChC,eAAe,EAAE,qBAAqB,CAAC;IACvC,mCAAmC;IACnC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,oDAAoD;IACpD,kBAAkB,EAAE,wBAAwB,CAAC;IAC7C,+CAA+C;IAC/C,gBAAgB,EAAE,sBAAsB,CAAC;CAC1C;AAMD,mEAAmE;AACnE,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,OAAO,CAAC;CAClB;AAsrBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,wBAAwB,CAAC,CA0DnC"}