@cleocode/core 2026.3.69 → 2026.3.71

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 {