@cleocode/core 2026.4.29 → 2026.4.31

package/src/memory/engine-compat.ts

@@ -1603,6 +1603,174 @@ export async function memorySearchHybrid(
   }
 }
 
+// ============================================================================
+// Brain Graph Traversal Operations (T535)
+// ============================================================================
+
+/**
+ * BFS traversal of the brain knowledge graph from a seed node.
+ *
+ * @param params - Traversal parameters: nodeId and optional maxDepth (default 3)
+ * @param projectRoot - Optional project root path; defaults to resolved root
+ * @returns EngineResult with traversal nodes annotated with depth
+ *
+ * @remarks
+ * Uses a recursive CTE against brain_page_nodes / brain_page_edges.
+ * Follows edges bidirectionally. Returns the seed node at depth 0.
+ *
+ * @example
+ * ```typescript
+ * const result = await memoryGraphTrace({ nodeId: 'decision:D-abc123', maxDepth: 2 }, '/project');
+ * ```
+ */
+export async function memoryGraphTrace(
+  params: { nodeId: string; maxDepth?: number },
+  projectRoot?: string,
+): Promise<EngineResult> {
+  if (!params.nodeId) {
+    return { success: false, error: { code: 'E_INVALID_INPUT', message: 'nodeId is required' } };
+  }
+
+  try {
+    const root = resolveRoot(projectRoot);
+    const { traceBrainGraph } = await import('./graph-queries.js');
+    const nodes = await traceBrainGraph(root, params.nodeId, params.maxDepth ?? 3);
+
+    if (nodes.length === 0) {
+      return {
+        success: false,
+        error: { code: 'E_NOT_FOUND', message: `Node '${params.nodeId}' not found in brain graph` },
+      };
+    }
+
+    return { success: true, data: { nodes, total: nodes.length, seed: params.nodeId } };
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        code: 'E_GRAPH_TRACE',
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+/**
+ * Return the immediate (1-hop) neighbours of a brain graph node.
+ *
+ * @param params - Parameters: nodeId, optional edgeType filter
+ * @param projectRoot - Optional project root path; defaults to resolved root
+ * @returns EngineResult with neighbour nodes and edge metadata
+ *
+ * @remarks
+ * Follows edges in both directions. Results include direction ('in'/'out'),
+ * edge type, and weight.
+ *
+ * @example
+ * ```typescript
+ * const result = await memoryGraphRelated({ nodeId: 'decision:D-abc123', edgeType: 'applies_to' }, '/project');
+ * ```
+ */
+export async function memoryGraphRelated(
+  params: { nodeId: string; edgeType?: string },
+  projectRoot?: string,
+): Promise<EngineResult> {
+  if (!params.nodeId) {
+    return { success: false, error: { code: 'E_INVALID_INPUT', message: 'nodeId is required' } };
+  }
+
+  try {
+    const root = resolveRoot(projectRoot);
+    const { relatedBrainNodes } = await import('./graph-queries.js');
+    const related = await relatedBrainNodes(root, params.nodeId, params.edgeType);
+    return { success: true, data: { related, total: related.length, seed: params.nodeId } };
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        code: 'E_GRAPH_RELATED',
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+/**
+ * Return a 360-degree context view of a single brain graph node.
+ *
+ * @param params - Parameters: nodeId
+ * @param projectRoot - Optional project root path; defaults to resolved root
+ * @returns EngineResult with the node, all edges, and neighbouring nodes
+ *
+ * @remarks
+ * Includes the node itself, in-edges, out-edges, and all immediately
+ * reachable neighbour nodes with their edge relationships.
+ *
+ * @example
+ * ```typescript
+ * const result = await memoryGraphContext({ nodeId: 'decision:D-abc123' }, '/project');
+ * ```
+ */
+export async function memoryGraphContext(
+  params: { nodeId: string },
+  projectRoot?: string,
+): Promise<EngineResult> {
+  if (!params.nodeId) {
+    return { success: false, error: { code: 'E_INVALID_INPUT', message: 'nodeId is required' } };
+  }
+
+  try {
+    const root = resolveRoot(projectRoot);
+    const { contextBrainNode } = await import('./graph-queries.js');
+    const context = await contextBrainNode(root, params.nodeId);
+
+    if (!context) {
+      return {
+        success: false,
+        error: { code: 'E_NOT_FOUND', message: `Node '${params.nodeId}' not found in brain graph` },
+      };
+    }
+
+    return { success: true, data: context };
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        code: 'E_GRAPH_CONTEXT',
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
+/**
+ * Return aggregate statistics for the brain knowledge graph.
+ *
+ * @param projectRoot - Optional project root path; defaults to resolved root
+ * @returns EngineResult with node counts by type, edge counts by type, and totals
+ *
+ * @example
+ * ```typescript
+ * const result = await memoryGraphStatsFull('/project');
+ * ```
+ */
+export async function memoryGraphStatsFull(projectRoot?: string): Promise<EngineResult> {
+  try {
+    const root = resolveRoot(projectRoot);
+    const { graphStats } = await import('./graph-queries.js');
+    const stats = await graphStats(root);
+    return { success: true, data: stats };
+  } catch (error) {
+    return {
+      success: false,
+      error: {
+        code: 'E_GRAPH_STATS',
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+}
+
 /**
  * Remove a node or edge from the PageIndex graph.
  *

package/src/memory/graph-auto-populate.ts

@@ -0,0 +1,173 @@
+/**
+ * Graph auto-population helpers for CLEO BRAIN.
+ *
+ * Provides upsertGraphNode and addGraphEdge helpers that write to the
+ * brain_page_nodes and brain_page_edges tables whenever memory entries
+ * are created via the legitimate write paths (storeDecision, observeBrain,
+ * storePattern, storeLearning, and task completion).
+ *
+ * Design constraints:
+ * - All writes are BEST-EFFORT — never block or fail the primary operation.
+ * - All writes are gated on brain.autoCapture via isAutoCaptureEnabled.
+ * - Uses INSERT OR REPLACE (onConflictDoUpdate) for upsert semantics.
+ * - Edge inserts are idempotent via the composite PK (fromId, toId, edgeType).
+ *
+ * @task T537
+ * @epic T523
+ */
+
+import { createHash } from 'node:crypto';
+import type { BrainEdgeType, BrainNodeType } from '../store/brain-schema.js';
+import { brainPageEdges, brainPageNodes } from '../store/brain-schema.js';
+import { getBrainDb } from '../store/brain-sqlite.js';
+
+// Re-export types so callers can import them from this module without
+// reaching into brain-schema directly.
+export type { BrainEdgeType, BrainNodeType };
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Return true when brain.autoCapture is enabled for the project.
+ * Delegates to the shared isAutoCaptureEnabled helper in handler-helpers.ts.
+ * Returns false on any error to keep graph writes safely disabled when the
+ * config or brain.db is unavailable.
+ */
+async function shouldAutoPopulateGraph(projectRoot: string): Promise<boolean> {
+  try {
+    const { isAutoCaptureEnabled } = await import('../hooks/handlers/handler-helpers.js');
+    return isAutoCaptureEnabled(projectRoot);
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Upsert a graph node for a typed table entry.
+ *
+ * Uses INSERT OR REPLACE to handle both new and existing entries. If the
+ * node already exists (same id), its label, qualityScore, lastActivityAt,
+ * updatedAt, and metadataJson are refreshed while createdAt is preserved.
+ *
+ * The contentHash is derived from a SHA-256 prefix of the canonical content.
+ * External-reference nodes (task, session, epic) may pass an empty string for
+ * content; their hash will be null so duplicates are not rejected.
+ *
+ * This function is gated on brain.autoCapture. If the gate is disabled or any
+ * error occurs, it returns silently without throwing.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param nodeId - Stable composite ID in the form '<type>:<source-id>'.
+ * @param nodeType - Discriminated type from BRAIN_NODE_TYPES.
+ * @param label - Human-readable label (title, task ID, etc.).
+ * @param qualityScore - 0.0 (noise) to 1.0 (canonical).
+ * @param content - Canonical text used to derive the content hash.
+ * @param metadata - Optional type-specific metadata blob.
+ *
+ * @task T537
+ */
+export async function upsertGraphNode(
+  projectRoot: string,
+  nodeId: string,
+  nodeType: BrainNodeType,
+  label: string,
+  qualityScore: number,
+  content: string,
+  metadata?: Record<string, unknown>,
+): Promise<void> {
+  try {
+    if (!(await shouldAutoPopulateGraph(projectRoot))) return;
+
+    const db = await getBrainDb(projectRoot);
+    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+    // Only compute a content hash for non-trivial content (external reference
+    // nodes like task/session/epic may have empty content).
+    const trimmed = content.trim().toLowerCase();
+    const contentHash = trimmed
+      ? createHash('sha256').update(trimmed).digest('hex').substring(0, 16)
+      : null;
+
+    await db
+      .insert(brainPageNodes)
+      .values({
+        id: nodeId,
+        nodeType,
+        label: label.substring(0, 200),
+        qualityScore,
+        contentHash,
+        metadataJson: metadata ? JSON.stringify(metadata) : null,
+        lastActivityAt: now,
+        createdAt: now,
+        updatedAt: now,
+      })
+      .onConflictDoUpdate({
+        target: brainPageNodes.id,
+        set: {
+          label: label.substring(0, 200),
+          qualityScore,
+          lastActivityAt: now,
+          updatedAt: now,
+          metadataJson: metadata ? JSON.stringify(metadata) : null,
+        },
+      });
+  } catch (err) {
+    // Log but never surface — this is a best-effort side effect.
+    console.warn('[brain-graph] upsertGraphNode failed:', err);
+  }
+}
+
+/**
+ * Add a directed, typed edge between two graph nodes (idempotent).
+ *
+ * The composite primary key (fromId, toId, edgeType) prevents duplicate edges
+ * of the same type. Conflicting rows are ignored so this is safe to call
+ * multiple times with the same arguments.
+ *
+ * This function is gated on brain.autoCapture. If the gate is disabled or any
+ * error occurs, it returns silently without throwing.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param fromId - Source node ID (brain_page_nodes.id).
+ * @param toId - Target node ID (brain_page_nodes.id or external nexus ID).
+ * @param edgeType - Typed relationship from BRAIN_EDGE_TYPES.
+ * @param weight - Edge confidence/weight (0.0–1.0). Defaults to 1.0.
+ * @param provenance - Human-readable note on why this edge was emitted.
+ *
+ * @task T537
+ */
+export async function addGraphEdge(
+  projectRoot: string,
+  fromId: string,
+  toId: string,
+  edgeType: BrainEdgeType,
+  weight = 1.0,
+  provenance?: string,
+): Promise<void> {
+  try {
+    if (!(await shouldAutoPopulateGraph(projectRoot))) return;
+
+    const db = await getBrainDb(projectRoot);
+    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+
+    await db
+      .insert(brainPageEdges)
+      .values({
+        fromId,
+        toId,
+        edgeType,
+        weight,
+        provenance: provenance ?? null,
+        createdAt: now,
+      })
+      .onConflictDoNothing();
+  } catch (err) {
+    console.warn('[brain-graph] addGraphEdge failed:', err);
+  }
+}