@cleocode/core 2026.4.29 → 2026.4.31

package/src/memory/quality-scoring.ts

@@ -0,0 +1,173 @@
+/**
+ * Quality scoring for CLEO BRAIN memory entries.
+ *
+ * Computes a 0.0–1.0 quality score at insert time for each typed brain table entry.
+ * Entries with a score below the minimum threshold are excluded from search results.
+ *
+ * Score formula per CA1 spec Section 3: source reliability * content richness * recency signals.
+ * Each helper clamps the result to [0.0, 1.0].
+ *
+ * Exported for use in backfill (T530) and future scoring hooks.
+ *
+ * @task T531
+ * @epic T523
+ */
+
+/** Minimum quality score for inclusion in search results. */
+export const QUALITY_SCORE_THRESHOLD = 0.3;
+
+// ============================================================================
+// Pattern quality
+// ============================================================================
+
+/** Input shape for pattern quality computation — mirrors StorePatternParams. */
+export interface PatternQualityInput {
+  type: string;
+  pattern: string;
+  context?: string | null;
+  examples_json?: string | null;
+}
+
+/**
+ * Compute quality score for a brain_patterns row.
+ *
+ * Base: 0.4 (auto-generated patterns start lower).
+ * Bonuses:
+ *   +0.10 for 'workflow' type (structured operational knowledge)
+ *   +0.05 for 'success' type (validated positive pattern)
+ *   +0.10 if pattern text exceeds 100 chars (richer description)
+ *   +0.10 if context exceeds 50 chars (contextual detail present)
+ *   +0.10 if examples_json contains more than 3 items (empirically validated)
+ *
+ * Result clamped to [0.0, 1.0].
+ */
+export function computePatternQuality(params: PatternQualityInput): number {
+  let score = 0.4;
+
+  if (params.type === 'workflow') score += 0.1;
+  if (params.type === 'success') score += 0.05;
+
+  if (params.pattern.length > 100) score += 0.1;
+  if (params.context && params.context.length > 50) score += 0.1;
+
+  if (params.examples_json) {
+    try {
+      const examples = JSON.parse(params.examples_json) as unknown[];
+      if (Array.isArray(examples) && examples.length > 3) score += 0.1;
+    } catch {
+      // Malformed JSON — no bonus
+    }
+  }
+
+  return clamp(score);
+}
+
+// ============================================================================
+// Learning quality
+// ============================================================================
+
+/** Input shape for learning quality computation — mirrors StoreLearningParams. */
+export interface LearningQualityInput {
+  confidence: number;
+  actionable?: boolean | null;
+  insight: string;
+  application?: string | null;
+}
+
+/**
+ * Compute quality score for a brain_learnings row.
+ *
+ * Base: confidence value (already 0.0–1.0, caller-provided).
+ * Bonuses:
+ *   +0.10 if actionable (directly applicable guidance)
+ *   +0.10 if insight text exceeds 100 chars (detailed insight)
+ *   +0.10 if application exceeds 20 chars (concrete application context)
+ *
+ * Result clamped to [0.0, 1.0].
+ */
+export function computeLearningQuality(params: LearningQualityInput): number {
+  let score = params.confidence ?? 0.5;
+
+  if (params.actionable) score += 0.1;
+  if (params.insight.length > 100) score += 0.1;
+  if (params.application && params.application.length > 20) score += 0.1;
+
+  return clamp(score);
+}
+
+// ============================================================================
+// Decision quality
+// ============================================================================
+
+/** Input shape for decision quality computation — mirrors StoreDecisionParams. */
+export interface DecisionQualityInput {
+  confidence: 'low' | 'medium' | 'high';
+  rationale?: string | null;
+  contextTaskId?: string | null;
+}
+
+/** Numeric value map from confidence level. */
+const CONFIDENCE_SCORE_MAP: Record<'low' | 'medium' | 'high', number> = {
+  high: 0.9,
+  medium: 0.7,
+  low: 0.5,
+};
+
+/**
+ * Compute quality score for a brain_decisions row.
+ *
+ * Base: mapped from confidence level (high=0.9, medium=0.7, low=0.5).
+ * Bonuses:
+ *   +0.10 if rationale exceeds 50 chars (substantiated reasoning)
+ *   +0.05 if linked to a specific task (anchored in real work)
+ *
+ * Result clamped to [0.0, 1.0].
+ */
+export function computeDecisionQuality(params: DecisionQualityInput): number {
+  let score = CONFIDENCE_SCORE_MAP[params.confidence] ?? 0.5;
+
+  if (params.rationale && params.rationale.length > 50) score += 0.1;
+  if (params.contextTaskId) score += 0.05;
+
+  return clamp(score);
+}
+
+// ============================================================================
+// Observation quality
+// ============================================================================
+
+/** Input shape for observation quality computation — mirrors ObserveBrainParams. */
+export interface ObservationQualityInput {
+  text: string;
+  title?: string | null;
+}
+
+/**
+ * Compute quality score for a brain_observations row.
+ *
+ * Base: 0.6 (manual observations start higher than auto-extracted entries).
+ * Bonuses:
+ *   +0.10 if text exceeds 200 chars (rich narrative)
+ *   +0.05 if title exceeds 10 chars (meaningful label)
+ *
+ * Result clamped to [0.0, 1.0].
+ */
+export function computeObservationQuality(params: ObservationQualityInput): number {
+  let score = 0.6;
+
+  if (params.text && params.text.length > 200) score += 0.1;
+  if (params.title && params.title.length > 10) score += 0.05;
+
+  return clamp(score);
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Clamp a score to the valid [0.0, 1.0] range.
+ */
+function clamp(score: number): number {
+  return Math.min(1.0, Math.max(0.0, score));
+}

package/src/sessions/__tests__/session-memory-bridge.test.ts

@@ -1,61 +1,39 @@
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-const mocks = vi.hoisted(() => ({
-  observeBrain: vi.fn(),
-}));
-
-vi.mock('../../memory/brain-retrieval.js', () => ({
-  observeBrain: mocks.observeBrain,
-}));
+import { describe, expect, it } from 'vitest';
 
 import { bridgeSessionToMemory } from '../session-memory-bridge.js';
 
+/**
+ * T527: bridgeSessionToMemory is now a no-op. Session data already lives in
+ * the sessions table; the duplicate observeBrain write and extractSessionEndMemory
+ * call were removed to reduce brain.db noise.
+ *
+ * These tests verify the function remains safe to call from sessions/index.ts
+ * without throwing.
+ */
 describe('bridgeSessionToMemory', () => {
-  beforeEach(() => {
-    mocks.observeBrain.mockReset();
-  });
-
-  it('records a session summary observation on success', async () => {
-    mocks.observeBrain.mockResolvedValue(undefined);
-
-    await bridgeSessionToMemory('/tmp/project', {
-      sessionId: 'session-100',
-      scope: 'epic:T5417',
-      tasksCompleted: ['T5464', 'T5466'],
-      duration: 125,
-    });
-
-    expect(mocks.observeBrain).toHaveBeenCalledTimes(1);
-    expect(mocks.observeBrain).toHaveBeenCalledWith('/tmp/project', {
-      text: 'Session session-100 ended. Scope: epic:T5417. Duration: 2 min. Tasks completed: T5464, T5466.',
-      title: 'Session summary: session-100',
-      type: 'change',
-      sourceSessionId: 'session-100',
-      sourceType: 'agent',
-    });
+  it('resolves without throwing for a normal session', async () => {
+    await expect(
+      bridgeSessionToMemory('/tmp/project', {
+        sessionId: 'session-100',
+        scope: 'epic:T5417',
+        tasksCompleted: ['T5464', 'T5466'],
+        duration: 125,
+      }),
+    ).resolves.toBeUndefined();
   });
 
-  it('uses "none" for empty task completion lists', async () => {
-    mocks.observeBrain.mockResolvedValue(undefined);
-
-    await bridgeSessionToMemory('/tmp/project', {
-      sessionId: 'session-101',
-      scope: 'global',
-      tasksCompleted: [],
-      duration: 59,
-    });
-
-    expect(mocks.observeBrain).toHaveBeenCalledWith(
-      '/tmp/project',
-      expect.objectContaining({
-        text: 'Session session-101 ended. Scope: global. Duration: 1 min. Tasks completed: none.',
+  it('resolves without throwing for empty task completion list', async () => {
+    await expect(
+      bridgeSessionToMemory('/tmp/project', {
+        sessionId: 'session-101',
+        scope: 'global',
+        tasksCompleted: [],
+        duration: 59,
       }),
-    );
+    ).resolves.toBeUndefined();
   });
 
-  it('swallows persistence errors to preserve session-end flow', async () => {
-    mocks.observeBrain.mockRejectedValue(new Error('database is locked'));
-
+  it('resolves without throwing even when called with minimal data', async () => {
     await expect(
       bridgeSessionToMemory('/tmp/project', {
         sessionId: 'session-102',

package/src/sessions/session-memory-bridge.ts

@@ -1,16 +1,19 @@
 /**
- * Memory-session bridge — records session summaries as brain observations.
+ * Memory-session bridge — no-op placeholder retained for call-site compatibility.
  *
- * Hooks into the session end flow to persist a summary of the session's
- * work (tasks completed, scope, duration) into brain.db as an observation.
- * This is best-effort: failures do not affect the session end operation.
+ * Previously this function wrote a session summary observation to brain.db and
+ * triggered auto-extraction of structured memory. Both were removed in T527
+ * because session data already lives in the sessions table; duplicating it to
+ * brain_observations was pure noise.
+ *
+ * The function is kept (as a no-op) so callers in sessions/index.ts do not need
+ * to be updated in this task.
  *
  * @task T5392
  * @epic T5149
+ * @see T527 — removal of duplicate session observation writes
  */
 
-import { observeBrain } from '../memory/brain-retrieval.js';
-
 /** Session data needed to create a memory bridge observation. */
 export interface SessionBridgeData {
   sessionId: string;
@@ -20,50 +23,19 @@ export interface SessionBridgeData {
 }
 
 /**
- * Bridge session end data to brain.db as an observation.
+ * Bridge session end data — currently a no-op.
  *
- * Builds a summary text from the session metadata and saves it
- * as a 'change' observation with source_type 'agent'.
+ * Retained for call-site compatibility. Previously wrote a duplicate summary
+ * observation to brain.db and triggered extractSessionEndMemory; both were
+ * removed in T527 to reduce brain.db noise.
  *
- * @param projectRoot - Project root directory for brain.db resolution
- * @param sessionData - Session metadata to record
+ * @param _projectRoot - Project root directory (unused)
+ * @param _sessionData - Session metadata (unused)
  */
 export async function bridgeSessionToMemory(
-  projectRoot: string,
-  sessionData: SessionBridgeData,
+  _projectRoot: string,
+  _sessionData: SessionBridgeData,
 ): Promise<void> {
-  try {
-    const taskList =
-      sessionData.tasksCompleted.length > 0 ? sessionData.tasksCompleted.join(', ') : 'none';
-
-    const durationMinutes = Math.round(sessionData.duration / 60);
-
-    const summary = [
-      `Session ${sessionData.sessionId} ended.`,
-      `Scope: ${sessionData.scope}.`,
-      `Duration: ${durationMinutes} min.`,
-      `Tasks completed: ${taskList}.`,
-    ].join(' ');
-
-    await observeBrain(projectRoot, {
-      text: summary,
-      title: `Session summary: ${sessionData.sessionId}`,
-      type: 'change',
-      sourceSessionId: sessionData.sessionId,
-      sourceType: 'agent',
-    });
-
-    // Auto-extract structured memory from session end (best-effort)
-    try {
-      const { extractSessionEndMemory, resolveTaskDetails } = await import(
-        '../memory/auto-extract.js'
-      );
-      const taskDetails = await resolveTaskDetails(projectRoot, sessionData.tasksCompleted);
-      await extractSessionEndMemory(projectRoot, sessionData, taskDetails);
-    } catch {
-      /* Session memory extraction is best-effort */
-    }
-  } catch {
-    // Best-effort: session bridge must never fail the session end flow
-  }
+  // T527: Intentional no-op. Session data is already in the sessions table.
+  // Removed: observeBrain duplicate write and extractSessionEndMemory call.
 }

package/src/store/__tests__/brain-accessor-pageindex.test.ts

@@ -5,6 +5,10 @@
  * addPageEdge, getPageEdges, getNeighbors, and removePageEdge using
  * in-memory brain.db instances.
  *
+ * Updated for T528: uses expanded BRAIN_NODE_TYPES and BRAIN_EDGE_TYPES.
+ * Old values mapped per T528 cross-validation report:
+ *   'doc' → 'concept', 'depends_on' → 'derived_from', 'relates_to' → 'informed_by'
+ *
  * @epic T5149
  * @task T5384
  */
@@ -49,6 +53,10 @@ describe('BrainDataAccessor PageIndex', () => {
     expect(node.label).toBe('BRAIN/NEXUS Cognitive Infrastructure');
     expect(node.metadataJson).toBe('{"priority":"critical"}');
     expect(node.createdAt).toBeTruthy();
+    // New fields with defaults
+    expect(node.qualityScore).toBe(0.5);
+    expect(node.contentHash).toBeNull();
+    expect(node.lastActivityAt).toBeTruthy();
   });
 
   it('getPageNode returns node by ID', async () => {
@@ -57,16 +65,17 @@ describe('BrainDataAccessor PageIndex', () => {
     closeBrainDb();
 
     const accessor = await getBrainAccessor();
+    // 'doc' was removed from BRAIN_NODE_TYPES in T528; use 'concept' instead
     await accessor.addPageNode({
-      id: 'doc:BRAIN-SPEC',
-      nodeType: 'doc',
+      id: 'concept:BRAIN-SPEC',
+      nodeType: 'concept',
       label: 'CLEO BRAIN Specification',
     });
 
-    const fetched = await accessor.getPageNode('doc:BRAIN-SPEC');
+    const fetched = await accessor.getPageNode('concept:BRAIN-SPEC');
     expect(fetched).not.toBeNull();
-    expect(fetched!.id).toBe('doc:BRAIN-SPEC');
-    expect(fetched!.nodeType).toBe('doc');
+    expect(fetched!.id).toBe('concept:BRAIN-SPEC');
+    expect(fetched!.nodeType).toBe('concept');
     expect(fetched!.label).toBe('CLEO BRAIN Specification');
   });
 
@@ -87,7 +96,8 @@ describe('BrainDataAccessor PageIndex', () => {
 
     const accessor = await getBrainAccessor();
     await accessor.addPageNode({ id: 'task:T1', nodeType: 'task', label: 'Task 1' });
-    await accessor.addPageNode({ id: 'doc:D1', nodeType: 'doc', label: 'Doc 1' });
+    // 'doc' removed in T528; use 'concept'
+    await accessor.addPageNode({ id: 'concept:D1', nodeType: 'concept', label: 'Concept 1' });
     await accessor.addPageNode({ id: 'task:T2', nodeType: 'task', label: 'Task 2' });
     await accessor.addPageNode({ id: 'file:F1', nodeType: 'file', label: 'File 1' });
 
@@ -95,14 +105,47 @@ describe('BrainDataAccessor PageIndex', () => {
     expect(tasks).toHaveLength(2);
     expect(tasks.every((n) => n.nodeType === 'task')).toBe(true);
 
-    const docs = await accessor.findPageNodes({ nodeType: 'doc' });
-    expect(docs).toHaveLength(1);
-    expect(docs[0]!.id).toBe('doc:D1');
+    const concepts = await accessor.findPageNodes({ nodeType: 'concept' });
+    expect(concepts).toHaveLength(1);
+    expect(concepts[0]!.id).toBe('concept:D1');
 
     const all = await accessor.findPageNodes();
     expect(all).toHaveLength(4);
   });
 
+  it('findPageNodes filters by minQualityScore', async () => {
+    const { getBrainAccessor } = await import('../brain-accessor.js');
+    const { closeBrainDb } = await import('../brain-sqlite.js');
+    closeBrainDb();
+
+    const accessor = await getBrainAccessor();
+    await accessor.addPageNode({
+      id: 'decision:D1',
+      nodeType: 'decision',
+      label: 'High quality',
+      qualityScore: 0.9,
+    });
+    await accessor.addPageNode({
+      id: 'decision:D2',
+      nodeType: 'decision',
+      label: 'Low quality',
+      qualityScore: 0.1,
+    });
+    await accessor.addPageNode({
+      id: 'decision:D3',
+      nodeType: 'decision',
+      label: 'Medium quality',
+      qualityScore: 0.5,
+    });
+
+    const highQuality = await accessor.findPageNodes({ minQualityScore: 0.8 });
+    expect(highQuality).toHaveLength(1);
+    expect(highQuality[0]!.id).toBe('decision:D1');
+
+    const mediumAndAbove = await accessor.findPageNodes({ minQualityScore: 0.5 });
+    expect(mediumAndAbove).toHaveLength(2);
+  });
+
   it('addPageEdge creates edge and returns it', async () => {
     const { getBrainAccessor } = await import('../brain-accessor.js');
     const { closeBrainDb } = await import('../brain-sqlite.js');
@@ -112,20 +155,41 @@ describe('BrainDataAccessor PageIndex', () => {
     await accessor.addPageNode({ id: 'task:T1', nodeType: 'task', label: 'Task 1' });
     await accessor.addPageNode({ id: 'task:T2', nodeType: 'task', label: 'Task 2' });
 
+    // 'depends_on' removed in T528; use 'derived_from'
     const edge = await accessor.addPageEdge({
       fromId: 'task:T1',
       toId: 'task:T2',
-      edgeType: 'depends_on',
+      edgeType: 'derived_from',
       weight: 0.8,
     });
 
     expect(edge.fromId).toBe('task:T1');
     expect(edge.toId).toBe('task:T2');
-    expect(edge.edgeType).toBe('depends_on');
+    expect(edge.edgeType).toBe('derived_from');
     expect(edge.weight).toBe(0.8);
     expect(edge.createdAt).toBeTruthy();
   });
 
+  it('addPageEdge supports provenance field', async () => {
+    const { getBrainAccessor } = await import('../brain-accessor.js');
+    const { closeBrainDb } = await import('../brain-sqlite.js');
+    closeBrainDb();
+
+    const accessor = await getBrainAccessor();
+    await accessor.addPageNode({ id: 'observation:O1', nodeType: 'observation', label: 'Obs 1' });
+    await accessor.addPageNode({ id: 'decision:D1', nodeType: 'decision', label: 'Decision 1' });
+
+    const edge = await accessor.addPageEdge({
+      fromId: 'observation:O1',
+      toId: 'decision:D1',
+      edgeType: 'supports',
+      provenance: 'auto:task-complete',
+    });
+
+    expect(edge.provenance).toBe('auto:task-complete');
+    expect(edge.weight).toBe(1.0);
+  });
+
   it('getPageEdges returns in/out/both edges', async () => {
     const { getBrainAccessor } = await import('../brain-accessor.js');
     const { closeBrainDb } = await import('../brain-sqlite.js');
@@ -134,9 +198,11 @@ describe('BrainDataAccessor PageIndex', () => {
     const accessor = await getBrainAccessor();
     await accessor.addPageNode({ id: 'A', nodeType: 'task', label: 'A' });
     await accessor.addPageNode({ id: 'B', nodeType: 'task', label: 'B' });
-    await accessor.addPageNode({ id: 'C', nodeType: 'doc', label: 'C' });
+    // 'concept' replaces 'doc'
+    await accessor.addPageNode({ id: 'C', nodeType: 'concept', label: 'C' });
 
-    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'depends_on' });
+    // 'depends_on' → 'derived_from'; 'documents' is still valid
+    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'derived_from' });
     await accessor.addPageEdge({ fromId: 'C', toId: 'A', edgeType: 'documents' });
 
     const outEdges = await accessor.getPageEdges('A', 'out');
@@ -159,15 +225,17 @@ describe('BrainDataAccessor PageIndex', () => {
     const accessor = await getBrainAccessor();
     await accessor.addPageNode({ id: 'A', nodeType: 'task', label: 'A' });
     await accessor.addPageNode({ id: 'B', nodeType: 'task', label: 'B' });
-    await accessor.addPageNode({ id: 'C', nodeType: 'doc', label: 'C' });
+    // 'concept' replaces 'doc'
+    await accessor.addPageNode({ id: 'C', nodeType: 'concept', label: 'C' });
 
-    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'depends_on' });
+    // 'depends_on' → 'derived_from'; 'documents' is still valid
+    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'derived_from' });
     await accessor.addPageEdge({ fromId: 'A', toId: 'C', edgeType: 'documents' });
 
     const allNeighbors = await accessor.getNeighbors('A');
     expect(allNeighbors).toHaveLength(2);
 
-    const depNeighbors = await accessor.getNeighbors('A', 'depends_on');
+    const depNeighbors = await accessor.getNeighbors('A', 'derived_from');
     expect(depNeighbors).toHaveLength(1);
     expect(depNeighbors[0]!.id).toBe('B');
   });
@@ -180,9 +248,11 @@ describe('BrainDataAccessor PageIndex', () => {
     const accessor = await getBrainAccessor();
     await accessor.addPageNode({ id: 'A', nodeType: 'task', label: 'A' });
     await accessor.addPageNode({ id: 'B', nodeType: 'task', label: 'B' });
-    await accessor.addPageNode({ id: 'C', nodeType: 'doc', label: 'C' });
+    // 'concept' replaces 'doc'
+    await accessor.addPageNode({ id: 'C', nodeType: 'concept', label: 'C' });
 
-    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'depends_on' });
+    // 'depends_on' → 'derived_from'; 'documents' is still valid
+    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'derived_from' });
     await accessor.addPageEdge({ fromId: 'C', toId: 'A', edgeType: 'documents' });
 
     await accessor.removePageNode('A');
@@ -209,16 +279,17 @@ describe('BrainDataAccessor PageIndex', () => {
     await accessor.addPageNode({ id: 'A', nodeType: 'task', label: 'A' });
     await accessor.addPageNode({ id: 'B', nodeType: 'task', label: 'B' });
 
-    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'depends_on' });
-    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'relates_to' });
+    // 'depends_on' → 'derived_from'; 'relates_to' → 'informed_by'
+    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'derived_from' });
+    await accessor.addPageEdge({ fromId: 'A', toId: 'B', edgeType: 'informed_by' });
 
     let edges = await accessor.getPageEdges('A', 'out');
     expect(edges).toHaveLength(2);
 
-    await accessor.removePageEdge('A', 'B', 'depends_on');
+    await accessor.removePageEdge('A', 'B', 'derived_from');
 
     edges = await accessor.getPageEdges('A', 'out');
     expect(edges).toHaveLength(1);
-    expect(edges[0]!.edgeType).toBe('relates_to');
+    expect(edges[0]!.edgeType).toBe('informed_by');
   });
 });

package/src/store/brain-accessor.ts

@@ -439,18 +439,25 @@ export class BrainDataAccessor {
   }
 
   async findPageNodes(
-    params: { nodeType?: (typeof brainSchema.BRAIN_NODE_TYPES)[number]; limit?: number } = {},
+    params: {
+      nodeType?: (typeof brainSchema.BRAIN_NODE_TYPES)[number];
+      minQualityScore?: number;
+      limit?: number;
+    } = {},
   ): Promise<BrainPageNodeRow[]> {
     const conditions: SQL[] = [];
 
     if (params.nodeType) {
       conditions.push(eq(brainSchema.brainPageNodes.nodeType, params.nodeType));
     }
+    if (params.minQualityScore !== undefined) {
+      conditions.push(gte(brainSchema.brainPageNodes.qualityScore, params.minQualityScore));
+    }
 
     let query = this.db
       .select()
       .from(brainSchema.brainPageNodes)
-      .orderBy(desc(brainSchema.brainPageNodes.createdAt));
+      .orderBy(desc(brainSchema.brainPageNodes.lastActivityAt));
 
     if (conditions.length > 0) {
       query = query.where(and(...conditions)) as typeof query;
@@ -463,6 +470,13 @@ export class BrainDataAccessor {
     return query;
   }
 
+  async updatePageNode(id: string, updates: Partial<NewBrainPageNodeRow>): Promise<void> {
+    await this.db
+      .update(brainSchema.brainPageNodes)
+      .set({ ...updates, updatedAt: new Date().toISOString().replace('T', ' ').slice(0, 19) })
+      .where(eq(brainSchema.brainPageNodes.id, id));
+  }
+
   async removePageNode(id: string): Promise<void> {
     // Remove associated edges first (both directions)
     await this.db
@@ -493,6 +507,38 @@ export class BrainDataAccessor {
     return result[0]!;
   }
 
+  async findPageEdges(
+    params: {
+      edgeType?: (typeof brainSchema.BRAIN_EDGE_TYPES)[number];
+      provenance?: string;
+      limit?: number;
+    } = {},
+  ): Promise<BrainPageEdgeRow[]> {
+    const conditions: SQL[] = [];
+
+    if (params.edgeType) {
+      conditions.push(eq(brainSchema.brainPageEdges.edgeType, params.edgeType));
+    }
+    if (params.provenance) {
+      conditions.push(eq(brainSchema.brainPageEdges.provenance, params.provenance));
+    }
+
+    let query = this.db
+      .select()
+      .from(brainSchema.brainPageEdges)
+      .orderBy(desc(brainSchema.brainPageEdges.createdAt));
+
+    if (conditions.length > 0) {
+      query = query.where(and(...conditions)) as typeof query;
+    }
+
+    if (params.limit) {
+      query = query.limit(params.limit) as typeof query;
+    }
+
+    return query;
+  }
+
   async getPageEdges(
     nodeId: string,
     direction: 'in' | 'out' | 'both' = 'both',