scythe-context-mcp 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -6,6 +6,19 @@ This project follows semantic versioning before npm publication where practical.
 
 ## [Unreleased]
 
+## [0.1.5] - 2026-06-14
+
+### Added
+
+- Add a context-search benchmark comparing `rg`, keyword-only Scythe search, and Gemini-backed hybrid search.
+- Add a local code-aware reranker that uses path, snippet, symbol, import graph, file-role, and source-counterpart signals without extra model/API calls.
+
+## [0.1.4] - 2026-06-14
+
+### Added
+
+- Add keyword-only fallback for hybrid search/context-pack calls when query embedding is unavailable, while preserving explicit `embedding_unavailable` diagnostics for semantic-only mode.
+
 ## [0.1.3] - 2026-06-14
 
 ### Changed

package/README.en.md

@@ -244,11 +244,13 @@ Use `PWD/p` only if you intentionally run a Windows Node process and need WSL to
 | `repo_related_files` | Shows symbols, imports, and importedBy for one file. |
 | `gemini_embedding_probe` | Tests Gemini or proxy compatibility and returns endpoint, latency, error classification, and remediation hints. |
 
+`repo_context_pack(mode="hybrid")` and `repo_semantic_search(mode="hybrid")` degrade to keyword-only results when query embedding is unavailable, returning `effectiveMode: "keyword"` and `fallback.reason: "embedding_unavailable"`. `mode="semantic"` does not degrade and returns `status: "embedding_unavailable"` because pure semantic search requires query embedding. Use `rg` / direct file reads for exact strings, known paths, or small targeted checks.
+
 ## Feature Status
 
-Implemented: repo scanning, chunking, SQLite metadata, SQLite FTS5, sqlite-vec, Gemini Embedding 2 provider, semantic/keyword/hybrid search, lightweight symbol/dependency graph, related-file lookup, `repo_context_pack`, provider diagnostics, and index freshness diagnostics.
+Implemented: repo scanning, chunking, SQLite metadata, SQLite FTS5, sqlite-vec, Gemini Embedding 2 provider, semantic/keyword/hybrid search, keyword-only fallback when embeddings fail, local code-aware reranker, lightweight symbol/dependency graph, related-file lookup, `repo_context_pack`, provider diagnostics, and index freshness diagnostics.
 
-Next: provider capability cache, install/native dependency doctor, keyword-only fallback when embeddings fail, and tree-sitter symbol extraction if needed.
+Next: provider capability cache, install/native dependency doctor, and tree-sitter symbol extraction if needed.
 
 ## Privacy and Local Files
 
@@ -266,6 +268,7 @@ Do not include API keys, proxy tokens, private source snippets, or index databas
 - [Gemini Compatibility](docs/gemini-compatibility.md)
 - [Tech Stack](docs/tech-stack.md)
 - [Codex Integration Review](docs/codex-integration.md)
+- [Context Search Benchmark](docs/benchmark.md)
 
 ## Development and Publishing Checks
 

package/README.md

@@ -244,11 +244,13 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看單一檔案的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 測試 Gemini 或 proxy 相容性，回傳 endpoint、latency、錯誤分類與可修復建議。 |
 
+`repo_context_pack(mode="hybrid")` 和 `repo_semantic_search(mode="hybrid")` 在 query embedding 不可用時會降級成 keyword-only 結果，並回傳 `effectiveMode: "keyword"` 與 `fallback.reason: "embedding_unavailable"`。`mode="semantic"` 不會降級，會回傳 `status: "embedding_unavailable"`，因為純 semantic search 必須有 query embedding。精確字串、已知路徑或小範圍檢查仍建議直接用 `rg` / 直接讀檔。
+
 ## 功能狀態
 
-已完成：repo 掃描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、輕量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。
+已完成：repo 掃描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、embedding 失敗時的 keyword-only fallback、local code-aware reranker、輕量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。
 
-下一步：provider capability cache、安裝/原生依賴 doctor、embedding 失敗時的 keyword-only fallback、必要時加入 tree-sitter symbol extraction。
+下一步：provider capability cache、安裝/原生依賴 doctor、必要時加入 tree-sitter symbol extraction。
 
 ## 隱私與本機檔案
 
@@ -266,6 +268,7 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 - [Gemini 相容性](docs/gemini-compatibility.md)
 - [技術棧](docs/tech-stack.md)
 - [Codex 整合審查](docs/codex-integration.md)
+- [Context search benchmark](docs/benchmark.md)
 
 ## 開發與發佈檢查
 

package/README.zh-CN.md

@@ -244,11 +244,13 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 | `repo_related_files` | 查看单一文件的 symbols、imports、importedBy。 |
 | `gemini_embedding_probe` | 测试 Gemini 或 proxy 兼容性，返回 endpoint、latency、错误分类与可修复建议。 |
 
+`repo_context_pack(mode="hybrid")` 和 `repo_semantic_search(mode="hybrid")` 在 query embedding 不可用时会降级成 keyword-only 结果，并返回 `effectiveMode: "keyword"` 与 `fallback.reason: "embedding_unavailable"`。`mode="semantic"` 不会降级，会返回 `status: "embedding_unavailable"`，因为纯 semantic search 必须有 query embedding。精确字符串、已知路径或小范围检查仍建议直接用 `rg` / 直接读文件。
+
 ## 功能状态
 
-已完成：repo 扫描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、轻量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。
+已完成：repo 扫描、chunking、SQLite metadata、SQLite FTS5、sqlite-vec、Gemini Embedding 2 provider、semantic/keyword/hybrid search、embedding 失败时的 keyword-only fallback、local code-aware reranker、轻量 symbol/dependency graph、related-file lookup、`repo_context_pack`、provider diagnostics、index freshness diagnostics。
 
-下一步：provider capability cache、安装/原生依赖 doctor、embedding 失败时的 keyword-only fallback、必要时加入 tree-sitter symbol extraction。
+下一步：provider capability cache、安装/原生依赖 doctor、必要时加入 tree-sitter symbol extraction。
 
 ## 隐私与本地文件
 
@@ -266,6 +268,7 @@ GEMINI_OUTPUT_DIMENSIONALITY = "1536"
 - [Gemini 兼容性](docs/gemini-compatibility.md)
 - [技术栈](docs/tech-stack.md)
 - [Codex 集成审查](docs/codex-integration.md)
+- [Context search benchmark](docs/benchmark.md)
 
 ## 开发与发布检查
 

package/benchmarks/context-search-cases.json

@@ -0,0 +1,78 @@
+[
+  {
+    "id": "embedding-fallback",
+    "query": "embedding unavailable should fall back to keyword-only context pack",
+    "expectedPaths": [
+      "src/tools/registerTools.ts",
+      "src/indexing/hybridSearch.ts"
+    ],
+    "notes": "Task-style query for the hybrid-to-keyword fallback path."
+  },
+  {
+    "id": "stable-chunk-ids",
+    "query": "preserve stable chunk row ids so embedding cache remains useful after reindex",
+    "expectedPaths": [
+      "src/indexing/indexWriter.ts",
+      "src/storage/schema.ts",
+      "src/storage/sqliteVec.test.ts"
+    ],
+    "notes": "Looks for storage and reindex behavior tied to embedding reuse."
+  },
+  {
+    "id": "utf8-binary-detection",
+    "query": "UTF-8 scanner should not treat a file as binary when prefix ends in multibyte character",
+    "expectedPaths": [
+      "src/indexing/binary.ts",
+      "src/indexing/scanner.test.ts"
+    ],
+    "notes": "Regression coverage for text detection around multibyte boundaries."
+  },
+  {
+    "id": "codex-wsl-config",
+    "query": "Codex App WSL Windows node setup with PWD and WSLENV",
+    "expectedPaths": [
+      "README.md",
+      "docs/codex-integration.md",
+      "src/config.ts"
+    ],
+    "notes": "Documentation and config lookup for the Windows Node plus WSL workspace mode."
+  },
+  {
+    "id": "related-file-graph",
+    "query": "related files imports reverse imports graph for context pack",
+    "expectedPaths": [
+      "src/indexing/relatedFiles.ts",
+      "src/indexing/contextPack.ts"
+    ],
+    "notes": "Finds symbol and dependency graph code used by repo_context_pack."
+  },
+  {
+    "id": "gemini-proxy-url",
+    "query": "Gemini v1beta compatible proxy base URL bearer auth output dimensionality",
+    "expectedPaths": [
+      "src/providers/gemini.ts",
+      "src/config.ts",
+      "docs/gemini-compatibility.md"
+    ],
+    "notes": "Provider compatibility query with base URL and auth details."
+  },
+  {
+    "id": "npm-bin-mode",
+    "query": "npm package executable bin mode should be checked before publish",
+    "expectedPaths": [
+      "scripts/bin-mode.mjs",
+      "package.json",
+      "src/cli.ts"
+    ],
+    "notes": "Release packaging and executable bit smoke coverage."
+  },
+  {
+    "id": "fts-keyword-search",
+    "query": "FTS trigram keyword search ranks chunks by bm25 and file path fallback",
+    "expectedPaths": [
+      "src/indexing/keywordSearch.ts",
+      "src/storage/schema.ts"
+    ],
+    "notes": "Keyword search internals and schema lookup."
+  }
+]

package/dist/cli.js

@@ -1,4 +1,4 @@
-export const PACKAGE_VERSION = "0.1.3";
+export const PACKAGE_VERSION = "0.1.5";
 export function parseCliArgs(args) {
     if (args.length === 0)
         return { kind: "serve" };

package/dist/indexing/codeAwareReranker.js

@@ -0,0 +1,240 @@
+import Database from "better-sqlite3";
+import { keywordTerms } from "./keywordSearch.js";
+import { classifyRelatedPath } from "./relatedFiles.js";
+const sourceExtensions = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
+function compactSnippet(text, maxChars) {
+    const normalized = text.replace(/\s+$/g, "");
+    if (normalized.length <= maxChars)
+        return normalized;
+    return `${normalized.slice(0, Math.max(0, maxChars - 3))}...`;
+}
+function normalizeTerm(value) {
+    return value.toLowerCase();
+}
+function splitIdentifier(value) {
+    return value
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .split(/[^A-Za-z0-9_]+|_/g)
+        .map((part) => part.toLowerCase())
+        .filter((part) => part.length >= 2);
+}
+function queryTerms(query) {
+    const terms = new Set();
+    for (const term of keywordTerms(query)) {
+        terms.add(normalizeTerm(term));
+        for (const part of splitIdentifier(term))
+            terms.add(part);
+    }
+    return Array.from(terms).filter((term) => term.length >= 2);
+}
+function isCodeIntent(terms) {
+    return terms.some((term) => [
+        "function",
+        "class",
+        "type",
+        "interface",
+        "handler",
+        "provider",
+        "schema",
+        "index",
+        "chunk",
+        "row",
+        "cache",
+        "fallback",
+        "rerank",
+        "search",
+        "embedding",
+        "sqlite",
+        "storage",
+        "scanner",
+        "binary",
+    ].includes(term));
+}
+function isDocsIntent(terms) {
+    return terms.some((term) => ["readme", "docs", "documentation", "codex", "wsl", "windows", "setup", "config", "npm", "publish"].includes(term));
+}
+function isTestIntent(terms) {
+    return terms.some((term) => ["test", "tests", "spec", "regression", "fixture"].includes(term));
+}
+function sourceCounterparts(testPath, activePaths) {
+    const counterparts = [];
+    for (const extension of sourceExtensions) {
+        const suffixes = [`.test${extension}`, `.spec${extension}`];
+        for (const suffix of suffixes) {
+            if (!testPath.endsWith(suffix))
+                continue;
+            const base = testPath.slice(0, -suffix.length);
+            for (const sourceExtension of sourceExtensions) {
+                const candidate = `${base}${sourceExtension}`;
+                if (activePaths.has(candidate))
+                    counterparts.push(candidate);
+            }
+        }
+    }
+    return counterparts;
+}
+function readActivePaths(db) {
+    const rows = db.prepare("select path from files").all();
+    return new Set(rows.map((row) => row.path));
+}
+function readCandidateDetails(db, path) {
+    const file = db.prepare("select id from files where path = ?").get(path);
+    if (!file)
+        return { symbols: [], imports: 0, importedBy: 0 };
+    const symbols = db.prepare("select name from file_symbols where file_id = ? limit 80").all(file.id);
+    const imports = db.prepare("select count(*) as count from file_dependencies where file_id = ?").get(file.id).count;
+    const importedBy = db
+        .prepare(`
+        select count(*) as count
+        from file_dependencies
+        join files on files.path = file_dependencies.resolved_path
+        where files.id = ?
+      `)
+        .get(file.id).count;
+    return {
+        symbols: symbols.flatMap((symbol) => [symbol.name, ...splitIdentifier(symbol.name)]),
+        imports,
+        importedBy,
+    };
+}
+function readFirstChunk(db, path, maxSnippetChars) {
+    const row = db
+        .prepare(`
+      select files.path,
+             chunks.start_line as startLine,
+             chunks.end_line as endLine,
+             chunks.text
+      from chunks
+      join files on files.id = chunks.file_id
+      where files.path = ?
+      order by chunks.start_line
+      limit 1
+    `)
+        .get(path);
+    if (!row)
+        return undefined;
+    return {
+        path: row.path,
+        startLine: row.startLine,
+        endLine: row.endLine,
+        score: 0,
+        snippet: compactSnippet(row.text, maxSnippetChars),
+        matchTypes: ["local"],
+    };
+}
+function pathScore(path, terms) {
+    const normalizedPath = path.toLowerCase();
+    const basename = normalizedPath.split("/").at(-1) ?? normalizedPath;
+    let score = 0;
+    for (const term of terms) {
+        if (normalizedPath.includes(term))
+            score += 0.25;
+        if (basename.includes(term))
+            score += 0.2;
+    }
+    return Math.min(score, 2.5);
+}
+function snippetScore(snippet, terms) {
+    if (!snippet)
+        return 0;
+    const text = snippet.toLowerCase();
+    let score = 0;
+    for (const term of terms) {
+        if (text.includes(term))
+            score += 0.08;
+    }
+    return Math.min(score, 0.8);
+}
+function symbolScore(details, terms) {
+    if (details.symbols.length === 0)
+        return 0;
+    const symbols = details.symbols.map((symbol) => symbol.toLowerCase());
+    let score = 0;
+    for (const term of terms) {
+        if (symbols.some((symbol) => symbol === term))
+            score += 0.7;
+        else if (symbols.some((symbol) => symbol.includes(term)))
+            score += 0.25;
+    }
+    return Math.min(score, 2.2);
+}
+function roleScore(path, terms) {
+    const role = classifyRelatedPath(path);
+    const codeIntent = isCodeIntent(terms);
+    const docsIntent = isDocsIntent(terms);
+    const testIntent = isTestIntent(terms);
+    if (role === "generated")
+        return -2;
+    if (role === "test")
+        return testIntent ? 0.4 : codeIntent ? -0.85 : -0.25;
+    if (role === "docs")
+        return docsIntent ? 0.45 : codeIntent ? -0.8 : -0.15;
+    if (role === "source")
+        return codeIntent ? 0.65 : 0.15;
+    return -0.25;
+}
+function graphScore(details) {
+    return Math.min(0.5, details.imports * 0.04 + details.importedBy * 0.08);
+}
+function baseScore(result) {
+    return result.score ?? 0;
+}
+function addCandidate(candidates, candidate) {
+    const key = `${candidate.path}:${candidate.startLine}:${candidate.endLine}`;
+    const existing = candidates.get(key);
+    if (!existing || baseScore(candidate) > baseScore(existing)) {
+        candidates.set(key, candidate);
+    }
+}
+export function rerankCodeAware(options) {
+    if (!Number.isInteger(options.maxResults) || options.maxResults <= 0) {
+        throw new Error("maxResults must be a positive integer");
+    }
+    const terms = queryTerms(options.query);
+    if (terms.length === 0 || options.results.length === 0) {
+        return options.results.slice(0, options.maxResults);
+    }
+    const db = new Database(options.dbPath, { readonly: true });
+    try {
+        const activePaths = readActivePaths(db);
+        const candidates = new Map();
+        for (const result of options.results) {
+            addCandidate(candidates, result);
+            for (const counterpart of sourceCounterparts(result.path, activePaths)) {
+                const counterpartResult = readFirstChunk(db, counterpart, options.maxSnippetChars);
+                if (counterpartResult) {
+                    counterpartResult.score = Math.max(0, baseScore(result) * 0.85);
+                    addCandidate(candidates, counterpartResult);
+                }
+            }
+        }
+        const detailCache = new Map();
+        const detailsFor = (candidatePath) => {
+            const existing = detailCache.get(candidatePath);
+            if (existing)
+                return existing;
+            const details = readCandidateDetails(db, candidatePath);
+            detailCache.set(candidatePath, details);
+            return details;
+        };
+        return Array.from(candidates.values())
+            .map((candidate) => {
+            const details = detailsFor(candidate.path);
+            const rerankScore = baseScore(candidate) +
+                pathScore(candidate.path, terms) +
+                snippetScore(candidate.snippet, terms) +
+                symbolScore(details, terms) +
+                roleScore(candidate.path, terms) +
+                graphScore(details);
+            return {
+                ...candidate,
+                score: rerankScore,
+            };
+        })
+            .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.startLine - b.startLine)
+            .slice(0, options.maxResults);
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/indexing/hybridSearch.js

@@ -1,4 +1,5 @@
 import { searchByKeyword } from "./keywordSearch.js";
+import { rerankCodeAware } from "./codeAwareReranker.js";
 import { searchByVector } from "./semanticSearch.js";
 function keyOf(result) {
     return `${result.path}:${result.startLine}:${result.endLine}`;
@@ -63,5 +64,26 @@ export function searchHybrid(options) {
         maxResults: Math.max(options.maxResults * 2, options.maxResults),
         maxSnippetChars: options.maxSnippetChars,
     });
-    return mergeHybridResults(semanticResults, keywordResults, options.maxResults);
+    return rerankCodeAware({
+        dbPath: options.dbPath,
+        query: options.query,
+        results: mergeHybridResults(semanticResults, keywordResults, Math.max(options.maxResults * 3, options.maxResults)),
+        maxResults: options.maxResults,
+        maxSnippetChars: options.maxSnippetChars,
+    });
+}
+export function searchKeywordOnly(options) {
+    const keywordResults = searchByKeyword({
+        dbPath: options.dbPath,
+        query: options.query,
+        maxResults: Math.max(options.maxResults * 2, options.maxResults),
+        maxSnippetChars: options.maxSnippetChars,
+    });
+    return rerankCodeAware({
+        dbPath: options.dbPath,
+        query: options.query,
+        results: mergeHybridResults([], keywordResults, Math.max(options.maxResults * 3, options.maxResults)),
+        maxResults: options.maxResults,
+        maxSnippetChars: options.maxSnippetChars,
+    });
 }

package/dist/indexing/resultFormat.js

@@ -15,6 +15,9 @@ export function matchReason(result) {
     if (matchTypes.includes("keyword")) {
         return "keyword/path match";
     }
+    if (matchTypes.includes("local")) {
+        return "local code-aware related file";
+    }
     if (typeof result.distance === "number") {
         return `semantic similarity distance ${result.distance.toFixed(4)}`;
     }

package/dist/tools/registerTools.js

@@ -4,7 +4,7 @@ import { z } from "zod";
 import { buildContextPack } from "../indexing/contextPack.js";
 import { reindexDryRun } from "../indexing/dryRun.js";
 import { indexMissingEmbeddings } from "../indexing/embeddingWriter.js";
-import { searchHybrid } from "../indexing/hybridSearch.js";
+import { searchHybrid, searchKeywordOnly } from "../indexing/hybridSearch.js";
 import { readDetailedIndexStatus, readIndexFreshness, recommendedNextActions } from "../indexing/indexStatus.js";
 import { persistentReindexMetadata } from "../indexing/indexWriter.js";
 import { readRelatedFileGraph, readRelatedFiles } from "../indexing/relatedFiles.js";
@@ -35,6 +35,37 @@ function searchIndexedChunks(options) {
             maxSnippetChars: options.maxSnippetChars,
         });
 }
+function searchKeywordOnlyChunks(options) {
+    return searchKeywordOnly({
+        dbPath: options.dbPath,
+        query: options.query,
+        maxResults: options.maxResults,
+        maxSnippetChars: options.maxSnippetChars,
+    });
+}
+function embeddingFailureDetails(error) {
+    const geminiError = error instanceof GeminiEmbeddingError ? error : undefined;
+    return {
+        type: error instanceof Error ? error.name : "UnknownError",
+        message: error instanceof Error ? error.message : String(error),
+        httpStatus: geminiError?.status,
+        retryable: geminiError?.retryable ?? false,
+        bodySnippet: geminiError?.bodySnippet,
+    };
+}
+function embeddingUnavailablePayload(error) {
+    return {
+        status: "embedding_unavailable",
+        fallbackAvailable: "Use mode=hybrid to allow keyword-only fallback, or use rg/direct file reads for exact strings and known paths.",
+        error: embeddingFailureDetails(error),
+        recommendedNextActions: [
+            "Run gemini_embedding_probe with a short test string.",
+            "Verify GEMINI_API_KEY, GEMINI_BASE_URL, GEMINI_AUTH_MODE, and GEMINI_OUTPUT_DIMENSIONALITY.",
+            "Use repo_context_pack with mode=hybrid for keyword-only degraded results while embeddings are unavailable.",
+            "Use rg/direct file reads for exact strings, known paths, or small targeted checks.",
+        ],
+    };
+}
 function buildGeminiDiagnostics(config, expectedDimensions) {
     const diagnostics = {
         baseUrl: config.baseUrl,
@@ -223,20 +254,50 @@ export function registerTools(server, config) {
                 message: "Run repo_reindex with dry_run=false and index_embeddings=true before semantic search.",
             });
         }
-        const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
         const dimensions = expectedDimensions;
-        if (queryEmbedding.dimensions !== dimensions) {
-            throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+        let effectiveMode = mode;
+        let fallback;
+        let rawResults;
+        try {
+            const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
+            if (queryEmbedding.dimensions !== dimensions) {
+                throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+            }
+            rawResults = searchIndexedChunks({
+                dbPath,
+                query,
+                dimensions,
+                queryVector: queryEmbedding.vector,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+                mode,
+            });
+        }
+        catch (error) {
+            if (mode === "semantic") {
+                return asJsonText({
+                    query,
+                    projectPath,
+                    dbPath,
+                    dimensions,
+                    mode,
+                    ...embeddingUnavailablePayload(error),
+                });
+            }
+            effectiveMode = "keyword";
+            fallback = {
+                reason: "embedding_unavailable",
+                fromMode: mode,
+                toMode: "keyword",
+                error: embeddingFailureDetails(error),
+            };
+            rawResults = searchKeywordOnlyChunks({
+                dbPath,
+                query,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+            });
         }
-        const rawResults = searchIndexedChunks({
-            dbPath,
-            query,
-            dimensions,
-            queryVector: queryEmbedding.vector,
-            maxResults: max_results,
-            maxSnippetChars: max_snippet_chars,
-            mode,
-        });
         const formatted = formatSearchResults(query, rawResults, { maxContextChars: max_context_chars });
         return asJsonText({
             query,
@@ -244,6 +305,8 @@ export function registerTools(server, config) {
             dbPath,
             dimensions,
             mode,
+            effectiveMode,
+            fallback,
             results: formatted.results,
             context: formatted.summary,
             resultCount: rawResults.length,
@@ -308,20 +371,50 @@ export function registerTools(server, config) {
                 message: "Run repo_reindex with dry_run=false and index_embeddings=true before building a context pack.",
             });
         }
-        const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
         const dimensions = expectedDimensions;
-        if (queryEmbedding.dimensions !== dimensions) {
-            throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+        let effectiveMode = mode;
+        let fallback;
+        let rawResults;
+        try {
+            const queryEmbedding = await embeddingProvider.embed({ kind: "query", text: query });
+            if (queryEmbedding.dimensions !== dimensions) {
+                throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${queryEmbedding.dimensions}`);
+            }
+            rawResults = searchIndexedChunks({
+                dbPath,
+                query,
+                dimensions,
+                queryVector: queryEmbedding.vector,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+                mode,
+            });
+        }
+        catch (error) {
+            if (mode === "semantic") {
+                return asJsonText({
+                    query,
+                    projectPath,
+                    dbPath,
+                    dimensions,
+                    mode,
+                    ...embeddingUnavailablePayload(error),
+                });
+            }
+            effectiveMode = "keyword";
+            fallback = {
+                reason: "embedding_unavailable",
+                fromMode: mode,
+                toMode: "keyword",
+                error: embeddingFailureDetails(error),
+            };
+            rawResults = searchKeywordOnlyChunks({
+                dbPath,
+                query,
+                maxResults: max_results,
+                maxSnippetChars: max_snippet_chars,
+            });
         }
-        const rawResults = searchIndexedChunks({
-            dbPath,
-            query,
-            dimensions,
-            queryVector: queryEmbedding.vector,
-            maxResults: max_results,
-            maxSnippetChars: max_snippet_chars,
-            mode,
-        });
         const relatedPaths = Array.from(new Set(rawResults.map((result) => result.path))).slice(0, Math.min(max_seed_files, max_related_files));
         const relatedFiles = readRelatedFileGraph({
             dbPath,
@@ -355,6 +448,8 @@ export function registerTools(server, config) {
             dbPath,
             dimensions,
             mode,
+            effectiveMode,
+            fallback,
             relatedDepth: related_depth,
             relatedSeedCount: relatedPaths.length,
             includeRelatedSnippets: include_related_snippets,

package/docs/benchmark.md

@@ -0,0 +1,41 @@
+# Context Search Benchmark
+
+This benchmark compares three lookup modes:
+
+- `rg-smart`: local ripgrep baseline without MCP or embeddings.
+- `scythe-keyword`: Scythe metadata, FTS, symbols, dependencies, and context packing without embeddings.
+- `scythe-hybrid`: Scythe hybrid search with Gemini-compatible query embeddings plus keyword results.
+
+Run the default no-API baseline:
+
+```bash
+npm run bench:context
+```
+
+When running from a source checkout after changing TypeScript files, rebuild first or use:
+
+```bash
+npm run bench:context:source
+```
+
+Run with Gemini-backed hybrid search:
+
+```bash
+npm run bench:context -- --include-hybrid
+```
+
+The benchmark runner loads `.env` the same way the MCP server does. If `GEMINI_API_KEY` is not available to the benchmark process, `scythe-hybrid` is reported as skipped instead of failed.
+
+Write a machine-readable report:
+
+```bash
+npm run bench:context -- --json --output local/benchmark/context-search.json
+```
+
+The benchmark expects an existing `.scythe-context/index.sqlite` for the target project. Refresh it before measuring:
+
+```bash
+# Through the MCP tool, run repo_reindex with dry_run=false.
+```
+
+The default case file is `benchmarks/context-search-cases.json`. Each case has a natural-language query and one or more expected paths. The summary reports ok/skipped/error counts, hit@1, hit@3, hit@5, MRR, and latency. Use this before and after ranking changes so reranker improvements are measured instead of judged by feel.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scythe-context-mcp",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Local MCP context engine for Codex with Gemini Embedding 2 support.",
   "type": "module",
   "license": "Apache-2.0",
@@ -30,11 +30,15 @@
     "README.zh-CN.md",
     "CHANGELOG.md",
     "LICENSE",
+    "benchmarks",
     "docs",
+    "scripts/context-benchmark.mjs",
     ".env.example"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/bin-mode.mjs ensure",
+    "bench:context": "node scripts/context-benchmark.mjs",
+    "bench:context:source": "npm run build && node scripts/context-benchmark.mjs",
     "dev": "tsx src/index.ts",
     "prepack": "npm run build",
     "smoke": "node dist/index.js --version && node dist/index.js --help",

package/scripts/context-benchmark.mjs

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { spawnSync } from "node:child_process";
+import { performance } from "node:perf_hooks";
+
+const DEFAULT_CASES_PATH = "benchmarks/context-search-cases.json";
+
+function parseArgs(argv) {
+  const args = {
+    project: process.cwd(),
+    cases: DEFAULT_CASES_PATH,
+    maxResults: 8,
+    maxSnippetChars: 1200,
+    maxContextChars: 16000,
+    includeHybrid: false,
+    json: false,
+    output: undefined,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = () => {
+      i += 1;
+      if (i >= argv.length) throw new Error(`${arg} requires a value`);
+      return argv[i];
+    };
+
+    switch (arg) {
+      case "--project":
+        args.project = next();
+        break;
+      case "--cases":
+        args.cases = next();
+        break;
+      case "--max-results":
+        args.maxResults = Number(next());
+        break;
+      case "--max-snippet-chars":
+        args.maxSnippetChars = Number(next());
+        break;
+      case "--max-context-chars":
+        args.maxContextChars = Number(next());
+        break;
+      case "--include-hybrid":
+        args.includeHybrid = true;
+        break;
+      case "--json":
+        args.json = true;
+        break;
+      case "--output":
+        args.output = next();
+        break;
+      case "--help":
+      case "-h":
+        printHelp();
+        process.exit(0);
+      default:
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  for (const key of ["maxResults", "maxSnippetChars", "maxContextChars"]) {
+    if (!Number.isInteger(args[key]) || args[key] <= 0) {
+      throw new Error(`${key} must be a positive integer`);
+    }
+  }
+
+  return args;
+}
+
+function printHelp() {
+  console.log(`Usage: npm run bench:context -- [options]
+
+Options:
+  --project <path>             Project to benchmark. Defaults to cwd.
+  --cases <path>               JSON case file. Defaults to ${DEFAULT_CASES_PATH}.
+  --max-results <n>            Ranked results to keep per method. Defaults to 8.
+  --include-hybrid             Also run Gemini-backed hybrid search.
+  --json                       Print JSON instead of a table.
+  --output <path>              Write JSON report to a file.
+`);
+}
+
+function readCases(casesPath) {
+  const raw = fs.readFileSync(casesPath, "utf8");
+  const cases = JSON.parse(raw);
+  if (!Array.isArray(cases)) throw new Error("Benchmark cases must be a JSON array");
+  return cases.map((item, index) => {
+    if (!item.id || !item.query || !Array.isArray(item.expectedPaths) || item.expectedPaths.length === 0) {
+      throw new Error(`Invalid benchmark case at index ${index}`);
+    }
+    return item;
+  });
+}
+
+function uniquePaths(results) {
+  const seen = new Set();
+  const paths = [];
+  for (const result of results) {
+    const candidate = typeof result === "string" ? result : result.path;
+    if (!candidate) continue;
+    const normalized = normalizeRelativePath(candidate);
+    if (!normalized || seen.has(normalized)) continue;
+    seen.add(normalized);
+    paths.push(normalized);
+  }
+  return paths;
+}
+
+function normalizeRelativePath(value) {
+  return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+
+function rankOfExpected(paths, expectedPaths) {
+  const expected = new Set(expectedPaths.map(normalizeRelativePath));
+  const index = paths.findIndex((candidate) => expected.has(candidate));
+  return index >= 0 ? index + 1 : null;
+}
+
+function metricsFor(paths, expectedPaths) {
+  const rank = rankOfExpected(paths, expectedPaths);
+  return {
+    rank,
+    hitAt1: rank === 1,
+    hitAt3: rank !== null && rank <= 3,
+    hitAt5: rank !== null && rank <= 5,
+    reciprocalRank: rank ? 1 / rank : 0,
+  };
+}
+
+function mean(values) {
+  if (values.length === 0) return 0;
+  return values.reduce((sum, value) => sum + value, 0) / values.length;
+}
+
+function percentile(values, p) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[index];
+}
+
+function benchmarkMethod(name, cases, runCase) {
+  const caseResults = [];
+  for (const testCase of cases) {
+    const startedAt = performance.now();
+    try {
+      const result = runCase(testCase);
+      const latencyMs = performance.now() - startedAt;
+      const paths = uniquePaths(result.paths ?? []);
+      caseResults.push({
+        id: testCase.id,
+        query: testCase.query,
+        expectedPaths: testCase.expectedPaths,
+        status: result.status ?? "ok",
+        latencyMs,
+        paths,
+        contextPaths: result.contextPaths ? uniquePaths(result.contextPaths) : undefined,
+        error: result.error,
+        ...metricsFor(paths, testCase.expectedPaths),
+        context: result.contextPaths ? metricsFor(uniquePaths(result.contextPaths), testCase.expectedPaths) : undefined,
+      });
+    } catch (error) {
+      const latencyMs = performance.now() - startedAt;
+      caseResults.push({
+        id: testCase.id,
+        query: testCase.query,
+        expectedPaths: testCase.expectedPaths,
+        status: "error",
+        latencyMs,
+        paths: [],
+        error: error instanceof Error ? error.message : String(error),
+        ...metricsFor([], testCase.expectedPaths),
+      });
+    }
+  }
+
+  return {
+    method: name,
+    summary: summarizeCases(caseResults),
+    cases: caseResults,
+  };
+}
+
+function summarizeCases(caseResults) {
+  return {
+    cases: caseResults.length,
+    ok: caseResults.filter((item) => item.status === "ok").length,
+    skipped: caseResults.filter((item) => item.status === "skipped").length,
+    errors: caseResults.filter((item) => item.status === "error").length,
+    hitAt1: mean(caseResults.map((item) => (item.hitAt1 ? 1 : 0))),
+    hitAt3: mean(caseResults.map((item) => (item.hitAt3 ? 1 : 0))),
+    hitAt5: mean(caseResults.map((item) => (item.hitAt5 ? 1 : 0))),
+    mrr: mean(caseResults.map((item) => item.reciprocalRank)),
+    meanLatencyMs: mean(caseResults.map((item) => item.latencyMs)),
+    p95LatencyMs: percentile(caseResults.map((item) => item.latencyMs), 95),
+  };
+}
+
+function rgAvailable() {
+  const result = spawnSync("rg", ["--version"], { encoding: "utf8" });
+  return result.status === 0;
+}
+
+function rgSmartSearch(projectPath, query, maxResults, keywordTerms) {
+  if (!rgAvailable()) {
+    return { status: "skipped", paths: [], error: "rg is not available on PATH" };
+  }
+
+  const terms = keywordTerms(query)
+    .filter((term) => term.length >= 3)
+    .slice(0, 10);
+  if (terms.length === 0) return { paths: [] };
+
+  const args = [
+    "--json",
+    "--ignore-case",
+    "--line-number",
+    "--glob",
+    "!.scythe-context/**",
+    "--glob",
+    "!local/**",
+    "--glob",
+    "!node_modules/**",
+    "--glob",
+    "!dist/**",
+    "--glob",
+    "!build/**",
+    "--glob",
+    "!coverage/**",
+    "--glob",
+    "!package-lock.json",
+    "--glob",
+    "!pnpm-lock.yaml",
+    "--glob",
+    "!yarn.lock",
+  ];
+  for (const term of terms) args.push("-e", term);
+  args.push(".");
+
+  const result = spawnSync("rg", args, {
+    cwd: projectPath,
+    encoding: "utf8",
+    maxBuffer: 32 * 1024 * 1024,
+  });
+
+  if (result.status !== 0 && result.status !== 1) {
+    return {
+      status: "error",
+      paths: [],
+      error: result.stderr.trim() || `rg exited with status ${result.status}`,
+    };
+  }
+
+  const scores = new Map();
+  const lines = result.stdout.split(/\r?\n/).filter(Boolean);
+  for (const line of lines) {
+    let event;
+    try {
+      event = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (event.type !== "match") continue;
+    const filePath = event.data?.path?.text;
+    if (!filePath) continue;
+    const lineText = event.data?.lines?.text ?? "";
+    const matches = event.data?.submatches?.length ?? 1;
+    const current = scores.get(filePath) ?? { path: filePath, score: 0, firstLine: event.data?.line_number ?? 0 };
+    current.score += matches + terms.filter((term) => lineText.toLowerCase().includes(term.toLowerCase())).length * 0.25;
+    current.firstLine = Math.min(current.firstLine || Infinity, event.data?.line_number ?? Infinity);
+    scores.set(filePath, current);
+  }
+
+  const paths = Array.from(scores.values())
+    .sort((a, b) => b.score - a.score || a.firstLine - b.firstLine || a.path.localeCompare(b.path))
+    .slice(0, maxResults)
+    .map((item) => item.path);
+
+  return { paths };
+}
+
+function contextPathsFromResults(rawResults, buildContextPack, readRelatedFileGraph, options) {
+  const seedPaths = uniquePaths(rawResults).slice(0, 3);
+  const relatedFiles = readRelatedFileGraph({
+    dbPath: options.dbPath,
+    seedPaths,
+    maxDepth: 1,
+    maxFiles: 10,
+    maxResultsPerFile: 8,
+  });
+  const pack = buildContextPack(options.query, rawResults, relatedFiles, {
+    maxContextChars: options.maxContextChars,
+    maxRelatedFiles: 10,
+    maxRelatedItems: 8,
+  });
+  return pack.suggestedPaths;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), "..");
+  const projectPath = path.resolve(args.project);
+  const casesPath = path.resolve(args.cases);
+  const cases = readCases(casesPath);
+  const dbPath = path.join(projectPath, ".scythe-context", "index.sqlite");
+
+  if (!fs.existsSync(dbPath)) {
+    throw new Error(`Index database not found: ${dbPath}. Run repo_reindex first.`);
+  }
+
+  const [
+    { keywordTerms },
+    { searchKeywordOnly, searchHybrid },
+    { buildContextPack },
+    { readRelatedFileGraph },
+  ] = await Promise.all([
+    import(path.join(repoRoot, "dist/indexing/keywordSearch.js")),
+    import(path.join(repoRoot, "dist/indexing/hybridSearch.js")),
+    import(path.join(repoRoot, "dist/indexing/contextPack.js")),
+    import(path.join(repoRoot, "dist/indexing/relatedFiles.js")),
+  ]);
+
+  const methods = [
+    benchmarkMethod("rg-smart", cases, (testCase) =>
+      rgSmartSearch(projectPath, testCase.query, args.maxResults, keywordTerms),
+    ),
+    benchmarkMethod("scythe-keyword", cases, (testCase) => {
+      const rawResults = searchKeywordOnly({
+        dbPath,
+        query: testCase.query,
+        maxResults: args.maxResults,
+        maxSnippetChars: args.maxSnippetChars,
+      });
+      return {
+        paths: rawResults,
+        contextPaths: contextPathsFromResults(rawResults, buildContextPack, readRelatedFileGraph, {
+          dbPath,
+          query: testCase.query,
+          maxContextChars: args.maxContextChars,
+        }),
+      };
+    }),
+  ];
+
+  if (args.includeHybrid) {
+    const [{ loadConfig }, { GeminiEmbeddingProvider }] = await Promise.all([
+      import(path.join(repoRoot, "dist/config.js")),
+      import(path.join(repoRoot, "dist/providers/gemini.js")),
+    ]);
+    const config = loadConfig();
+    if (!config.gemini.apiKey) {
+      const hybridCases = cases.map((testCase) => ({
+        id: testCase.id,
+        query: testCase.query,
+        expectedPaths: testCase.expectedPaths,
+        status: "skipped",
+        latencyMs: 0,
+        paths: [],
+        error: "GEMINI_API_KEY is not set",
+        ...metricsFor([], testCase.expectedPaths),
+      }));
+      methods.push({
+        method: "scythe-hybrid",
+        summary: summarizeCases(hybridCases),
+        cases: hybridCases,
+      });
+    } else {
+      const provider = new GeminiEmbeddingProvider(config.gemini);
+      const dimensions = config.gemini.outputDimensionality ?? 1536;
+
+      const hybridCases = [];
+      for (const testCase of cases) {
+        const startedAt = performance.now();
+        try {
+          const embedding = await provider.embed({ kind: "query", text: testCase.query });
+          if (embedding.dimensions !== dimensions) {
+            throw new Error(`Query embedding dimensions mismatch: expected ${dimensions}, got ${embedding.dimensions}`);
+          }
+          const rawResults = searchHybrid({
+            dbPath,
+            query: testCase.query,
+            dimensions,
+            queryVector: embedding.vector,
+            maxResults: args.maxResults,
+            maxSnippetChars: args.maxSnippetChars,
+          });
+          const paths = uniquePaths(rawResults);
+          const contextPaths = contextPathsFromResults(rawResults, buildContextPack, readRelatedFileGraph, {
+            dbPath,
+            query: testCase.query,
+            maxContextChars: args.maxContextChars,
+          });
+          hybridCases.push({
+            id: testCase.id,
+            query: testCase.query,
+            expectedPaths: testCase.expectedPaths,
+            status: "ok",
+            latencyMs: performance.now() - startedAt,
+            paths,
+            contextPaths: uniquePaths(contextPaths),
+            ...metricsFor(paths, testCase.expectedPaths),
+            context: metricsFor(uniquePaths(contextPaths), testCase.expectedPaths),
+          });
+        } catch (error) {
+          hybridCases.push({
+            id: testCase.id,
+            query: testCase.query,
+            expectedPaths: testCase.expectedPaths,
+            status: "error",
+            latencyMs: performance.now() - startedAt,
+            paths: [],
+            error: error instanceof Error ? error.message : String(error),
+            ...metricsFor([], testCase.expectedPaths),
+          });
+        }
+      }
+      methods.push({
+        method: "scythe-hybrid",
+        summary: summarizeCases(hybridCases),
+        cases: hybridCases,
+      });
+    }
+  }
+
+  const report = {
+    generatedAt: new Date().toISOString(),
+    projectPath,
+    casesPath,
+    dbPath,
+    maxResults: args.maxResults,
+    methods,
+  };
+
+  if (args.output) {
+    const outputPath = path.resolve(args.output);
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, `${JSON.stringify(report, null, 2)}\n`);
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  console.log(`Context search benchmark`);
+  console.log(`Project: ${projectPath}`);
+  console.log(`Cases: ${cases.length}`);
+  console.log("");
+  console.log("method           ok/skp/err  hit@1  hit@3  hit@5  MRR    mean ms  p95 ms");
+  console.log("---------------  ----------  -----  -----  -----  -----  -------  ------");
+  for (const method of methods) {
+    const summary = method.summary;
+    console.log(
+      `${method.method.padEnd(15)}  ${String(`${summary.ok}/${summary.skipped}/${summary.errors}`).padStart(10)}  ${summary.hitAt1.toFixed(2).padStart(5)}  ${summary.hitAt3.toFixed(2).padStart(5)}  ${summary.hitAt5.toFixed(2).padStart(5)}  ${summary.mrr.toFixed(2).padStart(5)}  ${summary.meanLatencyMs.toFixed(1).padStart(7)}  ${summary.p95LatencyMs.toFixed(1).padStart(6)}`,
+    );
+  }
+
+  console.log("");
+  console.log("Misses:");
+  for (const method of methods) {
+    const misses = method.cases.filter((item) => item.status === "ok" && !item.hitAt5);
+    if (misses.length === 0) continue;
+    console.log(`- ${method.method}: ${misses.map((item) => item.id).join(", ")}`);
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});