@cleocode/core 2026.4.58 → 2026.4.59

package/dist/memory/decisions.js

@@ -0,0 +1,242 @@
+/**
+ * Decision Memory module for CLEO BRAIN.
+ * Uses brain.db via BrainDataAccessor for persistent storage.
+ *
+ * Provides functions to store, recall, search, and update decisions
+ * with sequential ID generation (D001, D002, ...).
+ *
+ * @task T5155
+ * @epic T5149
+ */
+import { getBrainAccessor } from '../store/brain-accessor.js';
+import { taskExistsInTasksDb } from '../store/cross-db-cleanup.js';
+import { getDb } from '../store/sqlite.js';
+import { autoCrossLinkDecision } from './decision-cross-link.js';
+import { addGraphEdge, upsertGraphNode } from './graph-auto-populate.js';
+import { computeDecisionQuality } from './quality-scoring.js';
+import { detectSupersession, supersedeMemory } from './temporal-supersession.js';
+/**
+ * Generate the next sequential decision ID (D001, D002, ...).
+ * Reads the highest existing ID from brain_decisions to determine next.
+ */
+async function nextDecisionId(projectRoot) {
+    const { getBrainDb } = await import('../store/brain-sqlite.js');
+    const { brainDecisions } = await import('../store/brain-schema.js');
+    const { desc } = await import('drizzle-orm');
+    const db = await getBrainDb(projectRoot);
+    const rows = await db
+        .select({ id: brainDecisions.id })
+        .from(brainDecisions)
+        .orderBy(desc(brainDecisions.id))
+        .limit(1);
+    if (rows.length === 0) {
+        return 'D001';
+    }
+    const lastId = rows[0].id;
+    const num = parseInt(lastId.slice(1), 10);
+    if (Number.isNaN(num)) {
+        return 'D001';
+    }
+    return `D${String(num + 1).padStart(3, '0')}`;
+}
+/**
+ * Store a new decision or update an existing one if a duplicate is found.
+ * Duplicate detection: same decision text (case-insensitive).
+ *
+ * @task T5155
+ */
+export async function storeDecision(projectRoot, params) {
+    if (!params.decision?.trim()) {
+        throw new Error('Decision text is required');
+    }
+    if (!params.rationale?.trim()) {
+        throw new Error('Rationale is required');
+    }
+    const accessor = await getBrainAccessor(projectRoot);
+    // Check for duplicate (same decision text, case-insensitive)
+    const existing = await accessor.findDecisions({ type: params.type });
+    const duplicate = existing.find((d) => d.decision.toLowerCase() === params.decision.toLowerCase());
+    if (duplicate) {
+        // Update the existing decision
+        const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        await accessor.updateDecision(duplicate.id, {
+            rationale: params.rationale.trim(),
+            confidence: params.confidence,
+            outcome: params.outcome ?? duplicate.outcome,
+            alternativesJson: params.alternatives
+                ? JSON.stringify(params.alternatives)
+                : duplicate.alternativesJson,
+            updatedAt: now,
+        });
+        const updated = await accessor.getDecision(duplicate.id);
+        // Refresh the graph node for the updated decision (best-effort).
+        const updatedQuality = computeDecisionQuality({
+            confidence: params.confidence,
+            rationale: params.rationale.trim(),
+            contextTaskId: params.contextTaskId ?? null,
+        });
+        upsertGraphNode(projectRoot, `decision:${duplicate.id}`, 'decision', params.decision.trim().substring(0, 200), updatedQuality, params.decision.trim() + params.rationale.trim(), { type: params.type, confidence: params.confidence }).catch(() => {
+            /* best-effort */
+        });
+        return updated;
+    }
+    // Create new decision with sequential ID
+    const id = await nextDecisionId(projectRoot);
+    // Write-guard: validate cross-db task references before inserting
+    let validEpicId = params.contextEpicId;
+    let validTaskId = params.contextTaskId;
+    if (validEpicId || validTaskId) {
+        const tasksDb = await getDb(projectRoot);
+        if (validEpicId && !(await taskExistsInTasksDb(validEpicId, tasksDb))) {
+            validEpicId = undefined;
+        }
+        if (validTaskId && !(await taskExistsInTasksDb(validTaskId, tasksDb))) {
+            validTaskId = undefined;
+        }
+    }
+    // T549 Wave 1-A: Tier routing for decisions.
+    // Decisions are always medium-term semantic entries — they are intentional acts,
+    // always manually entered via cleo memory decision-store or the CLI.
+    // sourceConfidence = 'owner' (decisions are owner-stated facts by definition)
+    // verified = true (the act of deciding IS verification)
+    // memoryTier = 'medium' (decisions skip short-term; may promote to long after 7d+outcome:success)
+    // memoryType = 'semantic' (decisions are declarative architectural facts)
+    const memoryTier = 'medium';
+    const memoryType = 'semantic';
+    const sourceConfidence = 'owner';
+    const verified = true;
+    // Compute quality score from confidence level, rationale richness, task linkage,
+    // and T549 source multiplier (owner = 1.0, medium tier = +0.05).
+    const qualityScore = computeDecisionQuality({
+        confidence: params.confidence,
+        rationale: params.rationale.trim(),
+        contextTaskId: validTaskId ?? null,
+        sourceConfidence,
+        memoryTier,
+    });
+    const row = {
+        id,
+        type: params.type,
+        decision: params.decision.trim(),
+        rationale: params.rationale.trim(),
+        confidence: params.confidence,
+        outcome: params.outcome,
+        alternativesJson: params.alternatives ? JSON.stringify(params.alternatives) : undefined,
+        contextEpicId: validEpicId,
+        contextTaskId: validTaskId,
+        contextPhase: params.contextPhase,
+        qualityScore,
+        // T549 Wave 1-A: tier/type/confidence assigned at write time
+        memoryTier,
+        memoryType,
+        sourceConfidence,
+        verified,
+    };
+    const saved = await accessor.addDecision(row);
+    // Auto-populate graph node + edges for the new decision (best-effort, T537).
+    // All graph writes run fire-and-forget so they never block the return.
+    try {
+        await upsertGraphNode(projectRoot, `decision:${saved.id}`, 'decision', saved.decision.substring(0, 200), qualityScore, saved.decision + saved.rationale, { type: saved.type, confidence: saved.confidence });
+        // Link decision → task when a task context is present.
+        if (validTaskId) {
+            await upsertGraphNode(projectRoot, `task:${validTaskId}`, 'task', validTaskId, 1.0, '');
+            await addGraphEdge(projectRoot, `decision:${saved.id}`, `task:${validTaskId}`, 'applies_to', 1.0, 'auto:store-decision');
+        }
+        // Link decision → epic when an epic context is present.
+        if (validEpicId) {
+            await upsertGraphNode(projectRoot, `epic:${validEpicId}`, 'epic', validEpicId, 1.0, '');
+            await addGraphEdge(projectRoot, `decision:${saved.id}`, `epic:${validEpicId}`, 'applies_to', 1.0, 'auto:store-decision');
+        }
+        // Cross-link decision → referenced file/symbol nodes (T626 phase 1).
+        // Fire-and-forget — autoCrossLinkDecision swallows its own errors.
+        autoCrossLinkDecision(projectRoot, saved.id, saved.decision, saved.rationale).catch(() => {
+            /* best-effort */
+        });
+    }
+    catch {
+        /* Graph population is best-effort — never block the primary return */
+    }
+    // Detect supersession: check if this new decision supersedes any existing ones.
+    // Fire-and-forget — never block the primary return.
+    detectSupersession(projectRoot, {
+        id: saved.id,
+        text: saved.decision + ' ' + saved.rationale,
+        createdAt: saved.createdAt ?? new Date().toISOString().replace('T', ' ').slice(0, 19),
+    })
+        .then((candidates) => {
+        for (const candidate of candidates) {
+            supersedeMemory(projectRoot, candidate.existingId, saved.id, 'auto:decision-supersedes — high overlap detected at store time').catch(() => {
+                /* best-effort */
+            });
+        }
+    })
+        .catch(() => {
+        /* best-effort */
+    });
+    return saved;
+}
+/**
+ * Recall a specific decision by ID.
+ *
+ * @task T5155
+ */
+export async function recallDecision(projectRoot, id) {
+    const accessor = await getBrainAccessor(projectRoot);
+    return accessor.getDecision(id);
+}
+/**
+ * Search decisions by type, confidence, outcome, and/or free-text query.
+ * Query searches across decision + rationale fields using LIKE.
+ *
+ * @task T5155
+ */
+export async function searchDecisions(projectRoot, params = {}) {
+    const accessor = await getBrainAccessor(projectRoot);
+    // Use the accessor for structured filters
+    let results = await accessor.findDecisions({
+        type: params.type,
+        confidence: params.confidence,
+        outcome: params.outcome ?? undefined,
+        limit: params.query ? undefined : params.limit,
+    });
+    // Apply free-text search on top
+    if (params.query) {
+        const q = params.query.toLowerCase();
+        results = results.filter((d) => d.decision.toLowerCase().includes(q) || d.rationale.toLowerCase().includes(q));
+    }
+    if (params.limit && params.limit > 0) {
+        results = results.slice(0, params.limit);
+    }
+    return results;
+}
+/**
+ * List decisions with pagination.
+ *
+ * @task T5155
+ */
+export async function listDecisions(projectRoot, params = {}) {
+    const accessor = await getBrainAccessor(projectRoot);
+    // Get all decisions for total count
+    const all = await accessor.findDecisions({});
+    const total = all.length;
+    const offset = params.offset ?? 0;
+    const limit = params.limit ?? 50;
+    const decisions = all.slice(offset, offset + limit);
+    return { decisions, total };
+}
+/**
+ * Update the outcome of a decision after learning from results.
+ *
+ * @task T5155
+ */
+export async function updateDecisionOutcome(projectRoot, id, outcome) {
+    const accessor = await getBrainAccessor(projectRoot);
+    const existing = await accessor.getDecision(id);
+    if (!existing) {
+        throw new Error(`Decision not found: ${id}`);
+    }
+    await accessor.updateDecision(id, { outcome });
+    const updated = await accessor.getDecision(id);
+    return updated;
+}
+//# sourceMappingURL=decisions.js.map

package/dist/memory/decisions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decisions.js","sourceRoot":"","sources":["../../src/memory/decisions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AACzE,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AA8BjF;;;GAGG;AACH,KAAK,UAAU,cAAc,CAAC,WAAmB;IAC/C,MAAM,EAAE,UAAU,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IAChE,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACpE,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC;IAC7C,MAAM,EAAE,GAAG,MAAM,UAAU,CAAC,WAAW,CAAC,CAAC;IACzC,MAAM,IAAI,GAAG,MAAM,EAAE;SAClB,MAAM,CAAC,EAAE,EAAE,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC;SACjC,IAAI,CAAC,cAAc,CAAC;SACpB,OAAO,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC;SAChC,KAAK,CAAC,CAAC,CAAC,CAAC;IAEZ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC1B,MAAM,GAAG,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC1C,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,IAAI,MAAM,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AAChD,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,WAAmB,EACnB,MAA2B;IAE3B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,EAAE,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAErD,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,QAAQ,CAAC,IAAI,CAC7B,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,CAClE,CAAC;IAEF,IAAI,SAAS,EAAE,CAAC;QACd,+BAA+B;QAC/B,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACpE,MAAM,QAAQ,CAAC,cAAc,CAAC,SAAS,CAAC,EAAE,EAAE;YAC1C,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;YAClC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,SAAS,CAAC,OAAO;YAC5C,gBAAgB,EAAE,MAAM,CAAC,YAAY;gBACnC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC;gBACrC,CAAC,CAAC,SAAS,CAAC,gBAAgB;YAC9B,SAAS,EAAE,GAAG;SACf,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;QAEzD,iEAAiE;QACjE,MAAM,cAAc,GAAG,sBAAsB,CAAC;YAC5C,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;YAClC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,IAAI;SAC5C,CAAC,CAAC;QACH,eAAe,CACb,WAAW,EACX,YAAY,SAAS,CAAC,EAAE,EAAE,EAC1B,UAAU,EACV,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,EACxC,cAAc,EACd,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,EAChD,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,CACrD,CAAC,KAAK,CAAC,GAAG,EAAE;YACX,iBAAiB;QACnB,CAAC,CAAC,CAAC;QAEH,OAAO,OAAQ,CAAC;IAClB,CAAC;IAED,yCAAyC;IACzC,MAAM,EAAE,GAAG,MAAM,cAAc,CAAC,WAAW,CAAC,CAAC;IAE7C,kEAAkE;IAClE,IAAI,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC;IACvC,IAAI,WAAW,GAAG,MAAM,CAAC,aAAa,CAAC;IACvC,IAAI,WAAW,IAAI,WAAW,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,WAAW,CAAC,CAAC;QACzC,IAAI,WAAW,IAAI,CAAC,CAAC,MAAM,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;YACtE,WAAW,GAAG,SAAS,CAAC;QAC1B,CAAC;QACD,IAAI,WAAW,IAAI,CAAC,CAAC,MAAM,mBAAmB,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC,EAAE,CAAC;YACtE,WAAW,GAAG,SAAS,CAAC;QAC1B,CAAC;IACH,CAAC;IAED,6CAA6C;IAC7C,iFAAiF;IACjF,qEAAqE;IACrE,8EAA8E;IAC9E,wDAAwD;IACxD,kGAAkG;IAClG,0EAA0E;IAC1E,MAAM,UAAU,GAAG,QAAiB,CAAC;IACrC,MAAM,UAAU,GAAG,UAAmB,CAAC;IACvC,MAAM,gBAAgB,GAAG,OAAgB,CAAC;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC;IAEtB,iFAAiF;IACjF,iEAAiE;IACjE,MAAM,YAAY,GAAG,sBAAsB,CAAC;QAC1C,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;QAClC,aAAa,EAAE,WAAW,IAAI,IAAI;QAClC,gBAAgB;QAChB,UAAU;KACX,CAAC,CAAC;IAEH,MAAM,GAAG,GAAwB;QAC/B,EAAE;QACF,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE;QAChC,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE;QAClC,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO;QACvB,gBAAgB,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,SAAS;QACvF,aAAa,EAAE,WAAW;QAC1B,aAAa,EAAE,WAAW;QAC1B,YAAY,EAAE,MAAM,CAAC,YAAY;QACjC,YAAY;QACZ,6DAA6D;QAC7D,UAAU;QACV,UAAU;QACV,gBAAgB;QAChB,QAAQ;KACT,CAAC;IAEF,MAAM,KAAK,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAE9C,6EAA6E;IAC7E,uEAAuE;IACvE,IAAI,CAAC;QACH,MAAM,eAAe,CACnB,WAAW,EACX,YAAY,KAAK,CAAC,EAAE,EAAE,EACtB,UAAU,EACV,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,EAChC,YAAY,EACZ,KAAK,CAAC,QAAQ,GAAG,KAAK,CAAC,SAAS,EAChC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,CAAC,UAAU,EAAE,CACnD,CAAC;QAEF,uDAAuD;QACvD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,eAAe,CAAC,WAAW,EAAE,QAAQ,WAAW,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACxF,MAAM,YAAY,CAChB,WAAW,EACX,YAAY,KAAK,CAAC,EAAE,EAAE,EACtB,QAAQ,WAAW,EAAE,EACrB,YAAY,EACZ,GAAG,EACH,qBAAqB,CACtB,CAAC;QACJ,CAAC;QAED,wDAAwD;QACxD,IAAI,WAAW,EAAE,CAAC;YAChB,MAAM,eAAe,CAAC,WAAW,EAAE,QAAQ,WAAW,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;YACxF,MAAM,YAAY,CAChB,WAAW,EACX,YAAY,KAAK,CAAC,EAAE,EAAE,EACtB,QAAQ,WAAW,EAAE,EACrB,YAAY,EACZ,GAAG,EACH,qBAAqB,CACtB,CAAC;QACJ,CAAC;QAED,qEAAqE;QACrE,mEAAmE;QACnE,qBAAqB,CAAC,WAAW,EAAE,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;YACvF,iBAAiB;QACnB,CAAC,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;IAED,gFAAgF;IAChF,oDAAoD;IACpD,kBAAkB,CAAC,WAAW,EAAE;QAC9B,EAAE,EAAE,KAAK,CAAC,EAAE;QACZ,IAAI,EAAE,KAAK,CAAC,QAAQ,GAAG,GAAG,GAAG,KAAK,CAAC,SAAS;QAC5C,SAAS,EAAE,KAAK,CAAC,SAAS,IAAI,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;KACtF,CAAC;SACC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;QACnB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;YACnC,eAAe,CACb,WAAW,EACX,SAAS,CAAC,UAAU,EACpB,KAAK,CAAC,EAAE,EACR,gEAAgE,CACjE,CAAC,KAAK,CAAC,GAAG,EAAE;gBACX,iBAAiB;YACnB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC;SACD,KAAK,CAAC,GAAG,EAAE;QACV,iBAAiB;IACnB,CAAC,CAAC,CAAC;IAEL,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,WAAmB,EACnB,EAAU;IAEV,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACrD,OAAO,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;AAClC,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,WAAmB,EACnB,SAA+B,EAAE;IAEjC,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAErD,0CAA0C;IAC1C,IAAI,OAAO,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC;QACzC,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,UAAU,EAAE,MAAM,CAAC,UAAU;QAC7B,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,SAAS;QACpC,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK;KAC/C,CAAC,CAAC;IAEH,gCAAgC;IAChC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;QACrC,OAAO,GAAG,OAAO,CAAC,MAAM,CACtB,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC,CACrF,CAAC;IACJ,CAAC;IAED,IAAI,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,EAAE,CAAC;QACrC,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,WAAmB,EACnB,SAA6B,EAAE;IAE/B,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IAErD,oCAAoC;IACpC,MAAM,GAAG,GAAG,MAAM,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC;IAEzB,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAEjC,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;IAEpD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,WAAmB,EACnB,EAAU,EACV,OAAoC;IAEpC,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,WAAW,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAEhD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,MAAM,IAAI,KAAK,CAAC,uBAAuB,EAAE,EAAE,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,QAAQ,CAAC,cAAc,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;IAC/C,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;IAC/C,OAAO,OAAQ,CAAC;AAClB,CAAC"}

package/dist/memory/edge-types.js

@@ -0,0 +1,31 @@
+/**
+ * Canonical edge-type constants for `brain_page_edges`.
+ *
+ * All code that writes or queries `brain_page_edges.edge_type` MUST use
+ * these constants instead of raw string literals to prevent enum drift.
+ *
+ * The values here are a subset of `BRAIN_EDGE_TYPES` (brain-schema.ts).
+ * They are duplicated as constants so callers do not need to import the
+ * schema module (which carries Drizzle + SQLite dependencies).
+ *
+ * @epic T626
+ */
+export const EDGE_TYPES = {
+    // Plasticity (Hebbian / STDP co-retrieval)
+    CO_RETRIEVED: 'co_retrieved',
+    // Temporal supersession
+    SUPERSEDES: 'supersedes',
+    // Task / decision / pattern → target context
+    APPLIES_TO: 'applies_to',
+    // Provenance
+    DERIVED_FROM: 'derived_from',
+    // Observation → symbol/file impact
+    AFFECTS: 'affects',
+    // Observation → symbol name mention
+    MENTIONS: 'mentions',
+    // Observation → symbol/file structural link
+    DOCUMENTS: 'documents',
+    // Memory node → nexus symbol/file (T645)
+    CODE_REFERENCE: 'code_reference',
+};
+//# sourceMappingURL=edge-types.js.map

package/dist/memory/edge-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-types.js","sourceRoot":"","sources":["../../src/memory/edge-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,2CAA2C;IAC3C,YAAY,EAAE,cAAc;IAC5B,wBAAwB;IACxB,UAAU,EAAE,YAAY;IACxB,6CAA6C;IAC7C,UAAU,EAAE,YAAY;IACxB,aAAa;IACb,YAAY,EAAE,cAAc;IAC5B,mCAAmC;IACnC,OAAO,EAAE,SAAS;IAClB,oCAAoC;IACpC,QAAQ,EAAE,UAAU;IACpB,4CAA4C;IAC5C,SAAS,EAAE,WAAW;IACtB,yCAAyC;IACzC,cAAc,EAAE,gBAAgB;CACxB,CAAC"}

package/dist/memory/embedding-local.js

@@ -0,0 +1,102 @@
+/**
+ * Local embedding provider using @huggingface/transformers (transformers.js v4).
+ *
+ * Implements the EmbeddingProvider interface for brain memory vector search.
+ * Uses all-MiniLM-L6-v2 (22MB, 384 dimensions) — matches the brain_embeddings
+ * vec0 table schema. Model downloads on first call and is cached locally by
+ * the transformers library.
+ *
+ * @epic T134
+ * @task T136
+ * @why Ship vector search out-of-the-box without external API keys
+ * @what Local embedding provider using @huggingface/transformers all-MiniLM-L6-v2
+ * @remarks Brain embeddings are a FIRST-CLASS CLEO feature — the transformers
+ *   package is a regular dependency of `@cleocode/core`, not optional.
+ *   Migrated from `@xenova/transformers` v2 to `@huggingface/transformers`
+ *   v4 (upstream rename, same author) which drops the deprecated
+ *   `prebuild-install` transitive via `sharp@0.34+`.
+ */
+import { EMBEDDING_DIMENSIONS } from './brain-embedding.js';
+/** Model identifier for all-MiniLM-L6-v2 via Xenova hub. */
+const MODEL_NAME = 'Xenova/all-MiniLM-L6-v2';
+/** Pipeline singleton — initialized lazily on first call. */
+let _pipeline = null;
+/** Whether the pipeline has been successfully initialized. */
+let _ready = false;
+/**
+ * Load the transformers feature-extraction pipeline lazily.
+ * Dynamic import prevents the heavy model from loading unless embedding is enabled.
+ */
+async function loadPipeline() {
+    if (_ready)
+        return;
+    // Dynamic import — only resolves when embedding is explicitly enabled
+    const { pipeline } = await import('@huggingface/transformers');
+    _pipeline = await pipeline('feature-extraction', MODEL_NAME);
+    _ready = true;
+}
+/**
+ * Local embedding provider backed by @huggingface/transformers.
+ *
+ * Produces 384-dimension Float32Array vectors compatible with the
+ * brain_embeddings vec0 table. The model is downloaded on first use
+ * and cached locally by the transformers library.
+ *
+ * Use {@link initDefaultProvider} (in brain-embedding.ts) to register an
+ * instance when brain.embedding.enabled=true and
+ * brain.embedding.provider='local'.
+ */
+export class LocalEmbeddingProvider {
+    /** Number of dimensions produced — must match brain_embeddings vec0 table. */
+    dimensions = EMBEDDING_DIMENSIONS;
+    /**
+     * Whether the pipeline has been successfully initialized and is ready to produce embeddings.
+     */
+    isAvailable() {
+        return _ready;
+    }
+    /**
+     * Convert a single text string into a 384-dimension float vector.
+     * Triggers model download on first call if not already cached.
+     *
+     * @param text - The text to embed.
+     * @returns A Float32Array of length 384.
+     */
+    async embed(text) {
+        await loadPipeline();
+        const output = await _pipeline(text, { pooling: 'mean', normalize: true });
+        // output.data is DataArray (AnyTypedArray | any[]). For feature-extraction
+        // with all-MiniLM-L6-v2, the runtime value is always Float32Array. Copy via
+        // Float32Array constructor which accepts any iterable of numbers.
+        return Float32Array.from(output.data);
+    }
+    /**
+     * Embed multiple texts in sequence, reusing the cached pipeline.
+     *
+     * @param texts - Array of text strings to embed.
+     * @returns Array of Float32Array vectors, one per input text.
+     */
+    async embedBatch(texts) {
+        await loadPipeline();
+        const results = [];
+        for (const text of texts) {
+            const output = await _pipeline(text, { pooling: 'mean', normalize: true });
+            results.push(Float32Array.from(output.data));
+        }
+        return results;
+    }
+}
+/** Module-level singleton instance. */
+let _instance = null;
+/**
+ * Get or create the shared LocalEmbeddingProvider singleton.
+ *
+ * @returns The shared LocalEmbeddingProvider instance.
+ */
+export function getLocalEmbeddingProvider() {
+    if (!_instance) {
+        _instance = new LocalEmbeddingProvider();
+    }
+    return _instance;
+}
+//# sourceMappingURL=embedding-local.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-local.js","sourceRoot":"","sources":["../../src/memory/embedding-local.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAGH,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAE5D,4DAA4D;AAC5D,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAE7C,6DAA6D;AAC7D,IAAI,SAAS,GAAyE,IAAI,CAAC;AAE3F,8DAA8D;AAC9D,IAAI,MAAM,GAAG,KAAK,CAAC;AAEnB;;;GAGG;AACH,KAAK,UAAU,YAAY;IACzB,IAAI,MAAM;QAAE,OAAO;IACnB,sEAAsE;IACtE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC;IAC/D,SAAS,GAAG,MAAM,QAAQ,CAAC,oBAAoB,EAAE,UAAU,CAAC,CAAC;IAC7D,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,sBAAsB;IACjC,8EAA8E;IACrE,UAAU,GAAG,oBAAoB,CAAC;IAE3C;;OAEG;IACH,WAAW;QACT,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,IAAY;QACtB,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,MAAM,SAAU,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5E,2EAA2E;QAC3E,4EAA4E;QAC5E,kEAAkE;QAClE,OAAO,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAoB,CAAC,CAAC;IACxD,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU,CAAC,KAAe;QAC9B,MAAM,YAAY,EAAE,CAAC;QACrB,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,MAAM,SAAU,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5E,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,IAAoB,CAAC,CAAC,CAAC;QAC/D,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAED,uCAAuC;AACvC,IAAI,SAAS,GAAkC,IAAI,CAAC;AAEpD;;;;GAIG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,SAAS,GAAG,IAAI,sBAAsB,EAAE,CAAC;IAC3C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/memory/embedding-queue.js

@@ -0,0 +1,271 @@
+/**
+ * Embedding Queue Manager
+ *
+ * Manages an async queue of embedding requests, processing them in batches
+ * via a worker thread to avoid blocking the main Node.js event loop.
+ *
+ * Architecture:
+ *   - {@link EmbeddingQueue} is a singleton — one worker thread per process
+ *   - {@link EmbeddingQueue.enqueue} adds items; the drain loop batches them
+ *   - Batches up to {@link BATCH_SIZE} items per processing cycle
+ *   - Falls back to `setImmediate` + direct embedding when worker threads
+ *     are unavailable or the worker script cannot be resolved
+ *   - Registers a `process.on('exit')` handler for graceful shutdown
+ *
+ * @epic T134
+ * @task T137
+ * @why Non-blocking embedding generation for observeBrain()
+ * @what Singleton queue + worker-thread batch processor
+ */
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/** Maximum items processed per worker message cycle. */
+const BATCH_SIZE = 10;
+/** How long to wait between drain cycles when the queue is non-empty (ms). */
+const DRAIN_INTERVAL_MS = 50;
+/**
+ * Resolve the absolute path to the compiled embedding-worker script.
+ *
+ * Strategy (cheap-first):
+ * 1. Adjacent to this file (tsc dev: `dist/memory/embedding-worker.js`)
+ * 2. Falls back to null when the file cannot be found (esbuild bundle context)
+ */
+function resolveWorkerPath() {
+    try {
+        // In ESM, __dirname is not available — use import.meta.url
+        const currentDir = dirname(fileURLToPath(import.meta.url));
+        const candidate = join(currentDir, 'embedding-worker.js');
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        // Also try ../ for cases where the queue is loaded from a subdirectory
+        const parentCandidate = join(currentDir, '..', 'memory', 'embedding-worker.js');
+        if (existsSync(parentCandidate)) {
+            return parentCandidate;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Singleton embedding queue.
+ *
+ * Batches embedding requests and processes them via a worker thread,
+ * keeping heavy model inference off the main event loop.
+ *
+ * Use {@link getEmbeddingQueue} to obtain the shared instance.
+ */
+export class EmbeddingQueue {
+    queue = [];
+    worker = null;
+    workerAvailable = false;
+    draining = false;
+    shutdownPromise = null;
+    /**
+     * Store the observation ID → DB write callback so the worker result
+     * can be persisted back to brain_embeddings without coupling to SQLite here.
+     */
+    callbacks = new Map();
+    /** Initialise the worker thread if possible. Called lazily on first enqueue. */
+    async initWorker() {
+        if (this.workerAvailable || this.worker !== null)
+            return;
+        const workerPath = resolveWorkerPath();
+        if (!workerPath) {
+            // esbuild bundle context — worker file not available, use fallback
+            this.workerAvailable = false;
+            return;
+        }
+        try {
+            const { Worker } = await import('node:worker_threads');
+            const worker = new Worker(workerPath);
+            worker.on('message', (msg) => {
+                const cb = this.callbacks.get(msg.id);
+                if (!cb)
+                    return;
+                this.callbacks.delete(msg.id);
+                if (msg.embedding) {
+                    const vector = Float32Array.from(msg.embedding);
+                    cb(msg.id, vector).catch(() => {
+                        // Persistence is best-effort; observation already saved without vector
+                    });
+                }
+                // On error, skip silently — observation exists without embedding
+            });
+            worker.on('error', () => {
+                // Worker crashed — disable worker path, drain remaining via fallback
+                this.worker = null;
+                this.workerAvailable = false;
+                this.callbacks.clear();
+            });
+            worker.on('exit', () => {
+                this.worker = null;
+                this.workerAvailable = false;
+            });
+            this.worker = worker;
+            this.workerAvailable = true;
+        }
+        catch {
+            // worker_threads unavailable (rare)
+            this.workerAvailable = false;
+        }
+    }
+    /**
+     * Add an observation to the embedding queue.
+     *
+     * The observation must already be persisted in brain_observations before
+     * calling this method. `onComplete` is called asynchronously with the
+     * generated vector once the worker finishes.
+     *
+     * @param observationId - The brain observation ID (e.g. `O-abc123-0`)
+     * @param text - Raw text to embed
+     * @param onComplete - Callback to persist the embedding vector
+     */
+    enqueue(observationId, text, onComplete) {
+        if (this.shutdownPromise)
+            return; // queue is shutting down
+        this.callbacks.set(observationId, onComplete);
+        this.queue.push({ observationId, text });
+        if (!this.draining) {
+            this.scheduleDrain();
+        }
+    }
+    /** Schedule the next drain cycle via setImmediate. */
+    scheduleDrain() {
+        setImmediate(() => {
+            this.drain().catch(() => {
+                // Drain errors are non-fatal
+                this.draining = false;
+            });
+        });
+    }
+    /**
+     * Process up to {@link BATCH_SIZE} items from the queue.
+     * Uses the worker thread when available, falls back to inline setImmediate.
+     */
+    async drain() {
+        this.draining = true;
+        // Ensure worker is initialised (no-op after first call)
+        await this.initWorker();
+        while (this.queue.length > 0) {
+            const batch = this.queue.splice(0, BATCH_SIZE);
+            if (this.workerAvailable && this.worker) {
+                // Dispatch to worker thread — results arrive via 'message' event
+                for (const item of batch) {
+                    this.worker.postMessage({ id: item.observationId, text: item.text });
+                }
+            }
+            else {
+                // Fallback: process inline via setImmediate to yield to event loop
+                for (const item of batch) {
+                    setImmediate(() => {
+                        this.fallbackEmbed(item).catch(() => {
+                            // Silently skip — observation already persisted without embedding
+                            this.callbacks.delete(item.observationId);
+                        });
+                    });
+                }
+            }
+            if (this.queue.length > 0) {
+                // Yield to event loop between batches
+                await new Promise((resolve) => setTimeout(resolve, DRAIN_INTERVAL_MS));
+            }
+        }
+        this.draining = false;
+    }
+    /**
+     * Inline fallback embedding — used when worker thread is unavailable.
+     * Runs directly on the main thread (but inside setImmediate to yield first).
+     */
+    async fallbackEmbed(item) {
+        const cb = this.callbacks.get(item.observationId);
+        if (!cb)
+            return;
+        this.callbacks.delete(item.observationId);
+        const { getLocalEmbeddingProvider } = await import('./embedding-local.js');
+        const provider = getLocalEmbeddingProvider();
+        const vector = await provider.embed(item.text);
+        await cb(item.observationId, vector);
+    }
+    /**
+     * Flush the queue and terminate the worker thread.
+     *
+     * Waits for in-flight worker messages to drain, then terminates.
+     * Safe to call multiple times — subsequent calls return the same promise.
+     */
+    shutdown() {
+        if (this.shutdownPromise)
+            return this.shutdownPromise;
+        this.shutdownPromise = this.doShutdown();
+        return this.shutdownPromise;
+    }
+    async doShutdown() {
+        // Drain remaining queue items
+        if (this.queue.length > 0) {
+            await this.drain();
+        }
+        // Terminate the worker
+        if (this.worker) {
+            try {
+                await this.worker.terminate();
+            }
+            catch {
+                // Worker may already be gone
+            }
+            this.worker = null;
+        }
+        this.callbacks.clear();
+    }
+}
+/** Module-level singleton. */
+let _instance = null;
+/**
+ * Get or create the shared EmbeddingQueue singleton.
+ *
+ * Registers a process `exit` handler on first call to flush and
+ * terminate the worker thread cleanly.
+ *
+ * @returns The shared EmbeddingQueue instance.
+ */
+export function getEmbeddingQueue() {
+    if (!_instance) {
+        _instance = new EmbeddingQueue();
+        // Best-effort flush on process exit (synchronous handlers only get ~50ms)
+        process.on('exit', () => {
+            _instance?.shutdown().catch(() => {
+                // exit handler — cannot await
+            });
+        });
+        // For SIGTERM/SIGINT give the queue time to flush
+        const gracefulShutdown = () => {
+            if (_instance) {
+                _instance
+                    .shutdown()
+                    .catch(() => { })
+                    .finally(() => process.exit(0));
+            }
+            else {
+                process.exit(0);
+            }
+        };
+        process.once('SIGTERM', gracefulShutdown);
+        process.once('SIGINT', gracefulShutdown);
+    }
+    return _instance;
+}
+/**
+ * Reset the singleton (for testing only).
+ * Shuts down the existing queue before clearing the reference.
+ *
+ * @internal
+ */
+export async function resetEmbeddingQueue() {
+    if (_instance) {
+        await _instance.shutdown();
+        _instance = null;
+    }
+}
+//# sourceMappingURL=embedding-queue.js.map