@cleocode/core 2026.4.30 → 2026.4.35

package/src/memory/brain-search.ts

@@ -20,6 +20,7 @@ import { typedAll } from '../store/typed-query.js';
 import type { BrainSearchHit } from './brain-row-types.js';
 import type { SimilarityResult } from './brain-similarity.js';
 import { searchSimilar } from './brain-similarity.js';
+import { QUALITY_SCORE_THRESHOLD } from './quality-scoring.js';
 
 /** Search result with BM25 rank. */
 export interface BrainSearchResult {
@@ -281,7 +282,7 @@ export async function searchBrain(
   query: string,
   options?: BrainSearchOptions,
 ): Promise<BrainSearchResult> {
-  if (!query || !query.trim()) {
+  if (!query?.trim()) {
     return { decisions: [], patterns: [], learnings: [], observations: [] };
   }
 
@@ -339,10 +340,12 @@ function searchWithFts5(
         FROM brain_decisions_fts fts
         JOIN brain_decisions d ON d.rowid = fts.rowid
         WHERE brain_decisions_fts MATCH ?
+          AND (d.quality_score IS NULL OR d.quality_score >= ?)
         ORDER BY bm25(brain_decisions_fts)
         LIMIT ?
       `),
         safeQuery,
+        QUALITY_SCORE_THRESHOLD,
         limit,
       );
       result.decisions = rows;
@@ -360,10 +363,12 @@ function searchWithFts5(
         FROM brain_patterns_fts fts
         JOIN brain_patterns p ON p.rowid = fts.rowid
         WHERE brain_patterns_fts MATCH ?
+          AND (p.quality_score IS NULL OR p.quality_score >= ?)
         ORDER BY bm25(brain_patterns_fts)
         LIMIT ?
       `),
         safeQuery,
+        QUALITY_SCORE_THRESHOLD,
         limit,
       );
       result.patterns = rows;
@@ -380,10 +385,12 @@ function searchWithFts5(
         FROM brain_learnings_fts fts
         JOIN brain_learnings l ON l.rowid = fts.rowid
         WHERE brain_learnings_fts MATCH ?
+          AND (l.quality_score IS NULL OR l.quality_score >= ?)
         ORDER BY bm25(brain_learnings_fts)
         LIMIT ?
       `),
         safeQuery,
+        QUALITY_SCORE_THRESHOLD,
         limit,
       );
       result.learnings = rows;
@@ -400,10 +407,12 @@ function searchWithFts5(
         FROM brain_observations_fts fts
         JOIN brain_observations o ON o.rowid = fts.rowid
         WHERE brain_observations_fts MATCH ?
+          AND (o.quality_score IS NULL OR o.quality_score >= ?)
         ORDER BY bm25(brain_observations_fts)
         LIMIT ?
       `),
         safeQuery,
+        QUALITY_SCORE_THRESHOLD,
         limit,
       );
       result.observations = rows;
@@ -459,12 +468,14 @@ function likeSearchDecisions(
   return typedAll<BrainDecisionRow>(
     nativeDb.prepare(`
     SELECT * FROM brain_decisions
-    WHERE decision LIKE ? OR rationale LIKE ?
+    WHERE (decision LIKE ? OR rationale LIKE ?)
+      AND (quality_score IS NULL OR quality_score >= ?)
     ORDER BY created_at DESC
     LIMIT ?
   `),
     likePattern,
     likePattern,
+    QUALITY_SCORE_THRESHOLD,
     limit,
   );
 }
@@ -478,12 +489,14 @@ function likeSearchPatterns(
   return typedAll<BrainPatternRow>(
     nativeDb.prepare(`
     SELECT * FROM brain_patterns
-    WHERE pattern LIKE ? OR context LIKE ?
+    WHERE (pattern LIKE ? OR context LIKE ?)
+      AND (quality_score IS NULL OR quality_score >= ?)
     ORDER BY frequency DESC
     LIMIT ?
   `),
     likePattern,
     likePattern,
+    QUALITY_SCORE_THRESHOLD,
     limit,
   );
 }
@@ -497,12 +510,14 @@ function likeSearchLearnings(
   return typedAll<BrainLearningRow>(
     nativeDb.prepare(`
     SELECT * FROM brain_learnings
-    WHERE insight LIKE ? OR source LIKE ?
+    WHERE (insight LIKE ? OR source LIKE ?)
+      AND (quality_score IS NULL OR quality_score >= ?)
     ORDER BY confidence DESC
     LIMIT ?
   `),
     likePattern,
     likePattern,
+    QUALITY_SCORE_THRESHOLD,
     limit,
   );
 }
@@ -516,25 +531,61 @@ function likeSearchObservations(
   return typedAll<BrainObservationRow>(
     nativeDb.prepare(`
     SELECT * FROM brain_observations
-    WHERE title LIKE ? OR narrative LIKE ?
+    WHERE (title LIKE ? OR narrative LIKE ?)
+      AND (quality_score IS NULL OR quality_score >= ?)
     ORDER BY created_at DESC
     LIMIT ?
   `),
     likePattern,
     likePattern,
+    QUALITY_SCORE_THRESHOLD,
     limit,
   );
 }
 
 /**
  * Escape special FTS5 characters in query string.
- * Wraps each token in quotes to prevent syntax errors from special chars.
+ *
+ * Wraps each meaningful token in double quotes and joins with OR so that
+ * partial matches are returned even when some tokens are not indexable
+ * (e.g. task prefixes like "EPIC:", em-dashes "—", or short stop-words).
+ *
+ * Strategy:
+ *   1. Split on whitespace.
+ *   2. Keep only tokens that contain at least one word character (\w), which
+ *      ensures punctuation-only tokens (em dashes, colons standalone, etc.)
+ *      are dropped before they zero-out the entire result set.
+ *   3. Deduplicate case-insensitively.
+ *   4. Join with OR so the query broadens rather than requiring ALL tokens.
+ *
+ * Using AND (implicit FTS5 join) caused empty results whenever a task title
+ * contained non-word tokens such as em dashes ("—") or trailing colons
+ * ("EPIC:"), because FTS5's default tokenizer cannot index them and the
+ * AND semantics then guaranteed zero matches for the whole query. (T553 bug fix)
  */
 function escapeFts5Query(query: string): string {
-  // Split on whitespace, wrap each token in double quotes
-  const tokens = query.trim().split(/\s+/).filter(Boolean);
+  const rawTokens = query.trim().split(/\s+/).filter(Boolean);
+  if (rawTokens.length === 0) return '""';
+
+  // Keep tokens that have at least one alphanumeric character and are not
+  // pure stop-words (length ≥ 2 after stripping leading/trailing punctuation).
+  const seen = new Set<string>();
+  const tokens: string[] = [];
+  for (const t of rawTokens) {
+    // Strip leading/trailing non-word characters (e.g. "EPIC:" → "EPIC", "—" → "")
+    const stripped = t.replace(/^\W+|\W+$/g, '');
+    if (stripped.length < 2) continue; // skip very short or empty tokens
+    if (!/\w/.test(stripped)) continue; // skip tokens with no word chars
+    const lower = stripped.toLowerCase();
+    if (seen.has(lower)) continue; // deduplicate
+    seen.add(lower);
+    tokens.push(`"${stripped.replace(/"/g, '""')}"`);
+  }
+
   if (tokens.length === 0) return '""';
-  return tokens.map((t) => `"${t.replace(/"/g, '""')}"`).join(' ');
+
+  // OR semantics: any matching token returns the row, ranked by BM25 relevance.
+  return tokens.join(' OR ');
 }
 
 /**
@@ -591,7 +642,7 @@ export async function hybridSearch(
   projectRoot: string,
   options?: HybridSearchOptions,
 ): Promise<HybridResult[]> {
-  if (!query || !query.trim()) return [];
+  if (!query?.trim()) return [];
 
   const maxResults = options?.limit ?? 10;
   let ftsWeight = options?.ftsWeight ?? 0.5;

package/src/memory/decisions.ts

@@ -13,6 +13,8 @@ import { getBrainAccessor } from '../store/brain-accessor.js';
 import type { BrainDecisionRow, NewBrainDecisionRow } from '../store/brain-schema.js';
 import { taskExistsInTasksDb } from '../store/cross-db-cleanup.js';
 import { getDb } from '../store/sqlite.js';
+import { addGraphEdge, upsertGraphNode } from './graph-auto-populate.js';
+import { computeDecisionQuality } from './quality-scoring.js';
 
 /** Parameters for storing a new decision. */
 export interface StoreDecisionParams {
@@ -79,10 +81,10 @@ export async function storeDecision(
   projectRoot: string,
   params: StoreDecisionParams,
 ): Promise<BrainDecisionRow> {
-  if (!params.decision || !params.decision.trim()) {
+  if (!params.decision?.trim()) {
     throw new Error('Decision text is required');
   }
-  if (!params.rationale || !params.rationale.trim()) {
+  if (!params.rationale?.trim()) {
     throw new Error('Rationale is required');
   }
 
@@ -107,6 +109,25 @@ export async function storeDecision(
       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!;
   }
 
@@ -126,6 +147,28 @@ export async function storeDecision(
     }
   }
 
+  // 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' as const;
+  const memoryType = 'semantic' as const;
+  const sourceConfidence = 'owner' as const;
+  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: NewBrainDecisionRow = {
     id,
     type: params.type,
@@ -137,9 +180,59 @@ export async function storeDecision(
     contextEpicId: validEpicId,
     contextTaskId: validTaskId,
     contextPhase: params.contextPhase,
+    qualityScore,
+    // T549 Wave 1-A: tier/type/confidence assigned at write time
+    memoryTier,
+    memoryType,
+    sourceConfidence,
+    verified,
   };
 
-  return accessor.addDecision(row);
+  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',
+      );
+    }
+  } catch {
+    /* Graph population is best-effort — never block the primary return */
+  }
+
+  return saved;
 }
 
 /**

package/src/memory/engine-compat.ts

@@ -28,6 +28,8 @@ import {
   searchBrainCompact,
   timelineBrain,
 } from './brain-retrieval.js';
+// T545: Decision store with quality scoring and graph auto-population
+import { storeDecision } from './decisions.js';
 import {
   learningStats,
   type SearchLearningParams,
@@ -349,22 +351,18 @@ export async function memoryDecisionStore(
 
   try {
     const root = resolveRoot(projectRoot);
-    const accessor = await getBrainAccessor(root);
-    const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
-    const id = `D-${Date.now().toString(36)}`;
-
-    const row = await accessor.addDecision({
-      id,
+    // Route through storeDecision() so quality scoring and graph auto-population
+    // (upsertGraphNode) run on every insert — fixes T545 regression where
+    // engine-compat bypassed decisions.ts and wrote directly to the accessor,
+    // leaving quality_score NULL and no graph node created.
+    const row = await storeDecision(root, {
       type: 'technical',
       decision: params.decision,
       rationale: params.rationale,
       confidence: 'medium',
       outcome: 'pending',
-      alternativesJson: params.alternatives ? JSON.stringify(params.alternatives) : null,
-      contextTaskId: params.taskId ?? null,
-      contextEpicId: null,
-      contextPhase: null,
-      createdAt: now,
+      alternatives: params.alternatives,
+      contextTaskId: params.taskId,
     });
 
     return {
@@ -1603,6 +1601,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.
  *