@cleocode/core 2026.4.30 → 2026.4.35

package/src/store/brain-schema.ts

@@ -14,6 +14,57 @@ import { index, integer, primaryKey, real, sqliteTable, text } from 'drizzle-orm
 
 // === ENUM CONSTANTS ===
 
+/**
+ * Memory retention tiers for the tiered cognitive memory model (T549).
+ *
+ * - `short`  — Session-scoped working context. Volatile; auto-evicted after 48h if not promoted.
+ * - `medium` — Project-scoped verified facts. Retained for weeks; decays if unverified.
+ * - `long`   — Architectural bedrock. Permanent; supersession-only eviction.
+ *
+ * NULL semantics for legacy rows: treat NULL as 'medium' at query time.
+ * (Legacy rows survived the T523 purge, so medium is a safe tier assumption.)
+ */
+export const BRAIN_MEMORY_TIERS = ['short', 'medium', 'long'] as const;
+
+/** Discriminated union of all memory retention tiers. */
+export type BrainMemoryTier = (typeof BRAIN_MEMORY_TIERS)[number];
+
+/**
+ * Cognitive type taxonomy for the tiered memory model (T549).
+ *
+ * Uses `BRAIN_COGNITIVE_TYPES` (not `BRAIN_MEMORY_TYPES`) to avoid collision
+ * with the link table enum `BRAIN_MEMORY_TYPES` (which stores entity type names).
+ *
+ * - `semantic`   — Declarative facts: "what is true about this project"
+ *                  → brain_decisions (always), brain_learnings (default)
+ * - `episodic`   — Event records: "what happened and when"
+ *                  → brain_observations (always), brain_learnings (transcript-derived)
+ * - `procedural` — Process knowledge: "how to do things"
+ *                  → brain_patterns (always)
+ */
+export const BRAIN_COGNITIVE_TYPES = ['semantic', 'episodic', 'procedural'] as const;
+
+/** Discriminated union of all cognitive memory types. */
+export type BrainCognitiveType = (typeof BRAIN_COGNITIVE_TYPES)[number];
+
+/**
+ * Source reliability levels for the tiered memory model (T549).
+ *
+ * Separate dimension from content `quality_score` — captures source trustworthiness.
+ * Each level drives a quality multiplier applied at scoring time.
+ *
+ * | Level         | Meaning                                 | Quality multiplier |
+ * |---------------|-----------------------------------------|--------------------|
+ * | `owner`       | Owner explicitly stated this fact       | 1.0                |
+ * | `task-outcome`| Verified by completed task with result  | 0.90               |
+ * | `agent`       | Agent-inferred during work (default)    | 0.70               |
+ * | `speculative` | Agent hypothesis, not yet corroborated  | 0.40               |
+ */
+export const BRAIN_SOURCE_CONFIDENCE = ['owner', 'task-outcome', 'agent', 'speculative'] as const;
+
+/** Discriminated union of all source confidence levels. */
+export type BrainSourceConfidence = (typeof BRAIN_SOURCE_CONFIDENCE)[number];
+
 /** Decision types from ADR-009. */
 export const BRAIN_DECISION_TYPES = [
   'architecture',
@@ -94,8 +145,54 @@ export const brainDecisions = sqliteTable(
     contextEpicId: text('context_epic_id'), // soft FK to tasks.id in tasks.db
     contextTaskId: text('context_task_id'), // soft FK to tasks.id in tasks.db
     contextPhase: text('context_phase'),
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from confidence, content richness, and context.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
+
+    // T549: Tiered + Typed Memory columns
+
+    /** Memory retention tier. NULL on legacy rows → treat as 'medium' at query time. */
+    memoryTier: text('memory_tier', { enum: BRAIN_MEMORY_TIERS }).default('short'),
+
+    /** Cognitive type. Decisions are always 'semantic' (declarative architectural facts). */
+    memoryType: text('memory_type', { enum: BRAIN_COGNITIVE_TYPES }).default('semantic'),
+
+    /**
+     * Ground-truth verification flag.
+     * false = agent-inferred, pending verification.
+     * true = confirmed via owner statement, task outcome, corroboration, or manual `cleo memory verify`.
+     */
+    verified: integer('verified', { mode: 'boolean' }).notNull().default(false),
+
+    /**
+     * Bitemporal: when this decision became valid (ISO 8601 text).
+     * Defaults to creation time. Can be backdated for historical facts.
+     */
+    validAt: text('valid_at').notNull().default(sql`(datetime('now'))`),
+
+    /**
+     * Bitemporal: when this decision stopped being valid.
+     * NULL = currently valid. Prefer `supersedes` graph edges for decision supersession
+     * (ADR-009); this column is a convenience gate for bulk eviction queries.
+     */
+    invalidAt: text('invalid_at'),
+
+    /**
+     * Source reliability level — separate from content quality_score (T549 §3.1.5).
+     * Drives quality multiplier at scoring time.
+     */
+    sourceConfidence: text('source_confidence', { enum: BRAIN_SOURCE_CONFIDENCE }).default('agent'),
+
+    /**
+     * Number of times this decision has been cited/retrieved (T549 CONFLICT-03).
+     * Used by the consolidator for citation-based medium→long promotion.
+     */
+    citationCount: integer('citation_count').notNull().default(0),
   },
   (table) => [
     index('idx_brain_decisions_type').on(table.type),
@@ -103,6 +200,13 @@ export const brainDecisions = sqliteTable(
     index('idx_brain_decisions_outcome').on(table.outcome),
     index('idx_brain_decisions_context_epic').on(table.contextEpicId),
     index('idx_brain_decisions_context_task').on(table.contextTaskId),
+    index('idx_brain_decisions_quality').on(table.qualityScore),
+    // T549 indexes
+    index('idx_brain_decisions_tier').on(table.memoryTier),
+    index('idx_brain_decisions_mem_type').on(table.memoryType),
+    index('idx_brain_decisions_verified').on(table.verified),
+    index('idx_brain_decisions_valid_at').on(table.validAt),
+    index('idx_brain_decisions_source_conf').on(table.sourceConfidence),
   ],
 );
 
@@ -123,11 +227,63 @@ export const brainPatterns = sqliteTable(
     examplesJson: text('examples_json').default('[]'),
     extractedAt: text('extracted_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from type, content richness, and examples.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
+
+    // T549: Tiered + Typed Memory columns
+
+    /** Memory retention tier. NULL on legacy rows → treat as 'medium' at query time. */
+    memoryTier: text('memory_tier', { enum: BRAIN_MEMORY_TIERS }).default('short'),
+
+    /** Cognitive type. Patterns are always 'procedural' (process/workflow knowledge). */
+    memoryType: text('memory_type', { enum: BRAIN_COGNITIVE_TYPES }).default('procedural'),
+
+    /**
+     * Ground-truth verification flag.
+     * For patterns, this is complementary to frequency+successRate verification.
+     * false = agent-inferred. true = confirmed via owner statement or task outcome.
+     */
+    verified: integer('verified', { mode: 'boolean' }).notNull().default(false),
+
+    /**
+     * Bitemporal: when this pattern became valid (ISO 8601 text).
+     * Defaults to extraction time.
+     */
+    validAt: text('valid_at').notNull().default(sql`(datetime('now'))`),
+
+    /**
+     * Bitemporal: when this pattern stopped being valid.
+     * NULL = currently valid. Set by consolidator when frequency+successRate drops below threshold.
+     */
+    invalidAt: text('invalid_at'),
+
+    /**
+     * Source reliability level — separate from content quality_score (T549 §3.1.5).
+     * Drives quality multiplier at scoring time.
+     */
+    sourceConfidence: text('source_confidence', { enum: BRAIN_SOURCE_CONFIDENCE }).default('agent'),
+
+    /**
+     * Number of times this pattern has been cited/retrieved (T549 CONFLICT-03).
+     * Used by the consolidator for citation-based medium→long promotion.
+     */
+    citationCount: integer('citation_count').notNull().default(0),
   },
   (table) => [
     index('idx_brain_patterns_type').on(table.type),
     index('idx_brain_patterns_impact').on(table.impact),
     index('idx_brain_patterns_frequency').on(table.frequency),
+    index('idx_brain_patterns_quality').on(table.qualityScore),
+    // T549 indexes
+    index('idx_brain_patterns_tier').on(table.memoryTier),
+    index('idx_brain_patterns_mem_type').on(table.memoryType),
+    index('idx_brain_patterns_verified').on(table.verified),
+    index('idx_brain_patterns_valid_at').on(table.validAt),
+    index('idx_brain_patterns_source_conf').on(table.sourceConfidence),
   ],
 );
 
@@ -145,10 +301,66 @@ export const brainLearnings = sqliteTable(
     applicableTypesJson: text('applicable_types_json'),
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from confidence, actionability, and content richness.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
+
+    // T549: Tiered + Typed Memory columns
+
+    /** Memory retention tier. NULL on legacy rows → treat as 'medium' at query time. */
+    memoryTier: text('memory_tier', { enum: BRAIN_MEMORY_TIERS }).default('short'),
+
+    /**
+     * Cognitive type. Learnings are 'semantic' by default (declarative facts).
+     * Transcript-derived learnings with source containing 'transcript:ses_' are 'episodic'.
+     */
+    memoryType: text('memory_type', { enum: BRAIN_COGNITIVE_TYPES }).default('semantic'),
+
+    /**
+     * Ground-truth verification flag.
+     * false = agent-inferred, pending verification.
+     * true = confirmed via owner statement, task outcome, corroboration, or manual verify.
+     */
+    verified: integer('verified', { mode: 'boolean' }).notNull().default(false),
+
+    /**
+     * Bitemporal: when this learning became valid (ISO 8601 text).
+     * Defaults to creation time. Facts can change — use invalidAt to retire stale ones.
+     */
+    validAt: text('valid_at').notNull().default(sql`(datetime('now'))`),
+
+    /**
+     * Bitemporal: when this learning stopped being valid.
+     * NULL = currently valid. Set by consolidator on contradiction detection or TTL decay.
+     */
+    invalidAt: text('invalid_at'),
+
+    /**
+     * Source reliability level — separate from content quality_score (T549 §3.1.5).
+     * Drives quality multiplier at scoring time.
+     */
+    sourceConfidence: text('source_confidence', { enum: BRAIN_SOURCE_CONFIDENCE }).default('agent'),
+
+    /**
+     * Number of times this learning has been cited/retrieved (T549 CONFLICT-03).
+     * Used by the consolidator for citation-based medium→long promotion.
+     */
+    citationCount: integer('citation_count').notNull().default(0),
   },
   (table) => [
     index('idx_brain_learnings_confidence').on(table.confidence),
     index('idx_brain_learnings_actionable').on(table.actionable),
+    index('idx_brain_learnings_quality').on(table.qualityScore),
+    // T549 indexes
+    index('idx_brain_learnings_tier').on(table.memoryTier),
+    index('idx_brain_learnings_mem_type').on(table.memoryType),
+    index('idx_brain_learnings_verified').on(table.verified),
+    index('idx_brain_learnings_valid_at').on(table.validAt),
+    index('idx_brain_learnings_invalid').on(table.invalidAt),
+    index('idx_brain_learnings_source_conf').on(table.sourceConfidence),
   ],
 );
 
@@ -176,8 +388,54 @@ export const brainObservations = sqliteTable(
     agent: text('agent'), // nullable — null for legacy observations
     contentHash: text('content_hash'), // SHA-256 prefix for dedup
     discoveryTokens: integer('discovery_tokens'), // cost to produce this observation
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical). Null for legacy entries.
+     * Computed at insert time from content richness and title length.
+     * Entries below 0.3 are excluded from search results (T531).
+     */
+    qualityScore: real('quality_score'),
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
     updatedAt: text('updated_at'),
+
+    // T549: Tiered + Typed Memory columns
+
+    /** Memory retention tier. NULL on legacy rows → treat as 'medium' at query time. */
+    memoryTier: text('memory_tier', { enum: BRAIN_MEMORY_TIERS }).default('short'),
+
+    /** Cognitive type. Observations are always 'episodic' (time-anchored event records). */
+    memoryType: text('memory_type', { enum: BRAIN_COGNITIVE_TYPES }).default('episodic'),
+
+    /**
+     * Ground-truth verification flag.
+     * false = agent-inferred, pending verification.
+     * true = confirmed via owner statement, task outcome, corroboration, or manual verify.
+     */
+    verified: integer('verified', { mode: 'boolean' }).notNull().default(false),
+
+    /**
+     * Bitemporal: when this observation became valid (ISO 8601 text).
+     * Defaults to creation time. Can be backdated for historical facts.
+     */
+    validAt: text('valid_at').notNull().default(sql`(datetime('now'))`),
+
+    /**
+     * Bitemporal: when this observation stopped being valid.
+     * NULL = currently valid. Set by consolidator on contradiction detection.
+     * Temporal query pattern: WHERE valid_at <= :t AND (invalid_at IS NULL OR invalid_at > :t)
+     */
+    invalidAt: text('invalid_at'),
+
+    /**
+     * Source reliability level — separate from content quality_score (T549 §3.1.5).
+     * Drives quality multiplier at scoring time.
+     */
+    sourceConfidence: text('source_confidence', { enum: BRAIN_SOURCE_CONFIDENCE }).default('agent'),
+
+    /**
+     * Number of times this observation has been cited/retrieved (T549 CONFLICT-03).
+     * Used by the consolidator for citation-based medium→long promotion.
+     */
+    citationCount: integer('citation_count').notNull().default(0),
   },
   (table) => [
     index('idx_brain_observations_type').on(table.type),
@@ -191,6 +449,15 @@ export const brainObservations = sqliteTable(
     index('idx_brain_observations_type_project').on(table.type, table.project),
     // T417: agent provenance index for memory.find --agent filter
     index('idx_brain_observations_agent').on(table.agent),
+    // T531: quality score filter index
+    index('idx_brain_observations_quality').on(table.qualityScore),
+    // T549 indexes
+    index('idx_brain_observations_tier').on(table.memoryTier),
+    index('idx_brain_observations_mem_type').on(table.memoryType),
+    index('idx_brain_observations_verified').on(table.verified),
+    index('idx_brain_observations_valid_at').on(table.validAt),
+    index('idx_brain_observations_invalid').on(table.invalidAt),
+    index('idx_brain_observations_source_conf').on(table.sourceConfidence),
   ],
 );
 
@@ -244,41 +511,163 @@ export const brainSchemaMeta = sqliteTable('brain_schema_meta', {
   value: text('value').notNull(),
 });
 
-// === PAGEINDEX GRAPH TABLES (T5160) ===
+// === PAGEINDEX GRAPH TABLES (T5160, expanded T528) ===
+
+/**
+ * Node types for the graph-native memory model.
+ * Mirrors typed tables (decision, pattern, learning, observation, sticky),
+ * adds task provenance (task, session, epic), codebase bridging (file, symbol),
+ * and abstract/synthesized types (concept, summary).
+ */
+export const BRAIN_NODE_TYPES = [
+  // Memory entity types (mirror typed tables)
+  'decision',
+  'pattern',
+  'learning',
+  'observation',
+  'sticky',
+  // Task provenance (soft FK into tasks.db)
+  'task',
+  'session',
+  'epic',
+  // Codebase integration (bridge to nexus.db code_index)
+  'file',
+  'symbol',
+  // Abstract / synthesized
+  'concept',
+  'summary',
+] as const;
+
+/** Discriminated union of all supported brain graph node types. */
+export type BrainNodeType = (typeof BRAIN_NODE_TYPES)[number];
 
-/** Node types for PageIndex graph. */
-export const BRAIN_NODE_TYPES = ['task', 'doc', 'file', 'concept'] as const;
+/**
+ * Edge types for the graph-native memory model.
+ * Covers provenance/derivation, semantic relationships, structural links,
+ * and graph bridging between memory entities and codebase nodes.
+ */
+export const BRAIN_EDGE_TYPES = [
+  // Provenance / derivation
+  'derived_from', // learning ← derived_from ← observation
+  'produced_by', // observation ← produced_by ← session
+  'informed_by', // decision ← informed_by ← pattern
+  // Semantic relationship
+  'supports', // observation → supports → decision
+  'contradicts', // observation → contradicts → decision
+  'supersedes', // decision → supersedes → decision (older)
+  'applies_to', // decision/pattern → applies_to → task/file/symbol
+  // Structural
+  'documents', // observation → documents → symbol/file
+  'summarizes', // summary → summarizes → observation (consolidation)
+  'part_of', // task → part_of → epic
+  // Graph bridging (memory ↔ code)
+  'references', // observation → references → symbol
+  'modified_by', // file → modified_by → session
+] as const;
 
-/** Edge types for PageIndex graph. */
-export const BRAIN_EDGE_TYPES = ['depends_on', 'relates_to', 'implements', 'documents'] as const;
+/** Discriminated union of all supported brain graph edge types. */
+export type BrainEdgeType = (typeof BRAIN_EDGE_TYPES)[number];
 
-/** Documents/concepts as graph nodes for cross-document linking. */
+/**
+ * Graph nodes table — the traversable knowledge graph layer.
+ *
+ * Every entity row in a typed table (decisions, patterns, learnings,
+ * observations) gets a corresponding node here. The typed table row is
+ * the source of truth; the graph node is the index entry for traversal
+ * and cross-entity reasoning.
+ *
+ * Node ID convention: '<type>:<source-id>'
+ * Examples: 'decision:D-abc123', 'observation:O-mntphoj6-0',
+ *           'task:T523', 'symbol:src/store/brain-schema.ts::brainPageNodes'
+ */
 export const brainPageNodes = sqliteTable(
   'brain_page_nodes',
   {
-    id: text('id').primaryKey(), // 'task:T5241', 'doc:BRAIN-SPEC', 'file:src/store/brain-schema.ts'
+    /** Stable composite ID: '<type>:<source-id>' */
+    id: text('id').primaryKey(),
+
+    /** Discriminated type from BRAIN_NODE_TYPES. */
     nodeType: text('node_type', { enum: BRAIN_NODE_TYPES }).notNull(),
+
+    /** Human-readable label (title, name, or generated summary). */
     label: text('label').notNull(),
-    metadataJson: text('metadata_json'), // JSON blob for extensible metadata
+
+    /**
+     * Quality score: 0.0 (noise) – 1.0 (canonical).
+     * Derived from: source confidence, edge density, age decay, agent provenance.
+     * Default 0.5 for unknown provenance; 0.0 triggers exclusion from traversal.
+     */
+    qualityScore: real('quality_score').notNull().default(0.5),
+
+    /**
+     * SHA-256 prefix (first 16 hex chars) of the canonical content.
+     * Computed at insert time; duplicate hashes are rejected.
+     * Null for external references (task, session, symbol nodes).
+     */
+    contentHash: text('content_hash'),
+
+    /**
+     * ISO 8601 timestamp of last activity on this node.
+     * Updated when new edges are added, quality changes, or content is revised.
+     */
+    lastActivityAt: text('last_activity_at').notNull().default(sql`(datetime('now'))`),
+
+    /**
+     * Extensible JSON metadata blob — type-specific payload.
+     * decision: { type, confidence, outcome }
+     * observation: { sourceType, agent, sessionId }
+     * symbol: { filePath, kind, startLine, endLine, language }
+     * task: { status, priority, epicId }
+     */
+    metadataJson: text('metadata_json'),
+
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
+    updatedAt: text('updated_at'),
   },
-  (table) => [index('idx_brain_nodes_type').on(table.nodeType)],
+  (table) => [
+    index('idx_brain_nodes_type').on(table.nodeType),
+    index('idx_brain_nodes_quality').on(table.qualityScore),
+    index('idx_brain_nodes_content_hash').on(table.contentHash),
+    index('idx_brain_nodes_last_activity').on(table.lastActivityAt),
+  ],
 );
 
-/** Directed links between graph nodes. */
+/**
+ * Graph edges table — directed, typed, weighted, provenance-aware links
+ * between brain_page_nodes entries (or external nexus node IDs).
+ *
+ * The composite primary key (fromId, toId, edgeType) prevents duplicate
+ * edges of the same type between the same pair of nodes.
+ */
 export const brainPageEdges = sqliteTable(
   'brain_page_edges',
   {
-    fromId: text('from_id').notNull(),
-    toId: text('to_id').notNull(),
+    fromId: text('from_id').notNull(), // brain_page_nodes.id
+    toId: text('to_id').notNull(), // brain_page_nodes.id or nexus node id
     edgeType: text('edge_type', { enum: BRAIN_EDGE_TYPES }).notNull(),
-    weight: real('weight').default(1.0),
+
+    /**
+     * Edge weight / confidence: 0.0 – 1.0.
+     * Semantic edges use extractor confidence (similarity score).
+     * Structural edges use 1.0 (deterministic).
+     * Contradiction edges store the overlap score that triggered detection.
+     */
+    weight: real('weight').notNull().default(1.0),
+
+    /**
+     * Human-readable note on why this edge was emitted.
+     * Examples: 'auto:task-complete' | 'auto:session-end' |
+     *           'auto:contradiction-detected' | 'auto:consolidation' | 'manual'
+     */
+    provenance: text('provenance'),
+
     createdAt: text('created_at').notNull().default(sql`(datetime('now'))`),
   },
   (table) => [
     primaryKey({ columns: [table.fromId, table.toId, table.edgeType] }),
     index('idx_brain_edges_from').on(table.fromId),
     index('idx_brain_edges_to').on(table.toId),
+    index('idx_brain_edges_type').on(table.edgeType),
   ],
 );
 
@@ -300,3 +689,4 @@ export type BrainPageEdgeRow = typeof brainPageEdges.$inferSelect;
 export type NewBrainPageEdgeRow = typeof brainPageEdges.$inferInsert;
 export type BrainStickyNoteRow = typeof brainStickyNotes.$inferSelect;
 export type NewBrainStickyNoteRow = typeof brainStickyNotes.$inferInsert;
+// BrainNodeType and BrainEdgeType are declared alongside their enum arrays above.

package/src/store/brain-sqlite.ts

@@ -22,6 +22,7 @@ import { getCleoDirAbsolute } from '../paths.js';
 import * as brainSchema from './brain-schema.js';
 import {
   createSafetyBackup,
+  ensureColumns,
   migrateWithRetry,
   reconcileJournal,
   tableExists,
@@ -96,6 +97,60 @@ function runBrainMigrations(
   // Pass nativeDb + existenceTable so migrateWithRetry can auto-reconcile any
   // partial migration (Scenario 3) that slips through the proactive check above.
   migrateWithRetry(db, migrationsFolder, nativeDb, 'brain_decisions', 'brain');
+
+  // Safety net: ensure all columns from T528/T531/T549 exist even if the
+  // migration files were never committed to git or the journal was not updated.
+  // ensureColumns uses PRAGMA table_info + ALTER TABLE ADD COLUMN — idempotent.
+
+  // T528: graph schema expansion — quality scoring, content hashing, last-activity.
+  // Note: last_activity_at uses nullable text (no non-constant default) because
+  // ALTER TABLE ADD COLUMN with datetime('now') default fails on non-empty tables.
+  ensureColumns(
+    nativeDb,
+    'brain_page_nodes',
+    [
+      { name: 'quality_score', ddl: 'real DEFAULT 0.5' },
+      { name: 'content_hash', ddl: 'text' },
+      { name: 'last_activity_at', ddl: 'text' },
+      { name: 'updated_at', ddl: 'text' },
+    ],
+    'brain',
+  );
+
+  // T531: quality score on typed brain tables
+  for (const table of [
+    'brain_decisions',
+    'brain_patterns',
+    'brain_learnings',
+    'brain_observations',
+  ] as const) {
+    ensureColumns(nativeDb, table, [{ name: 'quality_score', ddl: 'real' }], 'brain');
+  }
+
+  // T549: tiered + typed memory architecture
+  for (const table of [
+    'brain_decisions',
+    'brain_patterns',
+    'brain_learnings',
+    'brain_observations',
+  ] as const) {
+    ensureColumns(
+      nativeDb,
+      table,
+      [
+        { name: 'memory_tier', ddl: "text DEFAULT 'short'" },
+        { name: 'memory_type', ddl: "text DEFAULT 'episodic'" },
+        { name: 'verified', ddl: 'integer NOT NULL DEFAULT 0' },
+        // valid_at uses nullable text (no datetime('now') default) because
+        // ALTER TABLE ADD COLUMN with non-constant defaults fails on non-empty tables.
+        { name: 'valid_at', ddl: 'text' },
+        { name: 'invalid_at', ddl: 'text' },
+        { name: 'source_confidence', ddl: "text DEFAULT 'agent'" },
+        { name: 'citation_count', ddl: 'integer NOT NULL DEFAULT 0' },
+      ],
+      'brain',
+    );
+  }
 }
 
 /**
@@ -142,6 +197,30 @@ export function isBrainVecLoaded(): boolean {
   return _vecLoaded;
 }
 
+/**
+ * Initialize the default embedding provider when brain.embedding.enabled is true.
+ *
+ * Called asynchronously after getBrainDb() completes its synchronous setup.
+ * Uses dynamic import to avoid circular dependencies and keep the heavy
+ * @huggingface/transformers bundle out of the critical startup path.
+ *
+ * Best-effort: errors are swallowed by the caller so DB access is never blocked.
+ *
+ * @task T539
+ */
+async function initEmbeddingProvider(cwd?: string): Promise<void> {
+  try {
+    const { loadConfig } = await import('../config.js');
+    const config = await loadConfig(cwd);
+    if (config.brain?.embedding?.enabled) {
+      const { initDefaultProvider } = await import('../memory/brain-embedding.js');
+      await initDefaultProvider();
+    }
+  } catch {
+    // Config load or provider init failed — non-fatal, embedding stays unavailable
+  }
+}
+
 /**
  * Initialize the brain.db SQLite database (lazy, singleton).
  * Creates the database file and tables if they don't exist.
@@ -200,6 +279,17 @@ export async function getBrainDb(cwd?: string): Promise<NodeSQLiteDatabase<typeo
 
     // Set singleton only after migrations complete
     _db = db;
+
+    // Wire the default embedding provider when vec is loaded and embedding is enabled.
+    // Best-effort, async, never blocks DB access. (T539)
+    if (_vecLoaded) {
+      setImmediate(() => {
+        initEmbeddingProvider(cwd).catch(() => {
+          // Non-fatal — embedding will be unavailable until next startup
+        });
+      });
+    }
+
     return db;
   })();