@cleocode/core 2026.3.76 → 2026.4.0

package/dist/memory/brain-links.js

@@ -0,0 +1,148 @@
+/**
+ * Cross-reference management between BRAIN memory entries and tasks.
+ *
+ * Provides linking/unlinking and query functions for relationships
+ * between decisions, patterns, learnings and CLEO tasks.
+ *
+ * @task T5156
+ * @epic T5149
+ */
+import { getBrainAccessor } from '../store/brain-accessor.js';
+/**
+ * Link a memory entry to a task.
+ *
+ * @task T5156
+ */
+export async function linkMemoryToTask(projectRoot, memoryType, memoryId, taskId, linkType) {
+    if (!memoryId || !taskId) {
+        throw new Error('memoryId and taskId are required');
+    }
+    const accessor = await getBrainAccessor(projectRoot);
+    // Check if link already exists
+    const existingLinks = await accessor.getLinksForMemory(memoryType, memoryId);
+    const duplicate = existingLinks.find((l) => l.taskId === taskId && l.linkType === linkType);
+    if (duplicate) {
+        return duplicate;
+    }
+    await accessor.addLink({
+        memoryType,
+        memoryId,
+        taskId,
+        linkType,
+    });
+    // Return the created link
+    const links = await accessor.getLinksForMemory(memoryType, memoryId);
+    return links.find((l) => l.taskId === taskId && l.linkType === linkType);
+}
+/**
+ * Remove a link between a memory entry and a task.
+ *
+ * @task T5156
+ */
+export async function unlinkMemoryFromTask(projectRoot, memoryType, memoryId, taskId, linkType) {
+    const accessor = await getBrainAccessor(projectRoot);
+    await accessor.removeLink(memoryType, memoryId, taskId, linkType);
+}
+/**
+ * Get all memory entries linked to a specific task.
+ *
+ * @task T5156
+ */
+export async function getTaskLinks(projectRoot, taskId) {
+    const accessor = await getBrainAccessor(projectRoot);
+    return accessor.getLinksForTask(taskId);
+}
+/**
+ * Get all tasks linked to a specific memory entry.
+ *
+ * @task T5156
+ */
+export async function getMemoryLinks(projectRoot, memoryType, memoryId) {
+    const accessor = await getBrainAccessor(projectRoot);
+    return accessor.getLinksForMemory(memoryType, memoryId);
+}
+/**
+ * Batch create multiple links at once.
+ *
+ * @task T5156
+ */
+export async function bulkLink(projectRoot, links) {
+    const accessor = await getBrainAccessor(projectRoot);
+    let created = 0;
+    let skipped = 0;
+    for (const link of links) {
+        // Check for duplicate
+        const existing = await accessor.getLinksForMemory(link.memoryType, link.memoryId);
+        const duplicate = existing.find((l) => l.taskId === link.taskId && l.linkType === link.linkType);
+        if (duplicate) {
+            skipped++;
+            continue;
+        }
+        await accessor.addLink({
+            memoryType: link.memoryType,
+            memoryId: link.memoryId,
+            taskId: link.taskId,
+            linkType: link.linkType,
+        });
+        created++;
+    }
+    return { created, skipped };
+}
+/**
+ * Get all decisions linked to a task.
+ * Convenience method that fetches full decision rows.
+ *
+ * @task T5156
+ */
+export async function getLinkedDecisions(projectRoot, taskId) {
+    const accessor = await getBrainAccessor(projectRoot);
+    const links = await accessor.getLinksForTask(taskId);
+    const decisionLinks = links.filter((l) => l.memoryType === 'decision');
+    const decisions = [];
+    for (const link of decisionLinks) {
+        const decision = await accessor.getDecision(link.memoryId);
+        if (decision) {
+            decisions.push(decision);
+        }
+    }
+    return decisions;
+}
+/**
+ * Get all patterns linked to a task.
+ * Convenience method that fetches full pattern rows.
+ *
+ * @task T5156
+ */
+export async function getLinkedPatterns(projectRoot, taskId) {
+    const accessor = await getBrainAccessor(projectRoot);
+    const links = await accessor.getLinksForTask(taskId);
+    const patternLinks = links.filter((l) => l.memoryType === 'pattern');
+    const patterns = [];
+    for (const link of patternLinks) {
+        const pattern = await accessor.getPattern(link.memoryId);
+        if (pattern) {
+            patterns.push(pattern);
+        }
+    }
+    return patterns;
+}
+/**
+ * Get all learnings linked to a task.
+ * Convenience method that fetches full learning rows.
+ *
+ * @task T5156
+ */
+export async function getLinkedLearnings(projectRoot, taskId) {
+    const accessor = await getBrainAccessor(projectRoot);
+    const links = await accessor.getLinksForTask(taskId);
+    const learningLinks = links.filter((l) => l.memoryType === 'learning');
+    const learnings = [];
+    for (const link of learningLinks) {
+        const learning = await accessor.getLearning(link.memoryId);
+        if (learning) {
+            learnings.push(learning);
+        }
+    }
+    return learnings;
+}
+//# sourceMappingURL=brain-links.js.map

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

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

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

@@ -30,6 +30,15 @@ export interface BrainMaintenanceConsolidationResult {
     /** Number of original observations archived. */
     removed: number;
 }
+/** Orphaned reference reconciliation step result. */
+export interface BrainMaintenanceReconciliationResult {
+    /** Decisions with stale task/epic references fixed. */
+    decisionsFixed: number;
+    /** Observations with stale session references fixed. */
+    observationsFixed: number;
+    /** Memory links with stale task references removed. */
+    linksRemoved: number;
+}
 /** Embedding backfill step result. */
 export interface BrainMaintenanceEmbeddingsResult {
     /** Observations successfully embedded. */
@@ -50,6 +59,8 @@ export interface BrainMaintenanceResult {
     decay: BrainMaintenanceDecayResult;
     /** Results from the memory consolidation step. */
     consolidation: BrainMaintenanceConsolidationResult;
+    /** Results from the cross-DB orphaned reference reconciliation step. */
+    reconciliation: BrainMaintenanceReconciliationResult;
     /** Results from the embedding backfill step. */
     embeddings: BrainMaintenanceEmbeddingsResult;
     /** Total wall-clock duration of the maintenance run in milliseconds. */
@@ -66,6 +77,8 @@ export interface BrainMaintenanceOptions {
     skipDecay?: boolean;
     /** Skip the memory consolidation step. Default: false. */
     skipConsolidation?: boolean;
+    /** Skip the cross-DB orphaned reference reconciliation step. Default: false. */
+    skipReconciliation?: boolean;
     /** Skip the embedding backfill step. Default: false. */
     skipEmbeddings?: boolean;
     /**

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

@@ -1 +1 @@
-{"version":3,"file":"brain-maintenance.d.ts","sourceRoot":"","sources":["../../src/memory/brain-maintenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH,oEAAoE;AACpE,MAAM,WAAW,2BAA2B;IAC1C,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mCAAmC;IAClD,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sCAAsC;AACtC,MAAM,WAAW,gCAAgC;IAC/C,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,KAAK,EAAE,2BAA2B,CAAC;IACnC,kDAAkD;IAClD,aAAa,EAAE,mCAAmC,CAAC;IACnD,gDAAgD;IAChD,UAAU,EAAE,gCAAgC,CAAC;IAC7C,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wDAAwD;IACxD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACrE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAsDjC"}
+{"version":3,"file":"brain-maintenance.d.ts","sourceRoot":"","sources":["../../src/memory/brain-maintenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAUH,oEAAoE;AACpE,MAAM,WAAW,2BAA2B;IAC1C,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mCAAmC;IAClD,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qDAAqD;AACrD,MAAM,WAAW,oCAAoC;IACnD,uDAAuD;IACvD,cAAc,EAAE,MAAM,CAAC;IACvB,wDAAwD;IACxD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,sCAAsC;AACtC,MAAM,WAAW,gCAAgC;IAC/C,0CAA0C;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,KAAK,EAAE,2BAA2B,CAAC;IACnC,kDAAkD;IAClD,aAAa,EAAE,mCAAmC,CAAC;IACnD,wEAAwE;IACxE,cAAc,EAAE,oCAAoC,CAAC;IACrD,gDAAgD;IAChD,UAAU,EAAE,gCAAgC,CAAC;IAC7C,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,0DAA0D;IAC1D,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,wDAAwD;IACxD,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACrE;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,MAAM,EACnB,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAuEjC"}

package/dist/memory/brain-maintenance.js

@@ -0,0 +1,98 @@
+/**
+ * Brain Maintenance Runner
+ *
+ * Combines temporal decay, memory consolidation, and embedding backfill
+ * into a single idempotent maintenance pass. Designed to be run on a
+ * schedule or on-demand via `cleo brain maintenance`.
+ *
+ * Steps run in order:
+ *   1. Temporal decay   — reduce confidence of stale learnings
+ *   2. Consolidation    — merge duplicate/similar old observations
+ *   3. Embedding backfill — populate vectors for observations without them
+ *
+ * Each step is individually opt-outable via skip flags, making the
+ * operation safe to re-run at any frequency.
+ *
+ * @task T143
+ * @epic T134
+ * @why Enable scheduled brain optimization via single command
+ * @what Combined maintenance runner with CLI command and progress reporting
+ */
+import { applyTemporalDecay, consolidateMemories } from './brain-lifecycle.js';
+import { populateEmbeddings } from './brain-retrieval.js';
+// ============================================================================
+// Runner
+// ============================================================================
+/**
+ * Run a combined brain maintenance pass: decay, consolidation, and embeddings.
+ *
+ * The three steps always run in the same order:
+ *   1. `applyTemporalDecay` — decay stale learning confidence values
+ *   2. `consolidateMemories` — merge clustered old observations
+ *   3. `populateEmbeddings` — backfill missing vectors
+ *
+ * Each step is optional via the `skip*` flags. The function is idempotent:
+ * re-running it when there is nothing to process returns zero counts.
+ *
+ * @param projectRoot - Absolute path to the project root (used to locate brain.db)
+ * @param options - Optional skip flags and progress callback
+ * @returns Aggregated counts from each step plus total wall-clock duration
+ *
+ * @example
+ * ```ts
+ * const result = await runBrainMaintenance('/my/project', {
+ *   onProgress: (step, current, total) => {
+ *     console.log(`[${step}] ${current}/${total}`);
+ *   },
+ * });
+ * console.log(`Done in ${result.duration}ms`);
+ * ```
+ *
+ * @task T143
+ * @epic T134
+ */
+export async function runBrainMaintenance(projectRoot, options) {
+    const { skipDecay = false, skipConsolidation = false, skipEmbeddings = false, onProgress, } = options ?? {};
+    const startTime = Date.now();
+    // Default zero values for each step (used when step is skipped).
+    const decayResult = { affected: 0 };
+    const consolidationResult = { merged: 0, removed: 0 };
+    const embeddingsResult = {
+        processed: 0,
+        skipped: 0,
+        errors: 0,
+    };
+    // Step 1: Temporal decay
+    if (!skipDecay) {
+        onProgress?.('decay', 0, 1);
+        const raw = await applyTemporalDecay(projectRoot);
+        decayResult.affected = raw.updated;
+        onProgress?.('decay', 1, 1);
+    }
+    // Step 2: Memory consolidation
+    if (!skipConsolidation) {
+        onProgress?.('consolidation', 0, 1);
+        const raw = await consolidateMemories(projectRoot);
+        consolidationResult.merged = raw.merged;
+        consolidationResult.removed = raw.archived;
+        onProgress?.('consolidation', 1, 1);
+    }
+    // Step 3: Embedding backfill (with per-item progress relay)
+    if (!skipEmbeddings) {
+        const raw = await populateEmbeddings(projectRoot, {
+            onProgress: (current, total) => {
+                onProgress?.('embeddings', current, total);
+            },
+        });
+        embeddingsResult.processed = raw.processed;
+        embeddingsResult.skipped = raw.skipped;
+        embeddingsResult.errors = raw.errors;
+    }
+    return {
+        decay: decayResult,
+        consolidation: consolidationResult,
+        embeddings: embeddingsResult,
+        duration: Date.now() - startTime,
+    };
+}
+//# sourceMappingURL=brain-maintenance.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"brain-maintenance.js","sourceRoot":"","sources":["../../src/memory/brain-maintenance.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC/E,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAuE1D,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAAmB,EACnB,OAAiC;IAEjC,MAAM,EACJ,SAAS,GAAG,KAAK,EACjB,iBAAiB,GAAG,KAAK,EACzB,cAAc,GAAG,KAAK,EACtB,UAAU,GACX,GAAG,OAAO,IAAI,EAAE,CAAC;IAElB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAE7B,iEAAiE;IACjE,MAAM,WAAW,GAAgC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC;IACjE,MAAM,mBAAmB,GAAwC,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAC3F,MAAM,gBAAgB,GAAqC;QACzD,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;QACV,MAAM,EAAE,CAAC;KACV,CAAC;IAEF,yBAAyB;IACzB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,UAAU,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QAC5B,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,WAAW,CAAC,CAAC;QAClD,WAAW,CAAC,QAAQ,GAAG,GAAG,CAAC,OAAO,CAAC;QACnC,UAAU,EAAE,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC9B,CAAC;IAED,+BAA+B;IAC/B,IAAI,CAAC,iBAAiB,EAAE,CAAC;QACvB,UAAU,EAAE,CAAC,eAAe,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;QACpC,MAAM,GAAG,GAAG,MAAM,mBAAmB,CAAC,WAAW,CAAC,CAAC;QACnD,mBAAmB,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;QACxC,mBAAmB,CAAC,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC3C,UAAU,EAAE,CAAC,eAAe,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IACtC,CAAC;IAED,4DAA4D;IAC5D,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,MAAM,GAAG,GAAG,MAAM,kBAAkB,CAAC,WAAW,EAAE;YAChD,UAAU,EAAE,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE;gBAC7B,UAAU,EAAE,CAAC,YAAY,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;YAC7C,CAAC;SACF,CAAC,CAAC;QACH,gBAAgB,CAAC,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC;QAC3C,gBAAgB,CAAC,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;QACvC,gBAAgB,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IACvC,CAAC;IAED,OAAO;QACL,KAAK,EAAE,WAAW;QAClB,aAAa,EAAE,mBAAmB;QAClC,UAAU,EAAE,gBAAgB;QAC5B,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS;KACjC,CAAC;AACJ,CAAC"}

package/dist/memory/brain-migration.js

@@ -0,0 +1,149 @@
+/**
+ * Migrate BRAIN memory from JSONL files to brain.db SQLite tables.
+ * Reads .cleo/memory/patterns.jsonl and .cleo/memory/learnings.jsonl
+ * and inserts into brain_patterns and brain_learnings tables.
+ *
+ * Idempotent: checks for existing entries by ID to skip duplicates.
+ *
+ * @task T5129
+ * @epic T5149
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getBrainAccessor } from '../store/brain-accessor.js';
+/**
+ * Read a JSONL file and parse each line as JSON.
+ * Returns parsed objects and any parse error messages.
+ */
+function readJsonlFile(filePath) {
+    if (!existsSync(filePath)) {
+        return { entries: [], errors: [] };
+    }
+    const content = readFileSync(filePath, 'utf-8').trim();
+    if (!content) {
+        return { entries: [], errors: [] };
+    }
+    const entries = [];
+    const errors = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch (_err) {
+            errors.push(`Failed to parse line: ${trimmed.slice(0, 80)}...`);
+        }
+    }
+    return { entries, errors };
+}
+/**
+ * Migrate BRAIN memory data from JSONL files to brain.db.
+ *
+ * Reads:
+ * - .cleo/memory/patterns.jsonl -> brain_patterns table
+ * - .cleo/memory/learnings.jsonl -> brain_learnings table
+ *
+ * Skips entries where the ID already exists in the database (idempotent).
+ *
+ * @task T5129
+ */
+export async function migrateBrainData(projectRoot) {
+    const accessor = await getBrainAccessor(projectRoot);
+    const result = {
+        patternsImported: 0,
+        learningsImported: 0,
+        duplicatesSkipped: 0,
+        errors: [],
+    };
+    // Migrate patterns
+    const patternsPath = join(projectRoot, '.cleo', 'memory', 'patterns.jsonl');
+    const { entries: patterns, errors: patternErrors } = readJsonlFile(patternsPath);
+    result.errors.push(...patternErrors);
+    for (const p of patterns) {
+        try {
+            // Check if already exists
+            const existing = await accessor.getPattern(p.id);
+            if (existing) {
+                result.duplicatesSkipped++;
+                continue;
+            }
+            const row = {
+                id: p.id,
+                type: mapPatternType(p.type),
+                pattern: p.pattern,
+                context: p.context,
+                frequency: p.frequency ?? 1,
+                successRate: p.successRate ?? null,
+                impact: mapImpact(p.impact),
+                antiPattern: p.antiPattern ?? null,
+                mitigation: p.mitigation ?? null,
+                examplesJson: JSON.stringify(p.examples ?? []),
+                extractedAt: p.extractedAt ?? new Date().toISOString().replace('T', ' ').slice(0, 19),
+                updatedAt: p.updatedAt?.replace('T', ' ').slice(0, 19) ?? null,
+            };
+            await accessor.addPattern(row);
+            result.patternsImported++;
+        }
+        catch (err) {
+            result.errors.push(`Pattern ${p.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    // Migrate learnings
+    const learningsPath = join(projectRoot, '.cleo', 'memory', 'learnings.jsonl');
+    const { entries: learnings, errors: learningErrors } = readJsonlFile(learningsPath);
+    result.errors.push(...learningErrors);
+    for (const l of learnings) {
+        try {
+            // Check if already exists
+            const existing = await accessor.getLearning(l.id);
+            if (existing) {
+                result.duplicatesSkipped++;
+                continue;
+            }
+            const row = {
+                id: l.id,
+                insight: l.insight,
+                source: l.source,
+                confidence: l.confidence,
+                actionable: l.actionable ?? false,
+                application: l.application ?? null,
+                applicableTypesJson: JSON.stringify(l.applicableTypes ?? []),
+                createdAt: l.createdAt ?? new Date().toISOString().replace('T', ' ').slice(0, 19),
+                updatedAt: l.updatedAt?.replace('T', ' ').slice(0, 19) ?? null,
+            };
+            await accessor.addLearning(row);
+            result.learningsImported++;
+        }
+        catch (err) {
+            result.errors.push(`Learning ${l.id}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
+}
+/**
+ * Map JSONL pattern type to brain schema enum.
+ * Falls back to 'workflow' for unrecognized types.
+ */
+function mapPatternType(type) {
+    const valid = ['workflow', 'blocker', 'success', 'failure', 'optimization'];
+    if (valid.includes(type)) {
+        return type;
+    }
+    return 'workflow';
+}
+/**
+ * Map JSONL impact level to brain schema enum.
+ * Returns null for unrecognized values.
+ */
+function mapImpact(impact) {
+    if (!impact)
+        return null;
+    const valid = ['low', 'medium', 'high'];
+    if (valid.includes(impact)) {
+        return impact;
+    }
+    return null;
+}
+//# sourceMappingURL=brain-migration.js.map

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

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

package/dist/memory/brain-reasoning.js

@@ -0,0 +1,215 @@
+/**
+ * BRAIN Reasoning — causal trace through task dependency chains.
+ *
+ * `reasonWhy(taskId)` walks upstream through a task's blocker chain,
+ * enriching each node with related brain_decisions. Leaf tasks with
+ * no further unresolved blockers are identified as root causes.
+ *
+ * @task T5390
+ * @epic T5149
+ */
+import { getBrainAccessor } from '../store/brain-accessor.js';
+import { getAccessor } from '../store/data-accessor.js';
+import { searchBrain } from './brain-search.js';
+import { searchSimilar } from './brain-similarity.js';
+// ============================================================================
+// Implementation
+// ============================================================================
+const MAX_DEPTH = 10;
+/**
+ * Build a causal trace for why a task is blocked.
+ *
+ * Walks upstream through `depends` fields, collecting unresolved blockers
+ * and their associated brain decisions. Leaf blockers (no further unresolved
+ * deps) are reported as root causes.
+ */
+export async function reasonWhy(taskId, projectRoot, taskAccessor) {
+    const acc = taskAccessor ?? (await getAccessor(projectRoot));
+    const { tasks: reasonTasks } = await acc.queryTasks({});
+    const taskMap = new Map(reasonTasks.map((t) => [t.id, t]));
+    const completedStatuses = new Set(['done', 'cancelled']);
+    let accessor = null;
+    try {
+        accessor = await getBrainAccessor(projectRoot);
+    }
+    catch {
+        // brain.db may not exist — proceed without decisions
+    }
+    const visited = new Set();
+    const blockers = [];
+    let maxDepthReached = 0;
+    async function walk(id, depth) {
+        if (visited.has(id))
+            return;
+        if (depth > MAX_DEPTH)
+            return;
+        visited.add(id);
+        if (depth > maxDepthReached) {
+            maxDepthReached = depth;
+        }
+        const task = taskMap.get(id);
+        if (!task)
+            return;
+        // Collect unresolved dependencies
+        const unresolvedDeps = (task.depends ?? []).filter((depId) => {
+            const dep = taskMap.get(depId);
+            return dep && !completedStatuses.has(dep.status);
+        });
+        if (unresolvedDeps.length === 0 && id !== taskId) {
+            // This is a leaf blocker — no further unresolved deps
+            return;
+        }
+        for (const depId of unresolvedDeps) {
+            if (visited.has(depId))
+                continue;
+            const dep = taskMap.get(depId);
+            // Query brain decisions related to this blocker
+            let decisions = [];
+            if (accessor) {
+                const relatedDecisions = await findDecisionsForTask(accessor, depId);
+                decisions = relatedDecisions.map((d) => ({
+                    id: d.id,
+                    title: d.decision,
+                    rationale: d.rationale,
+                }));
+            }
+            blockers.push({
+                taskId: depId,
+                status: dep.status,
+                reason: dep.blockedBy ?? undefined,
+                decisions,
+            });
+            await walk(depId, depth + 1);
+        }
+    }
+    await walk(taskId, 0);
+    // Root causes: leaf blockers whose own deps are all resolved or absent
+    const blockerIds = new Set(blockers.map((b) => b.taskId));
+    const rootCauses = blockers
+        .filter((b) => {
+        const task = taskMap.get(b.taskId);
+        if (!task?.depends?.length)
+            return true;
+        return task.depends.every((depId) => {
+            const dep = taskMap.get(depId);
+            return !dep || completedStatuses.has(dep.status) || !blockerIds.has(depId);
+        });
+    })
+        .map((b) => b.taskId);
+    return {
+        taskId,
+        blockers,
+        rootCauses,
+        depth: maxDepthReached,
+    };
+}
+/**
+ * Query brain_decisions for a specific task context.
+ */
+async function findDecisionsForTask(accessor, taskId) {
+    return accessor.findDecisions({ contextTaskId: taskId });
+}
+/**
+ * Find entries similar to a given brain.db entry.
+ *
+ * 1. Loads the source entry's text from brain.db.
+ * 2. Calls searchSimilar() for vector-based similarity if embeddings exist.
+ * 3. Falls back to FTS5 keyword search if no embeddings are available.
+ * 4. Filters out the source entry itself.
+ *
+ * @param entryId - ID of the brain.db entry to find similar entries for
+ * @param projectRoot - Project root directory
+ * @param limit - Maximum results to return (default 10)
+ * @returns Array of similar entries ranked by distance/relevance
+ */
+export async function reasonSimilar(entryId, projectRoot, limit) {
+    const maxResults = limit ?? 10;
+    // Load the source entry's text — initialize brain.db before accessor use
+    const { getBrainDb } = await import('../store/brain-sqlite.js');
+    await getBrainDb(projectRoot);
+    const accessor = await getBrainAccessor(projectRoot);
+    let sourceText = null;
+    if (entryId.startsWith('D-') || /^D\d/.test(entryId)) {
+        const row = await accessor.getDecision(entryId);
+        if (row)
+            sourceText = `${row.decision} ${row.rationale}`;
+    }
+    else if (entryId.startsWith('P-') || /^P\d/.test(entryId)) {
+        const row = await accessor.getPattern(entryId);
+        if (row)
+            sourceText = `${row.pattern} ${row.context}`;
+    }
+    else if (entryId.startsWith('L-') || /^L\d/.test(entryId)) {
+        const row = await accessor.getLearning(entryId);
+        if (row)
+            sourceText = `${row.insight} ${row.source}`;
+    }
+    else {
+        const row = await accessor.getObservation(entryId);
+        if (row)
+            sourceText = row.narrative ?? row.title;
+    }
+    if (!sourceText)
+        return [];
+    // Try vector similarity first
+    const vecResults = await searchSimilar(sourceText, projectRoot, maxResults + 1);
+    if (vecResults.length > 0) {
+        return vecResults.filter((r) => r.id !== entryId).slice(0, maxResults);
+    }
+    // FTS5 fallback: extract key terms and search
+    const terms = sourceText
+        .split(/\s+/)
+        .filter((t) => t.length > 3)
+        .slice(0, 5)
+        .join(' ');
+    if (!terms)
+        return [];
+    const ftsResults = await searchBrain(projectRoot, terms, { limit: maxResults + 5 });
+    const entries = [];
+    for (const d of ftsResults.decisions) {
+        if (d.id === entryId)
+            continue;
+        entries.push({
+            id: d.id,
+            distance: 0,
+            type: 'decision',
+            title: d.decision,
+            text: `${d.decision} — ${d.rationale}`,
+        });
+    }
+    for (const p of ftsResults.patterns) {
+        if (p.id === entryId)
+            continue;
+        entries.push({
+            id: p.id,
+            distance: 0,
+            type: 'pattern',
+            title: p.pattern,
+            text: `${p.pattern} — ${p.context}`,
+        });
+    }
+    for (const l of ftsResults.learnings) {
+        if (l.id === entryId)
+            continue;
+        entries.push({
+            id: l.id,
+            distance: 0,
+            type: 'learning',
+            title: l.insight,
+            text: `${l.insight} (source: ${l.source})`,
+        });
+    }
+    for (const o of ftsResults.observations) {
+        if (o.id === entryId)
+            continue;
+        entries.push({
+            id: o.id,
+            distance: 0,
+            type: 'observation',
+            title: o.title,
+            text: o.narrative ?? o.title,
+        });
+    }
+    return entries.slice(0, maxResults);
+}
+//# sourceMappingURL=brain-reasoning.js.map