@cleocode/core 2026.3.69 → 2026.3.70

package/src/hooks/handlers/mcp-hooks.ts

@@ -1,9 +1,11 @@
 /**
  * MCP Prompt/Response Hook Handlers - Wave 2 of T5237
  *
- * Handlers for onPromptSubmit and onResponseComplete events.
- * By default, NO brain capture (too noisy). Brain observation is
- * opt-in via CLEO_BRAIN_CAPTURE_MCP=true environment variable.
+ * Handlers for onPromptSubmit and onResponseComplete events that capture
+ * ALL gateway operations (read and write) to BRAIN.
+ * By default, NO brain capture (too noisy). Enable via:
+ *   - Config: brain.captureMcp = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_MCP=true  (overrides config)
  * Auto-registers on module load.
  */
 
@@ -17,23 +19,39 @@ function isMissingBrainSchemaError(err: unknown): boolean {
 }
 
 /**
- * Check if brain capture is enabled for MCP events.
- * Defaults to false (too noisy for normal operation).
+ * Check whether MCP-level brain capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_MCP env var (explicit override)
+ *   2. brain.captureMcp project config value
+ *
+ * Defaults to false when neither is set (too noisy for normal operation).
  */
-function isBrainCaptureEnabled(): boolean {
-  return process.env['CLEO_BRAIN_CAPTURE_MCP'] === 'true';
+async function isBrainCaptureEnabled(projectRoot: string): Promise<boolean> {
+  const envOverride = process.env['CLEO_BRAIN_CAPTURE_MCP'];
+  if (envOverride !== undefined) {
+    return envOverride === 'true';
+  }
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.captureMcp ?? false;
+  } catch {
+    return false;
+  }
 }
 
 /**
- * Handle onPromptSubmit - optionally capture prompt events to BRAIN
+ * Handle onPromptSubmit - optionally capture ALL gateway prompt events to BRAIN.
  *
- * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
+ * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handlePromptSubmit(
   projectRoot: string,
   payload: OnPromptSubmitPayload,
 ): Promise<void> {
-  if (!isBrainCaptureEnabled()) return;
+  if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 
@@ -50,15 +68,16 @@ export async function handlePromptSubmit(
 }
 
 /**
- * Handle onResponseComplete - optionally capture response events to BRAIN
+ * Handle onResponseComplete - optionally capture ALL gateway response events to BRAIN.
  *
- * No-op by default. Set CLEO_BRAIN_CAPTURE_MCP=true to enable.
+ * No-op by default. Enable via brain.captureMcp config or CLEO_BRAIN_CAPTURE_MCP env.
+ * For selective mutation-only capture, use work-capture-hooks.ts instead.
  */
 export async function handleResponseComplete(
   projectRoot: string,
   payload: OnResponseCompletePayload,
 ): Promise<void> {
-  if (!isBrainCaptureEnabled()) return;
+  if (!(await isBrainCaptureEnabled(projectRoot))) return;
 
   const { observeBrain } = await import('../../memory/brain-retrieval.js');
 

package/src/hooks/handlers/memory-bridge-refresh.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared memory bridge refresh helper for hook handlers.
+ *
+ * Provides a config-gated, debounced wrapper around refreshMemoryBridge().
+ * Prevents rapid regeneration of .cleo/memory-bridge.md when multiple
+ * lifecycle events fire in quick succession (e.g. session end + task complete).
+ *
+ * Debounce: max one refresh per 30 seconds across all callers in the process.
+ *
+ * @task T138
+ * @epic T134
+ */
+
+/** Debounce window in milliseconds. */
+const DEBOUNCE_MS = 30_000;
+
+/** Timestamp of the last successful refresh call (module-level singleton). */
+let lastRefreshTime = 0;
+
+/**
+ * Refresh the memory bridge if autoRefresh is enabled and the debounce window
+ * has elapsed. Reads config via loadConfig() (cascaded). Never throws.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ */
+export async function maybeRefreshMemoryBridge(projectRoot: string): Promise<void> {
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+
+    if (!config.brain?.memoryBridge?.autoRefresh) {
+      return;
+    }
+
+    const now = Date.now();
+    if (now - lastRefreshTime < DEBOUNCE_MS) {
+      return;
+    }
+
+    lastRefreshTime = now;
+
+    const { refreshMemoryBridge } = await import('../../memory/memory-bridge.js');
+    await refreshMemoryBridge(projectRoot);
+  } catch {
+    // Best-effort: never block lifecycle events
+  }
+}

package/src/hooks/handlers/session-hooks.ts

@@ -3,10 +3,15 @@
  *
  * Handlers that capture session lifecycle events to BRAIN via memory.observe.
  * Auto-registers on module load.
+ *
+ * T138: Triggers memory bridge refresh on session start and end.
+ * T139: Regenerates bridge with session scope on start.
+ * T144: Extracts transcript observations on session end.
  */
 
 import { hooks } from '../registry.js';
 import type { OnSessionEndPayload, OnSessionStartPayload } from '../types.js';
+import { maybeRefreshMemoryBridge } from './memory-bridge-refresh.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -16,6 +21,9 @@ function isMissingBrainSchemaError(err: unknown): boolean {
 
 /**
  * Handle onSessionStart - capture initial session context
+ *
+ * T138: Refresh memory bridge on session start.
+ * T139: Regenerate bridge with session scope context.
  */
 export async function handleSessionStart(
   projectRoot: string,
@@ -34,10 +42,16 @@ export async function handleSessionStart(
   } catch (err) {
     if (!isMissingBrainSchemaError(err)) throw err;
   }
+
+  // T138/T139: Refresh memory bridge after session starts (best-effort)
+  await maybeRefreshMemoryBridge(projectRoot);
 }
 
 /**
  * Handle onSessionEnd - capture session summary
+ *
+ * T138: Refresh memory bridge after session ends.
+ * T144: Extract transcript observations via cross-provider adapter.
  */
 export async function handleSessionEnd(
   projectRoot: string,
@@ -64,6 +78,30 @@ export async function handleSessionEnd(
   } catch {
     // Grading must never block session end
   }
+
+  // T144: Cross-provider transcript extraction (best-effort)
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    if (config.brain?.autoCapture) {
+      const { AdapterManager } = await import('../../adapters/index.js');
+      const manager = AdapterManager.getInstance(projectRoot);
+      const activeAdapter = manager.getActive();
+      const hookProvider = activeAdapter?.hooks;
+      if (hookProvider && typeof hookProvider.getTranscript === 'function') {
+        const transcript = await hookProvider.getTranscript(payload.sessionId, projectRoot);
+        if (transcript) {
+          const { extractFromTranscript } = await import('../../memory/auto-extract.js');
+          await extractFromTranscript(projectRoot, payload.sessionId, transcript);
+        }
+      }
+    }
+  } catch {
+    // Graceful no-op: transcript extraction must never block session end
+  }
+
+  // T138: Refresh memory bridge after session ends (best-effort)
+  await maybeRefreshMemoryBridge(projectRoot);
 }
 
 // Register handlers on module load

package/src/hooks/handlers/task-hooks.ts

@@ -3,10 +3,13 @@
  *
  * Handlers that capture task lifecycle events to BRAIN via memory.observe.
  * Auto-registers on module load.
+ *
+ * T138: Triggers memory bridge refresh after task completion.
  */
 
 import { hooks } from '../registry.js';
 import type { OnToolCompletePayload, OnToolStartPayload } from '../types.js';
+import { maybeRefreshMemoryBridge } from './memory-bridge-refresh.js';
 
 function isMissingBrainSchemaError(err: unknown): boolean {
   if (!(err instanceof Error)) return false;
@@ -37,6 +40,8 @@ export async function handleToolStart(
 
 /**
  * Handle onToolComplete (maps to task.complete in CLEO)
+ *
+ * T138: Refresh memory bridge after task completion.
  */
 export async function handleToolComplete(
   projectRoot: string,
@@ -54,6 +59,9 @@ export async function handleToolComplete(
   } catch (err) {
     if (!isMissingBrainSchemaError(err)) throw err;
   }
+
+  // T138: Refresh memory bridge after task completes (best-effort)
+  await maybeRefreshMemoryBridge(projectRoot);
 }
 
 // Register handlers

package/src/hooks/handlers/work-capture-hooks.ts

@@ -0,0 +1,184 @@
+/**
+ * Active-Work Capture Hook Handlers
+ *
+ * Captures dispatch mutation events to BRAIN during active work, closing
+ * the gap between lifecycle-only capture (session end, task complete) and
+ * continuous capture. Only WRITE operations that represent meaningful work
+ * are captured — reads and operations already handled by lifecycle hooks
+ * are skipped to avoid flooding brain.db.
+ *
+ * Disabled by default. Enable via:
+ *   - Config: brain.captureWork = true  (checked first)
+ *   - Env:    CLEO_BRAIN_CAPTURE_WORK=true  (overrides config)
+ *
+ * Auto-registers on module load.
+ *
+ * @task T142
+ */
+
+import { hooks } from '../registry.js';
+import type { OnPromptSubmitPayload, OnResponseCompletePayload } from '../types.js';
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function isMissingBrainSchemaError(err: unknown): boolean {
+  if (!(err instanceof Error)) return false;
+  const message = String(err.message || '').toLowerCase();
+  return message.includes('no such table') && message.includes('brain_');
+}
+
+/**
+ * Check whether active-work capture is enabled.
+ *
+ * Resolution order (first truthy wins):
+ *   1. CLEO_BRAIN_CAPTURE_WORK env var (explicit override)
+ *   2. brain.captureWork project config value
+ *
+ * Defaults to false when neither is set.
+ */
+async function isWorkCaptureEnabled(projectRoot: string): Promise<boolean> {
+  const envOverride = process.env['CLEO_BRAIN_CAPTURE_WORK'];
+  if (envOverride !== undefined) {
+    return envOverride === 'true';
+  }
+  try {
+    const { loadConfig } = await import('../../config.js');
+    const config = await loadConfig(projectRoot);
+    return config.brain?.captureWork ?? false;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Smart-filter: which mutations to capture
+// ---------------------------------------------------------------------------
+
+/**
+ * Mutations that represent novel work not already captured by lifecycle hooks.
+ *
+ * Excluded (already captured elsewhere):
+ *   - tasks.complete  → task-hooks.ts (onToolComplete)
+ *   - session.start   → session-hooks.ts (onSessionStart)
+ *   - session.end     → session-hooks.ts (onSessionEnd)
+ *   - memory.brain.observe → observeBrain itself writes to brain; self-loop
+ *
+ * All query gateway operations are excluded by the gateway check before
+ * this set is consulted.
+ */
+const CAPTURE_OPERATIONS = new Set<string>([
+  'tasks.add',
+  'tasks.update',
+  'tasks.move',
+  'tasks.link',
+  'tasks.unlink',
+  'tasks.label',
+  'tasks.unlabel',
+  'tasks.note',
+]);
+
+/**
+ * Determine whether a mutate operation should be captured.
+ *
+ * Only `mutate` gateway operations in CAPTURE_OPERATIONS are captured.
+ * All `query` gateway calls are skipped (reads produce no novel work).
+ *
+ * @param gateway - 'query' or 'mutate'
+ * @param domain  - e.g. 'tasks'
+ * @param operation - e.g. 'add'
+ */
+function shouldCapture(gateway: string, domain: string, operation: string): boolean {
+  if (gateway !== 'mutate') return false;
+  const key = `${domain}.${operation}`;
+  return CAPTURE_OPERATIONS.has(key);
+}
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle onPromptSubmit — log incoming mutation intents to BRAIN.
+ *
+ * Only fires for mutate operations in CAPTURE_OPERATIONS.
+ * Gated behind brain.captureWork config (or CLEO_BRAIN_CAPTURE_WORK env).
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param payload     - onPromptSubmit event payload
+ */
+export async function handleWorkPromptSubmit(
+  projectRoot: string,
+  payload: OnPromptSubmitPayload,
+): Promise<void> {
+  if (!shouldCapture(payload.gateway, payload.domain, payload.operation)) return;
+  if (!(await isWorkCaptureEnabled(projectRoot))) return;
+
+  const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+  try {
+    await observeBrain(projectRoot, {
+      text: `Dispatch intent: ${payload.gateway}:${payload.domain}.${payload.operation}${payload.source ? ` (from ${payload.source})` : ''}`,
+      title: `Work intent: ${payload.domain}.${payload.operation}`,
+      type: 'discovery',
+      sourceType: 'agent',
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError(err)) throw err;
+  }
+}
+
+/**
+ * Handle onResponseComplete — capture completed mutations to BRAIN.
+ *
+ * Only fires for successful mutate operations in CAPTURE_OPERATIONS.
+ * Failures are skipped — the intent was already captured by handleWorkPromptSubmit.
+ * Gated behind brain.captureWork config (or CLEO_BRAIN_CAPTURE_WORK env).
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param payload     - onResponseComplete event payload
+ */
+export async function handleWorkResponseComplete(
+  projectRoot: string,
+  payload: OnResponseCompletePayload,
+): Promise<void> {
+  if (!shouldCapture(payload.gateway, payload.domain, payload.operation)) return;
+  // Only capture successful completions — failures are noise
+  if (!payload.success) return;
+  if (!(await isWorkCaptureEnabled(projectRoot))) return;
+
+  const { observeBrain } = await import('../../memory/brain-retrieval.js');
+
+  try {
+    const durationNote = payload.durationMs != null ? ` (${payload.durationMs}ms)` : '';
+    await observeBrain(projectRoot, {
+      text: `Dispatch complete: ${payload.gateway}:${payload.domain}.${payload.operation}${durationNote}`,
+      title: `Work done: ${payload.domain}.${payload.operation}`,
+      type: 'change',
+      sourceType: 'agent',
+    });
+  } catch (err) {
+    if (!isMissingBrainSchemaError(err)) throw err;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Auto-registration
+// ---------------------------------------------------------------------------
+
+// Register at lower priority (90) than lifecycle hooks (100) so lifecycle
+// handlers always run first.
+hooks.register({
+  id: 'work-capture-prompt-submit',
+  event: 'onPromptSubmit',
+  handler: handleWorkPromptSubmit,
+  priority: 90,
+});
+
+hooks.register({
+  id: 'work-capture-response-complete',
+  event: 'onResponseComplete',
+  handler: handleWorkResponseComplete,
+  priority: 90,
+});

package/src/index.ts

@@ -268,10 +268,15 @@ export type {
 export { Cleo } from './cleo.js';
 // Hooks
 export { HookRegistry, hooks } from './hooks/registry.js';
+export type {
+  PopulateEmbeddingsOptions,
+  PopulateEmbeddingsResult,
+} from './memory/brain-retrieval.js';
 // Memory
 export {
   fetchBrainEntries,
   observeBrain,
+  populateEmbeddings,
   searchBrainCompact,
   timelineBrain,
 } from './memory/brain-retrieval.js';

package/src/internal.ts

@@ -135,6 +135,23 @@ export { instantiateTessera, showTessera } from './lifecycle/tessera-engine.js';
 
 // MCP helpers
 export { detectEnvMode, generateMcpServerEntry, getMcpServerName } from './mcp/index.js';
+// Memory — brain lifecycle (temporal decay + consolidation)
+export type { ConsolidationResult, DecayResult } from './memory/brain-lifecycle.js';
+export { applyTemporalDecay, consolidateMemories } from './memory/brain-lifecycle.js';
+// Memory — brain maintenance
+export type {
+  BrainMaintenanceConsolidationResult,
+  BrainMaintenanceDecayResult,
+  BrainMaintenanceEmbeddingsResult,
+  BrainMaintenanceOptions,
+  BrainMaintenanceResult,
+} from './memory/brain-maintenance.js';
+export { runBrainMaintenance } from './memory/brain-maintenance.js';
+export type {
+  PopulateEmbeddingsOptions,
+  PopulateEmbeddingsResult,
+} from './memory/brain-retrieval.js';
+export { populateEmbeddings } from './memory/brain-retrieval.js';
 export { migrateClaudeMem } from './memory/claude-mem-migration.js';
 // Memory — engine-compat
 export {
@@ -686,6 +703,10 @@ export type { BuildConfig } from './config/build-config.js';
 export { BUILD_CONFIG } from './config/build-config.js';
 // Init (additional)
 export { initCoreSkills } from './init.js';
+// Memory — auto-extract (additional)
+export { extractFromTranscript } from './memory/auto-extract.js';
+// Memory — brain embedding (additional)
+export { initDefaultProvider } from './memory/brain-embedding.js';
 // Memory — brain row types
 export type {
   BrainAnchor,
@@ -699,9 +720,14 @@ export type {
   BrainTimelineNeighborRow,
 } from './memory/brain-row-types.js';
 // Memory (additional)
-export { writeMemoryBridge } from './memory/memory-bridge.js';
+export { generateContextAwareContent, writeMemoryBridge } from './memory/memory-bridge.js';
 export type { SessionMemoryContext } from './memory/session-memory.js';
-export { getSessionMemoryContext, persistSessionMemory } from './memory/session-memory.js';
+export {
+  buildSummarizationPrompt,
+  getSessionMemoryContext,
+  ingestStructuredSummary,
+  persistSessionMemory,
+} from './memory/session-memory.js';
 // Nexus — discoverRelated (exported as nexusDiscoverRelated to avoid name clash with tasks discoverRelated)
 // Nexus — searchAcrossProjects
 export {