opencode-rag-plugin 1.15.1 → 1.17.2

package/dist/plugin.js

@@ -4,7 +4,7 @@
  * automatic context injection and documentation mode.
  */
 import { tool } from "@opencode-ai/plugin/tool";
-import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig } from "./core/config.js";
+import { loadConfig, findConfigFile, DEFAULT_CONFIG, resolveLogConfig, persistProbedDimension } from "./core/config.js";
 import { createEmbedder } from "./embedder/factory.js";
 import { createDescriptionProvider } from "./describer/factory.js";
 import { createVectorStore } from "./vectorstore/factory.js";
@@ -22,12 +22,15 @@ import { loadDocProgress, markSubdirectoryDocumented } from "./core/doc-progress
 import { loadManifest } from "./core/manifest.js";
 import { createSessionLogger } from "./eval/session-logger.js";
 import { countTokens } from "./eval/token-counter.js";
-import { checkForUpdate } from "./updater.js";
-import { existsSync, readFileSync, unlinkSync } from "node:fs";
+import { checkForUpdate, getCurrentVersion } from "./core/version-check.js";
+import { destroyAllPooledConnections } from "./embedder/http.js";
+import { existsSync, readFileSync, readdirSync, unlinkSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn, execSync } from "node:child_process";
 import { tmpdir } from "node:os";
+/** Maximum entries per session map before oldest entries are evicted. */
+const MAX_SESSION_MAP_SIZE = 50;
 /** Cache of loaded RAG configurations keyed by workspace directory. */
 const configCache = new Map();
 /** Active background indexer instances keyed by workspace directory. */
@@ -36,6 +39,55 @@ const backgroundIndexers = new Map();
 const mcpServers = new Map();
 /** Pending update notifications keyed by workspace directory. */
 const pendingUpdateInfo = new Map();
+/** Workspace directories that have already been prompted about an update this session. */
+const notifiedUpdateDirs = new Set();
+/** Guard flag to prevent re-entrant shutdown. */
+let shutdownRegistered = false;
+/** Close all active background indexers and MCP servers, then destroy idle sockets. */
+async function shutdownPluginResources() {
+    for (const [dir, indexer] of backgroundIndexers) {
+        try {
+            await indexer.close();
+        }
+        catch { /* best-effort */ }
+        backgroundIndexers.delete(dir);
+    }
+    for (const [dir, server] of mcpServers) {
+        try {
+            await server.close();
+        }
+        catch { /* best-effort */ }
+        mcpServers.delete(dir);
+    }
+    configCache.clear();
+    pendingUpdateInfo.clear();
+    notifiedUpdateDirs.clear();
+    destroyAllPooledConnections();
+}
+/** Register a process.beforeExit handler so that resources are cleaned up
+ *  when the OpenCode process exits (rather than only on plugin reload). */
+function registerShutdownHandler() {
+    if (shutdownRegistered)
+        return;
+    shutdownRegistered = true;
+    process.once("beforeExit", () => {
+        void shutdownPluginResources();
+    });
+}
+registerShutdownHandler();
+/** Set a bounded Map entry, evicting the oldest key if the map exceeds maximum size. */
+function boundedSet(map, key, value, maxSize) {
+    if (map.has(key)) {
+        map.set(key, value);
+        return;
+    }
+    if (map.size >= maxSize) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined)
+            map.delete(oldest);
+    }
+    map.set(key, value);
+}
 /** Name of the semantic search tool as exposed to the LLM. */
 const CONTEXT_TOOL_NAME = "search_semantic";
 /** Marker string injected into context output to identify RAG-sourced content. */
@@ -230,10 +282,10 @@ function buildRetrievalQuery(hints) {
  * Perform a retrieval query against the vector store with the given parameters.
  * Returns an empty array for blank queries.
  */
-async function retrieveContext(query, embedder, store, topK, retrieveFn = retrieve, minScore = 0, keywordIndex, keywordWeight, queryPrefix, explain = false) {
+async function retrieveContext(query, embedder, store, topK, retrieveFn = retrieve, minScore = 0, keywordIndex, keywordWeight, queryPrefix, explain = false, hybridEnabled) {
     if (query.trim().length === 0)
         return [];
-    return retrieveFn(query, embedder, store, { topK, minScore, keywordIndex, keywordWeight, queryPrefix, explain });
+    return retrieveFn(query, embedder, store, { topK, minScore, keywordIndex, keywordWeight, hybridEnabled, queryPrefix, explain });
 }
 /**
  * Load results from one or two queries (primary + optional extra), optimize
@@ -243,9 +295,10 @@ async function retrieveContext(query, embedder, store, topK, retrieveFn = retrie
 async function loadRetrievedResults(query, embedder, store, cfg, retrieveFn = retrieve, topK = cfg.retrieval.topK, extraQuery, keywordIndex, queryPrefix, explain = false) {
     const minScore = cfg.retrieval.minScore;
     const kw = cfg.retrieval.hybridSearch?.keywordWeight;
-    const primaryResults = await retrieveContext(query, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain);
+    const hybridEnabled = cfg.retrieval.hybridSearch?.enabled;
+    const primaryResults = await retrieveContext(query, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled);
     const extraResults = extraQuery
-        ? await retrieveContext(extraQuery, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain)
+        ? await retrieveContext(extraQuery, embedder, store, topK, retrieveFn, minScore, keywordIndex, kw, queryPrefix, explain, hybridEnabled)
         : [];
     const optCfg = cfg.retrieval.contextOptimization ?? DEFAULT_CONTEXT_OPTIMIZATION;
     return optimizeContext([...primaryResults, ...extraResults], { topK, config: optCfg })
@@ -355,12 +408,20 @@ export function createRagHooks(options) {
     let cachedOverrides = loadRuntimeOverrides(options.storePath);
     let overridesLastCheck = 0;
     const OVERRIDES_TTL_MS = Number(process.env.OPENCODE_RAG_OVERRIDES_TTL_MS) || 3600000;
+    let lastEffectiveCfg = null;
+    let lastEffectiveCfgTime = 0;
     function getEffectiveCfg() {
         if (Date.now() - overridesLastCheck > OVERRIDES_TTL_MS) {
             cachedOverrides = loadRuntimeOverrides(options.storePath);
             overridesLastCheck = Date.now();
+            lastEffectiveCfg = null;
         }
-        return applyRuntimeOverrides(options.cfg, cachedOverrides);
+        if (lastEffectiveCfg && Date.now() - lastEffectiveCfgTime < 1000) {
+            return lastEffectiveCfg;
+        }
+        lastEffectiveCfg = applyRuntimeOverrides(options.cfg, cachedOverrides);
+        lastEffectiveCfgTime = Date.now();
+        return lastEffectiveCfg;
     }
     // Session-level caches for lazy retrieval
     const sessionLastMessage = new Map();
@@ -538,6 +599,7 @@ export function createRagHooks(options) {
             sessionLastMessage,
             sessionRetrievalCache,
             keywordIndex,
+            maxSessionCacheSize: MAX_SESSION_MAP_SIZE,
         });
         tools["read"] = readTool;
         appendDebugLog(options.logFilePath, {
@@ -562,8 +624,8 @@ export function createRagHooks(options) {
                     if (msgInfo?.role === "assistant" &&
                         typeof msgInfo.sessionID === "string" &&
                         typeof msgInfo.id === "string") {
-                        sessionAssistantMessageId.set(msgInfo.sessionID, msgInfo.id);
-                        sessionAssistantText.set(msgInfo.sessionID, "");
+                        boundedSet(sessionAssistantMessageId, msgInfo.sessionID, msgInfo.id, MAX_SESSION_MAP_SIZE);
+                        boundedSet(sessionAssistantText, msgInfo.sessionID, "", MAX_SESSION_MAP_SIZE);
                     }
                 }
                 else if (event.type === "message.part.updated") {
@@ -577,7 +639,7 @@ export function createRagHooks(options) {
                         const assistantMsgId = sessionAssistantMessageId.get(part.sessionID);
                         if (assistantMsgId && part.messageID === assistantMsgId) {
                             const existing = sessionAssistantText.get(part.sessionID) ?? "";
-                            sessionAssistantText.set(part.sessionID, existing + delta);
+                            boundedSet(sessionAssistantText, part.sessionID, existing + delta, MAX_SESSION_MAP_SIZE);
                         }
                     }
                 }
@@ -592,48 +654,61 @@ export function createRagHooks(options) {
                 scope: "experimental.chat.system.transform",
                 message: "system guidance injected",
             });
-            const guidance = [
-                "MANDATORY: OpenCodeRAG tools MUST be used before any code task:",
-                "- `search_semantic(query)`: retrieve relevant code chunks. Call BEFORE planning, editing, or answering. Accepts `pathHints` and `languageHints`.",
-                "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
-                "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
-                "- `describe_image(filePath)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image.",
-                "",
-                "Decision tree — ALWAYS follow this order:",
-                "1. User mentions code behavior/architecture → `search_semantic(query)`",
-                "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
-                "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
-                "4. User asks a code question → `search_semantic` to gather context before answering",
-                "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
-                "",
-                "Proactive triggers — you MUST call these tools when:",
-                "- User asks about code behavior, architecture, or implementation details",
-                "- User asks to edit, refactor, or fix code — call `find_usages` first",
-                "- User references files or functions you haven't read yet",
-                "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
-                "- User refers to an image, screenshot, diagram, or visual asset",
-                "- Before answering ANY code-related question, retrieve context first",
-                "- Before reading ANY file, call `get_file_skeleton` to orient first",
-                "",
-                "Anti-patterns — NEVER do these:",
-                "- Reading full files without calling `get_file_skeleton` first (wastes tokens)",
-                "- Editing a function without calling `find_usages` first (breaks call sites)",
-                "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
-                "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
-                "- Treating image files as text — use `describe_image` instead of reading raw bytes",
-            ];
-            output.system.unshift(guidance.join("\n"));
-            // Inject update notification if available
+            const cfg = getEffectiveCfg();
+            if (cfg.openCode.injectSystemPrompt !== false) {
+                const guidance = [
+                    "MANDATORY: OpenCodeRAG tools MUST be used before any code task:",
+                    "- `search_semantic(query)`: retrieve relevant code chunks. Call BEFORE planning, editing, or answering. Accepts `pathHints` and `languageHints`.",
+                    "- `get_file_skeleton(filePath)`: structural overview of a file. Call BEFORE reading any file.",
+                    "- `find_usages(symbolName)`: find all references. Call BEFORE editing any function, class, or variable.",
+                    "- `describe_image(filePath)`: describe an image file using a vision model. Call when user refers to a screenshot, diagram, or image.",
+                    "",
+                    "Decision tree — ALWAYS follow this order:",
+                    "1. User mentions code behavior/architecture → `search_semantic(query)`",
+                    "2. User mentions a file path → `get_file_skeleton(filePath)` THEN `read` on specific lines",
+                    "3. User mentions a function/class/variable to edit → `find_usages(symbolName)` THEN `search_semantic` THEN `edit`",
+                    "4. User asks a code question → `search_semantic` to gather context before answering",
+                    "5. User asks about an image or visual asset → `describe_image(filePath)` to retrieve its generated description, then optionally `search_semantic` for related code",
+                    "",
+                    "Proactive triggers — you MUST call these tools when:",
+                    "- User asks about code behavior, architecture, or implementation details",
+                    "- User asks to edit, refactor, or fix code — call `find_usages` first",
+                    "- User references files or functions you haven't read yet",
+                    "- User says \"find\", \"search\", \"look up\", \"where is\", \"how does\"",
+                    "- User refers to an image, screenshot, diagram, or visual asset",
+                    "- Before answering ANY code-related question, retrieve context first",
+                    "- Before reading ANY file, call `get_file_skeleton` to orient first",
+                    "",
+                    "Anti-patterns — NEVER do these:",
+                    "- Reading full files without calling `get_file_skeleton` first (wastes tokens)",
+                    "- Editing a function without calling `find_usages` first (breaks call sites)",
+                    "- Answering code questions without calling `search_semantic` first (you guess at behavior)",
+                    "- Using `grep`/`glob` when `search_semantic` would find the answer faster",
+                    "- Treating image files as text — use `describe_image` instead of reading raw bytes",
+                ];
+                output.system.unshift(guidance.join("\n"));
+            }
+            // Inject a one-time update prompt so the agent asks the user to install.
+            // Fires only once per workspace per session to avoid nagging on every turn.
             const updateInfo = pendingUpdateInfo.get(options.worktree);
-            if (updateInfo) {
-                output.system.unshift(`OpenCodeRAG update available: ${updateInfo.currentVersion} → ${updateInfo.latestVersion}. ` +
-                    `Run \`opencode-rag update\` to install.`);
+            if (updateInfo && !notifiedUpdateDirs.has(options.worktree)) {
+                notifiedUpdateDirs.add(options.worktree);
+                pendingUpdateInfo.delete(options.worktree);
+                output.system.unshift(`A newer OpenCodeRAG version is available: ${updateInfo.currentVersion} → ${updateInfo.latestVersion}. ` +
+                    `At the very start of your next response, briefly tell the user a new version is available and ask whether ` +
+                    `they would like you to install it. If they agree, run \`opencode-rag update\` via the bash tool, then tell ` +
+                    `them to restart OpenCode to load the new version. Do not mention this notice again.`);
             }
             // Inject documentation mode system prompt if enabled
             const docMode = getEffectiveCfg().documentationMode;
             if (docMode?.enabled && docMode.systemPrompt) {
                 output.system.unshift(docMode.systemPrompt);
             }
+            // Inject wiki mode system prompt if enabled
+            const wikiMode = getEffectiveCfg().wikiMode;
+            if (wikiMode?.enabled && wikiMode.systemPrompt) {
+                output.system.unshift(wikiMode.systemPrompt);
+            }
         },
         async "chat.message"(input, output) {
             try {
@@ -650,7 +725,7 @@ export function createRagHooks(options) {
                 });
                 if (text.length === 0)
                     return;
-                sessionLastMessage.set(input.sessionID, text);
+                boundedSet(sessionLastMessage, input.sessionID, text, MAX_SESSION_MAP_SIZE);
                 // Handle /doc slash command
                 if (text.startsWith("/doc")) {
                     const docMode = getEffectiveCfg().documentationMode;
@@ -735,6 +810,64 @@ export function createRagHooks(options) {
                     }
                     return;
                 }
+                // Handle /wiki slash command
+                if (text.startsWith("/wiki")) {
+                    const wikiMode = getEffectiveCfg().wikiMode;
+                    if (!wikiMode?.enabled) {
+                        const parts = output?.parts ?? output?.message?.parts;
+                        if (Array.isArray(parts) && parts.length > 0) {
+                            const first = parts[0];
+                            if (typeof first.text === "string") {
+                                parts[0] = { ...first, text: "Wiki mode is not enabled. Set `wikiMode.enabled` to `true` in opencode-rag.json." };
+                            }
+                        }
+                        return;
+                    }
+                    const arg = text.slice(5).trim().toLowerCase();
+                    const wikiDir = path.join(options.worktree, ".opencode", "wiki");
+                    const lines = [];
+                    if (arg === "lint") {
+                        lines.push("## Wiki Lint", "", "Run a health check on the wiki. Check for:", "- Orphan pages with no inbound [[links]]", "- Stale pages whose sourceRefs files changed since lastReviewed", "- Contradictions between pages", "- Important concepts mentioned but lacking their own page", "", "Append findings to .opencode/wiki/log.md and fix any issues found.");
+                    }
+                    else if (arg === "seed") {
+                        lines.push("## Wiki Seed", "", "Generate the initial wiki from existing sources:", "1. Read README and top-level docs for project overview → create overview page", "2. Scan file structure with get_file_skeleton for major modules → create entity pages", "3. Identify common conventions from code patterns → create concept pages", "4. Create .opencode/wiki/index.md listing all pages", "5. Create .opencode/wiki/log.md with initial entry", "6. Keep pages focused — one concept per page, short prose, cross-referenced with [[links]]");
+                    }
+                    else {
+                        if (existsSync(wikiDir)) {
+                            const entries = readdirSync(wikiDir);
+                            const pages = entries.filter((e) => e.endsWith(".md") && e !== "log.md").length;
+                            const hasIndex = entries.includes("index.md");
+                            const hasLog = entries.includes("log.md");
+                            const dirs = entries.filter((e) => !e.includes(".")).length;
+                            let lastLogEntry = "";
+                            const logPath = path.join(wikiDir, "log.md");
+                            if (hasLog && existsSync(logPath)) {
+                                const logContent = readFileSync(logPath, "utf-8");
+                                const logLines = logContent.trim().split("\n").filter((l) => l.startsWith("## ["));
+                                if (logLines.length > 0) {
+                                    lastLogEntry = logLines[logLines.length - 1] ?? "";
+                                }
+                            }
+                            lines.push("## Wiki Status", "", `Wiki: \`.opencode/wiki/\``, `Pages: ~${pages} (.md files)`, `Subdirectories: \`${dirs}\``, `Index: ${hasIndex ? "yes" : "no"} | Log: ${hasLog ? "yes" : "no"}`);
+                            if (lastLogEntry) {
+                                lines.push(`Latest log: \`${lastLogEntry}\``);
+                            }
+                            lines.push("", "Commands:", "- `/wiki` — show this status", "- `/wiki lint` — health-check the wiki", "- `/wiki seed` — generate initial wiki pages from the codebase");
+                        }
+                        else {
+                            lines.push("## Wiki Status", "", "No wiki yet at `.opencode/wiki/`.", "Use `/wiki seed` to generate the initial wiki from existing sources.");
+                        }
+                    }
+                    const wikiMsg = lines.join("\n");
+                    const parts = output?.parts ?? output?.message?.parts;
+                    if (Array.isArray(parts) && parts.length > 0) {
+                        const first = parts[0];
+                        if (typeof first.text === "string") {
+                            parts[0] = { ...first, text: wikiMsg };
+                        }
+                    }
+                    return;
+                }
                 // Handle hotkey-triggered RAG injection (Ctrl+Enter / Ctrl+Alt+Enter)
                 const pendingInjection = consumePendingRagInjection(options.storePath);
                 if (pendingInjection) {
@@ -1025,29 +1158,52 @@ export const ragPlugin = async (input, _options) => {
         }
         mcpServers.delete(input.directory);
     }
+    // Clean up stale config cache and pending update info for this directory
+    configCache.delete(input.directory);
+    pendingUpdateInfo.delete(input.directory);
+    notifiedUpdateDirs.delete(input.directory);
+    // Clean up idle HTTP sockets from previous provider connections
+    destroyAllPooledConnections();
     appendDebugLog(logFilePath, {
         scope: "plugin",
         message: `OpenCode plugin enabled for ${input.directory}`,
     }, logLevel);
-    // Probe vector dimension and create store with correct dimension
+    // Use cached dimension from config if available (avoids blocking startup with an API call)
+    // If not set, probe the embedding provider once and persist the result.
     const embedder = createEmbedder(effectiveCfg);
-    let vectorDimension = 384;
-    try {
-        const probe = await embedder.embed(["dimension-probe"], "query");
-        if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
-            vectorDimension = probe[0].length;
-        }
+    let vectorDimension = effectiveCfg.embedding.vectorDimension;
+    if (vectorDimension && vectorDimension > 0) {
         appendDebugLog(logFilePath, {
             scope: "plugin",
-            message: `Vector dimension: ${vectorDimension}`,
+            message: `Vector dimension: ${vectorDimension} (cached in config)`,
         }, logLevel);
     }
-    catch (err) {
-        appendDebugLog(logFilePath, {
-            scope: "plugin",
-            message: `Dimension probe failed, falling back to ${vectorDimension}`,
-            error: err,
-        }, logLevel);
+    else {
+        vectorDimension = 384;
+        try {
+            const probe = await embedder.embed(["dimension-probe"], "query");
+            if (probe && probe[0] && probe[0].length > 0 && typeof probe[0][0] === "number") {
+                vectorDimension = probe[0].length;
+                const configPath = findConfigFile(input.directory);
+                if (configPath) {
+                    try {
+                        persistProbedDimension(configPath, vectorDimension);
+                    }
+                    catch { /* best-effort */ }
+                }
+            }
+            appendDebugLog(logFilePath, {
+                scope: "plugin",
+                message: `Vector dimension: ${vectorDimension}`,
+            }, logLevel);
+        }
+        catch (err) {
+            appendDebugLog(logFilePath, {
+                scope: "plugin",
+                message: `Dimension probe failed, falling back to ${vectorDimension}`,
+                error: err,
+            }, logLevel);
+        }
     }
     const store = createVectorStore(effectiveCfg, storePath, vectorDimension);
     // Load or create keyword index for hybrid search
@@ -1081,6 +1237,7 @@ export const ragPlugin = async (input, _options) => {
             logLevel,
             keywordIndex,
             descriptionProvider,
+            dimension: vectorDimension,
         });
         backgroundIndexers.set(input.directory, indexer);
     }
@@ -1103,18 +1260,13 @@ export const ragPlugin = async (input, _options) => {
         const mcpInstance = startMcpServerProcess(input.directory, logFilePath, logLevel);
         mcpServers.set(input.directory, mcpInstance);
     }
-    // Auto-update check (non-blocking, best-effort)
+    // Auto-update check (non-blocking, best-effort). On by default; can be
+    // disabled via `autoUpdate.enabled: false` in opencode-rag.json. When a newer
+    // release is found it is stored and surfaced as a one-time install prompt via
+    // the system transform hook (see createRagHooks).
     const autoUpdateCfg = effectiveCfg.autoUpdate;
     if (autoUpdateCfg?.enabled) {
-        const currentVersion = (() => {
-            try {
-                const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "package.json");
-                return JSON.parse(readFileSync(pkgPath, "utf-8")).version;
-            }
-            catch {
-                return "0.0.0";
-            }
-        })();
+        const currentVersion = getCurrentVersion();
         checkForUpdate(currentVersion)
             .then((info) => {
             if (info.updateAvailable) {

package/dist/retriever/keyword-index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @fileoverview In-memory inverted keyword index with stemming, tokenization, and optional serialization.
  */
-import type { Chunk, SearchResult } from "../core/interfaces.js";
+import type { Chunk, SearchResult, MetadataFilter } from "../core/interfaces.js";
 /**
  * Tokenize text into normalized tokens including stems, camelCase parts, and snake_case parts.
  *
@@ -22,7 +22,8 @@ export declare class KeywordIndex {
     addChunks(chunks: Chunk[]): void;
     getMatchedTerms(query: string, chunkId: string): string[];
     removeByFilePath(filePath: string): void;
-    search(query: string, topK: number): SearchResult[];
+    search(query: string, topK: number, filter?: MetadataFilter): SearchResult[];
+    close(): void;
     clear(): void;
     count(): number;
     save(storePath?: string): Promise<void>;

package/dist/retriever/keyword-index.js

@@ -124,7 +124,7 @@ export class KeywordIndex {
             }
         }
     }
-    search(query, topK) {
+    search(query, topK, filter) {
         if (this.chunkMap.size === 0)
             return [];
         const queryTokens = tokenize(query);
@@ -144,6 +144,7 @@ export class KeywordIndex {
             }
         }
         const sorted = [...scores.entries()]
+            .filter(([id]) => matchesFilter(this.chunkMap.get(id), filter))
             .sort((a, b) => b[1] - a[1])
             .slice(0, topK);
         return sorted.map(([chunkId, score]) => {
@@ -151,6 +152,10 @@ export class KeywordIndex {
             return { chunk, score };
         });
     }
+    close() {
+        this.invertedIndex.clear();
+        this.chunkMap.clear();
+    }
     clear() {
         this.invertedIndex.clear();
         this.chunkMap.clear();
@@ -232,4 +237,23 @@ export class KeywordIndex {
         await writeFile(targetPath, JSON.stringify({ version: INDEX_VERSION, tokens: [], chunkMap: {} }), "utf-8");
     }
 }
+function globMatch(pattern, filePath) {
+    const GLOBSTAR = "\x00GS\x00";
+    let re = pattern.replace(/\*\*/g, GLOBSTAR);
+    re = re.replace(/([.+^${}()|[\]\\])/g, "\\$1");
+    re = re.replace(new RegExp(GLOBSTAR, "g"), ".*");
+    re = re.replace(/\*/g, "[^/]*");
+    re = re.replace(/\?/g, ".");
+    return new RegExp("^" + re + "$").test(filePath);
+}
+function matchesFilter(chunk, filter) {
+    if (!filter)
+        return true;
+    if (filter.languages?.length && !filter.languages.includes(chunk.metadata.language))
+        return false;
+    if (filter.pathPatterns?.length) {
+        return filter.pathPatterns.some((p) => globMatch(p, chunk.metadata.filePath));
+    }
+    return true;
+}
 //# sourceMappingURL=keyword-index.js.map

package/dist/retriever/retriever.d.ts

@@ -1,15 +1,18 @@
 /**
  * @fileoverview Performs hybrid vector-keyword retrieval with configurable scoring and explanation.
  */
-import type { EmbeddingProvider, KeywordIndex, VectorStore, SearchResult } from "../core/interfaces.js";
+import type { EmbeddingProvider, KeywordIndex, VectorStore, SearchResult, MetadataFilter } from "../core/interfaces.js";
 /** Options controlling the retrieval behavior. */
 export interface RetrieveOptions {
     topK?: number;
     minScore?: number;
     keywordIndex?: KeywordIndex;
     keywordWeight?: number;
+    /** Whether hybrid search is enabled. When false, keyword index is ignored. */
+    hybridEnabled?: boolean;
     queryPrefix?: string;
     explain?: boolean;
+    filter?: MetadataFilter;
 }
 /**
  * Perform hybrid vector-keyword retrieval with configurable scoring.

package/dist/retriever/retriever.js

@@ -2,6 +2,9 @@
  *  We request extra results up-front, then after hybrid fusion + minScore filtering,
  *  we slice back to the requested topK. */
 const FETCH_OVERFETCH_FACTOR = 3;
+const RRF_K = 60;
+/** Multiply raw RRF scores by (K+1) to normalize to ~[0,1]. */
+const RRF_NORMALIZE = RRF_K + 1;
 /**
  * Perform hybrid vector-keyword retrieval with configurable scoring.
  *
@@ -28,13 +31,13 @@ export async function retrieve(query, embedder, store, options = {}) {
         if (typeof embedding[0] !== "number") {
             return [];
         }
-        const vectorResults = await store.search(embedding, topK * FETCH_OVERFETCH_FACTOR);
+        const vectorResults = await store.searchWithFilter(embedding, topK * FETCH_OVERFETCH_FACTOR, options.filter);
         let keywordResults = [];
-        if (options.keywordIndex) {
-            keywordResults = options.keywordIndex.search(query, topK * FETCH_OVERFETCH_FACTOR);
+        if (options.keywordIndex && options.hybridEnabled !== false) {
+            keywordResults = options.keywordIndex.search(query, topK * FETCH_OVERFETCH_FACTOR, options.filter);
         }
         if (keywordResults.length === 0) {
-            const filtered = vectorResults.filter((r) => r.score >= minScore);
+            const filtered = vectorResults.filter((r) => r.score >= minScore).slice(0, topK);
             if (options.explain) {
                 const kw = options.keywordWeight ?? 0.4;
                 for (const r of filtered) {
@@ -51,65 +54,40 @@ export async function retrieve(query, embedder, store, options = {}) {
             }
             return filtered;
         }
-        const kwTopScore = keywordResults.length > 0 ? keywordResults[0].score : 1;
-        const combined = new Map();
-        for (const r of vectorResults) {
-            combined.set(r.chunk.id, {
-                chunk: r.chunk,
-                vScore: r.score,
-                kScore: 0,
-                rawVScore: r.score,
-                rawKScore: 0,
-            });
-        }
-        for (const r of keywordResults) {
-            const existing = combined.get(r.chunk.id);
-            const normalizedK = kwTopScore > 0 ? r.score / kwTopScore : 0;
-            if (existing) {
-                existing.kScore = normalizedK;
-                existing.rawKScore = r.score;
-            }
-            else {
-                combined.set(r.chunk.id, {
-                    chunk: r.chunk,
-                    vScore: 0,
-                    kScore: normalizedK,
-                    rawVScore: 0,
-                    rawKScore: r.score,
-                });
-            }
-        }
+        const vRank = new Map(vectorResults.map((r, i) => [r.chunk.id, i]));
+        const kRank = new Map(keywordResults.map((r, i) => [r.chunk.id, i]));
+        const chunkById = new Map();
+        for (const r of vectorResults)
+            chunkById.set(r.chunk.id, r);
+        for (const r of keywordResults)
+            if (!chunkById.has(r.chunk.id))
+                chunkById.set(r.chunk.id, r);
         const kw = options.keywordWeight ?? 0.4;
-        const combinedResults = [...combined.values()]
-            .map((entry) => {
-            const hasVector = entry.vScore > 0;
-            const hasKeyword = entry.kScore > 0;
-            const score = hasVector && hasKeyword
-                ? (1 - kw) * entry.vScore + kw * entry.kScore
-                : hasVector
-                    ? entry.vScore
-                    : entry.kScore * 0.9;
-            const result = {
-                chunk: entry.chunk,
-                score,
-            };
+        const allIds = new Set([...vRank.keys(), ...kRank.keys()]);
+        const combinedResults = [...allIds].map((id) => {
+            const vR = vRank.get(id);
+            const kR = kRank.get(id);
+            const vContrib = vR !== undefined ? ((1 - kw) * RRF_NORMALIZE) / (RRF_K + vR + 1) : 0;
+            const kContrib = kR !== undefined ? (kw * RRF_NORMALIZE) / (RRF_K + kR + 1) : 0;
+            const score = vContrib + kContrib;
+            const result = { chunk: chunkById.get(id).chunk, score };
             if (options.explain) {
-                const explanation = {
+                result.explanation = {
                     scoreBreakdown: {
-                        vectorScore: entry.vScore,
-                        keywordScore: entry.kScore,
-                        rawVectorScore: entry.rawVScore,
-                        rawKeywordScore: entry.rawKScore,
+                        vectorScore: vContrib,
+                        keywordScore: kContrib,
+                        rawVectorScore: vR !== undefined ? vectorResults[vR].score : 0,
+                        rawKeywordScore: kR !== undefined ? keywordResults[kR].score : 0,
                         keywordWeight: kw,
+                        vectorRank: vR,
+                        keywordRank: kR,
                     },
                 };
-                if (options.keywordIndex && entry.rawKScore > 0) {
-                    const terms = options.keywordIndex.getMatchedTerms(query, entry.chunk.id);
-                    if (terms.length > 0) {
-                        explanation.matchedTerms = terms;
-                    }
+                if (options.keywordIndex && kR !== undefined) {
+                    const terms = options.keywordIndex.getMatchedTerms(query, id);
+                    if (terms.length > 0)
+                        result.explanation.matchedTerms = terms;
                 }
-                result.explanation = explanation;
             }
             return result;
         })