@cleocode/core 2026.4.58 → 2026.4.59

package/dist/memory/graph-auto-populate.js

@@ -0,0 +1,148 @@
+/**
+ * Graph auto-population helpers for CLEO BRAIN.
+ *
+ * Provides upsertGraphNode and addGraphEdge helpers that write to the
+ * brain_page_nodes and brain_page_edges tables whenever memory entries
+ * are created via the legitimate write paths (storeDecision, observeBrain,
+ * storePattern, storeLearning, and task completion).
+ *
+ * Design constraints:
+ * - All writes are BEST-EFFORT — never block or fail the primary operation.
+ * - All writes are gated on brain.autoCapture via isAutoCaptureEnabled.
+ * - Uses INSERT OR REPLACE (onConflictDoUpdate) for upsert semantics.
+ * - Edge inserts are idempotent via the composite PK (fromId, toId, edgeType).
+ *
+ * @task T537
+ * @epic T523
+ */
+import { createHash } from 'node:crypto';
+import { brainPageEdges, brainPageNodes } from '../store/brain-schema.js';
+import { getBrainDb } from '../store/brain-sqlite.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Return true when brain.autoCapture is enabled for the project.
+ * Delegates to the shared isAutoCaptureEnabled helper in handler-helpers.ts.
+ * Returns false on any error to keep graph writes safely disabled when the
+ * config or brain.db is unavailable.
+ */
+async function shouldAutoPopulateGraph(projectRoot) {
+    try {
+        const { isAutoCaptureEnabled } = await import('../hooks/handlers/handler-helpers.js');
+        return isAutoCaptureEnabled(projectRoot);
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Upsert a graph node for a typed table entry.
+ *
+ * Uses INSERT OR REPLACE to handle both new and existing entries. If the
+ * node already exists (same id), its label, qualityScore, lastActivityAt,
+ * updatedAt, and metadataJson are refreshed while createdAt is preserved.
+ *
+ * The contentHash is derived from a SHA-256 prefix of the canonical content.
+ * External-reference nodes (task, session, epic) may pass an empty string for
+ * content; their hash will be null so duplicates are not rejected.
+ *
+ * This function is gated on brain.autoCapture. If the gate is disabled or any
+ * error occurs, it returns silently without throwing.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param nodeId - Stable composite ID in the form '<type>:<source-id>'.
+ * @param nodeType - Discriminated type from BRAIN_NODE_TYPES.
+ * @param label - Human-readable label (title, task ID, etc.).
+ * @param qualityScore - 0.0 (noise) to 1.0 (canonical).
+ * @param content - Canonical text used to derive the content hash.
+ * @param metadata - Optional type-specific metadata blob.
+ *
+ * @task T537
+ */
+export async function upsertGraphNode(projectRoot, nodeId, nodeType, label, qualityScore, content, metadata) {
+    try {
+        if (!(await shouldAutoPopulateGraph(projectRoot)))
+            return;
+        const db = await getBrainDb(projectRoot);
+        const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        // Only compute a content hash for non-trivial content (external reference
+        // nodes like task/session/epic may have empty content).
+        const trimmed = content.trim().toLowerCase();
+        const contentHash = trimmed
+            ? createHash('sha256').update(trimmed).digest('hex').substring(0, 16)
+            : null;
+        await db
+            .insert(brainPageNodes)
+            .values({
+            id: nodeId,
+            nodeType,
+            label: label.substring(0, 200),
+            qualityScore,
+            contentHash,
+            metadataJson: metadata ? JSON.stringify(metadata) : null,
+            lastActivityAt: now,
+            createdAt: now,
+            updatedAt: now,
+        })
+            .onConflictDoUpdate({
+            target: brainPageNodes.id,
+            set: {
+                label: label.substring(0, 200),
+                qualityScore,
+                lastActivityAt: now,
+                updatedAt: now,
+                metadataJson: metadata ? JSON.stringify(metadata) : null,
+            },
+        });
+    }
+    catch (err) {
+        // Log but never surface — this is a best-effort side effect.
+        console.warn('[brain-graph] upsertGraphNode failed:', err);
+    }
+}
+/**
+ * Add a directed, typed edge between two graph nodes (idempotent).
+ *
+ * The composite primary key (fromId, toId, edgeType) prevents duplicate edges
+ * of the same type. Conflicting rows are ignored so this is safe to call
+ * multiple times with the same arguments.
+ *
+ * This function is gated on brain.autoCapture. If the gate is disabled or any
+ * error occurs, it returns silently without throwing.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @param fromId - Source node ID (brain_page_nodes.id).
+ * @param toId - Target node ID (brain_page_nodes.id or external nexus ID).
+ * @param edgeType - Typed relationship from BRAIN_EDGE_TYPES.
+ * @param weight - Edge confidence/weight (0.0–1.0). Defaults to 1.0.
+ * @param provenance - Human-readable note on why this edge was emitted.
+ *
+ * @task T537
+ */
+export async function addGraphEdge(projectRoot, fromId, toId, edgeType, weight = 1.0, provenance) {
+    try {
+        if (!(await shouldAutoPopulateGraph(projectRoot)))
+            return;
+        const db = await getBrainDb(projectRoot);
+        const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        await db
+            .insert(brainPageEdges)
+            .values({
+            fromId,
+            toId,
+            edgeType,
+            weight,
+            provenance: provenance ?? null,
+            createdAt: now,
+        })
+            .onConflictDoNothing();
+    }
+    catch (err) {
+        console.warn('[brain-graph] addGraphEdge failed:', err);
+    }
+}
+//# sourceMappingURL=graph-auto-populate.js.map

package/dist/memory/graph-auto-populate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-auto-populate.js","sourceRoot":"","sources":["../../src/memory/graph-auto-populate.ts"],"names":[],"mappings":"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"}

package/dist/memory/graph-memory-bridge.js

@@ -0,0 +1,517 @@
+/**
+ * Graph Memory Bridge — connects brain.db memory nodes to nexus.db code nodes.
+ *
+ * Scans brain observations, decisions, patterns, and learnings for entity
+ * references (file paths, function names, symbol names) and matches them
+ * against nexus_nodes in the global nexus.db. Matching pairs are linked via
+ * `code_reference` edges written to brain_page_edges in brain.db.
+ *
+ * Design constraints:
+ * - brain.db is read-write (edges written here).
+ * - nexus.db is READ-ONLY from this module — never mutated.
+ * - All operations are BEST-EFFORT; failures never surface to callers.
+ * - Cross-DB join is handled in-process: read nexus nodes, then write brain edges.
+ * - Entity matching: exact match on filePath or symbol name; fuzzy match on
+ *   symbol name (case-insensitive substring, minimum 4 chars).
+ *
+ * @task graph-memory-bridge
+ * @epic T523
+ */
+import { brainPageEdges, brainPageNodes } from '../store/brain-schema.js';
+import { getBrainDb, getBrainNativeDb } from '../store/brain-sqlite.js';
+import { getNexusDb, getNexusNativeDb } from '../store/nexus-sqlite.js';
+import { typedAll } from '../store/typed-query.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Regex patterns to extract entity references from text.
+ *
+ * Matches:
+ * - File paths: relative paths ending in known source extensions
+ * - Function/symbol names: camelCase, PascalCase, snake_case identifiers (≥4 chars)
+ */
+const FILE_PATH_PATTERN = /(?:^|\s|['"`(])([a-zA-Z0-9_\-./]+\.(?:ts|tsx|js|jsx|rs|go|py|mjs|cjs))(?:$|\s|['"`)])/g;
+const SYMBOL_PATTERN = /\b([a-zA-Z_][a-zA-Z0-9_]*(?:[A-Z][a-zA-Z0-9_]*)+|[a-zA-Z_]{4,}[a-zA-Z0-9_]*)\b/g;
+/** Common stop-words to skip in symbol extraction (short-circuits false positives). */
+const SYMBOL_STOP_WORDS = new Set([
+    'true',
+    'false',
+    'null',
+    'undefined',
+    'const',
+    'async',
+    'await',
+    'return',
+    'export',
+    'import',
+    'from',
+    'type',
+    'interface',
+    'function',
+    'class',
+    'this',
+    'super',
+    'extends',
+    'implements',
+    'with',
+    'that',
+    'then',
+    'when',
+    'have',
+    'been',
+    'will',
+    'should',
+    'could',
+    'would',
+    'error',
+    'result',
+    'value',
+    'data',
+    'info',
+    'note',
+    'todo',
+    'done',
+    'fail',
+    'pass',
+]);
+/**
+ * Extract file paths from text.
+ */
+function extractFilePaths(text) {
+    const paths = new Set();
+    for (const m of text.matchAll(FILE_PATH_PATTERN)) {
+        const p = m[1];
+        if (p)
+            paths.add(p);
+    }
+    return Array.from(paths);
+}
+/**
+ * Extract potential symbol names from text (camelCase / PascalCase / snake_case ≥ 4 chars).
+ */
+function extractSymbolCandidates(text) {
+    const syms = new Set();
+    for (const m of text.matchAll(SYMBOL_PATTERN)) {
+        const s = m[1];
+        if (s && s.length >= 4 && !SYMBOL_STOP_WORDS.has(s.toLowerCase())) {
+            syms.add(s);
+        }
+    }
+    return Array.from(syms);
+}
+/**
+ * Build a plain-text corpus from a brain_page_nodes metadata_json blob.
+ * Returns empty string if metadata is absent or malformed.
+ */
+function metadataText(metaJson) {
+    if (!metaJson)
+        return '';
+    try {
+        const obj = JSON.parse(metaJson);
+        return Object.values(obj)
+            .filter((v) => typeof v === 'string')
+            .join(' ');
+    }
+    catch {
+        return '';
+    }
+}
+// ---------------------------------------------------------------------------
+// linkMemoryToCode — manual single-link creation
+// ---------------------------------------------------------------------------
+/**
+ * Create a `code_reference` edge from a brain memory node to a nexus code node.
+ *
+ * Writes to brain_page_edges (brain.db). The nexus node must already exist in
+ * nexus.db but is never mutated. The brain node is upserted as a stub if it
+ * does not yet exist in brain_page_nodes.
+ *
+ * This function is idempotent — calling it multiple times with the same
+ * (memoryId, codeSymbol) pair is safe (the composite PK prevents duplicates).
+ *
+ * @param projectRoot - Absolute path to project root (locates brain.db)
+ * @param memoryId - Brain memory node ID (format: '<type>:<source-id>')
+ * @param codeSymbol - Nexus node ID (format: '<filePath>::<name>' or '<filePath>')
+ * @returns True if the edge was created or already existed; false on error
+ */
+export async function linkMemoryToCode(projectRoot, memoryId, codeSymbol) {
+    try {
+        const brainDb = await getBrainDb(projectRoot);
+        // Ensure nexus.db is initialized so we can verify the target node exists
+        await getNexusDb();
+        const nexusNative = getNexusNativeDb();
+        if (!nexusNative)
+            return false;
+        // Verify the nexus node exists (read-only check)
+        const nexusNode = nexusNative
+            .prepare('SELECT id, label, file_path, kind FROM nexus_nodes WHERE id = ? LIMIT 1')
+            .get(codeSymbol);
+        if (!nexusNode)
+            return false;
+        const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        // Upsert the memory node stub in brain_page_nodes so the edge FK is satisfied
+        // (the real node may already exist from graph-auto-populate; onConflictDoUpdate
+        //  only refreshes lastActivityAt if the node already exists).
+        const idParts = memoryId.split(':');
+        const nodeType = idParts[0] ?? 'observation';
+        await brainDb
+            .insert(brainPageNodes)
+            .values({
+            id: memoryId,
+            nodeType,
+            label: memoryId,
+            qualityScore: 0.5,
+            contentHash: null,
+            lastActivityAt: now,
+            createdAt: now,
+            updatedAt: now,
+        })
+            .onConflictDoUpdate({
+            target: brainPageNodes.id,
+            set: { lastActivityAt: now, updatedAt: now },
+        });
+        // Write the code_reference edge ('code_reference' is now in BRAIN_EDGE_TYPES — T645)
+        await brainDb
+            .insert(brainPageEdges)
+            .values({
+            fromId: memoryId,
+            toId: codeSymbol,
+            edgeType: 'code_reference',
+            weight: 1.0,
+            provenance: 'manual',
+            createdAt: now,
+        })
+            .onConflictDoNothing();
+        return true;
+    }
+    catch (err) {
+        console.warn('[graph-memory-bridge] linkMemoryToCode failed:', err);
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// autoLinkMemories — scan brain nodes and link to nexus matches
+// ---------------------------------------------------------------------------
+/**
+ * Scan brain memory nodes for entity references and match them against nexus.
+ *
+ * For each brain node, extracts:
+ * - File path references → matched against nexus_nodes.file_path (exact)
+ * - Symbol name references → matched against nexus_nodes.name (exact, then fuzzy)
+ *
+ * Matching edges are written to brain_page_edges with edgeType='code_reference'.
+ * This function is idempotent — existing edges are skipped.
+ *
+ * Should be called from runConsolidation() as a best-effort step. All errors
+ * are caught and logged; never throws.
+ *
+ * @param projectRoot - Absolute path to project root (locates brain.db)
+ * @returns Summary of scanned entries and created links
+ */
+export async function autoLinkMemories(projectRoot) {
+    const result = { scanned: 0, linked: 0, alreadyLinked: 0, links: [] };
+    try {
+        await getBrainDb(projectRoot);
+        const brainNative = getBrainNativeDb();
+        await getNexusDb();
+        const nexusNative = getNexusNativeDb();
+        if (!brainNative || !nexusNative)
+            return result;
+        // Load all brain page nodes that are memory entity types
+        const brainNodes = typedAll(brainNative.prepare(`
+        SELECT id, node_type, label, quality_score, metadata_json
+        FROM brain_page_nodes
+        WHERE node_type IN ('observation', 'decision', 'pattern', 'learning')
+          AND quality_score >= 0.3
+        ORDER BY quality_score DESC
+        LIMIT 500
+      `));
+        result.scanned = brainNodes.length;
+        if (brainNodes.length === 0)
+            return result;
+        // Load nexus nodes into memory (indexed by name and filePath for fast lookup).
+        // We load only essential columns to keep memory usage low.
+        const nexusNodes = typedAll(nexusNative.prepare(`
+        SELECT id, label, name, file_path, kind
+        FROM nexus_nodes
+        WHERE kind NOT IN ('community', 'process', 'folder')
+        LIMIT 20000
+      `));
+        if (nexusNodes.length === 0)
+            return result;
+        // Build lookup indexes
+        const byFilePath = new Map();
+        const byNameExact = new Map();
+        const byNameLower = new Map();
+        for (const node of nexusNodes) {
+            if (node.file_path) {
+                const fp = node.file_path.toLowerCase();
+                const existing = byFilePath.get(fp) ?? [];
+                existing.push(node);
+                byFilePath.set(fp, existing);
+            }
+            if (node.name) {
+                // Exact (case-sensitive)
+                const exact = byNameExact.get(node.name) ?? [];
+                exact.push(node);
+                byNameExact.set(node.name, exact);
+                // Lowercase for fuzzy
+                const lower = node.name.toLowerCase();
+                const fuzzy = byNameLower.get(lower) ?? [];
+                fuzzy.push(node);
+                byNameLower.set(lower, fuzzy);
+            }
+        }
+        const now = new Date().toISOString().replace('T', ' ').slice(0, 19);
+        // Load existing code_reference edges to avoid duplicates
+        const existingEdges = new Set();
+        const rawEdges = typedAll(brainNative.prepare(`
+        SELECT from_id, to_id FROM brain_page_edges WHERE edge_type = 'code_reference'
+      `));
+        for (const e of rawEdges) {
+            existingEdges.add(`${e.from_id}|${e.to_id}`);
+        }
+        // Process each brain node
+        for (const brainNode of brainNodes) {
+            const corpus = `${brainNode.label} ${metadataText(brainNode.metadata_json)}`;
+            const filePaths = extractFilePaths(corpus);
+            const symbolCandidates = extractSymbolCandidates(corpus);
+            const candidates = [];
+            // 1. Exact file path matches
+            for (const fp of filePaths) {
+                const matches = byFilePath.get(fp.toLowerCase());
+                if (matches) {
+                    for (const n of matches) {
+                        candidates.push({ nexusNode: n, strategy: 'exact-file', weight: 1.0 });
+                    }
+                }
+            }
+            // 2. Exact symbol name matches
+            for (const sym of symbolCandidates) {
+                const exactMatches = byNameExact.get(sym);
+                if (exactMatches) {
+                    for (const n of exactMatches) {
+                        candidates.push({ nexusNode: n, strategy: 'exact-symbol', weight: 1.0 });
+                    }
+                }
+            }
+            // 3. Fuzzy (case-insensitive) symbol matches — only for symbols not already exact-matched
+            const exactSymSet = new Set(symbolCandidates.flatMap((s) => byNameExact.get(s) ?? []).map((n) => n.id));
+            for (const sym of symbolCandidates) {
+                if (sym.length < 5)
+                    continue; // skip very short symbols for fuzzy
+                const lower = sym.toLowerCase();
+                const fuzzyMatches = byNameLower.get(lower);
+                if (fuzzyMatches) {
+                    for (const n of fuzzyMatches) {
+                        if (!exactSymSet.has(n.id)) {
+                            candidates.push({ nexusNode: n, strategy: 'fuzzy-symbol', weight: 0.6 });
+                        }
+                    }
+                }
+            }
+            // Deduplicate candidates (keep highest weight per nexus node)
+            const bestByNexusId = new Map();
+            for (const c of candidates) {
+                const existing = bestByNexusId.get(c.nexusNode.id);
+                if (!existing || c.weight > existing.weight) {
+                    bestByNexusId.set(c.nexusNode.id, c);
+                }
+            }
+            // Write edges (cap at 10 per brain node to avoid noise)
+            const sortedCandidates = Array.from(bestByNexusId.values())
+                .sort((a, b) => b.weight - a.weight)
+                .slice(0, 10);
+            for (const { nexusNode, strategy, weight } of sortedCandidates) {
+                const edgeKey = `${brainNode.id}|${nexusNode.id}`;
+                if (existingEdges.has(edgeKey)) {
+                    result.alreadyLinked++;
+                    continue;
+                }
+                // Upsert brain node stub (idempotent — real node may already exist)
+                brainNative
+                    .prepare(`
+            INSERT OR IGNORE INTO brain_page_nodes
+              (id, node_type, label, quality_score, content_hash, metadata_json, last_activity_at, created_at, updated_at)
+            VALUES (?, ?, ?, ?, NULL, NULL, ?, ?, ?)
+          `)
+                    .run(brainNode.id, brainNode.node_type, brainNode.label, brainNode.quality_score, now, now, now);
+                // Write edge
+                try {
+                    brainNative
+                        .prepare(`
+              INSERT OR IGNORE INTO brain_page_edges
+                (from_id, to_id, edge_type, weight, provenance, created_at)
+              VALUES (?, ?, 'code_reference', ?, ?, ?)
+            `)
+                        .run(brainNode.id, nexusNode.id, weight, `auto:${strategy}`, now);
+                    existingEdges.add(edgeKey);
+                    result.linked++;
+                    result.links.push({
+                        brainNodeId: brainNode.id,
+                        nexusNodeId: nexusNode.id,
+                        nexusLabel: nexusNode.label,
+                        matchStrategy: strategy,
+                        weight,
+                    });
+                }
+                catch (edgeErr) {
+                    console.warn('[graph-memory-bridge] edge insert failed:', edgeErr);
+                }
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[graph-memory-bridge] autoLinkMemories failed:', err);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// queryMemoriesForCode — find memories related to a code symbol
+// ---------------------------------------------------------------------------
+/**
+ * Given a code symbol (nexus node ID), find related brain memory nodes.
+ *
+ * Traverses `code_reference` edges in brain_page_edges where the target is
+ * the given nexus node ID. Returns the brain memory nodes with edge metadata.
+ *
+ * @param projectRoot - Absolute path to project root (locates brain.db)
+ * @param symbol - Nexus node ID (format: '<filePath>::<name>' or '<filePath>')
+ * @returns Memory nodes that reference the given code symbol
+ */
+export async function queryMemoriesForCode(projectRoot, symbol) {
+    const result = { nexusNodeId: symbol, memories: [] };
+    try {
+        await getBrainDb(projectRoot);
+        const brainNative = getBrainNativeDb();
+        if (!brainNative)
+            return result;
+        const rows = typedAll(brainNative.prepare(`
+        SELECT n.id, n.node_type, n.label, n.quality_score,
+               e.weight, e.provenance
+        FROM brain_page_edges e
+        JOIN brain_page_nodes n ON n.id = e.from_id
+        WHERE e.to_id = ?
+          AND e.edge_type = 'code_reference'
+        ORDER BY e.weight DESC, n.quality_score DESC
+        LIMIT 50
+      `), symbol);
+        result.memories = rows.map((r) => ({
+            nodeId: r.id,
+            nodeType: r.node_type,
+            label: r.label,
+            qualityScore: r.quality_score,
+            edgeWeight: r.weight,
+            matchStrategy: r.provenance?.replace('auto:', '') ?? 'manual',
+        }));
+    }
+    catch (err) {
+        console.warn('[graph-memory-bridge] queryMemoriesForCode failed:', err);
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// queryCodeForMemory — find code nodes related to a memory entry
+// ---------------------------------------------------------------------------
+/**
+ * Given a brain memory node ID, find related nexus code nodes.
+ *
+ * Traverses `code_reference` edges in brain_page_edges from the given memory
+ * node ID, then fetches the corresponding nexus node metadata.
+ *
+ * @param projectRoot - Absolute path to project root (locates brain.db)
+ * @param memoryId - Brain memory node ID (format: '<type>:<source-id>')
+ * @returns Nexus code nodes referenced by the given memory entry
+ */
+export async function queryCodeForMemory(projectRoot, memoryId) {
+    const result = { brainNodeId: memoryId, codeNodes: [] };
+    try {
+        await getBrainDb(projectRoot);
+        const brainNative = getBrainNativeDb();
+        await getNexusDb();
+        const nexusNative = getNexusNativeDb();
+        if (!brainNative || !nexusNative)
+            return result;
+        const brainEdges = typedAll(brainNative.prepare(`
+        SELECT to_id, weight, provenance
+        FROM brain_page_edges
+        WHERE from_id = ?
+          AND edge_type = 'code_reference'
+        ORDER BY weight DESC
+        LIMIT 50
+      `), memoryId);
+        if (brainEdges.length === 0)
+            return result;
+        // Fetch nexus node metadata for each target (read-only)
+        for (const edge of brainEdges) {
+            const nexusNode = nexusNative
+                .prepare('SELECT id, label, file_path, kind FROM nexus_nodes WHERE id = ? LIMIT 1')
+                .get(edge.to_id);
+            if (nexusNode) {
+                result.codeNodes.push({
+                    nexusNodeId: nexusNode.id,
+                    label: nexusNode.label,
+                    filePath: nexusNode.file_path,
+                    kind: nexusNode.kind,
+                    edgeWeight: edge.weight,
+                    matchStrategy: edge.provenance?.replace('auto:', '') ?? 'manual',
+                });
+            }
+        }
+    }
+    catch (err) {
+        console.warn('[graph-memory-bridge] queryCodeForMemory failed:', err);
+    }
+    return result;
+}
+/**
+ * Return all `code_reference` edges from brain.db enriched with nexus metadata.
+ *
+ * Used by `cleo memory code-links` CLI command.
+ *
+ * @param projectRoot - Absolute path to project root (locates brain.db)
+ * @param limit - Maximum number of entries to return (default 100)
+ * @returns Array of code link entries sorted by weight descending
+ */
+export async function listCodeLinks(projectRoot, limit = 100) {
+    const entries = [];
+    try {
+        await getBrainDb(projectRoot);
+        const brainNative = getBrainNativeDb();
+        await getNexusDb();
+        const nexusNative = getNexusNativeDb();
+        if (!brainNative || !nexusNative)
+            return entries;
+        const rows = typedAll(brainNative.prepare(`
+        SELECT e.from_id, e.to_id, e.weight, e.created_at,
+               n.node_type, n.label
+        FROM brain_page_edges e
+        JOIN brain_page_nodes n ON n.id = e.from_id
+        WHERE e.edge_type = 'code_reference'
+        ORDER BY e.weight DESC, e.created_at DESC
+        LIMIT ?
+      `), limit);
+        for (const row of rows) {
+            const nexusNode = nexusNative
+                .prepare('SELECT id, label, file_path, kind FROM nexus_nodes WHERE id = ? LIMIT 1')
+                .get(row.to_id);
+            entries.push({
+                brainNodeId: row.from_id,
+                brainNodeType: row.node_type,
+                brainNodeLabel: row.label,
+                nexusNodeId: row.to_id,
+                nexusNodeLabel: nexusNode?.label ?? row.to_id,
+                filePath: nexusNode?.file_path ?? null,
+                kind: nexusNode?.kind ?? 'unknown',
+                weight: row.weight,
+                createdAt: row.created_at,
+            });
+        }
+    }
+    catch (err) {
+        console.warn('[graph-memory-bridge] listCodeLinks failed:', err);
+    }
+    return entries;
+}
+//# sourceMappingURL=graph-memory-bridge.js.map