@prih/mcp-graph-memory 1.0.3

package/dist/lib/search/bm25.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * BM25 keyword search index with incremental updates.
+ * Used alongside vector cosine similarity for hybrid search.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BM25Index = void 0;
+exports.tokenize = tokenize;
+exports.rrfFuse = rrfFuse;
+// ---------------------------------------------------------------------------
+// Tokenizer
+// ---------------------------------------------------------------------------
+/**
+ * Tokenize text: split on whitespace/punctuation, split camelCase, lowercase.
+ * "getUserById" → ["get", "user", "by", "id"]
+ * "JWT tokens" → ["jwt", "tokens"]
+ */
+function tokenize(text) {
+    if (!text)
+        return [];
+    // Split camelCase/PascalCase boundaries, then split on non-alphanumeric
+    const parts = text
+        .replace(/([a-z])([A-Z])/g, '$1 $2') // camelCase → camel Case
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2') // XMLParser → XML Parser
+        .split(/[^a-zA-Z0-9]+/)
+        .map(t => t.toLowerCase())
+        .filter(t => t.length > 0);
+    return parts;
+}
+// ---------------------------------------------------------------------------
+// BM25 Index
+// ---------------------------------------------------------------------------
+class BM25Index {
+    docs = new Map();
+    df = new Map(); // document frequency per term
+    totalLength = 0;
+    k1;
+    b;
+    textExtractor;
+    constructor(textExtractor, opts) {
+        this.textExtractor = textExtractor;
+        this.k1 = opts?.k1 ?? 1.2;
+        this.b = opts?.b ?? 0.75;
+    }
+    get size() {
+        return this.docs.size;
+    }
+    hasDocument(id) {
+        return this.docs.has(id);
+    }
+    addDocument(id, attrs) {
+        // Remove old version first if exists
+        if (this.docs.has(id))
+            this.removeDocument(id);
+        const text = this.textExtractor(attrs);
+        const tokens = tokenize(text);
+        const termFreqs = new Map();
+        for (const token of tokens) {
+            termFreqs.set(token, (termFreqs.get(token) ?? 0) + 1);
+        }
+        // Update document frequency for each unique term
+        for (const term of termFreqs.keys()) {
+            this.df.set(term, (this.df.get(term) ?? 0) + 1);
+        }
+        this.docs.set(id, { termFreqs, length: tokens.length });
+        this.totalLength += tokens.length;
+    }
+    removeDocument(id) {
+        const doc = this.docs.get(id);
+        if (!doc)
+            return;
+        // Decrement document frequency for each unique term
+        for (const term of doc.termFreqs.keys()) {
+            const current = this.df.get(term) ?? 0;
+            if (current <= 1) {
+                this.df.delete(term);
+            }
+            else {
+                this.df.set(term, current - 1);
+            }
+        }
+        this.totalLength -= doc.length;
+        this.docs.delete(id);
+    }
+    updateDocument(id, attrs) {
+        this.removeDocument(id);
+        this.addDocument(id, attrs);
+    }
+    clear() {
+        this.docs.clear();
+        this.df.clear();
+        this.totalLength = 0;
+    }
+    /**
+     * Compute BM25 scores for all documents matching the query.
+     * Returns only documents with score > 0 (at least one query term matches).
+     */
+    score(query) {
+        const queryTokens = tokenize(query);
+        if (queryTokens.length === 0)
+            return new Map();
+        const N = this.docs.size;
+        if (N === 0)
+            return new Map();
+        const avgDl = this.totalLength / N;
+        const results = new Map();
+        for (const [id, doc] of this.docs) {
+            let docScore = 0;
+            for (const term of queryTokens) {
+                const tf = doc.termFreqs.get(term) ?? 0;
+                if (tf === 0)
+                    continue;
+                const docFreq = this.df.get(term) ?? 0;
+                // IDF: log((N - df + 0.5) / (df + 0.5) + 1)
+                const idf = Math.log((N - docFreq + 0.5) / (docFreq + 0.5) + 1);
+                // TF saturation: (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * dl/avgdl))
+                const tfNorm = (tf * (this.k1 + 1)) / (tf + this.k1 * (1 - this.b + this.b * doc.length / avgDl));
+                docScore += idf * tfNorm;
+            }
+            if (docScore > 0) {
+                results.set(id, docScore);
+            }
+        }
+        return results;
+    }
+}
+exports.BM25Index = BM25Index;
+// ---------------------------------------------------------------------------
+// Reciprocal Rank Fusion
+// ---------------------------------------------------------------------------
+/**
+ * Fuse two ranked lists using Reciprocal Rank Fusion (RRF).
+ * score(d) = 1/(k + rank_vector(d)) + 1/(k + rank_bm25(d))
+ *
+ * Nodes appearing in only one list get rank = Infinity for the other → only 1/(k+rank) from one source.
+ */
+function rrfFuse(vectorScores, bm25Scores, k = 60) {
+    // Build ranked lists (sorted desc by score, rank starts at 1)
+    const vectorRank = buildRankMap(vectorScores);
+    const bm25Rank = buildRankMap(bm25Scores);
+    // Collect all unique document IDs
+    const allIds = new Set();
+    for (const id of vectorScores.keys())
+        allIds.add(id);
+    for (const id of bm25Scores.keys())
+        allIds.add(id);
+    const fused = new Map();
+    for (const id of allIds) {
+        const vRank = vectorRank.get(id);
+        const bRank = bm25Rank.get(id);
+        let score = 0;
+        if (vRank != null)
+            score += 1 / (k + vRank);
+        if (bRank != null)
+            score += 1 / (k + bRank);
+        fused.set(id, score);
+    }
+    return fused;
+}
+function buildRankMap(scores) {
+    const sorted = [...scores.entries()].sort((a, b) => b[1] - a[1]);
+    const ranks = new Map();
+    for (let i = 0; i < sorted.length; i++) {
+        ranks.set(sorted[i][0], i + 1); // rank starts at 1
+    }
+    return ranks;
+}

package/dist/lib/search/code.js

@@ -0,0 +1,103 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchCode = searchCode;
+const embedder_1 = require("../../lib/embedder");
+const bm25_1 = require("../../lib/search/bm25");
+/**
+ * Semantic search over the code graph.
+ *
+ * 1. Score every node by cosine similarity to the query embedding.
+ * 2. Filter seeds below `minScore`, take top `topK`.
+ * 3. BFS expansion via graph edges up to `bfsDepth` hops with score decay.
+ * 4. De-duplicate, re-filter, sort, cap at `maxResults`.
+ */
+function searchCode(graph, queryEmbedding, options = {}) {
+    const { topK = 5, bfsDepth = 1, maxResults = 20, minScore = 0.5, bfsDecay = 0.8, queryText, bm25Index, searchMode = 'hybrid', rrfK = 60 } = options;
+    const useVector = searchMode !== 'keyword';
+    const useBm25 = searchMode !== 'vector' && !!queryText && !!bm25Index;
+    // --- 1. Score all nodes ---
+    const scored = [];
+    if (useVector) {
+        graph.forEachNode((id, attrs) => {
+            if (attrs.embedding.length === 0)
+                return;
+            scored.push({ id, score: (0, embedder_1.cosineSimilarity)(queryEmbedding, attrs.embedding) });
+        });
+    }
+    if (useBm25) {
+        const bm25Scores = bm25Index.score(queryText);
+        const positiveScored = useVector ? scored.filter(s => s.score > 0) : [];
+        if (positiveScored.length > 0) {
+            const vectorMap = new Map(positiveScored.map(s => [s.id, s.score]));
+            const fused = (0, bm25_1.rrfFuse)(vectorMap, bm25Scores, rrfK);
+            scored.length = 0;
+            for (const [id, score] of fused)
+                scored.push({ id, score });
+        }
+        else {
+            scored.length = 0;
+            for (const [id, score] of bm25Scores)
+                scored.push({ id, score });
+        }
+        // Normalize scores to 0–1 so minScore threshold works uniformly
+        const maxScore = scored.reduce((m, s) => Math.max(m, s.score), 0);
+        if (maxScore > 0) {
+            for (const s of scored)
+                s.score /= maxScore;
+        }
+    }
+    if (scored.length === 0)
+        return [];
+    scored.sort((a, b) => b.score - a.score);
+    // --- 2. Filter seeds ---
+    const minS = minScore;
+    const seeds = scored.filter(s => s.score >= minS).slice(0, topK);
+    if (seeds.length === 0)
+        return [];
+    // --- 3. BFS expansion ---
+    const scoreMap = new Map(seeds.map(s => [s.id, s.score]));
+    function bfs(startId, seedScore) {
+        const queue = [
+            { id: startId, depth: 0, score: seedScore },
+        ];
+        const visited = new Set();
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (visited.has(item.id))
+                continue;
+            visited.add(item.id);
+            const prev = scoreMap.get(item.id) ?? -Infinity;
+            if (item.score > prev)
+                scoreMap.set(item.id, item.score);
+            if (item.depth >= bfsDepth)
+                continue;
+            if (item.score * bfsDecay < minS)
+                continue;
+            const nextScore = item.score * bfsDecay;
+            graph.outNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+            graph.inNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+        }
+    }
+    for (const seed of seeds) {
+        bfs(seed.id, seed.score);
+    }
+    // --- 4. Build results ---
+    return [...scoreMap.entries()]
+        .filter(([, score]) => score >= minS)
+        .map(([id, score]) => {
+        const attrs = graph.getNodeAttributes(id);
+        return {
+            id,
+            fileId: attrs.fileId,
+            kind: attrs.kind,
+            name: attrs.name,
+            signature: attrs.signature,
+            docComment: attrs.docComment,
+            startLine: attrs.startLine,
+            endLine: attrs.endLine,
+            score,
+        };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+}

package/dist/lib/search/docs.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.search = search;
+const embedder_1 = require("../../lib/embedder");
+const bm25_1 = require("../../lib/search/bm25");
+/**
+ * Semantic search over the graph.
+ *
+ * 1. Score every node by cosine similarity to the query embedding.
+ * 2. Discard seeds below `minScore` (default 0 = keep all).
+ * 3. Take the top `topK` remaining seeds.
+ * 4. BFS from each seed up to `bfsDepth` hops; BFS nodes inherit the seed's
+ *    score multiplied by `bfsDecay` per hop (default 0.8), so deeper nodes
+ *    rank lower and are filtered by `minScore` too.
+ * 5. De-duplicate and return results sorted by score, capped at `maxResults`.
+ */
+function search(graph, queryEmbedding, options = {}) {
+    const { topK = 5, bfsDepth = 1, maxResults = 20, minScore = 0.5, bfsDecay = 0.8, queryText, bm25Index, searchMode = 'hybrid', rrfK = 60 } = options;
+    const useVector = searchMode !== 'keyword';
+    const useBm25 = searchMode !== 'vector' && !!queryText && !!bm25Index;
+    // --- 1. Score all nodes ---
+    const scored = [];
+    if (useVector) {
+        graph.forEachNode((id, attrs) => {
+            if (attrs.embedding.length === 0)
+                return;
+            scored.push({ id, score: (0, embedder_1.cosineSimilarity)(queryEmbedding, attrs.embedding) });
+        });
+    }
+    if (useBm25) {
+        const bm25Scores = bm25Index.score(queryText);
+        // Only include vector results with positive scores for fusion
+        const positiveScored = useVector ? scored.filter(s => s.score > 0) : [];
+        if (positiveScored.length > 0) {
+            // RRF fusion
+            const vectorMap = new Map(positiveScored.map(s => [s.id, s.score]));
+            const fused = (0, bm25_1.rrfFuse)(vectorMap, bm25Scores, rrfK);
+            scored.length = 0;
+            for (const [id, score] of fused)
+                scored.push({ id, score });
+        }
+        else {
+            // BM25-only or vector returned nothing — use BM25 as fallback
+            scored.length = 0;
+            for (const [id, score] of bm25Scores)
+                scored.push({ id, score });
+        }
+        // Normalize scores to 0–1 so minScore threshold works uniformly
+        const maxScore = scored.reduce((m, s) => Math.max(m, s.score), 0);
+        if (maxScore > 0) {
+            for (const s of scored)
+                s.score /= maxScore;
+        }
+    }
+    if (scored.length === 0)
+        return [];
+    scored.sort((a, b) => b.score - a.score);
+    // --- 2. Filter seeds by minScore, then take topK ---
+    const minS = minScore;
+    const seeds = scored.filter(s => s.score >= minS).slice(0, topK);
+    if (seeds.length === 0)
+        return [];
+    // --- 3. BFS expansion with score decay ---
+    // scoreMap holds the best score seen for each node
+    const scoreMap = new Map(seeds.map(s => [s.id, s.score]));
+    function bfs(startId, seedScore) {
+        const queue = [
+            { id: startId, depth: 0, score: seedScore },
+        ];
+        const localVisited = new Set();
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (localVisited.has(item.id))
+                continue;
+            localVisited.add(item.id);
+            // Keep the best score this node has received across all BFS runs
+            const prev = scoreMap.get(item.id) ?? -Infinity;
+            if (item.score > prev)
+                scoreMap.set(item.id, item.score);
+            if (item.depth >= bfsDepth)
+                continue;
+            if (item.score * bfsDecay < minS)
+                continue; // prune: deeper hops won't pass threshold
+            const nextScore = item.score * bfsDecay;
+            graph.outNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+            graph.inNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+        }
+    }
+    for (const seed of seeds) {
+        bfs(seed.id, seed.score);
+    }
+    // --- 4. Build results from scoreMap, apply minScore filter, sort, cap ---
+    return [...scoreMap.entries()]
+        .filter(([, score]) => score >= minS)
+        .map(([id, score]) => {
+        const attrs = graph.getNodeAttributes(id);
+        return {
+            id,
+            fileId: attrs.fileId,
+            title: attrs.title,
+            content: attrs.content,
+            level: attrs.level,
+            score,
+        };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+}

package/dist/lib/search/file-index.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchFileIndex = searchFileIndex;
+const embedder_1 = require("../../lib/embedder");
+/**
+ * Semantic search over file nodes by path embedding.
+ * Only searches file nodes (directories have empty embeddings).
+ * Pure cosine similarity, no BFS expansion.
+ */
+function searchFileIndex(graph, queryEmbedding, options = {}) {
+    const { topK = 10, minScore = 0.3 } = options;
+    const scored = [];
+    graph.forEachNode((_, attrs) => {
+        if (attrs.kind !== 'file' || attrs.embedding.length === 0)
+            return;
+        const score = (0, embedder_1.cosineSimilarity)(queryEmbedding, attrs.embedding);
+        if (score >= minScore) {
+            scored.push({
+                filePath: attrs.filePath,
+                fileName: attrs.fileName,
+                extension: attrs.extension,
+                language: attrs.language,
+                size: attrs.size,
+                score,
+            });
+        }
+    });
+    return scored
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK);
+}

package/dist/lib/search/files.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchDocFiles = searchDocFiles;
+exports.searchCodeFiles = searchCodeFiles;
+const embedder_1 = require("../../lib/embedder");
+function searchDocFiles(graph, queryEmbedding, options = {}) {
+    const { topK = 10, minScore = 0.3 } = options;
+    // Collect root chunks (level=1) that have a fileEmbedding
+    const scored = [];
+    graph.forEachNode((_, attrs) => {
+        if (attrs.level !== 1 || attrs.fileEmbedding.length === 0)
+            return;
+        scored.push({
+            fileId: attrs.fileId,
+            title: attrs.title,
+            score: (0, embedder_1.cosineSimilarity)(queryEmbedding, attrs.fileEmbedding),
+        });
+    });
+    // Count chunks per file
+    const chunkCounts = new Map();
+    graph.forEachNode((_, attrs) => {
+        chunkCounts.set(attrs.fileId, (chunkCounts.get(attrs.fileId) ?? 0) + 1);
+    });
+    return scored
+        .filter(s => s.score >= minScore)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK)
+        .map(s => ({
+        fileId: s.fileId,
+        title: s.title,
+        chunks: chunkCounts.get(s.fileId) ?? 0,
+        score: s.score,
+    }));
+}
+function searchCodeFiles(graph, queryEmbedding, options = {}) {
+    const { topK = 10, minScore = 0.3 } = options;
+    // Collect file nodes that have a fileEmbedding
+    const scored = [];
+    graph.forEachNode((_, attrs) => {
+        if (attrs.kind !== 'file' || attrs.fileEmbedding.length === 0)
+            return;
+        scored.push({
+            fileId: attrs.fileId,
+            score: (0, embedder_1.cosineSimilarity)(queryEmbedding, attrs.fileEmbedding),
+        });
+    });
+    // Count symbols per file
+    const symbolCounts = new Map();
+    graph.forEachNode((_, attrs) => {
+        symbolCounts.set(attrs.fileId, (symbolCounts.get(attrs.fileId) ?? 0) + 1);
+    });
+    return scored
+        .filter(s => s.score >= minScore)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, topK)
+        .map(s => ({
+        fileId: s.fileId,
+        symbolCount: symbolCounts.get(s.fileId) ?? 0,
+        score: s.score,
+    }));
+}

package/dist/lib/search/knowledge.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchKnowledge = searchKnowledge;
+const embedder_1 = require("../../lib/embedder");
+const bm25_1 = require("../../lib/search/bm25");
+/**
+ * Semantic search over the knowledge graph.
+ *
+ * 1. Score every node by cosine similarity to the query embedding.
+ * 2. Filter seeds below `minScore`, take top `topK`.
+ * 3. BFS expansion via relation edges up to `bfsDepth` hops with score decay.
+ * 4. De-duplicate, re-filter, sort, cap at `maxResults`.
+ */
+function searchKnowledge(graph, queryEmbedding, options = {}) {
+    const { topK = 5, bfsDepth = 1, maxResults = 20, minScore = 0.5, bfsDecay = 0.8, queryText, bm25Index, searchMode = 'hybrid', rrfK = 60 } = options;
+    const useVector = searchMode !== 'keyword';
+    const useBm25 = searchMode !== 'vector' && !!queryText && !!bm25Index;
+    // --- 1. Score all nodes (skip proxy nodes) ---
+    const scored = [];
+    if (useVector) {
+        graph.forEachNode((id, attrs) => {
+            if (attrs.proxyFor)
+                return;
+            if (attrs.embedding.length === 0)
+                return;
+            scored.push({ id, score: (0, embedder_1.cosineSimilarity)(queryEmbedding, attrs.embedding) });
+        });
+    }
+    if (useBm25) {
+        const bm25Scores = bm25Index.score(queryText);
+        const positiveScored = useVector ? scored.filter(s => s.score > 0) : [];
+        if (positiveScored.length > 0) {
+            const vectorMap = new Map(positiveScored.map(s => [s.id, s.score]));
+            const fused = (0, bm25_1.rrfFuse)(vectorMap, bm25Scores, rrfK);
+            scored.length = 0;
+            for (const [id, score] of fused)
+                scored.push({ id, score });
+        }
+        else {
+            scored.length = 0;
+            for (const [id, score] of bm25Scores)
+                scored.push({ id, score });
+        }
+        // Normalize scores to 0–1 so minScore threshold works uniformly
+        const maxScore = scored.reduce((m, s) => Math.max(m, s.score), 0);
+        if (maxScore > 0) {
+            for (const s of scored)
+                s.score /= maxScore;
+        }
+    }
+    if (scored.length === 0)
+        return [];
+    scored.sort((a, b) => b.score - a.score);
+    // --- 2. Filter seeds ---
+    const minS = minScore;
+    const seeds = scored.filter(s => s.score >= minS).slice(0, topK);
+    if (seeds.length === 0)
+        return [];
+    // --- 3. BFS expansion ---
+    const scoreMap = new Map(seeds.map(s => [s.id, s.score]));
+    function bfs(startId, seedScore) {
+        const queue = [
+            { id: startId, depth: 0, score: seedScore },
+        ];
+        const visited = new Set();
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (visited.has(item.id))
+                continue;
+            visited.add(item.id);
+            const prev = scoreMap.get(item.id) ?? -Infinity;
+            if (item.score > prev)
+                scoreMap.set(item.id, item.score);
+            if (item.depth >= bfsDepth)
+                continue;
+            if (item.score * bfsDecay < minS)
+                continue;
+            const nextScore = item.score * bfsDecay;
+            graph.outNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+            graph.inNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+        }
+    }
+    for (const seed of seeds) {
+        bfs(seed.id, seed.score);
+    }
+    // --- 4. Build results (exclude proxy nodes) ---
+    return [...scoreMap.entries()]
+        .filter(([id, score]) => score >= minS && !graph.getNodeAttribute(id, 'proxyFor'))
+        .map(([id, score]) => {
+        const attrs = graph.getNodeAttributes(id);
+        return {
+            id,
+            title: attrs.title,
+            content: attrs.content,
+            tags: attrs.tags,
+            score,
+        };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+}

package/dist/lib/search/skills.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.searchSkills = searchSkills;
+const embedder_1 = require("../../lib/embedder");
+const bm25_1 = require("../../lib/search/bm25");
+/**
+ * Semantic search over the skill graph.
+ *
+ * 1. Score every node by cosine similarity to the query embedding.
+ * 2. Filter seeds below `minScore`, take top `topK`.
+ * 3. BFS expansion via relation edges up to `bfsDepth` hops with score decay.
+ * 4. De-duplicate, re-filter, sort, cap at `maxResults`.
+ */
+function searchSkills(graph, queryEmbedding, options = {}) {
+    const { topK = 5, bfsDepth = 1, maxResults = 20, minScore = 0.5, bfsDecay = 0.8, queryText, bm25Index, searchMode = 'hybrid', rrfK = 60 } = options;
+    const useVector = searchMode !== 'keyword';
+    const useBm25 = searchMode !== 'vector' && !!queryText && !!bm25Index;
+    // --- 1. Score all nodes (skip proxy nodes) ---
+    const scored = [];
+    if (useVector) {
+        graph.forEachNode((id, attrs) => {
+            if (attrs.proxyFor)
+                return;
+            if (attrs.embedding.length === 0)
+                return;
+            scored.push({ id, score: (0, embedder_1.cosineSimilarity)(queryEmbedding, attrs.embedding) });
+        });
+    }
+    if (useBm25) {
+        const bm25Scores = bm25Index.score(queryText);
+        const positiveScored = useVector ? scored.filter(s => s.score > 0) : [];
+        if (positiveScored.length > 0) {
+            const vectorMap = new Map(positiveScored.map(s => [s.id, s.score]));
+            const fused = (0, bm25_1.rrfFuse)(vectorMap, bm25Scores, rrfK);
+            scored.length = 0;
+            for (const [id, score] of fused)
+                scored.push({ id, score });
+        }
+        else {
+            scored.length = 0;
+            for (const [id, score] of bm25Scores)
+                scored.push({ id, score });
+        }
+        // Normalize scores to 0–1 so minScore threshold works uniformly
+        const maxScore = scored.reduce((m, s) => Math.max(m, s.score), 0);
+        if (maxScore > 0) {
+            for (const s of scored)
+                s.score /= maxScore;
+        }
+    }
+    if (scored.length === 0)
+        return [];
+    scored.sort((a, b) => b.score - a.score);
+    // --- 2. Filter seeds ---
+    const minS = minScore;
+    const seeds = scored.filter(s => s.score >= minS).slice(0, topK);
+    if (seeds.length === 0)
+        return [];
+    // --- 3. BFS expansion ---
+    const scoreMap = new Map(seeds.map(s => [s.id, s.score]));
+    function bfs(startId, seedScore) {
+        const queue = [
+            { id: startId, depth: 0, score: seedScore },
+        ];
+        const visited = new Set();
+        while (queue.length > 0) {
+            const item = queue.shift();
+            if (visited.has(item.id))
+                continue;
+            visited.add(item.id);
+            const prev = scoreMap.get(item.id) ?? -Infinity;
+            if (item.score > prev)
+                scoreMap.set(item.id, item.score);
+            if (item.depth >= bfsDepth)
+                continue;
+            if (item.score * bfsDecay < minS)
+                continue;
+            const nextScore = item.score * bfsDecay;
+            graph.outNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+            graph.inNeighbors(item.id).forEach(n => queue.push({ id: n, depth: item.depth + 1, score: nextScore }));
+        }
+    }
+    for (const seed of seeds) {
+        bfs(seed.id, seed.score);
+    }
+    // --- 4. Build results (exclude proxy nodes) ---
+    return [...scoreMap.entries()]
+        .filter(([id, score]) => score >= minS && !graph.getNodeAttribute(id, 'proxyFor'))
+        .map(([id, score]) => {
+        const attrs = graph.getNodeAttributes(id);
+        return {
+            id,
+            title: attrs.title,
+            description: attrs.description,
+            source: attrs.source,
+            confidence: attrs.confidence,
+            usageCount: attrs.usageCount,
+            tags: attrs.tags,
+            score,
+        };
+    })
+        .sort((a, b) => b.score - a.score)
+        .slice(0, maxResults);
+}