codesearch-mcp 0.0.15-alpha → 0.0.17-alpha

package/dist/src/services/LoggerService.js

@@ -50,17 +50,20 @@ class LoggerService {
     static silent() {
         return new LoggerService((0, pino_1.default)({ level: 'silent' }));
     }
-    static fromEnv(name) {
-        const level = (process.env.LOG_LEVEL ?? 'error');
-        const logDirEnv = process.env.LOG_DIR;
-        const enabled = logDirEnv !== 'false' && logDirEnv !== '0';
+    static fromConfig(cfg, name) {
+        const level = cfg.level;
+        const dirVal = cfg.dir;
+        const enabled = dirVal !== 'false' && dirVal !== '0';
         let filePath = null;
         if (enabled) {
-            const logDir = logDirEnv || DEFAULT_LOG_DIR;
+            const logDir = dirVal || DEFAULT_LOG_DIR;
             filePath = name
                 ? path.join(logDir, name, `${name}.log`)
                 : path.join(logDir, 'rag.log');
         }
+        return LoggerService.buildFromPath(level, filePath);
+    }
+    static buildFromPath(level, filePath) {
         if (filePath)
             fs.mkdirSync(path.dirname(filePath), { recursive: true });
         const transport = filePath

package/dist/src/services/McpServer.d.ts

@@ -7,6 +7,7 @@ export declare class McpServer {
     private logger;
     constructor(searcher: SearcherService, config: Config, logger?: LoggerService);
     start(startupError?: Error): Promise<void>;
+    private formatGraphContext;
     private formatChunk;
     private formatDependencies;
     private formatDependents;

package/dist/src/services/McpServer.js

@@ -59,10 +59,13 @@ Pick one workflow based on what you need:
 | Type | Signals | Workflow |
 |---|---|---|
 | **Lookup** | "where is X defined", "find Y" | find_symbol (if name known) → search_codebase (if not found) |
+| **Caller trace** | "who calls X", "find usages of Y", "what invokes Z" | find_symbol → get_callers |
 | **Conceptual** | "how does X work", "what is Y" | search_codebase → read_file_range |
 | **Flow audit** | "how does X connect to Y", "audit this flow", "trace the path" | search_codebase → **get_dependencies + get_dependents** → Grep |
 | **Impact** | "what would break if I change X", "what uses Z" | get_dependents → search_codebase for context |
 
+> **No results?** Never conclude the code doesn't exist after a single attempt. Retry with \`threshold\` raised by 0.05–0.10 (e.g. 0.45 → 0.50 → 0.55) before giving up. The code may exist under a different name or domain term.
+
 ## Tools
 
 - **list_projects** — call this first to see what projects are indexed and their exact names.
@@ -71,6 +74,7 @@ Pick one workflow based on what you need:
 - **get_dependencies** — show what files a given file imports (direct or transitive). Use to understand what a file depends on.
 - **get_dependents** — show which files import a given file (reverse graph). Use before refactoring to find all callers.
 - **find_symbol** — find where a symbol (function, class, type, interface, variable, method) is defined by exact name. Faster than semantic search when you know the name.
+- **get_callers** — find all call sites of a function or method by exact name. Uses the call graph index — faster and more precise than grep. Use after find_symbol to trace where a symbol is actually called.
 - **list_files** — browse the directory tree of a project path. Use to understand project structure before reading files.
 - **read_file** — read a complete file by **absolute path** with line numbers. Truncates at max_lines with a hint to continue.
 
@@ -81,8 +85,9 @@ Pick one workflow based on what you need:
 2. Use \`search_codebase\` to find relevant code by meaning. If your query uses an ambiguous term (e.g. "subscription" could mean pub/sub or billing), pass a lower \`threshold\` (e.g. \`0.40–0.45\`) to filter out weak matches.
 3. If a result looks **truncated or incomplete**, call \`read_file_range\` with the returned \`file_path\` and \`start_line\`.
 4. For exploratory searches where results span chunk boundaries, pass \`include_neighbors: true\`.
-5. Use \`find_symbol\` when you know the exact name — faster than semantic search. Use \`kind: "method"\` for class methods — grep matches lines where \`public\`, \`async\`, \`static\`, or \`override\` appears before the name.
-6. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file by absolute path.
+5. To immediately see a file's imports and callers without extra tool calls, pass \`include_graph_context: true\` to \`search_codebase\`. Use this when doing a quick structural survey; switch to \`get_dependencies\`/\`get_dependents\` for full transitive graphs.
+6. Use \`find_symbol\` when you know the exact name — faster than semantic search. Use \`kind: "method"\` for class methods — grep matches lines where \`public\`, \`async\`, \`static\`, or \`override\` appears before the name. After locating a symbol, use \`get_callers\` to find all call sites — faster and more precise than grep (requires \`rag-index backfill --calls\` to have been run).
+7. Use \`list_files\` to explore project structure before diving into files. Use \`read_file\` to read a complete file by absolute path.
 
 ### Flow audit (mandatory steps — do not skip 3 and 4)
 1. Use \`list_projects\` to confirm project names.
@@ -129,6 +134,9 @@ class McpServer {
         this.logger = logger;
     }
     async start(startupError) {
+        if (startupError) {
+            this.logger.error('McpServer: startup failed, server will report error on every tool call', { reason: startupError.message });
+        }
         const server = new index_js_1.Server({ name: 'local-rag', version: PKG_VERSION }, { capabilities: { tools: {} }, instructions: buildInstructions(this.config.search.similarityThreshold) });
         server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
             tools: [
@@ -142,6 +150,7 @@ class McpServer {
                             limit: { type: 'number', description: `Max results (default ${this.config.search.defaultLimit}, max ${this.config.search.maxLimit})` },
                             project: { type: 'string', description: 'Filter by project name (optional). Use list_projects to see available names.' },
                             include_neighbors: { type: 'boolean', description: 'Also include the chunk before and after each result from the same file (Small-to-Big retrieval). Useful when results look truncated.' },
+                            include_graph_context: { type: 'boolean', description: 'Append direct imports and dependents list to each result. Shows "Imports: X · Y" and "Used by: Z" without extra tool calls.' },
                             threshold: { type: 'number', description: `Max cosine distance (0–1). Lower = stricter. Default: ${this.config.search.similarityThreshold}. Use 0.40–0.45 for precise technical queries, 0.55–0.60 for broad exploration.` },
                         },
                         required: ['query'],
@@ -206,6 +215,19 @@ class McpServer {
                         required: ['name'],
                     },
                 },
+                {
+                    name: 'get_callers',
+                    description: 'Find all call sites of a function or method by exact name. Uses the call graph index — faster and more precise than grep. Use after find_symbol to trace where a symbol is actually called. Returns empty if rag-index backfill --calls has not been run.',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            symbol: { type: 'string', description: 'Exact function or method name (case-sensitive)' },
+                            project: { type: 'string', description: 'Project name (from list_projects)' },
+                            callee_file: { type: 'string', description: 'Optional: filter by definition file path (as returned by find_symbol) to disambiguate overloaded names' },
+                        },
+                        required: ['symbol', 'project'],
+                    },
+                },
                 {
                     name: 'list_files',
                     description: 'List files and directories in a project path as an indented tree. Use to understand project structure before reading files.',
@@ -244,8 +266,10 @@ class McpServer {
                 };
             }
             try {
+                const t0 = Date.now();
                 if (req.params.name === 'list_projects') {
                     const rows = await this.searcher.listProjects();
+                    this.logger.debug('McpServer: list_projects', { count: rows.length, ms: Date.now() - t0 });
                     if (rows.length === 0) {
                         return { content: [{ type: 'text', text: 'No indexed projects found.' }] };
                     }
@@ -271,6 +295,7 @@ class McpServer {
                     const limit = Math.min(Math.max(1, Number(req.params.arguments?.limit) || this.config.search.defaultLimit), this.config.search.maxLimit);
                     const project = req.params.arguments?.project ? String(req.params.arguments.project) : null;
                     const includeNeighbors = Boolean(req.params.arguments?.include_neighbors);
+                    const includeGraphContext = Boolean(req.params.arguments?.include_graph_context);
                     const rawThreshold = req.params.arguments?.threshold;
                     const parsedThreshold = Number(rawThreshold);
                     const threshold = rawThreshold != null && !isNaN(parsedThreshold)
@@ -278,17 +303,30 @@ class McpServer {
                         : undefined;
                     const { query, translated } = await this.searcher.prepareQuery(raw);
                     const results = await this.searcher.searchChunks(query, limit, project, threshold);
+                    this.logger.debug('McpServer: search_codebase', {
+                        query: raw.slice(0, 120),
+                        project,
+                        threshold: threshold ?? this.config.search.similarityThreshold,
+                        limit,
+                        translated,
+                        count: results.length,
+                        ms: Date.now() - t0,
+                    });
                     if (results.length === 0) {
                         return { content: [{ type: 'text', text: 'No relevant results found.' }] };
                     }
                     const header = translated ? `> Query translated: "${raw}" → "${query}"\n\n` : '';
+                    let graphCtx = null;
+                    if (includeGraphContext) {
+                        graphCtx = await this.searcher.fetchGraphContext(results);
+                    }
                     if (includeNeighbors) {
                         const withNeighbors = await this.searcher.fetchNeighbors(results);
                         const blocks = withNeighbors.map(({ result, prevChunk, nextChunk }) => {
                             const parts = [];
                             if (prevChunk)
                                 parts.push(this.formatChunk(prevChunk, 'prev chunk'));
-                            parts.push(`${this.formatChunk(result)}\n**Relevance:** ${result.score}`);
+                            parts.push(`${this.formatChunk(result)}\n**Relevance:** ${result.score}${this.formatGraphContext(graphCtx?.get(result.filePath))}`);
                             if (nextChunk)
                                 parts.push(this.formatChunk(nextChunk, 'next chunk'));
                             return parts.join('\n\n');
@@ -296,7 +334,7 @@ class McpServer {
                         return { content: [{ type: 'text', text: header + blocks.join('\n\n---\n\n') }] };
                     }
                     const text = results
-                        .map(r => `${this.formatChunk(r)}\n**Relevance:** ${r.score}`)
+                        .map(r => `${this.formatChunk(r)}\n**Relevance:** ${r.score}${this.formatGraphContext(graphCtx?.get(r.filePath))}`)
                         .join('\n\n---\n\n');
                     return { content: [{ type: 'text', text: header + text }] };
                 }
@@ -305,6 +343,7 @@ class McpServer {
                     const startLine = Math.max(1, Number(req.params.arguments?.start_line) || 1);
                     const endLine = Number(req.params.arguments?.end_line) || startLine + 99;
                     const range = await this.searcher.readFileRange(filePath, startLine, endLine);
+                    this.logger.debug('McpServer: read_file_range', { file: filePath, startLine, endLine, ok: range.ok, ms: Date.now() - t0 });
                     if (!range.ok) {
                         const message = range.reason === 'invalid_path' ? `Invalid file path (outside workspace): ${filePath}` :
                             range.reason === 'not_indexed' ? `File is not indexed: ${filePath}. Run indexing first.` :
@@ -324,6 +363,7 @@ class McpServer {
                     const symbol = req.params.arguments?.symbol ? String(req.params.arguments.symbol) : null;
                     const transitive = Boolean(req.params.arguments?.transitive);
                     const rows = await this.searcher.getDependencies(filePath, project, symbol, transitive);
+                    this.logger.debug('McpServer: get_dependencies', { file: filePath, project, transitive, count: rows.length, ms: Date.now() - t0 });
                     if (rows.length === 0) {
                         return { content: [{ type: 'text', text: `No dependencies found for: ${filePath}` }] };
                     }
@@ -335,6 +375,7 @@ class McpServer {
                     const symbol = req.params.arguments?.symbol ? String(req.params.arguments.symbol) : null;
                     const transitive = Boolean(req.params.arguments?.transitive);
                     const rows = await this.searcher.getDependents(filePath, project, symbol, transitive);
+                    this.logger.debug('McpServer: get_dependents', { file: filePath, project, symbol, transitive, count: rows.length, ms: Date.now() - t0 });
                     if (rows.length > 0) {
                         return { content: [{ type: 'text', text: this.formatDependents(filePath, rows, transitive) }] };
                     }
@@ -365,6 +406,7 @@ class McpServer {
                     const validKinds = ['function', 'class', 'type', 'interface', 'variable', 'method', 'all'];
                     const kind = validKinds.includes(rawKind) ? rawKind : 'all';
                     const { hits, truncated } = await this.searcher.findSymbol(name, project, kind);
+                    this.logger.debug('McpServer: find_symbol', { name, kind, project, count: hits.length, ms: Date.now() - t0 });
                     if (hits.length === 0) {
                         return { content: [{ type: 'text', text: `No definitions found for symbol: ${name}` }] };
                     }
@@ -384,6 +426,7 @@ class McpServer {
                     const depth = isNaN(rawDepth) || rawDepth < 1 ? 2 : Math.min(5, rawDepth);
                     const pattern = req.params.arguments?.pattern ? String(req.params.arguments.pattern) : null;
                     const { tree, error } = this.searcher.listFiles(relPath, project, depth, pattern);
+                    this.logger.debug('McpServer: list_files', { path: relPath, project, depth, ms: Date.now() - t0 });
                     if (error) {
                         return { content: [{ type: 'text', text: `list_files error: ${error}` }] };
                     }
@@ -394,6 +437,7 @@ class McpServer {
                     const rawMax = Number(req.params.arguments?.max_lines);
                     const maxLines = isNaN(rawMax) || rawMax < 1 ? 300 : Math.min(1000, rawMax);
                     const result = await this.searcher.readFileAbsolute(filePath, maxLines);
+                    this.logger.debug('McpServer: read_file', { file: filePath, maxLines, ok: result.ok, ms: Date.now() - t0 });
                     if (!result.ok) {
                         const message = result.reason === 'invalid_path' ? `Invalid path (outside workspace): ${filePath}` :
                             `File not found on disk: ${filePath}`;
@@ -406,6 +450,23 @@ class McpServer {
                     }
                     return { content: [{ type: 'text', text }] };
                 }
+                if (req.params.name === 'get_callers') {
+                    const symbol = String(req.params.arguments?.symbol ?? '');
+                    const project = String(req.params.arguments?.project ?? '');
+                    const calleeFile = req.params.arguments?.callee_file ? String(req.params.arguments.callee_file) : null;
+                    const rows = await this.searcher.getCallers(symbol, project, calleeFile);
+                    this.logger.debug('McpServer: get_callers', { symbol, project, count: rows.length, ms: Date.now() - t0 });
+                    if (rows.length === 0) {
+                        return { content: [{ type: 'text', text: `No call sites found for \`${symbol}\` in project \`${project}\`. Run \`rag-index backfill --calls\` if the call graph has not been populated yet.` }] };
+                    }
+                    const lines = [`**Call sites of \`${symbol}\`** (${rows.length} found)\n`];
+                    for (const r of rows) {
+                        const loc = r.line != null ? ` line ${r.line}` : '';
+                        const ctx = r.fromSymbol ? `, in \`${r.fromSymbol}\`` : '';
+                        lines.push(`  → \`${r.fromFile}\`${loc}${ctx}`);
+                    }
+                    return { content: [{ type: 'text', text: lines.join('\n') }] };
+                }
                 throw new Error(`Unknown tool: ${req.params.name}`);
             }
             catch (err) {
@@ -414,6 +475,15 @@ class McpServer {
             }
         });
         await server.connect(new stdio_js_1.StdioServerTransport());
+        this.logger.info('McpServer: started', { version: PKG_VERSION });
+    }
+    formatGraphContext(ctx) {
+        const parts = [];
+        if (ctx?.imports.length)
+            parts.push(`**Imports:** ${ctx.imports.join(' · ')}`);
+        if (ctx?.usedBy.length)
+            parts.push(`**Used by:** ${ctx.usedBy.join(' · ')}`);
+        return parts.length > 0 ? '\n' + parts.join('\n') : '';
     }
     formatChunk(r, label) {
         return `${label ? `*(${label})*\n` : ''}**File:** ${r.filePath}\n**Project:** ${r.serviceName}\n**Line:** ${r.startLine}\n\`\`\`\n${r.content}\n\`\`\``;

package/dist/src/services/OllamaEmbedder.d.ts

@@ -3,7 +3,9 @@ import type { IEmbedder } from '../interfaces/IEmbedder';
 export declare class OllamaEmbedder implements IEmbedder {
     private config;
     private client;
+    rerank?: (query: string, documents: string[], topN: number) => Promise<number[]>;
     constructor(config: Config);
     embed(text: string): Promise<number[]>;
     translate(text: string, model: string): Promise<string>;
+    private _rerank;
 }

package/dist/src/services/OllamaEmbedder.js

@@ -5,9 +5,18 @@ const ollama_1 = require("ollama");
 class OllamaEmbedder {
     config;
     client;
+    rerank;
     constructor(config) {
         this.config = config;
         this.client = new ollama_1.Ollama({ host: config.ollama.host });
+        if (config.search.rerankerEnabled) {
+            if (config.ollama.rerankerModel) {
+                this.rerank = this._rerank.bind(this);
+            }
+            else {
+                console.warn('[OllamaEmbedder] RERANKER_ENABLED=true but RERANKER_MODEL is not set — reranking disabled');
+            }
+        }
     }
     async embed(text) {
         const { embedding } = await this.client.embeddings({
@@ -23,5 +32,25 @@ class OllamaEmbedder {
         });
         return response.message.content.trim();
     }
+    async _rerank(query, documents, topN) {
+        const res = await fetch(this.config.ollama.rerankerUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            signal: AbortSignal.timeout(30_000),
+            body: JSON.stringify({
+                model: this.config.ollama.rerankerModel,
+                query,
+                documents,
+                top_n: topN,
+                truncate: true,
+            }),
+        });
+        if (!res.ok) {
+            const body = (await res.text().catch(() => res.statusText)).slice(0, 200);
+            throw new Error(`Ollama rerank failed: ${res.status} ${body}`);
+        }
+        const data = await res.json();
+        return data.results.map(r => r.index);
+    }
 }
 exports.OllamaEmbedder = OllamaEmbedder;

package/dist/src/services/SearcherService.d.ts

@@ -17,6 +17,10 @@ export interface NeighborResult {
     prevChunk: ChunkRow | null;
     nextChunk: ChunkRow | null;
 }
+export interface GraphContext {
+    imports: string[];
+    usedBy: string[];
+}
 export type FileRangeResult = {
     ok: true;
     filePath: string;
@@ -46,6 +50,13 @@ export interface GrepMatch {
     line: number;
 }
 export type SymbolKind = 'function' | 'class' | 'type' | 'interface' | 'variable' | 'method' | 'all';
+export interface CallerRow {
+    fromFile: string;
+    fromSymbol: string | null;
+    calleeName: string;
+    calleeFile: string;
+    line: number | null;
+}
 export interface SymbolHit {
     filePath: string;
     line: number;
@@ -66,8 +77,10 @@ export declare class SearcherService {
     listProjects(): Promise<ProjectRow[]>;
     searchChunks(query: string, limit: number, project: string | null, threshold?: number): Promise<SearchResult[]>;
     fetchNeighbors(results: SearchResult[]): Promise<NeighborResult[]>;
+    fetchGraphContext(results: SearchResult[]): Promise<Map<string, GraphContext>>;
     getDependencies(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
     getDependents(filePath: string, project: string, symbol?: string | null, transitive?: boolean): Promise<DependencyRow[]>;
+    getCallers(symbol: string, project: string, calleeFile?: string | null): Promise<CallerRow[]>;
     grepSymbol(symbol: string, project: string, excludeFile: string): {
         matches: GrepMatch[];
         truncated: boolean;

package/dist/src/services/SearcherService.js

@@ -58,12 +58,13 @@ class SearcherService {
         this.logger = logger;
     }
     async prepareQuery(raw) {
+        const t0 = Date.now();
         if (this.config.search.autoTranslate && this.isNonEnglish(raw) && this.embedder.translate) {
             const query = await this.embedder.translate(raw, this.config.search.translateModel);
-            this.logger.debug('SearcherService: prepareQuery', { translated: true, raw: raw.slice(0, 120), query: query.slice(0, 120) });
+            this.logger.debug('SearcherService: prepareQuery', { translated: true, raw: raw.slice(0, 120), query: query.slice(0, 120), ms: Date.now() - t0 });
             return { query, translated: true };
         }
-        this.logger.debug('SearcherService: prepareQuery', { translated: false, query: raw.slice(0, 120) });
+        this.logger.debug('SearcherService: prepareQuery', { translated: false, query: raw.slice(0, 120), ms: Date.now() - t0 });
         return { query: raw, translated: false };
     }
     async listProjects() {
@@ -77,32 +78,51 @@ class SearcherService {
         });
     }
     async searchChunks(query, limit, project, threshold) {
+        const t0 = Date.now();
         const effectiveThreshold = threshold ?? this.config.search.similarityThreshold;
+        const fetchLimit = this.embedder.rerank
+            ? Math.min(limit * this.config.search.rerankerOverfetch, 200)
+            : limit;
         this.logger.debug('SearcherService: searchChunks', {
-            query: query.slice(0, 120), limit, project, threshold: effectiveThreshold,
+            query: query.slice(0, 120), limit, fetchLimit, project, threshold: effectiveThreshold,
         });
         const embedding = await this.embedder.embed(query);
-        const params = [`[${embedding}]`, effectiveThreshold, limit];
+        const params = [`[${embedding}]`, effectiveThreshold, fetchLimit];
         let projectFilter = '';
         if (project) {
             params.push(project);
             projectFilter = `AND "serviceName" = $${params.length}`;
         }
-        const results = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content,
+        const candidates = await this.db.query(`SELECT "serviceName", "filePath", "startLine", content,
               ROUND((embedding <=> $1)::numeric, 4)::float8 AS score
        FROM code_chunk
        WHERE embedding <=> $1 < $2
        ${projectFilter}
        ORDER BY embedding <=> $1
        LIMIT $3`, params);
-        this.logger.debug('SearcherService: searchChunks results', {
-            count: results.length,
-            scores: results.map(r => r.score),
-            files: results.map(r => r.filePath),
+        this.logger.debug('SearcherService: searchChunks candidates', {
+            count: candidates.length,
+            scores: candidates.map(r => r.score),
+            files: candidates.map(r => r.filePath),
+            ms: Date.now() - t0,
         });
-        return results;
+        if (!this.embedder.rerank || candidates.length === 0)
+            return candidates;
+        try {
+            const indices = await this.embedder.rerank(query, candidates.map(r => r.content), limit);
+            this.logger.debug('SearcherService: searchChunks rerank done', { indices, ms: Date.now() - t0 });
+            return indices.filter(i => i >= 0 && i < candidates.length).map(i => candidates[i]);
+        }
+        catch (err) {
+            this.logger.warn('SearcherService: rerank failed, falling back to vector order', {
+                reason: err.message,
+                ms: Date.now() - t0,
+            });
+            return candidates.slice(0, limit);
+        }
     }
     async fetchNeighbors(results) {
+        const t0 = Date.now();
         if (results.length === 0)
             return [];
         this.logger.debug('SearcherService: fetchNeighbors', { count: results.length });
@@ -128,13 +148,64 @@ class SearcherService {
             prevChunk: row.prev_fp ? { serviceName: row.prev_sn, filePath: row.prev_fp, startLine: row.prev_sl, content: row.prev_c } : null,
             nextChunk: row.next_fp ? { serviceName: row.next_sn, filePath: row.next_fp, startLine: row.next_sl, content: row.next_c } : null,
         }));
-        this.logger.debug('SearcherService: fetchNeighbors results', {
+        this.logger.debug('SearcherService: fetchNeighbors result', {
             withPrev: neighbors.filter(n => n.prevChunk).length,
             withNext: neighbors.filter(n => n.nextChunk).length,
+            ms: Date.now() - t0,
         });
         return neighbors;
     }
+    async fetchGraphContext(results) {
+        const t0 = Date.now();
+        const seen = new Map();
+        for (const r of results) {
+            const key = `${r.serviceName}::${r.filePath}`;
+            if (!seen.has(key))
+                seen.set(key, { filePath: r.filePath, project: r.serviceName });
+        }
+        const pairs = [...seen.values()];
+        this.logger.debug('SearcherService: fetchGraphContext', { files: pairs.length });
+        if (pairs.length === 0)
+            return new Map();
+        const n = pairs.length;
+        const firstHalf = pairs.map((_, i) => `($${i * 2 + 1}::text, $${i * 2 + 2}::text)`).join(', ');
+        const secondHalf = pairs.map((_, i) => `($${n * 2 + i * 2 + 1}::text, $${n * 2 + i * 2 + 2}::text)`).join(', ');
+        const params = [
+            ...pairs.flatMap(p => [p.filePath, p.project]),
+            ...pairs.flatMap(p => [p.filePath, p.project]),
+        ];
+        const rows = await this.db.query(`SELECT r.fp AS "filePath", 'import' AS direction, d."toFile" AS related
+         FROM (VALUES ${firstHalf}) AS r(fp, proj)
+         JOIN code_dependency d ON d."fromFile" = r.fp AND d.project = r.proj
+
+         UNION ALL
+
+         SELECT r.fp AS "filePath", 'usedby' AS direction, d."fromFile" AS related
+         FROM (VALUES ${secondHalf}) AS r(fp, proj)
+         JOIN code_dependency d ON d."toFile" = r.fp AND d.project = r.proj
+
+         LIMIT 2000`, params);
+        const ctx = new Map();
+        for (const { filePath } of pairs)
+            ctx.set(filePath, { imports: new Set(), usedBy: new Set() });
+        for (const row of rows) {
+            const g = ctx.get(row.filePath);
+            if (row.direction === 'import')
+                g.imports.add(row.related);
+            else
+                g.usedBy.add(row.related);
+        }
+        this.logger.debug('SearcherService: fetchGraphContext result', { files: pairs.length, rows: rows.length, ms: Date.now() - t0 });
+        const result = new Map();
+        for (const [fp, g] of ctx)
+            result.set(fp, {
+                imports: [...g.imports].slice(0, 50),
+                usedBy: [...g.usedBy].slice(0, 50),
+            });
+        return result;
+    }
     async getDependencies(filePath, project, symbol = null, transitive = false) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: getDependencies', { filePath, project, symbol, transitive });
         const params = [filePath, project];
         let symbolFilter = '';
@@ -148,7 +219,7 @@ class SearcherService {
        ${symbolFilter}
        ORDER BY "toFile"`, params);
         if (!transitive) {
-            this.logger.debug('SearcherService: getDependencies result', { direct: direct.length });
+            this.logger.debug('SearcherService: getDependencies result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
         }
         const indirect = await this.db.query(`WITH RECURSIVE deps AS (
@@ -173,10 +244,11 @@ class SearcherService {
        WHERE depth > 1
        GROUP BY "toFile"
        ORDER BY MIN(depth), "toFile"`, [filePath, project]);
-        this.logger.debug('SearcherService: getDependencies result', { direct: direct.length, indirect: indirect.length });
+        this.logger.debug('SearcherService: getDependencies result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
         return [...direct, ...indirect];
     }
     async getDependents(filePath, project, symbol = null, transitive = false) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: getDependents', { filePath, project, symbol, transitive });
         const params = [filePath, project];
         let symbolFilter = '';
@@ -190,7 +262,7 @@ class SearcherService {
        ${symbolFilter}
        ORDER BY "fromFile"`, params);
         if (!transitive) {
-            this.logger.debug('SearcherService: getDependents result', { direct: direct.length });
+            this.logger.debug('SearcherService: getDependents result', { direct: direct.length, ms: Date.now() - t0 });
             return direct;
         }
         const indirect = await this.db.query(`WITH RECURSIVE rdeps AS (
@@ -215,10 +287,29 @@ class SearcherService {
        WHERE depth > 1
        GROUP BY "fromFile"
        ORDER BY MIN(depth), "fromFile"`, [filePath, project]);
-        this.logger.debug('SearcherService: getDependents result', { direct: direct.length, indirect: indirect.length });
+        this.logger.debug('SearcherService: getDependents result', { direct: direct.length, indirect: indirect.length, ms: Date.now() - t0 });
         return [...direct, ...indirect];
     }
+    async getCallers(symbol, project, calleeFile = null) {
+        const t0 = Date.now();
+        this.logger.debug('SearcherService: getCallers', { symbol, project, calleeFile });
+        const params = [symbol, project];
+        let fileFilter = '';
+        if (calleeFile) {
+            params.push(calleeFile);
+            fileFilter = `AND "calleeFile" = $${params.length}`;
+        }
+        const rows = await this.db.query(`SELECT "fromFile", "fromSymbol", "calleeName", "calleeFile", line
+       FROM code_call
+       WHERE "calleeName" = $1 AND project = $2
+       ${fileFilter}
+       ORDER BY "fromFile", line
+       LIMIT 200`, params);
+        this.logger.debug('SearcherService: getCallers result', { count: rows.length, ms: Date.now() - t0 });
+        return rows;
+    }
     grepSymbol(symbol, project, excludeFile) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: grepSymbol', { symbol, project, excludeFile });
         const projectDir = path.join(this.config.workspaceRoot, project);
         const result = (0, child_process_1.spawnSync)('grep', [
@@ -245,7 +336,7 @@ class SearcherService {
             return [{ filePath: path.relative(this.config.workspaceRoot, absFile), line: parseInt(lineNum, 10) }];
         });
         const truncated = all.length > GREP_MAX_RESULTS;
-        this.logger.debug('SearcherService: grepSymbol result', { matches: Math.min(all.length, GREP_MAX_RESULTS), truncated });
+        this.logger.debug('SearcherService: grepSymbol result', { matches: Math.min(all.length, GREP_MAX_RESULTS), truncated, ms: Date.now() - t0 });
         return { matches: all.slice(0, GREP_MAX_RESULTS), truncated };
     }
     // Sync wrapper: validates name (throws synchronously), then returns Promise.
@@ -258,6 +349,7 @@ class SearcherService {
         return this.findSymbolFromIndex(name, project, kind);
     }
     async findSymbolFromIndex(name, project, kind) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: findSymbol', { name, project, kind, source: 'index' });
         try {
             const params = [name];
@@ -285,15 +377,16 @@ class SearcherService {
                 kind: row.kind,
                 signature: row.signature ?? row.name,
             }));
-            this.logger.debug('SearcherService: findSymbol result', { source: 'index', hits: hits.length, truncated });
+            this.logger.debug('SearcherService: findSymbol result', { source: 'index', hits: hits.length, truncated, ms: Date.now() - t0 });
             return { hits, truncated };
         }
         catch {
-            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { name, project });
+            this.logger.warn('SearcherService: symbol index unavailable, falling back to grep', { name, project, ms: Date.now() - t0 });
             return this.grepFindSymbol(name, project, kind);
         }
     }
     grepFindSymbol(name, project, kind) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: findSymbol', { name, project, kind, source: 'grep' });
         const searchDir = project
             ? path.join(this.config.workspaceRoot, project)
@@ -335,10 +428,11 @@ class SearcherService {
                 signature: matchedLine.trim(),
             });
         }
-        this.logger.debug('SearcherService: findSymbol result', { source: 'grep', hits: hits.length, truncated: hits.length >= FIND_SYMBOL_LIMIT });
+        this.logger.debug('SearcherService: findSymbol result', { source: 'grep', hits: hits.length, truncated: hits.length >= FIND_SYMBOL_LIMIT, ms: Date.now() - t0 });
         return { hits, truncated: hits.length >= FIND_SYMBOL_LIMIT };
     }
     listFiles(relativePath, project, depth, pattern) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: listFiles', { relativePath, project, depth, pattern });
         const projectRoot = path.join(this.config.workspaceRoot, project);
         const resolvedTarget = path.resolve(projectRoot, relativePath);
@@ -355,13 +449,14 @@ class SearcherService {
         const clampedDepth = Math.min(5, Math.max(1, depth));
         const lines = [];
         this.walkDir(resolvedTarget, 0, clampedDepth - 1, pattern, lines);
-        this.logger.debug('SearcherService: listFiles result', { entries: lines.length });
+        this.logger.debug('SearcherService: listFiles result', { entries: lines.length, ms: Date.now() - t0 });
         if (lines.length === 0) {
             return { tree: pattern ? `No files matching "${pattern}" found.` : '(empty directory)' };
         }
         return { tree: lines.join('\n') };
     }
     async readFileAbsolute(absPath, maxLines) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: readFileAbsolute', { absPath, maxLines });
         const resolvedRoot = path.resolve(this.config.workspaceRoot);
         const resolved = path.resolve(absPath);
@@ -395,10 +490,11 @@ class SearcherService {
             throw err;
         }
         const relPath = path.relative(resolvedRoot, resolved);
-        this.logger.debug('SearcherService: readFileAbsolute result', { linesRead: lines.length, hasMore });
+        this.logger.debug('SearcherService: readFileAbsolute result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
         return { ok: true, filePath: relPath, startLine: 1, endLine: lines.length, lines, hasMore };
     }
     async readFileRange(filePath, startLine, endLine) {
+        const t0 = Date.now();
         this.logger.debug('SearcherService: readFileRange', { filePath, startLine, endLine });
         const resolvedRoot = path.resolve(this.config.workspaceRoot);
         const absPath = path.resolve(resolvedRoot, filePath);
@@ -429,7 +525,7 @@ class SearcherService {
                 break;
             }
         }
-        this.logger.debug('SearcherService: readFileRange result', { linesRead: lines.length, hasMore });
+        this.logger.debug('SearcherService: readFileRange result', { linesRead: lines.length, hasMore, ms: Date.now() - t0 });
         return { ok: true, filePath, startLine, endLine: Math.min(endLine, lastRead), lines, hasMore };
     }
     isNonEnglish(text) {