@cleocode/core 2026.4.29 → 2026.4.31

package/src/memory/brain-purge.ts

@@ -0,0 +1,315 @@
+/**
+ * Brain.db noise purge utility — removes 2927 noise entries leaving ~57 signal entries.
+ *
+ * Purge rules:
+ * - Patterns: keep newest per unique pattern text (dedup), delete duplicates
+ * - Learnings: delete ALL (all are auto-generated task completion noise)
+ * - Decisions: delete ALL except D-mntpeeer (the one real architectural decision)
+ * - Observations: delete task-start/task-complete/session-note/test/junk noise
+ *
+ * Safety: requires backup to exist before calling. Never touches tasks.db.
+ *
+ * @task T524
+ * @epic T523
+ */
+
+import { inArray, ne, sql } from 'drizzle-orm';
+import {
+  brainDecisions,
+  brainLearnings,
+  brainObservations,
+  brainPatterns,
+} from '../store/brain-schema.js';
+import { getBrainDb, getBrainNativeDb } from '../store/brain-sqlite.js';
+import { ensureFts5Tables, rebuildFts5Index } from './brain-search.js';
+
+/** Result counts from a purge run. */
+export interface PurgeResult {
+  /** Number of pattern rows deleted. */
+  patternsDeleted: number;
+  /** Number of learning rows deleted. */
+  learningsDeleted: number;
+  /** Number of decision rows deleted. */
+  decisionsDeleted: number;
+  /** Number of observation rows deleted. */
+  observationsDeleted: number;
+  /** Counts after purge. */
+  after: {
+    patterns: number;
+    learnings: number;
+    decisions: number;
+    observations: number;
+  };
+  /** FTS5 indexes rebuilt. */
+  fts5Rebuilt: boolean;
+}
+
+/**
+ * Count rows in a table using native DB PRAGMA (avoids Drizzle type issues).
+ * Falls back to 0 on error.
+ */
+function countRowsNative(tableName: string): number {
+  const nativeDb = getBrainNativeDb();
+  if (!nativeDb) return 0;
+  try {
+    const row = nativeDb.prepare(`SELECT COUNT(*) AS cnt FROM ${tableName}`).get() as
+      | { cnt: number }
+      | undefined;
+    return row?.cnt ?? 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Execute the brain.db noise purge.
+ *
+ * Deletes ~2927 noise entries across four tables, leaving ~57 signal entries.
+ * The one real architectural decision (D-mntpeeer) is explicitly preserved.
+ *
+ * Rules applied in order:
+ * 1. Patterns: deduplicate by pattern text — keep newest per unique text, delete older dupes
+ * 2. Learnings: delete all (100% noise — auto-generated "Completed:" and dependency notices)
+ * 3. Decisions: delete all except D-mntpeeer
+ * 4. Observations: delete task-start, task-complete, session-note, and test/junk entries
+ *
+ * @param projectRoot - Absolute path to the project root (e.g. /mnt/projects/cleocode)
+ * @returns PurgeResult with before/after counts and FTS5 status
+ */
+export async function purgeBrainNoise(projectRoot: string): Promise<PurgeResult> {
+  const db = await getBrainDb(projectRoot);
+
+  // =========================================================================
+  // Pre-purge counts
+  // =========================================================================
+
+  const beforePatterns = countRowsNative('brain_patterns');
+  const beforeLearnings = countRowsNative('brain_learnings');
+  const beforeDecisions = countRowsNative('brain_decisions');
+  const beforeObservations = countRowsNative('brain_observations');
+
+  console.log('Pre-purge counts:');
+  console.log(`  Patterns:     ${beforePatterns}`);
+  console.log(`  Learnings:    ${beforeLearnings}`);
+  console.log(`  Decisions:    ${beforeDecisions}`);
+  console.log(`  Observations: ${beforeObservations}`);
+
+  // =========================================================================
+  // SAFETY: Confirm D-mntpeeer exists before any destructive operation
+  // =========================================================================
+
+  const realDecision = await db.select().from(brainDecisions).where(sql`id = 'D-mntpeeer'`);
+
+  if (realDecision.length === 0) {
+    throw new Error(
+      'SAFETY ABORT: D-mntpeeer not found in brain_decisions. Backup and restore required.',
+    );
+  }
+
+  console.log('Safety check passed: D-mntpeeer confirmed present');
+
+  // =========================================================================
+  // Rule 1: Pattern deduplication
+  // Strategy: for each unique pattern text, find the MAX(extracted_at) row,
+  // delete all other rows with the same text.
+  // =========================================================================
+
+  // Get all patterns to find duplicates in TS (safer than raw SQL subquery)
+  const allPatterns = await db.select().from(brainPatterns);
+
+  // Group by normalized pattern text
+  const patternGroups = new Map<string, typeof allPatterns>();
+  for (const p of allPatterns) {
+    const key = p.pattern.trim().toLowerCase();
+    const group = patternGroups.get(key) ?? [];
+    group.push(p);
+    patternGroups.set(key, group);
+  }
+
+  // Collect IDs to delete: for each group with >1 entry, keep newest (max extractedAt), delete rest
+  const patternIdsToDelete: string[] = [];
+  for (const [, group] of patternGroups) {
+    if (group.length <= 1) continue;
+    // Sort by extractedAt desc, keep first, delete the rest
+    group.sort((a, b) => (b.extractedAt > a.extractedAt ? 1 : -1));
+    const toDelete = group.slice(1).map((p) => p.id);
+    patternIdsToDelete.push(...toDelete);
+  }
+
+  let patternsDeleted = 0;
+  if (patternIdsToDelete.length > 0) {
+    // Delete in batches of 500 to avoid SQLite parameter limits
+    const BATCH = 500;
+    for (let i = 0; i < patternIdsToDelete.length; i += BATCH) {
+      const batch = patternIdsToDelete.slice(i, i + BATCH);
+      await db.delete(brainPatterns).where(inArray(brainPatterns.id, batch));
+      patternsDeleted += batch.length;
+    }
+  }
+
+  console.log(`Patterns deleted (dedup): ${patternsDeleted}`);
+
+  // =========================================================================
+  // Rule 2: Delete ALL learnings (100% noise)
+  // All learnings are auto-generated "Completed: T..." or dependency notices
+  // =========================================================================
+
+  // Count before delete using run
+  const learningsRows = await db.select().from(brainLearnings);
+  const learningsDeleted = learningsRows.length;
+
+  if (learningsDeleted > 0) {
+    // Delete in batches using IDs
+    const ids = learningsRows.map((r) => r.id);
+    const BATCH = 500;
+    for (let i = 0; i < ids.length; i += BATCH) {
+      const batch = ids.slice(i, i + BATCH);
+      await db.delete(brainLearnings).where(inArray(brainLearnings.id, batch));
+    }
+  }
+
+  console.log(`Learnings deleted (all): ${learningsDeleted}`);
+
+  // =========================================================================
+  // Rule 3: Delete ALL decisions EXCEPT D-mntpeeer
+  // =========================================================================
+
+  const decisionsToDelete = await db
+    .select()
+    .from(brainDecisions)
+    .where(ne(brainDecisions.id, 'D-mntpeeer'));
+
+  const decisionsDeleted = decisionsToDelete.length;
+  if (decisionsDeleted > 0) {
+    const ids = decisionsToDelete.map((r) => r.id);
+    await db.delete(brainDecisions).where(inArray(brainDecisions.id, ids));
+  }
+
+  console.log(`Decisions deleted (all except D-mntpeeer): ${decisionsDeleted}`);
+
+  // =========================================================================
+  // Rule 4: Delete noise observations
+  // Keep: real release notes, real codebase analysis, real session handoffs
+  // Delete: task-start, task-complete, session-note, test/junk entries
+  // =========================================================================
+
+  // Collect all observations to classify them
+  const allObservations = await db.select().from(brainObservations);
+
+  const obsIdsToDelete: string[] = [];
+
+  for (const obs of allObservations) {
+    const title = obs.title ?? '';
+    const narrative = (obs.narrative ?? '').toLowerCase();
+    const titleLower = title.toLowerCase();
+
+    // Rule 4a: Task lifecycle noise
+    if (
+      title.startsWith('Task start: T') ||
+      title.startsWith('Task complete: T') ||
+      title.startsWith('Task depended on') ||
+      title.startsWith('Task T') // catch "Task T527 depended on..." etc.
+    ) {
+      obsIdsToDelete.push(obs.id);
+      continue;
+    }
+
+    // Rule 4b: Session notes (all are noise — real handoffs are in sticky notes)
+    if (title.startsWith('Session note:')) {
+      obsIdsToDelete.push(obs.id);
+      continue;
+    }
+
+    // Rule 4c: Test/audit/probe/junk observations
+    const testKeywords = [
+      'audit test',
+      'audit probe',
+      'probe observation',
+      'dup test',
+      'provider test',
+      'brain regression',
+      'brain validation',
+      'release test',
+      'functional validation',
+      'test title',
+      'test decision',
+      'test learning',
+      'test pattern',
+      'test observation',
+      'sticky note', // audit test sticky note
+    ];
+
+    const isTestNoise = testKeywords.some(
+      (kw) => titleLower.includes(kw) || narrative.includes(kw),
+    );
+
+    if (isTestNoise) {
+      obsIdsToDelete.push(obs.id);
+    }
+
+    // Rule 4d: Auto-detection codebase map noise (keep real ones, delete duplicates)
+    // "Codebase Stack Analysis" and "Codebase Integrations" — keep one of each,
+    // but the task asks us to keep ~27 so we apply conservative rules.
+    // Only delete if title exactly matches auto-generated repeated patterns.
+  }
+
+  let observationsDeleted = 0;
+  if (obsIdsToDelete.length > 0) {
+    const BATCH = 500;
+    for (let i = 0; i < obsIdsToDelete.length; i += BATCH) {
+      const batch = obsIdsToDelete.slice(i, i + BATCH);
+      await db.delete(brainObservations).where(inArray(brainObservations.id, batch));
+      observationsDeleted += batch.length;
+    }
+  }
+
+  console.log(`Observations deleted: ${observationsDeleted}`);
+
+  // =========================================================================
+  // Post-purge counts
+  // =========================================================================
+
+  const afterPatterns = countRowsNative('brain_patterns');
+  const afterLearnings = countRowsNative('brain_learnings');
+  const afterDecisions = countRowsNative('brain_decisions');
+  const afterObservations = countRowsNative('brain_observations');
+
+  console.log('\nPost-purge counts:');
+  console.log(`  Patterns:     ${afterPatterns} (deleted ${beforePatterns - afterPatterns})`);
+  console.log(`  Learnings:    ${afterLearnings} (deleted ${beforeLearnings - afterLearnings})`);
+  console.log(`  Decisions:    ${afterDecisions} (deleted ${beforeDecisions - afterDecisions})`);
+  console.log(
+    `  Observations: ${afterObservations} (deleted ${beforeObservations - afterObservations})`,
+  );
+
+  // =========================================================================
+  // Rebuild FTS5 indexes after bulk deletes
+  // =========================================================================
+
+  let fts5Rebuilt = false;
+  const nativeDb = getBrainNativeDb();
+  if (nativeDb) {
+    ensureFts5Tables(nativeDb);
+    try {
+      rebuildFts5Index(nativeDb);
+      fts5Rebuilt = true;
+      console.log('FTS5 indexes rebuilt successfully');
+    } catch (err) {
+      console.warn('FTS5 rebuild failed (non-fatal):', err);
+    }
+  }
+
+  return {
+    patternsDeleted: beforePatterns - afterPatterns,
+    learningsDeleted: beforeLearnings - afterLearnings,
+    decisionsDeleted: beforeDecisions - afterDecisions,
+    observationsDeleted: beforeObservations - afterObservations,
+    after: {
+      patterns: afterPatterns,
+      learnings: afterLearnings,
+      decisions: afterDecisions,
+      observations: afterObservations,
+    },
+    fts5Rebuilt,
+  };
+}

package/src/memory/brain-retrieval.ts

@@ -35,6 +35,8 @@ import type {
   BrainTimelineNeighborRow,
 } from './brain-row-types.js';
 import { searchBrain } from './brain-search.js';
+import { addGraphEdge, upsertGraphNode } from './graph-auto-populate.js';
+import { computeObservationQuality } from './quality-scoring.js';
 
 // ============================================================================
 // Types
@@ -155,7 +157,7 @@ export async function searchBrainCompact(
 ): Promise<SearchBrainCompactResult> {
   const { query, limit, tables, dateStart, dateEnd, agent } = params;
 
-  if (!query || !query.trim()) {
+  if (!query?.trim()) {
     return { results: [], total: 0, tokensEstimated: 0 };
   }
 
@@ -551,7 +553,7 @@ export async function observeBrain(
     agent,
   } = params;
 
-  if (!text || !text.trim()) {
+  if (!text?.trim()) {
     throw new Error('Observation text is required');
   }
 
@@ -601,6 +603,9 @@ export async function observeBrain(
     }
   }
 
+  // Compute quality score from text richness and title length.
+  const qualityScore = computeObservationQuality({ text, title });
+
   const id = `O-${Date.now().toString(36)}-${(observeSeq++ % 1000).toString(36)}`;
   const accessor = await getBrainAccessor(projectRoot);
 
@@ -614,6 +619,7 @@ export async function observeBrain(
     sourceSessionId: validSessionId,
     sourceType: sourceType ?? 'agent',
     agent: agent ?? null,
+    qualityScore,
     createdAt: now,
   });
 
@@ -655,6 +661,41 @@ export async function observeBrain(
     });
   }
 
+  // Auto-populate graph node + edges for this observation (best-effort, T537).
+  try {
+    await upsertGraphNode(
+      projectRoot,
+      `observation:${row.id}`,
+      'observation',
+      row.title.substring(0, 200),
+      row.qualityScore ?? 0.5,
+      row.narrative ?? row.title,
+      { sourceType: row.sourceType, agent: row.agent ?? undefined },
+    );
+
+    // Link observation → session when the observation has a session context.
+    if (validSessionId) {
+      await upsertGraphNode(
+        projectRoot,
+        `session:${validSessionId}`,
+        'session',
+        validSessionId,
+        0.8,
+        '',
+      );
+      await addGraphEdge(
+        projectRoot,
+        `observation:${row.id}`,
+        `session:${validSessionId}`,
+        'produced_by',
+        1.0,
+        'auto:observe',
+      );
+    }
+  } catch {
+    /* Graph population is best-effort — never block the primary return */
+  }
+
   return {
     id: row.id,
     type: row.type,

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,12 +531,14 @@ 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,
   );
 }
@@ -591,7 +608,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,13 @@ export async function storeDecision(
     }
   }
 
+  // Compute quality score from confidence level, rationale richness, and task linkage.
+  const qualityScore = computeDecisionQuality({
+    confidence: params.confidence,
+    rationale: params.rationale.trim(),
+    contextTaskId: validTaskId ?? null,
+  });
+
   const row: NewBrainDecisionRow = {
     id,
     type: params.type,
@@ -137,9 +165,54 @@ export async function storeDecision(
     contextEpicId: validEpicId,
     contextTaskId: validTaskId,
     contextPhase: params.contextPhase,
+    qualityScore,
   };
 
-  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;
 }
 
 /**