byterover-cli 1.7.2 → 2.0.0

package/dist/agent/infra/tools/implementations/search-knowledge-service.js

@@ -2,13 +2,40 @@ import MiniSearch from 'minisearch';
 import { join } from 'node:path';
 import { removeStopwords } from 'stopword';
 import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR } from '../../../../server/constants.js';
+import { parseFrontmatterScoring, updateScoringInContent, } from '../../../../server/core/domain/knowledge/markdown-writer.js';
+import { applyDecay, applyDefaultScoring, compoundScore, determineTier, recordAccessHits, } from '../../../../server/core/domain/knowledge/memory-scoring.js';
+import { isPathLikeQuery, matchMemoryPath, parseSymbolicQuery } from './memory-path-matcher.js';
+import { buildReferenceIndex, buildSymbolTree, getSubtreeDocumentIds, getSymbolKindLabel, getSymbolOverview, MemorySymbolKind, } from './memory-symbol-tree.js';
 const MAX_CONTEXT_TREE_FILES = 10_000;
 const DEFAULT_CACHE_TTL_MS = 5000;
+/** Bump when MINISEARCH_OPTIONS fields/boost change to invalidate cached indexes */
+const INDEX_SCHEMA_VERSION = 4;
+/** Only include results whose normalized score is at least this fraction of the top result's score */
+const SCORE_GAP_RATIO = 0.75;
+/** Minimum normalized score for the top result. Below this, the query is considered out-of-domain */
+const MINIMUM_RELEVANCE_SCORE = 0.6;
+/** Normalized score threshold above which results are trusted despite unmatched query terms */
+const UNMATCHED_TERM_SCORE_THRESHOLD = 0.85;
+/** Minimum query term length to consider "significant" for OOD term-based detection */
+const UNMATCHED_TERM_MIN_LENGTH = 4;
+/** Chunk size in characters for smart excerpt extraction (~200 tokens) */
+const CHUNK_SIZE_CHARS = 800;
+/** Overlap between chunks in characters (15% of chunk size) */
+const CHUNK_OVERLAP_CHARS = 120;
+/**
+ * Normalize raw MiniSearch BM25 score to [0, 1) range.
+ * Uses the monotonic formula: score / (1 + score)
+ * Maps: strong(15)→0.94, medium(8)→0.89, moderate(4)→0.80, weak(1)→0.50, none(0)→0.
+ * Query-independent — no per-query normalization needed.
+ */
+function normalizeScore(rawScore) {
+    return rawScore / (1 + rawScore);
+}
 const MINISEARCH_OPTIONS = {
-    fields: ['title', 'content'],
+    fields: ['title', 'content', 'path'],
     idField: 'id',
     searchOptions: {
-        boost: { title: 2 },
+        boost: { path: 1.5, title: 3 },
         fuzzy: 0.2,
         prefix: true,
     },
@@ -19,48 +46,116 @@ function filterStopWords(query) {
     const filtered = removeStopwords(words);
     return filtered.length > 0 ? filtered.join(' ') : query;
 }
+/**
+ * Checks if any significant query term is completely unmatched across search results.
+ * Uses MiniSearch's queryTerms property to identify which terms actually matched.
+ * A "significant" term is one with length >= UNMATCHED_TERM_MIN_LENGTH (filters out
+ * short generic words that are noisy for OOD detection).
+ */
+function hasUnmatchedSignificantTerms(queryTerms, searchResults) {
+    const significantTerms = queryTerms.filter((t) => t.length >= UNMATCHED_TERM_MIN_LENGTH);
+    if (significantTerms.length === 0)
+        return false;
+    const allMatchedQueryTerms = new Set();
+    for (const result of searchResults.slice(0, 10)) {
+        for (const term of result.queryTerms) {
+            allMatchedQueryTerms.add(term);
+        }
+    }
+    return significantTerms.some((t) => !allMatchedQueryTerms.has(t));
+}
 function extractTitle(content, fallbackTitle) {
     const match = /^# (.+)$/m.exec(content);
     return match ? match[1].trim() : fallbackTitle;
 }
+/**
+ * Find the best semantic break point in a chunk slice.
+ * Searches the last 30% of the text for break points with priority:
+ * paragraph (\n\n) > sentence (. ? !) > line (\n).
+ * Returns the character offset to break at, or -1 if no good break found.
+ */
+function findBreakPoint(slice) {
+    const searchStart = Math.floor(slice.length * 0.7);
+    const searchSlice = slice.slice(searchStart);
+    const paraBreak = searchSlice.lastIndexOf('\n\n');
+    if (paraBreak !== -1) {
+        return searchStart + paraBreak + 2;
+    }
+    const sentEnd = Math.max(searchSlice.lastIndexOf('. '), searchSlice.lastIndexOf('.\n'), searchSlice.lastIndexOf('? '), searchSlice.lastIndexOf('?\n'), searchSlice.lastIndexOf('! '), searchSlice.lastIndexOf('!\n'));
+    if (sentEnd !== -1) {
+        return searchStart + sentEnd + 2;
+    }
+    const lineBreak = searchSlice.lastIndexOf('\n');
+    if (lineBreak !== -1) {
+        return searchStart + lineBreak + 1;
+    }
+    return -1;
+}
+/**
+ * Chunk a document into overlapping pieces with smart break-point detection.
+ * Inspired by QMD's chunking strategy — breaks at semantic boundaries
+ * (paragraph > sentence > line > word) for coherent excerpts.
+ */
+function chunkDocument(content) {
+    if (content.length <= CHUNK_SIZE_CHARS) {
+        return [{ pos: 0, text: content }];
+    }
+    const chunks = [];
+    let charPos = 0;
+    while (charPos < content.length) {
+        let endPos = Math.min(charPos + CHUNK_SIZE_CHARS, content.length);
+        // Find best break point in last 30% of chunk
+        if (endPos < content.length) {
+            const breakOffset = findBreakPoint(content.slice(charPos, endPos));
+            if (breakOffset !== -1) {
+                endPos = charPos + breakOffset;
+            }
+        }
+        // Ensure forward progress
+        if (endPos <= charPos) {
+            endPos = Math.min(charPos + CHUNK_SIZE_CHARS, content.length);
+        }
+        chunks.push({ pos: charPos, text: content.slice(charPos, endPos) });
+        if (endPos >= content.length)
+            break;
+        // Overlap with previous chunk
+        charPos = endPos - CHUNK_OVERLAP_CHARS;
+        if (charPos <= chunks.at(-1).pos) {
+            charPos = endPos;
+        }
+    }
+    return chunks;
+}
 function extractExcerpt(content, query, maxLength = 800) {
+    // Strip ## Relations section and title heading
     const relationsMatch = /^## Relations\n([\S\s]*?)(?=\n## |\n# |$)/m.exec(content);
     let cleanContent = content;
     if (relationsMatch) {
         cleanContent = content.replace(relationsMatch[0], '').trim();
     }
     cleanContent = cleanContent.replace(/^# .+$/m, '').trim();
+    // Chunk the document into semantically coherent pieces
+    const chunks = chunkDocument(cleanContent);
+    // Score each chunk by query term density and pick the best
     const queryTerms = query
         .toLowerCase()
         .split(/\s+/)
         .filter((t) => t.length >= 2);
-    const lines = cleanContent.split('\n');
-    let bestStartIndex = 0;
-    let bestScore = 0;
-    for (const [i, line] of lines.entries()) {
-        const lineLower = line.toLowerCase();
-        let score = 0;
-        for (const term of queryTerms) {
-            if (lineLower.includes(term)) {
-                score++;
-            }
-        }
+    let bestChunk = chunks[0];
+    let bestScore = -1;
+    for (const chunk of chunks) {
+        const chunkLower = chunk.text.toLowerCase();
+        const score = queryTerms.reduce((acc, term) => acc + (chunkLower.includes(term) ? 1 : 0), 0);
         if (score > bestScore) {
             bestScore = score;
-            bestStartIndex = i;
+            bestChunk = chunk;
         }
     }
-    let excerpt = '';
-    for (const line of lines.slice(bestStartIndex)) {
-        if (excerpt.length >= maxLength)
-            break;
-        excerpt += line + '\n';
-    }
-    excerpt = excerpt.trim();
+    let excerpt = bestChunk.text.trim();
     if (excerpt.length > maxLength) {
         excerpt = excerpt.slice(0, maxLength).trim() + '...';
     }
-    else if (bestStartIndex > 0 || excerpt.length < cleanContent.length) {
+    else if (chunks.length > 1) {
         excerpt += '...';
     }
     return excerpt || cleanContent.slice(0, maxLength) + (cleanContent.length > maxLength ? '...' : '');
@@ -110,6 +205,9 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             fileMtimes: new Map(),
             index,
             lastValidatedAt: now,
+            referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
+            schemaVersion: INDEX_SCHEMA_VERSION,
+            symbolTree: { root: [], symbolMap: new Map() },
         };
     }
     const documentPromises = filesWithMtime.map(async ({ mtime, path: filePath }) => {
@@ -117,11 +215,13 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             const fullPath = join(contextTreePath, filePath);
             const { content } = await fileSystem.readFile(fullPath);
             const title = extractTitle(content, filePath.replace(/\.md$/, '').split('/').pop() || filePath);
+            const scoring = parseFrontmatterScoring(content) ?? applyDefaultScoring();
             return {
                 content,
                 id: filePath,
                 mtime,
                 path: filePath,
+                scoring,
                 title,
             };
         }
@@ -139,23 +239,30 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
     }
     const index = new MiniSearch(MINISEARCH_OPTIONS);
     index.addAll(documents);
+    // Build symbolic structures from the document map
+    const symbolTree = buildSymbolTree(documentMap);
+    const referenceIndex = buildReferenceIndex(documentMap);
     return {
         contextTreePath,
         documentMap,
         fileMtimes,
         index,
         lastValidatedAt: now,
+        referenceIndex,
+        schemaVersion: INDEX_SCHEMA_VERSION,
+        symbolTree,
     };
 }
 /**
  * Acquires the search index, using cached data when valid or building a fresh index.
  * Uses promise-based locking to prevent duplicate builds during parallel execution.
  */
-async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
+async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeBuild) {
     const now = Date.now();
     // Fast path: TTL-based cache hit (no I/O needed)
     if (state.cachedIndex &&
         state.cachedIndex.contextTreePath === contextTreePath &&
+        state.cachedIndex.schemaVersion === INDEX_SCHEMA_VERSION &&
         ttlMs > 0 &&
         now - state.cachedIndex.lastValidatedAt < ttlMs) {
         return state.cachedIndex;
@@ -181,6 +288,9 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
                     fileMtimes: new Map(),
                     index: emptyIndex,
                     lastValidatedAt: 0,
+                    referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
+                    schemaVersion: INDEX_SCHEMA_VERSION,
+                    symbolTree: { root: [], symbolMap: new Map() },
                 };
             }
         }
@@ -188,6 +298,7 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
         // Re-check cache validity after getting file list (another call may have finished)
         if (state.cachedIndex &&
             state.cachedIndex.contextTreePath === contextTreePath &&
+            state.cachedIndex.schemaVersion === INDEX_SCHEMA_VERSION &&
             isCacheValid(state.cachedIndex, currentFiles)) {
             // Update timestamp atomically by creating a new object
             const updatedCache = {
@@ -197,6 +308,10 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs) {
             state.cachedIndex = updatedCache;
             return updatedCache;
         }
+        // Flush pending access hits before building so updated scoring is picked up
+        if (onBeforeBuild) {
+            await onBeforeBuild(contextTreePath);
+        }
         // Build fresh index
         const freshIndex = await buildFreshIndex(fileSystem, contextTreePath, currentFiles);
         state.cachedIndex = freshIndex;
@@ -232,6 +347,7 @@ export class SearchKnowledgeService {
     baseDirectory;
     cacheTtlMs;
     fileSystem;
+    pendingAccessHits = new Map();
     state = {
         buildingPromise: undefined,
         cachedIndex: undefined,
@@ -241,23 +357,52 @@ export class SearchKnowledgeService {
         this.baseDirectory = config.baseDirectory ?? process.cwd();
         this.cacheTtlMs = config.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
     }
+    /**
+     * Flush accumulated access hits to disk by updating frontmatter scoring.
+     * Called during index rebuild to batch writes and avoid write amplification.
+     * Best-effort: errors are swallowed per file.
+     */
+    async flushAccessHits(contextTreePath) {
+        if (this.pendingAccessHits.size === 0) {
+            return;
+        }
+        const hits = new Map(this.pendingAccessHits);
+        this.pendingAccessHits.clear();
+        const tasks = [...hits.entries()].map(async ([relPath, count]) => {
+            try {
+                const fullPath = join(contextTreePath, relPath);
+                const { content } = await this.fileSystem.readFile(fullPath);
+                const scoring = parseFrontmatterScoring(content) ?? applyDefaultScoring();
+                const updated = recordAccessHits(scoring, count);
+                const newTier = determineTier(updated.importance ?? 50, (updated.maturity ?? 'draft'));
+                const finalScoring = { ...updated, maturity: newTier };
+                const newContent = updateScoringInContent(content, finalScoring);
+                await this.fileSystem.writeFile(fullPath, newContent);
+            }
+            catch {
+                // Best-effort — swallow per-file errors
+            }
+        });
+        await Promise.allSettled(tasks);
+    }
     /**
      * Search the knowledge base for relevant topics.
+     * Supports symbolic path queries, scoped search, kind/maturity filtering, and overview mode.
      *
-     * @param query - Natural language query string
-     * @param options - Search options
-     * @returns Search results with matching topics
+     * @param query - Natural language query string or symbolic path (e.g. "auth/jwt")
+     * @param options - Search options including symbolic filters
+     * @returns Search results with matching topics, enriched with symbolic metadata
      */
     async search(query, options) {
         const limit = options?.limit ?? 10;
         const contextTreePath = join(this.baseDirectory, BRV_DIR, CONTEXT_TREE_DIR);
-        // Acquire index with parallel-safe locking
-        const indexResult = await acquireIndex(this.state, this.fileSystem, contextTreePath, this.cacheTtlMs);
+        // Acquire index with parallel-safe locking; flush pending access hits before any rebuild
+        const indexResult = await acquireIndex(this.state, this.fileSystem, contextTreePath, this.cacheTtlMs, (ctxPath) => this.flushAccessHits(ctxPath));
         // Handle error case (context tree not initialized)
         if ('error' in indexResult) {
             return indexResult.result;
         }
-        const { documentMap, index } = indexResult;
+        const { documentMap, index, referenceIndex, symbolTree } = indexResult;
         if (documentMap.size === 0) {
             return {
                 message: 'Context tree is empty. Use /curate to add knowledge.',
@@ -265,22 +410,179 @@ export class SearchKnowledgeService {
                 totalFound: 0,
             };
         }
+        // Overview mode: return tree structure instead of search results
+        if (options?.overview) {
+            return this.buildOverviewResult(symbolTree, referenceIndex, options.scope, options.overviewDepth);
+        }
+        // Symbolic path resolution: try path-based query first
+        if (isPathLikeQuery(query, symbolTree)) {
+            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, options);
+            if (symbolicResult) {
+                return symbolicResult;
+            }
+        }
+        // Parse query for potential scope prefix (e.g. "auth jwt refresh" → scope=auth, text="jwt refresh")
+        const parsed = parseSymbolicQuery(query, symbolTree);
+        const effectiveScope = options?.scope ?? parsed.scopePath;
+        const effectiveQuery = parsed.scopePath ? parsed.textQuery : query;
+        // Run text-based MiniSearch (existing pipeline), optionally scoped to a subtree
+        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, symbolTree, referenceIndex, options);
+        // If scoped search returned nothing and we had a scope, fall back to global search
+        if (textResult.results.length === 0 && effectiveScope && effectiveQuery) {
+            return this.runTextSearch(query, documentMap, index, limit, undefined, symbolTree, referenceIndex, options);
+        }
+        return textResult;
+    }
+    accumulateAccessHits(paths) {
+        for (const path of paths) {
+            this.pendingAccessHits.set(path, (this.pendingAccessHits.get(path) ?? 0) + 1);
+        }
+    }
+    /**
+     * Build overview result showing the tree structure at configurable depth.
+     */
+    buildOverviewResult(symbolTree, referenceIndex, scope, depth) {
+        const entries = getSymbolOverview(symbolTree, scope, depth ?? 2);
+        const results = entries.map((entry) => ({
+            backlinkCount: referenceIndex.backlinks.get(entry.path)?.length ?? 0,
+            excerpt: `${entry.kind} | ${entry.childCount} children | maturity: ${entry.maturity}`,
+            path: entry.path,
+            score: entry.importance / 100,
+            symbolKind: entry.kind,
+            symbolPath: entry.path,
+            title: entry.name,
+        }));
+        const domainCount = entries.filter((e) => e.kind === 'domain').length;
+        const topicCount = entries.filter((e) => e.kind === 'topic').length;
+        return {
+            message: `Knowledge tree overview (${domainCount} domains, ${topicCount} topics).`,
+            results,
+            totalFound: entries.length,
+        };
+    }
+    /**
+     * Enrich a search result with symbolic metadata and backlink info.
+     */
+    enrichResult(result, symbolTree, referenceIndex) {
+        const symbol = symbolTree.symbolMap.get(result.path);
+        const backlinks = referenceIndex.backlinks.get(result.path);
+        return {
+            ...result,
+            backlinkCount: backlinks?.length ?? 0,
+            relatedPaths: backlinks?.slice(0, 3),
+            symbolKind: symbol ? getSymbolKindLabel(symbol.kind) : undefined,
+            symbolPath: symbol?.path,
+        };
+    }
+    /**
+     * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
+     */
+    runTextSearch(query, documentMap, index, limit, scopePath, symbolTree, referenceIndex, options) {
         const filteredQuery = filterStopWords(query);
-        const searchResults = index.search(filteredQuery, { combineWith: 'OR' });
+        const filteredWords = filteredQuery.split(/\s+/).filter((w) => w.length >= 2);
+        // Build scope filter if a subtree is specified
+        let scopeFilter;
+        if (scopePath) {
+            const subtreeIds = getSubtreeDocumentIds(symbolTree, scopePath);
+            if (subtreeIds.size > 0) {
+                scopeFilter = (result) => subtreeIds.has(result.id);
+            }
+        }
+        // AND-first strategy: for multi-word queries, try AND for concentrated scores.
+        // If AND returns no results, fall back to OR to ensure no regression.
+        let rawResults;
+        let andSearchFailed = false;
+        const searchOpts = scopeFilter ? { filter: scopeFilter } : {};
+        if (filteredWords.length >= 2) {
+            rawResults = index.search(filteredQuery, { combineWith: 'AND', ...searchOpts });
+            if (rawResults.length === 0) {
+                andSearchFailed = true;
+                rawResults = index.search(filteredQuery, { combineWith: 'OR', ...searchOpts });
+            }
+        }
+        else {
+            rawResults = index.search(filteredQuery, { combineWith: 'OR', ...searchOpts });
+        }
+        // Normalize BM25 scores to [0, 1) then blend with importance + recency via compound scoring.
+        // Decay is computed lazily from file mtime — no disk writes during search.
+        const now = Date.now();
+        const searchResults = rawResults.map((r) => {
+            const doc = documentMap.get(r.id);
+            const scoring = doc?.scoring ?? applyDefaultScoring();
+            const daysSince = doc ? Math.max(0, (now - doc.mtime) / 86_400_000) : 0;
+            const decayed = applyDecay(scoring, daysSince);
+            const bm25 = normalizeScore(r.score);
+            return {
+                ...r,
+                score: compoundScore(bm25, decayed.importance ?? 50, decayed.recency ?? 1, decayed.maturity ?? 'draft'),
+            };
+        });
+        searchResults.sort((a, b) => b.score - a.score);
         const results = [];
-        const resultLimit = Math.min(limit, searchResults.length);
-        for (let i = 0; i < resultLimit; i++) {
-            const result = searchResults[i];
-            const document = documentMap.get(result.id);
-            if (document) {
-                results.push({
-                    excerpt: extractExcerpt(document.content, query),
-                    path: document.path,
-                    score: Math.round(result.score * 100) / 100,
-                    title: document.title,
-                });
+        if (searchResults.length > 0) {
+            // OOD detection: if the best result scores below the minimum floor,
+            // the query has no meaningful match in the knowledge base.
+            // Only apply for corpora with enough documents for reliable BM25 scoring.
+            if (documentMap.size >= 50 && searchResults[0].score < MINIMUM_RELEVANCE_SCORE) {
+                return {
+                    message: 'No matching knowledge found for this query. The topic may not be covered in the context tree.',
+                    results: [],
+                    totalFound: 0,
+                };
+            }
+            // Term-based OOD: when AND search failed, check if significant query terms
+            // are completely absent from the corpus. If unmatched terms exist and the
+            // score is below the trusted threshold, the query is about an uncovered topic.
+            if (andSearchFailed &&
+                documentMap.size >= 50 &&
+                searchResults[0].score < UNMATCHED_TERM_SCORE_THRESHOLD &&
+                hasUnmatchedSignificantTerms(filteredWords, searchResults)) {
+                return {
+                    message: 'No matching knowledge found for this query. The topic may not be covered in the context tree.',
+                    results: [],
+                    totalFound: 0,
+                };
+            }
+            const topScore = searchResults[0].score;
+            const scoreFloor = topScore * SCORE_GAP_RATIO;
+            const resultLimit = Math.min(limit, searchResults.length);
+            for (let i = 0; i < resultLimit; i++) {
+                const result = searchResults[i];
+                // Score-gap filter: skip results too far below the top score
+                if (result.score < scoreFloor)
+                    break;
+                const document = documentMap.get(result.id);
+                if (document) {
+                    const enriched = this.enrichResult({
+                        excerpt: extractExcerpt(document.content, query),
+                        path: document.path,
+                        score: Math.round(result.score * 100) / 100,
+                        title: document.title,
+                    }, symbolTree, referenceIndex);
+                    // Apply kind/maturity filters if specified
+                    if (options?.includeKinds && enriched.symbolKind && !options.includeKinds.includes(enriched.symbolKind)) {
+                        continue;
+                    }
+                    if (options?.excludeKinds && enriched.symbolKind && options.excludeKinds.includes(enriched.symbolKind)) {
+                        continue;
+                    }
+                    if (options?.minMaturity && enriched.symbolKind) {
+                        const tierRank = { core: 3, draft: 1, validated: 2 };
+                        const symbol = symbolTree.symbolMap.get(document.path);
+                        const docMaturity = symbol?.metadata.maturity ?? 'draft';
+                        if ((tierRank[docMaturity] ?? 1) < (tierRank[options.minMaturity] ?? 1)) {
+                            continue;
+                        }
+                    }
+                    results.push(enriched);
+                }
             }
         }
+        // Accumulate access hits for returned results (flushed during next index rebuild)
+        // Disabled for benchmark: prevents feedback loop from distorting scores across queries
+        // if (results.length > 0) {
+        //   this.accumulateAccessHits(results.map((r) => r.path))
+        // }
         return {
             message: results.length > 0
                 ? `Found ${searchResults.length} result(s). Use read_file to view full content.`
@@ -289,6 +591,57 @@ export class SearchKnowledgeService {
             totalFound: searchResults.length,
         };
     }
+    /**
+     * Try to resolve the query as a symbolic path. Returns null if no path match found.
+     */
+    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, options) {
+        const pathMatches = matchMemoryPath(symbolTree, query.split(/\s+/)[0].includes('/') ? query.split(/\s+/)[0] : query);
+        if (pathMatches.length === 0) {
+            return null;
+        }
+        const topMatch = pathMatches[0].matchedSymbol;
+        // If the matched symbol is a leaf Context, return it directly
+        if (topMatch.kind === MemorySymbolKind.Context) {
+            const doc = documentMap.get(topMatch.path);
+            if (!doc) {
+                return null;
+            }
+            const result = this.enrichResult({ excerpt: extractExcerpt(doc.content, query), path: doc.path, score: 1, title: doc.title }, symbolTree, referenceIndex);
+            this.accumulateAccessHits([doc.path]);
+            return {
+                message: `Found exact match: ${topMatch.path}`,
+                results: [result],
+                totalFound: 1,
+            };
+        }
+        // Matched a folder node (Domain/Topic/Subtopic) — check for remaining text query
+        const queryParts = query.trim().split(/\s+/);
+        const pathPart = queryParts[0].includes('/') ? queryParts[0] : topMatch.name;
+        const textPart = query.slice(query.indexOf(pathPart) + pathPart.length).trim();
+        if (textPart) {
+            // Scoped search: search text within the matched subtree
+            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, symbolTree, referenceIndex, options);
+        }
+        // No text part — return all children of the matched node
+        const subtreeIds = getSubtreeDocumentIds(symbolTree, topMatch.path);
+        const results = [];
+        for (const docId of subtreeIds) {
+            if (results.length >= limit)
+                break;
+            const doc = documentMap.get(docId);
+            if (!doc)
+                continue;
+            results.push(this.enrichResult({ excerpt: extractExcerpt(doc.content, query), path: doc.path, score: 0.9, title: doc.title }, symbolTree, referenceIndex));
+        }
+        if (results.length > 0) {
+            this.accumulateAccessHits(results.map((r) => r.path));
+        }
+        return {
+            message: `Found ${results.length} entries under ${topMatch.path}. Use read_file to view full content.`,
+            results,
+            totalFound: results.length,
+        };
+    }
 }
 /**
  * Factory function to create a SearchKnowledgeService instance.

package/dist/agent/infra/tools/implementations/search-knowledge-tool.d.ts

@@ -11,7 +11,8 @@ export interface SearchKnowledgeToolConfig {
  * Creates the search knowledge tool.
  *
  * Searches the curated knowledge base in .brv/context-tree/ for relevant topics.
- * Uses MiniSearch for full-text search with caching and indexing.
+ * Supports symbolic path queries, scoped search, kind/maturity filtering, and overview mode
+ * in addition to full-text BM25 search.
  *
  * @param fileSystem - File system service dependency
  * @param config - Optional configuration

package/dist/agent/infra/tools/implementations/search-knowledge-tool.js

@@ -3,6 +3,14 @@ import { ToolName } from '../../../core/domain/tools/constants.js';
 import { SearchKnowledgeService } from './search-knowledge-service.js';
 const SearchKnowledgeInputSchema = z
     .object({
+    excludeKinds: z
+        .array(z.enum(['context', 'domain', 'subtopic', 'topic']))
+        .optional()
+        .describe('Symbol kinds to exclude from results'),
+    includeKinds: z
+        .array(z.enum(['context', 'domain', 'subtopic', 'topic']))
+        .optional()
+        .describe('Symbol kinds to include in results (filters out others)'),
     limit: z
         .number()
         .int()
@@ -10,14 +18,40 @@ const SearchKnowledgeInputSchema = z
         .optional()
         .default(10)
         .describe('Maximum number of results to return (default: 10)'),
-    query: z.string().min(1).describe('Natural language query string to search for in the knowledge base'),
+    minMaturity: z
+        .enum(['core', 'draft', 'validated'])
+        .optional()
+        .describe('Minimum maturity tier for results'),
+    overview: z
+        .boolean()
+        .optional()
+        .describe('If true, return tree structure overview instead of search results'),
+    overviewDepth: z
+        .number()
+        .int()
+        .min(0)
+        .max(3)
+        .optional()
+        .default(2)
+        .describe('Depth for overview mode (default: 2, showing domains + topics)'),
+    query: z
+        .string()
+        .min(1)
+        .describe('Natural language query or symbolic path. ' +
+        'Supports path queries like "auth/jwt" to navigate the knowledge hierarchy. ' +
+        'Use "/" to scope searches (e.g., "auth/jwt refresh strategy" searches within auth/jwt).'),
+    scope: z
+        .string()
+        .optional()
+        .describe('Path prefix to scope search within (e.g., "auth" or "auth/jwt-tokens")'),
 })
     .strict();
 /**
  * Creates the search knowledge tool.
  *
  * Searches the curated knowledge base in .brv/context-tree/ for relevant topics.
- * Uses MiniSearch for full-text search with caching and indexing.
+ * Supports symbolic path queries, scoped search, kind/maturity filtering, and overview mode
+ * in addition to full-text BM25 search.
  *
  * @param fileSystem - File system service dependency
  * @param config - Optional configuration
@@ -28,11 +62,21 @@ export function createSearchKnowledgeTool(fileSystem, config = {}) {
     const service = new SearchKnowledgeService(fileSystem, config);
     return {
         description: 'Search the curated knowledge base in .brv/context-tree/ for relevant topics. ' +
-            'Use natural language queries to find knowledge about specific topics (e.g., "auth design", "API patterns"). ' +
-            'Returns matching file paths, titles, and relevant excerpts.',
+            'Use natural language queries or symbolic paths (e.g., "auth/jwt", "/auth/jwt-tokens") ' +
+            'to navigate the knowledge hierarchy. Supports scoped search, kind filtering, ' +
+            'maturity filtering, and overview mode. Returns matching file paths, titles, excerpts, ' +
+            'and symbolic metadata (kind, backlinks).',
         async execute(input, _context) {
-            const { limit, query } = SearchKnowledgeInputSchema.parse(input);
-            return service.search(query, { limit });
+            const parsed = SearchKnowledgeInputSchema.parse(input);
+            return service.search(parsed.query, {
+                excludeKinds: parsed.excludeKinds,
+                includeKinds: parsed.includeKinds,
+                limit: parsed.limit,
+                minMaturity: parsed.minMaturity,
+                overview: parsed.overview,
+                overviewDepth: parsed.overviewDepth,
+                scope: parsed.scope,
+            });
         },
         id: ToolName.SEARCH_KNOWLEDGE,
         inputSchema: SearchKnowledgeInputSchema,