@cleocode/core 2026.3.42 → 2026.3.44

package/src/memory/brain-row-types.ts

@@ -7,21 +7,21 @@
  * @task T5800
  */
 
-/** Row returned by FTS content_hash duplicate check. */
+/** Row returned by FTS content_hash duplicate check (brain-retrieval.ts observeBrain). */
 export interface BrainFtsRow {
   id: string;
   type: string;
   created_at: string;
 }
 
-/** Row returned by narrative backfill query (missing embeddings). */
+/** Row returned by narrative backfill query (brain-retrieval.ts populateEmbeddings). */
 export interface BrainNarrativeRow {
   id: string;
   narrative: string;
   title: string;
 }
 
-/** Flattened FTS hit used in hybrid search scoring. */
+/** Flattened FTS hit used in hybrid search scoring (brain-search.ts hybridSearch). */
 export interface BrainSearchHit {
   id: string;
   type: string;
@@ -29,22 +29,59 @@ export interface BrainSearchHit {
   text: string;
 }
 
-/** Row returned by KNN vector similarity query. */
+/** Row returned by KNN vector similarity query (brain-similarity.ts searchSimilar). */
 export interface BrainKnnRow {
   id: string;
   distance: number;
 }
 
-/** Decision node attached to a blocker in causal traces. */
+/** Decision node attached to a blocker in causal traces (brain-reasoning.ts reasonWhy). */
 export interface BrainDecisionNode {
   id: string;
   title: string;
   rationale?: string;
 }
 
-/** Anchor entry in a timeline result. */
+/** Anchor entry in a timeline result (brain-retrieval.ts timelineBrain). */
 export interface BrainAnchor {
   id: string;
   type: string;
   data: unknown;
 }
+
+/**
+ * Row returned by timeline UNION ALL neighbor queries (brain-retrieval.ts timelineBrain).
+ *
+ * Represents an entry from any of the four brain tables projected to
+ * a common {id, type, date} shape for chronological ordering.
+ */
+export interface BrainTimelineNeighborRow {
+  id: string;
+  type: string;
+  date: string;
+}
+
+/**
+ * Row returned by the consolidation observation query (brain-lifecycle.ts consolidateMemories).
+ *
+ * Fetches old observations for keyword-based clustering and archival.
+ * Uses snake_case column names matching the raw SQLite row shape.
+ */
+export interface BrainConsolidationObservationRow {
+  id: string;
+  type: string;
+  title: string;
+  narrative: string | null;
+  project: string | null;
+  created_at: string;
+}
+
+/**
+ * Row returned by ID existence check queries (claude-mem-migration.ts).
+ *
+ * Used by `SELECT id FROM brain_observations WHERE id = ?` and similar
+ * single-column lookups for idempotent migration dedup.
+ */
+export interface BrainIdCheckRow {
+  id: string;
+}

package/src/memory/brain-search.ts

@@ -16,6 +16,7 @@ import type {
   BrainObservationRow,
   BrainPatternRow,
 } from '../store/brain-schema.js';
+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';
@@ -332,16 +333,18 @@ function searchWithFts5(
 
   if (tables.includes('decisions')) {
     try {
-      const rows = nativeDb
-        .prepare(`
+      const rows = typedAll<BrainDecisionRow>(
+        nativeDb.prepare(`
         SELECT d.*
         FROM brain_decisions_fts fts
         JOIN brain_decisions d ON d.rowid = fts.rowid
         WHERE brain_decisions_fts MATCH ?
         ORDER BY bm25(brain_decisions_fts)
         LIMIT ?
-      `)
-        .all(safeQuery, limit) as unknown as BrainDecisionRow[];
+      `),
+        safeQuery,
+        limit,
+      );
       result.decisions = rows;
     } catch {
       // FTS query failed, fall back to LIKE for this table
@@ -351,16 +354,18 @@ function searchWithFts5(
 
   if (tables.includes('patterns')) {
     try {
-      const rows = nativeDb
-        .prepare(`
+      const rows = typedAll<BrainPatternRow>(
+        nativeDb.prepare(`
         SELECT p.*
         FROM brain_patterns_fts fts
         JOIN brain_patterns p ON p.rowid = fts.rowid
         WHERE brain_patterns_fts MATCH ?
         ORDER BY bm25(brain_patterns_fts)
         LIMIT ?
-      `)
-        .all(safeQuery, limit) as unknown as BrainPatternRow[];
+      `),
+        safeQuery,
+        limit,
+      );
       result.patterns = rows;
     } catch {
       result.patterns = likeSearchPatterns(nativeDb, query, limit);
@@ -369,16 +374,18 @@ function searchWithFts5(
 
   if (tables.includes('learnings')) {
     try {
-      const rows = nativeDb
-        .prepare(`
+      const rows = typedAll<BrainLearningRow>(
+        nativeDb.prepare(`
         SELECT l.*
         FROM brain_learnings_fts fts
         JOIN brain_learnings l ON l.rowid = fts.rowid
         WHERE brain_learnings_fts MATCH ?
         ORDER BY bm25(brain_learnings_fts)
         LIMIT ?
-      `)
-        .all(safeQuery, limit) as unknown as BrainLearningRow[];
+      `),
+        safeQuery,
+        limit,
+      );
       result.learnings = rows;
     } catch {
       result.learnings = likeSearchLearnings(nativeDb, query, limit);
@@ -387,16 +394,18 @@ function searchWithFts5(
 
   if (tables.includes('observations')) {
     try {
-      const rows = nativeDb
-        .prepare(`
+      const rows = typedAll<BrainObservationRow>(
+        nativeDb.prepare(`
         SELECT o.*
         FROM brain_observations_fts fts
         JOIN brain_observations o ON o.rowid = fts.rowid
         WHERE brain_observations_fts MATCH ?
         ORDER BY bm25(brain_observations_fts)
         LIMIT ?
-      `)
-        .all(safeQuery, limit) as unknown as BrainObservationRow[];
+      `),
+        safeQuery,
+        limit,
+      );
       result.observations = rows;
     } catch {
       result.observations = likeSearchObservations(nativeDb, query, limit);
@@ -447,14 +456,17 @@ function likeSearchDecisions(
   limit: number,
 ): BrainDecisionRow[] {
   const likePattern = `%${query}%`;
-  return nativeDb
-    .prepare(`
+  return typedAll<BrainDecisionRow>(
+    nativeDb.prepare(`
     SELECT * FROM brain_decisions
     WHERE decision LIKE ? OR rationale LIKE ?
     ORDER BY created_at DESC
     LIMIT ?
-  `)
-    .all(likePattern, likePattern, limit) as unknown as BrainDecisionRow[];
+  `),
+    likePattern,
+    likePattern,
+    limit,
+  );
 }
 
 function likeSearchPatterns(
@@ -463,14 +475,17 @@ function likeSearchPatterns(
   limit: number,
 ): BrainPatternRow[] {
   const likePattern = `%${query}%`;
-  return nativeDb
-    .prepare(`
+  return typedAll<BrainPatternRow>(
+    nativeDb.prepare(`
     SELECT * FROM brain_patterns
     WHERE pattern LIKE ? OR context LIKE ?
     ORDER BY frequency DESC
     LIMIT ?
-  `)
-    .all(likePattern, likePattern, limit) as unknown as BrainPatternRow[];
+  `),
+    likePattern,
+    likePattern,
+    limit,
+  );
 }
 
 function likeSearchLearnings(
@@ -479,14 +494,17 @@ function likeSearchLearnings(
   limit: number,
 ): BrainLearningRow[] {
   const likePattern = `%${query}%`;
-  return nativeDb
-    .prepare(`
+  return typedAll<BrainLearningRow>(
+    nativeDb.prepare(`
     SELECT * FROM brain_learnings
     WHERE insight LIKE ? OR source LIKE ?
     ORDER BY confidence DESC
     LIMIT ?
-  `)
-    .all(likePattern, likePattern, limit) as unknown as BrainLearningRow[];
+  `),
+    likePattern,
+    likePattern,
+    limit,
+  );
 }
 
 function likeSearchObservations(
@@ -495,14 +513,17 @@ function likeSearchObservations(
   limit: number,
 ): BrainObservationRow[] {
   const likePattern = `%${query}%`;
-  return nativeDb
-    .prepare(`
+  return typedAll<BrainObservationRow>(
+    nativeDb.prepare(`
     SELECT * FROM brain_observations
     WHERE title LIKE ? OR narrative LIKE ?
     ORDER BY created_at DESC
     LIMIT ?
-  `)
-    .all(likePattern, likePattern, limit) as unknown as BrainObservationRow[];
+  `),
+    likePattern,
+    likePattern,
+    limit,
+  );
 }
 
 /**

package/src/memory/brain-similarity.ts

@@ -10,6 +10,7 @@
  */
 
 import { getBrainAccessor } from '../store/brain-accessor.js';
+import { typedAll } from '../store/typed-query.js';
 import { embedText, isEmbeddingAvailable } from './brain-embedding.js';
 import type { BrainKnnRow } from './brain-row-types.js';
 
@@ -83,14 +84,14 @@ export async function searchSimilar(
   // Run KNN query against vec0 table
   let knnRows: BrainKnnRow[];
   try {
-    knnRows = nativeDb
-      .prepare(
-        'SELECT id, distance FROM brain_embeddings WHERE embedding MATCH ? ORDER BY distance LIMIT ?',
-      )
-      .all(
-        new Float32Array(queryVector.buffer, queryVector.byteOffset, queryVector.length),
-        maxResults,
-      ) as unknown as BrainKnnRow[];
+    const stmt = nativeDb.prepare(
+      'SELECT id, distance FROM brain_embeddings WHERE embedding MATCH ? ORDER BY distance LIMIT ?',
+    );
+    knnRows = typedAll<BrainKnnRow>(
+      stmt,
+      new Float32Array(queryVector.buffer, queryVector.byteOffset, queryVector.length),
+      maxResults,
+    );
   } catch {
     // vec0 query failed — table may not exist or extension not loaded
     return [];

package/src/memory/claude-mem-migration.ts

@@ -15,6 +15,7 @@ import type { DatabaseSync as _DatabaseSyncType } from 'node:sqlite';
 import { getClaudeMemDbPath } from '../paths.js';
 import type { BRAIN_OBSERVATION_TYPES } from '../store/brain-schema.js';
 import { getBrainDb, getBrainNativeDb } from '../store/brain-sqlite.js';
+import type { BrainIdCheckRow } from './brain-row-types.js';
 import { ensureFts5Tables, rebuildFts5Index } from './brain-search.js';
 
 /** Type-safe wrapper for StatementSync.all(). */
@@ -204,7 +205,7 @@ export async function migrateClaudeMem(
           // Check if already imported (idempotent)
           const existing = nativeDb
             .prepare('SELECT id FROM brain_observations WHERE id = ?')
-            .get(obsId) as Record<string, unknown> | undefined;
+            .get(obsId) as BrainIdCheckRow | undefined;
 
           if (existing) {
             result.observationsSkipped++;
@@ -254,7 +255,7 @@ export async function migrateClaudeMem(
             const decId = `CMD-${row.id}`;
             const existingDec = nativeDb
               .prepare('SELECT id FROM brain_decisions WHERE id = ?')
-              .get(decId) as Record<string, unknown> | undefined;
+              .get(decId) as BrainIdCheckRow | undefined;
 
             if (!existingDec) {
               nativeDb
@@ -324,7 +325,7 @@ export async function migrateClaudeMem(
           // Check if already imported
           const existing = nativeDb
             .prepare('SELECT id FROM brain_learnings WHERE id = ?')
-            .get(learnId) as Record<string, unknown> | undefined;
+            .get(learnId) as BrainIdCheckRow | undefined;
 
           if (existing) {
             // Don't count as skipped — these are separate from observations