@cleocode/core 2026.3.69 → 2026.3.71

package/src/memory/auto-extract.ts

@@ -159,3 +159,43 @@ export async function resolveTaskDetails(projectRoot: string, taskIds: string[])
     await accessor.close();
   }
 }
+
+/** Action words that indicate a meaningful assistant turn worth storing. */
+const ACTION_PATTERNS =
+  /\b(implement|fix|add|create|update|remove|refactor|extract|migrate|resolve|complete|found|learned|discovered)\b/i;
+
+/**
+ * Extract key observations from a provider session transcript and store
+ * them in brain.db as learnings.
+ *
+ * Filters assistant lines that contain action words, stores up to 5 as
+ * learnings with 0.6 confidence. Always best-effort — never throws.
+ *
+ * @param projectRoot - Absolute path to project root.
+ * @param sessionId - The CLEO session ID being processed.
+ * @param transcript - Plain-text provider transcript (user/assistant turns).
+ * @task T144 @epic T134
+ */
+export async function extractFromTranscript(
+  projectRoot: string,
+  sessionId: string,
+  transcript: string,
+): Promise<void> {
+  try {
+    const lines = transcript.split('\n').filter((l) => l.trim().length > 20);
+    const actionLines = lines.filter((l) => ACTION_PATTERNS.test(l)).slice(0, 5);
+    if (actionLines.length === 0) return;
+
+    const { storeLearning } = await import('./learnings.js');
+    for (const line of actionLines) {
+      await storeLearning(projectRoot, {
+        insight: line.trim().slice(0, 250),
+        source: `transcript:${sessionId}`,
+        confidence: 0.6,
+        actionable: false,
+      });
+    }
+  } catch {
+    // Best-effort: must never throw
+  }
+}

package/src/memory/brain-embedding.ts

@@ -64,3 +64,21 @@ export async function embedText(text: string): Promise<Float32Array | null> {
 export function isEmbeddingAvailable(): boolean {
   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 @xenova/transformers
+ * bundle unless embedding is actually requested.
+ *
+ * @task T136 @epic T134
+ */
+export async function initDefaultProvider(): Promise<void> {
+  const { LocalEmbeddingProvider } = await import('./embedding-local.js');
+  const provider = new LocalEmbeddingProvider();
+  setEmbeddingProvider(provider);
+}

package/src/memory/brain-maintenance.ts

@@ -0,0 +1,183 @@
+/**
+ * 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';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/** Temporal decay step result subset used in maintenance output. */
+export interface BrainMaintenanceDecayResult {
+  /** Number of learnings whose confidence was updated. */
+  affected: number;
+}
+
+/** Memory consolidation step result subset used in maintenance output. */
+export interface BrainMaintenanceConsolidationResult {
+  /** Number of new summary observations created. */
+  merged: number;
+  /** Number of original observations archived. */
+  removed: number;
+}
+
+/** Embedding backfill step result. */
+export interface BrainMaintenanceEmbeddingsResult {
+  /** Observations successfully embedded. */
+  processed: number;
+  /** Observations skipped (no provider or no narrative). */
+  skipped: number;
+  /** Observations that failed embedding. */
+  errors: number;
+}
+
+/**
+ * Aggregated result from a full brain maintenance run.
+ *
+ * All counts are zero when a step is skipped via the corresponding
+ * `skip*` option.
+ */
+export interface BrainMaintenanceResult {
+  /** Results from the temporal decay step. */
+  decay: BrainMaintenanceDecayResult;
+  /** Results from the memory consolidation step. */
+  consolidation: BrainMaintenanceConsolidationResult;
+  /** Results from the embedding backfill step. */
+  embeddings: BrainMaintenanceEmbeddingsResult;
+  /** Total wall-clock duration of the maintenance run in milliseconds. */
+  duration: number;
+}
+
+/**
+ * Options for {@link runBrainMaintenance}.
+ *
+ * All `skip*` flags default to `false` — the full maintenance pass runs
+ * unless specific steps are disabled.
+ */
+export interface BrainMaintenanceOptions {
+  /** Skip the temporal decay step. Default: false. */
+  skipDecay?: boolean;
+  /** Skip the memory consolidation step. Default: false. */
+  skipConsolidation?: boolean;
+  /** Skip the embedding backfill step. Default: false. */
+  skipEmbeddings?: boolean;
+  /**
+   * Progress callback invoked before each step starts and after
+   * completion of each sub-item.
+   *
+   * @param step - Human-readable step name (e.g. "decay", "consolidation", "embeddings")
+   * @param current - Items processed so far within the current step (0 before step starts)
+   * @param total - Total items expected for the current step (0 if unknown before start)
+   */
+  onProgress?: (step: string, current: number, total: number) => void;
+}
+
+// ============================================================================
+// 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: string,
+  options?: BrainMaintenanceOptions,
+): Promise<BrainMaintenanceResult> {
+  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: BrainMaintenanceDecayResult = { affected: 0 };
+  const consolidationResult: BrainMaintenanceConsolidationResult = { merged: 0, removed: 0 };
+  const embeddingsResult: BrainMaintenanceEmbeddingsResult = {
+    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,
+  };
+}

package/src/memory/brain-retrieval.ts

@@ -596,6 +596,14 @@ export async function observeBrain(
       });
   }
 
+  // Auto-link observation to the currently focused task when a session is active. (T141)
+  // This is a fire-and-forget side effect — linking failure MUST NOT block the return.
+  if (sourceSessionId) {
+    autoLinkObservationToTask(projectRoot, row.id, accessor).catch(() => {
+      /* Auto-linking is best-effort */
+    });
+  }
+
   return {
     id: row.id,
     type: row.type,
@@ -603,6 +611,40 @@ export async function observeBrain(
   };
 }
 
+/**
+ * Auto-link a newly created observation to the currently focused task.
+ *
+ * Queries the active session via sessionStatus() and reads taskWork.taskId.
+ * If a task is focused, inserts a brain_memory_links row linking the
+ * observation to that task with linkType 'produced_by'.
+ *
+ * All failures are silently swallowed — this is a best-effort side effect.
+ *
+ * @param projectRoot - Project root directory
+ * @param observationId - ID of the newly created observation
+ * @param accessor - BrainDataAccessor to use for the link insert
+ */
+async function autoLinkObservationToTask(
+  projectRoot: string,
+  observationId: string,
+  accessor: Awaited<ReturnType<typeof getBrainAccessor>>,
+): Promise<void> {
+  const { sessionStatus } = await import('../sessions/index.js');
+  const session = await sessionStatus(projectRoot);
+
+  if (!session) return;
+
+  const taskId = session.taskWork?.taskId;
+  if (!taskId) return;
+
+  await accessor.addLink({
+    memoryType: 'observation',
+    memoryId: observationId,
+    taskId,
+    linkType: 'produced_by',
+  });
+}
+
 // ============================================================================
 // Embedding Backfill Pipeline (T5387)
 // ============================================================================
@@ -611,6 +653,29 @@ export async function observeBrain(
 export interface PopulateEmbeddingsResult {
   processed: number;
   skipped: number;
+  errors: number;
+}
+
+/**
+ * Options for the embedding backfill pipeline.
+ *
+ * @example
+ * ```ts
+ * await populateEmbeddings(root, {
+ *   batchSize: 25,
+ *   onProgress: (current, total) => console.log(`${current}/${total}`),
+ * });
+ * ```
+ */
+export interface PopulateEmbeddingsOptions {
+  /** Maximum items processed per batch cycle. Defaults to 50. */
+  batchSize?: number;
+  /**
+   * Progress callback invoked after each observation is attempted.
+   * `current` is the 1-based count of observations attempted so far;
+   * `total` is the full count of observations that need embeddings.
+   */
+  onProgress?: (current: number, total: number) => void;
 }
 
 /**
@@ -620,16 +685,22 @@ export interface PopulateEmbeddingsResult {
  * generates vectors using the registered embedding provider.
  * Processes in batches to avoid memory pressure.
  *
+ * An optional {@link PopulateEmbeddingsOptions.onProgress} callback is called
+ * after each observation is attempted, enabling callers to report progress.
+ *
  * @param projectRoot - Project root directory
- * @param options - Optional batch size configuration
- * @returns Count of processed and skipped observations
+ * @param options - Optional batch size and progress callback
+ * @returns Count of processed, skipped, and errored observations
+ *
+ * @epic T134
+ * @task T142
  */
 export async function populateEmbeddings(
   projectRoot: string,
-  options?: { batchSize?: number },
+  options?: PopulateEmbeddingsOptions,
 ): Promise<PopulateEmbeddingsResult> {
   if (!isEmbeddingAvailable()) {
-    return { processed: 0, skipped: 0 };
+    return { processed: 0, skipped: 0, errors: 0 };
   }
 
   const { getBrainDb, getBrainNativeDb } = await import('../store/brain-sqlite.js');
@@ -637,12 +708,14 @@ export async function populateEmbeddings(
   const nativeDb = getBrainNativeDb();
 
   if (!nativeDb) {
-    return { processed: 0, skipped: 0 };
+    return { processed: 0, skipped: 0, errors: 0 };
   }
 
   const batchSize = options?.batchSize ?? 50;
+  const { onProgress } = options ?? {};
   let processed = 0;
   let skipped = 0;
+  let errors = 0;
 
   // Find observations without embeddings
   const rows = typedAll<BrainNarrativeRow>(
@@ -655,6 +728,9 @@ export async function populateEmbeddings(
   `),
   );
 
+  const total = rows.length;
+  let attempted = 0;
+
   for (let i = 0; i < rows.length; i += batchSize) {
     const batch = rows.slice(i, i + batchSize);
     for (const row of batch) {
@@ -669,10 +745,12 @@ export async function populateEmbeddings(
           skipped++;
         }
       } catch {
-        skipped++;
+        errors++;
       }
+      attempted++;
+      onProgress?.(attempted, total);
     }
   }
 
-  return { processed, skipped };
+  return { processed, skipped, errors };
 }

package/src/memory/embedding-local.ts

@@ -0,0 +1,107 @@
+/**
+ * Local embedding provider using @xenova/transformers.
+ *
+ * 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 @xenova/transformers all-MiniLM-L6-v2
+ */
+
+import type { EmbeddingProvider } from './brain-embedding.js';
+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: import('@xenova/transformers').FeatureExtractionPipeline | null = 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(): Promise<void> {
+  if (_ready) return;
+  // Dynamic import — only resolves when embedding is explicitly enabled
+  const { pipeline } = await import('@xenova/transformers');
+  _pipeline = await pipeline('feature-extraction', MODEL_NAME);
+  _ready = true;
+}
+
+/**
+ * Local embedding provider backed by @xenova/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 implements EmbeddingProvider {
+  /** Number of dimensions produced — must match brain_embeddings vec0 table. */
+  readonly dimensions = EMBEDDING_DIMENSIONS;
+
+  /**
+   * Whether the pipeline has been successfully initialized and is ready to produce embeddings.
+   */
+  isAvailable(): boolean {
+    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: string): Promise<Float32Array> {
+    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 as Float32Array);
+  }
+
+  /**
+   * 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: string[]): Promise<Float32Array[]> {
+    await loadPipeline();
+    const results: Float32Array[] = [];
+    for (const text of texts) {
+      const output = await _pipeline!(text, { pooling: 'mean', normalize: true });
+      results.push(Float32Array.from(output.data as Float32Array));
+    }
+    return results;
+  }
+}
+
+/** Module-level singleton instance. */
+let _instance: LocalEmbeddingProvider | null = null;
+
+/**
+ * Get or create the shared LocalEmbeddingProvider singleton.
+ *
+ * @returns The shared LocalEmbeddingProvider instance.
+ */
+export function getLocalEmbeddingProvider(): LocalEmbeddingProvider {
+  if (!_instance) {
+    _instance = new LocalEmbeddingProvider();
+  }
+  return _instance;
+}