byterover-cli 3.1.0 → 3.3.0

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

@@ -2,17 +2,18 @@ import MiniSearch from 'minisearch';
 import { realpath } from 'node:fs/promises';
 import { join } from 'node:path';
 import { removeStopwords } from 'stopword';
-import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, OVERVIEW_EXTENSION, SUMMARY_INDEX_FILE } from '../../../../server/constants.js';
+import { BRV_DIR, CONTEXT_FILE_EXTENSION, CONTEXT_TREE_DIR, OVERVIEW_EXTENSION, SHARED_SOURCE_LOCAL_SCORE_BOOST, SUMMARY_INDEX_FILE, } 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 { loadSources } from '../../../../server/core/domain/source/source-schema.js';
 import { isArchiveStub, isDerivedArtifact } from '../../../../server/infra/context-tree/derived-artifact.js';
-import { parseArchiveStubFrontmatter, parseSummaryFrontmatter } from '../../../../server/infra/context-tree/summary-frontmatter.js';
+import { parseArchiveStubFrontmatter, parseSummaryFrontmatter, } from '../../../../server/infra/context-tree/summary-frontmatter.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;
+const INDEX_SCHEMA_VERSION = 5;
 /** Only include results whose normalized score is at least this fraction of the top result's score */
 const SCORE_GAP_RATIO = 0.7;
 /** Minimum normalized score for the top result. Below this, the query is considered out-of-domain */
@@ -34,6 +35,12 @@ const CHUNK_OVERLAP_CHARS = 120;
 function normalizeScore(rawScore) {
     return rawScore / (1 + rawScore);
 }
+function getSymbolPath(origin, relativePath) {
+    if (origin.origin === 'local') {
+        return relativePath;
+    }
+    return `[${origin.alias ?? origin.originKey}]:${relativePath}`;
+}
 /**
  * Propagate BM25 scores upward to parent domain/topic nodes.
  *
@@ -44,10 +51,11 @@ function normalizeScore(rawScore) {
  * @param results - Already-enriched search results (gap-ratio filtered)
  * @param symbolTree - Symbol tree for parent-chain traversal
  * @param summaryMap - Map of _index.md file paths → SummaryDocLike (for excerpt/metadata)
+ * @param symbolPathDocMap - symbolPath → IndexedDocument lookup for context.md fallback
  * @param propagationFactor - Score multiplier per level up (default 0.55)
  * @returns New parent entries only — caller merges and re-sorts
  */
-function propagateScoresToParents(results, symbolTree, summaryMap, documentMap, propagationFactor = 0.55) {
+function propagateScoresToParents(results, symbolTree, summaryMap, symbolPathDocMap, propagationFactor = 0.55) {
     const boosts = new Map();
     for (const r of results) {
         const symbol = symbolTree.symbolMap.get(r.path);
@@ -65,7 +73,7 @@ function propagateScoresToParents(results, symbolTree, summaryMap, documentMap,
     for (const [parentPath, score] of boosts.entries()) {
         if (existingPaths.has(parentPath))
             continue;
-        const doc = getSummarySource(parentPath, summaryMap, documentMap);
+        const doc = getSummarySource(parentPath, summaryMap, symbolPathDocMap);
         if (!doc)
             continue;
         // Propagate the strongest child BM25 signal upward, then apply the parent
@@ -97,10 +105,10 @@ const MINISEARCH_OPTIONS = {
     },
     storeFields: ['title', 'path'],
 };
-function getSummaryAccessPath(path, summaryMap, documentMap) {
-    return getSummarySource(path, summaryMap, documentMap)?.path ?? `${path}/${SUMMARY_INDEX_FILE}`;
+function getSummaryAccessPath(path, summaryMap, symbolPathDocMap) {
+    return getSummarySource(path, summaryMap, symbolPathDocMap)?.path ?? `${path}/${SUMMARY_INDEX_FILE}`;
 }
-function getSummarySource(path, summaryMap, documentMap) {
+function getSummarySource(path, summaryMap, symbolPathDocMap) {
     const summaryDoc = summaryMap.get(`${path}/${SUMMARY_INDEX_FILE}`);
     if (summaryDoc) {
         return {
@@ -109,7 +117,9 @@ function getSummarySource(path, summaryMap, documentMap) {
             scoring: summaryDoc.scoring,
         };
     }
-    const contextDoc = documentMap.get(`${path}/context.md`);
+    // Look up context.md via symbolPath-keyed map since documentMap keys are
+    // origin-qualified (e.g. 'local::path') but callers use symbol tree paths.
+    const contextDoc = symbolPathDocMap.get(`${path}/context.md`);
     if (contextDoc) {
         return {
             excerpt: extractExcerpt(contextDoc.content, contextDoc.title),
@@ -276,22 +286,12 @@ function isCacheValid(cache, currentFiles) {
     }
     return true;
 }
-async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
-    const now = Date.now();
-    if (filesWithMtime.length === 0) {
-        const index = new MiniSearch(MINISEARCH_OPTIONS);
-        return {
-            contextTreePath,
-            documentMap: new Map(),
-            fileMtimes: new Map(),
-            index,
-            lastValidatedAt: now,
-            referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
-            schemaVersion: INDEX_SCHEMA_VERSION,
-            summaryMap: new Map(),
-            symbolTree: { root: [], symbolMap: new Map() },
-        };
-    }
+/**
+ * Read and index documents from a single context tree origin.
+ * Returns documents with origin-qualified IDs (<originKey>::<path>)
+ * and summary docs keyed by origin-qualified paths.
+ */
+async function indexOriginDocuments(fileSystem, origin, filesWithMtime) {
     // Partition files: _index.md → summaryFiles, .overview.md → overviewFiles (for cache
     // invalidation + sibling detection), other derived artifacts → skip, rest → indexable
     const summaryFiles = [];
@@ -309,39 +309,45 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             overviewFiles.push(file);
         }
         else if (!isDerivedArtifact(file.path)) {
-            // Includes regular .md files AND .stub.md files (stubs are searchable)
             indexableFiles.push(file);
         }
         // .full.md, .abstract.md, and _manifest.json are skipped (isDerivedArtifact returns true)
     }
-    // Read indexable documents for BM25 index
     const documentPromises = indexableFiles.map(async ({ mtime, path: filePath }) => {
         try {
-            const fullPath = join(contextTreePath, filePath);
+            const fullPath = join(origin.contextTreeRoot, filePath);
             const { content } = await fileSystem.readFile(fullPath);
             const title = extractTitle(content, filePath.replace(/\.md$/, '').split('/').pop() || filePath);
             const scoring = parseFrontmatterScoring(content) ?? applyDefaultScoring();
+            const qualifiedId = `${origin.originKey}::${filePath}`;
+            const symbolPath = getSymbolPath(origin, filePath);
             // Check if a .overview.md sibling exists (written by abstract generation queue)
             const overviewRelPath = filePath.replace(/\.md$/, OVERVIEW_EXTENSION);
             const overviewPath = knownPaths.has(overviewRelPath) ? overviewRelPath : undefined;
-            return {
+            const doc = {
                 content,
-                id: filePath,
+                id: qualifiedId,
                 mtime,
+                origin: origin.origin,
+                originContextTreeRoot: origin.contextTreeRoot,
+                originKey: origin.originKey,
                 ...(overviewPath !== undefined && { overviewPath }),
                 path: filePath,
                 scoring,
+                symbolPath,
                 title,
             };
+            if (origin.alias)
+                doc.originAlias = origin.alias;
+            return doc;
         }
         catch {
             return null;
         }
     });
-    // Read _index.md files separately for summaryMap (not indexed in BM25)
     const summaryPromises = summaryFiles.map(async ({ path: filePath }) => {
         try {
-            const fullPath = join(contextTreePath, filePath);
+            const fullPath = join(origin.contextTreeRoot, filePath);
             const { content } = await fileSystem.readFile(fullPath);
             const fm = parseSummaryFrontmatter(content);
             if (!fm)
@@ -354,7 +360,7 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             return {
                 condensationOrder: fm.condensation_order,
                 excerpt: stripMarkdownFrontmatter(content).slice(0, 400),
-                path: filePath,
+                path: getSymbolPath(origin, filePath),
                 scoring,
                 tokenCount: fm.token_count,
             };
@@ -363,24 +369,18 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             return null;
         }
     });
-    const [docResults, summaryResults] = await Promise.all([
-        Promise.all(documentPromises),
-        Promise.all(summaryPromises),
-    ]);
+    const [docResults, summaryResults] = await Promise.all([Promise.all(documentPromises), Promise.all(summaryPromises)]);
     const documents = docResults.filter((doc) => doc !== null);
-    const documentMap = new Map();
     const fileMtimes = new Map();
     for (const doc of documents) {
-        documentMap.set(doc.id, doc);
-        fileMtimes.set(doc.path, doc.mtime);
+        fileMtimes.set(doc.id, doc.mtime);
     }
-    // Also track summary file mtimes for cache invalidation
     for (const sf of summaryFiles) {
-        fileMtimes.set(sf.path, sf.mtime);
+        fileMtimes.set(`${origin.originKey}::${sf.path}`, sf.mtime);
     }
     // Track .overview.md mtimes so the cache invalidates when a new overview is written
     for (const ov of overviewFiles) {
-        fileMtimes.set(ov.path, ov.mtime);
+        fileMtimes.set(`${origin.originKey}::${ov.path}`, ov.mtime);
     }
     const summaryMap = new Map();
     for (const summary of summaryResults) {
@@ -388,28 +388,87 @@ async function buildFreshIndex(fileSystem, contextTreePath, filesWithMtime) {
             summaryMap.set(summary.path, summary);
         }
     }
+    return { documents, fileMtimes, summaryMap };
+}
+async function buildFreshIndex(fileSystem, contextTreePath, localFiles, sharedOrigins, sourcesFileMtime) {
+    const now = Date.now();
+    // Build the local origin descriptor.
+    // Note: `originKey: 'local'` is a string sentinel — shared origins use a 12-char
+    // SHA-256 hex hash from `deriveOriginKey()`. Consumers comparing originKey should
+    // treat 'local' as a reserved literal, not a hash.
+    const localOrigin = {
+        contextTreeRoot: contextTreePath,
+        origin: 'local',
+        originKey: 'local',
+    };
+    // Index local documents
+    const localResult = await indexOriginDocuments(fileSystem, localOrigin, localFiles);
+    // Index shared origin documents in parallel
+    const sharedResults = await Promise.all(sharedOrigins.map(async (origin) => {
+        try {
+            const files = await findMarkdownFilesWithMtime(fileSystem, origin.contextTreeRoot);
+            const filtered = files.filter((f) => !isDerivedArtifact(f.path) || f.path.split('/').at(-1) === SUMMARY_INDEX_FILE);
+            return indexOriginDocuments(fileSystem, origin, filtered);
+        }
+        catch {
+            return { documents: [], fileMtimes: new Map(), summaryMap: new Map() };
+        }
+    }));
+    // Merge all documents, fileMtimes, and summaryMaps
+    const allDocuments = [...localResult.documents];
+    const fileMtimes = new Map(localResult.fileMtimes);
+    const summaryMap = new Map(localResult.summaryMap);
+    for (const result of sharedResults) {
+        allDocuments.push(...result.documents);
+        for (const [key, mtime] of result.fileMtimes) {
+            fileMtimes.set(key, mtime);
+        }
+        for (const [key, summary] of result.summaryMap) {
+            summaryMap.set(key, summary);
+        }
+    }
+    const documentMap = new Map();
+    const pathToDocumentId = new Map();
+    // Reverse lookup: symbolPath → document (for getSummarySource context.md fallback)
+    const symbolPathDocMap = new Map();
+    for (const doc of allDocuments) {
+        documentMap.set(doc.id, doc);
+        pathToDocumentId.set(doc.symbolPath, doc.id);
+        symbolPathDocMap.set(doc.symbolPath, doc);
+    }
     const index = new MiniSearch(MINISEARCH_OPTIONS);
-    index.addAll(documents);
-    // Build symbolic structures from the document map, with summary annotations
-    const symbolTree = buildSymbolTree(documentMap, summaryMap);
-    const referenceIndex = buildReferenceIndex(documentMap);
+    index.addAll(allDocuments);
+    const symbolDocumentMap = new Map();
+    for (const doc of allDocuments) {
+        symbolDocumentMap.set(doc.id, { ...doc, path: doc.symbolPath });
+    }
+    const symbolTree = buildSymbolTree(symbolDocumentMap, summaryMap);
+    // Reference index only uses local docs — cross-project references are not tracked
+    const referenceIndex = buildReferenceIndex(new Map(localResult.documents.map((doc) => [doc.id, doc])));
     return {
         contextTreePath,
         documentMap,
         fileMtimes,
         index,
         lastValidatedAt: now,
+        pathToDocumentId,
         referenceIndex,
         schemaVersion: INDEX_SCHEMA_VERSION,
+        sharedOrigins,
+        sourcesFileMtime,
         summaryMap,
+        symbolPathDocMap,
         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.
+ *
+ * Self-loads knowledge sources from `.brv/sources.json` during each validation
+ * cycle, with mtime-based invalidation to detect source additions/removals.
  */
-async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeBuild) {
+async function acquireIndex(state, fileSystem, contextTreePath, baseDirectory, ttlMs, onBeforeBuild) {
     const now = Date.now();
     // Fast path: TTL-based cache hit (no I/O needed)
     if (state.cachedIndex &&
@@ -425,6 +484,23 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
     }
     // Create and store the build promise SYNCHRONOUSLY before any await
     // This prevents race conditions where multiple parallel calls all start building
+    const emptyResult = () => {
+        const emptyIndex = new MiniSearch(MINISEARCH_OPTIONS);
+        return {
+            contextTreePath: '',
+            documentMap: new Map(),
+            fileMtimes: new Map(),
+            index: emptyIndex,
+            lastValidatedAt: 0,
+            pathToDocumentId: new Map(),
+            referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
+            schemaVersion: INDEX_SCHEMA_VERSION,
+            sharedOrigins: [],
+            summaryMap: new Map(),
+            symbolPathDocMap: new Map(),
+            symbolTree: { root: [], symbolMap: new Map() },
+        };
+    };
     const buildPromise = (async () => {
         // Check if context tree exists (only if no cache or different path)
         if (!state.cachedIndex || state.cachedIndex.contextTreePath !== contextTreePath) {
@@ -432,21 +508,13 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
                 await fileSystem.listDirectory(contextTreePath);
             }
             catch {
-                // Return empty index to signal error - caller will handle
-                const emptyIndex = new MiniSearch(MINISEARCH_OPTIONS);
-                return {
-                    contextTreePath: '',
-                    documentMap: new Map(),
-                    fileMtimes: new Map(),
-                    index: emptyIndex,
-                    lastValidatedAt: 0,
-                    referenceIndex: { backlinks: new Map(), forwardLinks: new Map() },
-                    schemaVersion: INDEX_SCHEMA_VERSION,
-                    summaryMap: new Map(),
-                    symbolTree: { root: [], symbolMap: new Map() },
-                };
+                return emptyResult();
             }
         }
+        // Self-load knowledge sources — mtime-based invalidation
+        const loadedSources = loadSources(baseDirectory);
+        const sourcesFileMtime = loadedSources?.mtime;
+        const sharedOrigins = loadedSources?.origins ?? [];
         let allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
         // Exclude non-indexable derived artifacts (.full.md) so that currentFiles
         // matches what buildFreshIndex tracks in fileMtimes. Without this filter,
@@ -454,7 +522,7 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
         // _index.md is kept (tracked for summary staleness), .stub.md is kept (BM25 indexed).
         // Keep _index.md (summary tracking) and .overview.md (sibling detection for overviewPath).
         // .full.md, .abstract.md, and _manifest.json remain excluded.
-        let currentFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
+        let localFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
             f.path.split('/').at(-1) === SUMMARY_INDEX_FILE ||
             f.path.endsWith(OVERVIEW_EXTENSION));
         // Flush pending access hits before reusing a stale-enough cache entry.
@@ -463,16 +531,32 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
             const wroteScoringUpdates = await onBeforeBuild(contextTreePath);
             if (wroteScoringUpdates) {
                 allFiles = await findMarkdownFilesWithMtime(fileSystem, contextTreePath);
-                currentFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
+                localFiles = allFiles.filter((f) => !isDerivedArtifact(f.path) ||
                     f.path.split('/').at(-1) === SUMMARY_INDEX_FILE ||
                     f.path.endsWith(OVERVIEW_EXTENSION));
             }
         }
-        // Re-check cache validity after getting file list (another call may have finished)
-        if (state.cachedIndex &&
+        // Qualify local file mtime keys with 'local::' prefix to match buildFreshIndex
+        const qualifiedLocalFiles = localFiles.map((f) => ({ mtime: f.mtime, path: `local::${f.path}` }));
+        // Glob shared origin files for cache validation (detect edits in shared projects)
+        const sharedFileArrays = await Promise.all(sharedOrigins.map(async (origin) => {
+            try {
+                const files = await findMarkdownFilesWithMtime(fileSystem, origin.contextTreeRoot);
+                const filtered = files.filter((f) => !isDerivedArtifact(f.path) || f.path.split('/').at(-1) === SUMMARY_INDEX_FILE);
+                return filtered.map((f) => ({ mtime: f.mtime, path: `${origin.originKey}::${f.path}` }));
+            }
+            catch {
+                return [];
+            }
+        }));
+        const allQualifiedFiles = [...qualifiedLocalFiles, ...sharedFileArrays.flat()];
+        // Re-check cache validity: local files + shared files + sources-file mtime must match
+        const sourcesFileChanged = state.cachedIndex?.sourcesFileMtime !== sourcesFileMtime;
+        if (!sourcesFileChanged &&
+            state.cachedIndex &&
             state.cachedIndex.contextTreePath === contextTreePath &&
             state.cachedIndex.schemaVersion === INDEX_SCHEMA_VERSION &&
-            isCacheValid(state.cachedIndex, currentFiles)) {
+            isCacheValid(state.cachedIndex, allQualifiedFiles)) {
             // Update timestamp atomically by creating a new object
             const updatedCache = {
                 ...state.cachedIndex,
@@ -481,8 +565,8 @@ async function acquireIndex(state, fileSystem, contextTreePath, ttlMs, onBeforeB
             state.cachedIndex = updatedCache;
             return updatedCache;
         }
-        // Build fresh index
-        const freshIndex = await buildFreshIndex(fileSystem, contextTreePath, currentFiles);
+        // Build fresh index with local + shared origins
+        const freshIndex = await buildFreshIndex(fileSystem, contextTreePath, localFiles, sharedOrigins, sourcesFileMtime);
         state.cachedIndex = freshIndex;
         return freshIndex;
     })();
@@ -565,15 +649,20 @@ export class SearchKnowledgeService {
      */
     async search(query, options) {
         const limit = options?.limit ?? 10;
+        // Normalize scope: strip trailing slashes so "project/" and "project" both work.
+        // The symbol tree stores paths without a trailing slash, and getSubtreeDocumentIds
+        // does an exact node lookup, so "project/" would otherwise miss the subtree entirely
+        // and silently fall back to global search via the block at the end of this method.
+        const normalizedScope = options?.scope?.trim().replace(/\/+$/, '') || undefined;
         const resolvedBaseDirectory = await realpath(this.baseDirectory).catch(() => this.baseDirectory);
         const contextTreePath = join(resolvedBaseDirectory, BRV_DIR, CONTEXT_TREE_DIR);
         // 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));
+        const indexResult = await acquireIndex(this.state, this.fileSystem, contextTreePath, this.baseDirectory, this.cacheTtlMs, (ctxPath) => this.flushAccessHits(ctxPath));
         // Handle error case (context tree not initialized)
         if ('error' in indexResult) {
             return indexResult.result;
         }
-        const { documentMap, index, referenceIndex, summaryMap, symbolTree } = indexResult;
+        const { documentMap, index, pathToDocumentId, referenceIndex, summaryMap, symbolPathDocMap, symbolTree } = indexResult;
         if (documentMap.size === 0) {
             return {
                 message: 'Context tree is empty. Use /curate to add knowledge.',
@@ -583,24 +672,29 @@ export class SearchKnowledgeService {
         }
         // Overview mode: return tree structure instead of search results
         if (options?.overview) {
-            return this.buildOverviewResult(symbolTree, referenceIndex, options.scope, options.overviewDepth);
+            return this.buildOverviewResult(symbolTree, referenceIndex, normalizedScope, options.overviewDepth);
         }
         // Symbolic path resolution: try path-based query first
         if (isPathLikeQuery(query, symbolTree)) {
-            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, summaryMap, options);
+            const symbolicResult = this.trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, 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;
+        // Strip trailing slashes from scope so "auth/" resolves to the same
+        // symbol-tree node as "auth". The symbol tree stores paths without
+        // trailing slashes; a mismatch causes getSubtreeDocumentIds() to
+        // return empty → unintended fallback to global search.
+        const rawScope = options?.scope?.trim().replace(/\/+$/, '');
+        const effectiveScope = (rawScope !== undefined && rawScope !== '' ? rawScope : undefined) ?? 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, summaryMap, options);
+        const textResult = this.runTextSearch(effectiveQuery || query, documentMap, index, limit, effectiveScope, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, 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, summaryMap, options);
+            return this.runTextSearch(query, documentMap, index, limit, undefined, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
         }
         return textResult;
     }
@@ -636,14 +730,15 @@ export class SearchKnowledgeService {
      * For archive stubs, extracts points_to path into archiveFullPath.
      */
     enrichResult(result, symbolTree, referenceIndex, documentMap) {
-        const symbol = symbolTree.symbolMap.get(result.path);
+        const doc = documentMap.get(result.id);
+        const symbolPath = doc?.symbolPath ?? result.path;
+        const symbol = symbolTree.symbolMap.get(symbolPath);
         const backlinks = referenceIndex.backlinks.get(result.path);
         // Detect archive stubs and extract points_to for drill-down
         let archiveFullPath;
         let symbolKind = symbol ? getSymbolKindLabel(symbol.kind) : undefined;
         if (isArchiveStub(result.path)) {
             symbolKind = 'archive_stub';
-            const doc = documentMap.get(result.path);
             if (doc) {
                 const stubFm = parseArchiveStubFrontmatter(doc.content);
                 if (stubFm) {
@@ -651,17 +746,26 @@ export class SearchKnowledgeService {
                 }
             }
         }
-        const doc = documentMap.get(result.path);
+        // Origin metadata for shared-source results
+        const origin = doc?.origin;
+        const originAlias = doc?.originAlias;
+        const originContextTreeRoot = doc?.origin === 'shared' ? doc.originContextTreeRoot : undefined;
         const overviewPath = doc?.overviewPath;
         const isContextSummary = doc?.path.endsWith('/context.md') || doc?.path === 'context.md';
         const summaryPath = isContextSummary
             ? doc?.path.slice(0, -'/context.md'.length) || doc?.path || result.path
             : result.path;
+        // Destructure to strip `id` from output — not part of SearchKnowledgeResult
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { id: _id, ...rest } = result;
         return {
-            ...result,
+            ...rest,
             ...(archiveFullPath && { archiveFullPath }),
             ...(overviewPath && { overviewPath }),
             backlinkCount: backlinks?.length ?? 0,
+            ...(origin && { origin }),
+            ...(originAlias && { originAlias }),
+            ...(originContextTreeRoot && { originContextTreeRoot }),
             ...(isContextSummary && { path: summaryPath }),
             relatedPaths: backlinks?.slice(0, 3),
             symbolKind: isContextSummary ? 'summary' : symbolKind,
@@ -671,15 +775,22 @@ export class SearchKnowledgeService {
     /**
      * Run the standard text-based MiniSearch pipeline, optionally scoped to a subtree.
      */
-    runTextSearch(query, documentMap, index, limit, scopePath, symbolTree, referenceIndex, summaryMap, options) {
+    runTextSearch(query, documentMap, index, limit, scopePath, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options) {
         const filteredQuery = filterStopWords(query);
         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);
+            const subtreePaths = getSubtreeDocumentIds(symbolTree, scopePath);
+            const subtreeQualifiedIds = new Set();
+            for (const symbolPath of subtreePaths) {
+                const docId = pathToDocumentId.get(symbolPath);
+                if (docId) {
+                    subtreeQualifiedIds.add(docId);
+                }
+            }
+            if (subtreeQualifiedIds.size > 0) {
+                scopeFilter = (result) => subtreeQualifiedIds.has(result.id);
             }
         }
         // AND-first strategy: for multi-word queries, try AND for concentrated scores.
@@ -699,6 +810,7 @@ export class SearchKnowledgeService {
         }
         // 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.
+        // Local results get a configurable score boost to prefer local knowledge over shared.
         const now = Date.now();
         const searchResults = rawResults.map((r) => {
             const doc = documentMap.get(r.id);
@@ -706,10 +818,15 @@ export class SearchKnowledgeService {
             const daysSince = doc ? Math.max(0, (now - doc.mtime) / 86_400_000) : 0;
             const decayed = applyDecay(scoring, daysSince);
             const bm25 = normalizeScore(r.score);
+            let finalScore = compoundScore(bm25, decayed.importance ?? 50, decayed.recency ?? 1, decayed.maturity ?? 'draft');
+            // Local score boost: prefer local results over shared when scores are close
+            if (doc?.origin === 'local') {
+                finalScore = Math.min(finalScore + SHARED_SOURCE_LOCAL_SCORE_BOOST, 1);
+            }
             return {
                 ...r,
                 bm25Score: bm25,
-                score: compoundScore(bm25, decayed.importance ?? 50, decayed.recency ?? 1, decayed.maturity ?? 'draft'),
+                score: finalScore,
             };
         });
         searchResults.sort((a, b) => b.score - a.score);
@@ -752,6 +869,7 @@ export class SearchKnowledgeService {
                 if (document) {
                     const enriched = this.enrichResult({
                         excerpt: extractExcerpt(document.content, query),
+                        id: result.id,
                         path: document.path,
                         score: Math.round(result.score * 100) / 100,
                         title: document.title,
@@ -765,10 +883,10 @@ export class SearchKnowledgeService {
                     }
                     if (options?.minMaturity && enriched.symbolKind) {
                         const docMaturity = enriched.symbolKind === 'summary'
-                            ? getSummarySource(enriched.path, summaryMap, documentMap)?.scoring?.maturity
-                                ?? symbolTree.symbolMap.get(enriched.path)?.metadata.maturity
-                                ?? 'draft'
-                            : symbolTree.symbolMap.get(document.path)?.metadata.maturity ?? 'draft';
+                            ? (getSummarySource(enriched.path, summaryMap, symbolPathDocMap)?.scoring?.maturity ??
+                                symbolTree.symbolMap.get(enriched.path)?.metadata.maturity ??
+                                'draft')
+                            : (symbolTree.symbolMap.get(document.symbolPath)?.metadata.maturity ?? 'draft');
                         if ((MATURITY_TIER_RANK[docMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1)) {
                             continue;
                         }
@@ -776,14 +894,17 @@ export class SearchKnowledgeService {
                     results.push(enriched);
                     propagationInputs.push({
                         bm25Score: result.bm25Score,
-                        path: document.path,
+                        path: document.symbolPath,
                     });
                 }
             }
         }
         // Propagate scores upward to parent domain/topic nodes (hierarchical retrieval)
-        const propagated = propagateScoresToParents(propagationInputs, symbolTree, summaryMap, documentMap);
+        const propagated = propagateScoresToParents(propagationInputs, symbolTree, summaryMap, symbolPathDocMap);
         for (const p of propagated) {
+            // Apply local score boost to propagated summaries so they stay competitive
+            // with boosted direct BM25 hits (the boost was already applied to direct hits above)
+            p.score = Math.min(p.score + SHARED_SOURCE_LOCAL_SCORE_BOOST, 1);
             if (scoreFloor !== undefined && p.score < scoreFloor)
                 continue;
             if (options?.includeKinds && p.symbolKind && !options.includeKinds.includes(p.symbolKind))
@@ -791,7 +912,7 @@ export class SearchKnowledgeService {
             if (options?.excludeKinds && p.symbolKind && options.excludeKinds.includes(p.symbolKind))
                 continue;
             if (options?.minMaturity && p.symbolKind === 'summary') {
-                const summaryDoc = getSummarySource(p.path, summaryMap, documentMap);
+                const summaryDoc = getSummarySource(p.path, summaryMap, symbolPathDocMap);
                 const summaryMaturity = summaryDoc?.scoring?.maturity ?? 'draft';
                 if ((MATURITY_TIER_RANK[summaryMaturity] ?? 1) < (MATURITY_TIER_RANK[options.minMaturity] ?? 1))
                     continue;
@@ -808,9 +929,7 @@ export class SearchKnowledgeService {
         // Synthetic 'summary' results carry folder-style paths (e.g. 'auth') that are not
         // real files; map them to their _index.md so flushAccessHits can read and update them.
         if (results.length > 0) {
-            this.accumulateAccessHits(results.map((r) => (r.symbolKind === 'summary'
-                ? getSummaryAccessPath(r.path, summaryMap, documentMap)
-                : r.path)));
+            this.accumulateAccessHits(results.map((r) => r.symbolKind === 'summary' ? getSummaryAccessPath(r.path, summaryMap, symbolPathDocMap) : r.path));
         }
         return {
             message: results.length > 0
@@ -823,7 +942,7 @@ export class SearchKnowledgeService {
     /**
      * Try to resolve the query as a symbolic path. Returns null if no path match found.
      */
-    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, summaryMap, options) {
+    trySymbolicSearch(query, symbolTree, referenceIndex, documentMap, index, limit, pathToDocumentId, summaryMap, symbolPathDocMap, options) {
         const pathMatches = matchMemoryPath(symbolTree, query.split(/\s+/)[0].includes('/') ? query.split(/\s+/)[0] : query);
         if (pathMatches.length === 0) {
             return null;
@@ -831,12 +950,15 @@ export class SearchKnowledgeService {
         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);
+            const docId = pathToDocumentId.get(topMatch.path);
+            const doc = docId ? documentMap.get(docId) : undefined;
             if (!doc) {
                 return null;
             }
-            const result = this.enrichResult({ excerpt: extractExcerpt(doc.content, query), path: doc.path, score: 1, title: doc.title }, symbolTree, referenceIndex, documentMap);
-            this.accumulateAccessHits([doc.path]);
+            const result = this.enrichResult({ excerpt: extractExcerpt(doc.content, query), id: doc.id, path: doc.path, score: 1, title: doc.title }, symbolTree, referenceIndex, documentMap);
+            if (doc.origin === 'local') {
+                this.accumulateAccessHits([doc.path]);
+            }
             return {
                 message: `Found exact match: ${topMatch.path}`,
                 results: [result],
@@ -849,13 +971,13 @@ export class SearchKnowledgeService {
         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, summaryMap, options);
+            return this.runTextSearch(textPart, documentMap, index, limit, topMatch.path, pathToDocumentId, symbolTree, referenceIndex, summaryMap, symbolPathDocMap, options);
         }
         // No text part — return all children of the matched node
         const subtreeIds = getSubtreeDocumentIds(symbolTree, topMatch.path);
         const results = [];
         const accessHitPaths = [];
-        const summaryDoc = getSummarySource(topMatch.path, summaryMap, documentMap);
+        const summaryDoc = getSummarySource(topMatch.path, summaryMap, symbolPathDocMap);
         if (summaryDoc) {
             results.push({
                 backlinkCount: 0,
@@ -868,13 +990,14 @@ export class SearchKnowledgeService {
             });
             accessHitPaths.push(summaryDoc.path);
         }
-        for (const docId of subtreeIds) {
+        for (const symbolPath of subtreeIds) {
             if (results.length >= limit)
                 break;
-            const doc = documentMap.get(docId);
+            const docId = pathToDocumentId.get(symbolPath);
+            const doc = docId ? documentMap.get(docId) : undefined;
             if (!doc)
                 continue;
-            results.push(this.enrichResult({ excerpt: extractExcerpt(doc.content, query), path: doc.path, score: 0.9, title: doc.title }, symbolTree, referenceIndex, documentMap));
+            results.push(this.enrichResult({ excerpt: extractExcerpt(doc.content, query), id: doc.id, path: doc.path, score: 0.9, title: doc.title }, symbolTree, referenceIndex, documentMap));
             accessHitPaths.push(doc.path);
         }
         if (accessHitPaths.length > 0) {