semantic_code_search

Find code by meaning using semantic search to locate relevant files based on concepts rather than exact keywords, enabling discovery of related functionality across your codebase.

Instructions

Search the codebase by MEANING, not just exact variable names. Uses Ollama embeddings over file headers and symbol names. Example: searching 'user authentication' finds files about login, sessions, JWT even if those exact words aren't used, with matched definition lines.

Input Schema

TableJSON Schema

Name	Required	Description
`query`	Yes	Natural language description of what you're looking for. Example: 'how are transactions signed'
`top_k`	No	Number of matches to return. Default: 5.
`semantic_weight`	No	Weight for embedding similarity in hybrid ranking. Default: 0.72.
`keyword_weight`	No	Weight for keyword overlap in hybrid ranking. Default: 0.28.
`min_semantic_score`	No	Minimum semantic score filter. Accepts 0-1 or 0-100.
`min_keyword_score`	No	Minimum keyword score filter. Accepts 0-1 or 0-100.
`min_combined_score`	No	Minimum final score filter. Accepts 0-1 or 0-100.
`require_keyword_match`	No	When true, only return files with keyword overlap.
`require_semantic_match`	No	When true, only return files with positive semantic similarity.

Implementation Reference

src/tools/semantic-search.ts:157-186 (handler)

The primary handler for the 'semantic_code_search' tool, which builds an index and performs a hybrid search.

export async function semanticCodeSearch(options: SemanticSearchOptions): Promise<string> {
  const index = await buildIndex(options.rootDir);
  const searchOptions: SearchQueryOptions = {
    topK: options.topK,
    semanticWeight: options.semanticWeight,
    keywordWeight: options.keywordWeight,
    minSemanticScore: options.minSemanticScore,
    minKeywordScore: options.minKeywordScore,
    minCombinedScore: options.minCombinedScore,
    requireKeywordMatch: options.requireKeywordMatch,
    requireSemanticMatch: options.requireSemanticMatch,
  };
  const results = await index.search(options.query, searchOptions);

  if (results.length === 0) return "No matching files found for the given query.";

  const lines: string[] = [`Top ${results.length} hybrid matches for: "${options.query}"\n`];

  for (let i = 0; i < results.length; i++) {
    const r = results[i];
    lines.push(`${i + 1}. ${r.path} (${r.score}% total)`);
    lines.push(`   Semantic: ${r.semanticScore}% | Keyword: ${r.keywordScore}%`);
    if (r.header) lines.push(`   Header: ${r.header}`);
    if (r.matchedSymbols.length > 0) lines.push(`   Matched symbols: ${r.matchedSymbols.join(", ")}`);
    if (r.matchedSymbolLocations.length > 0) lines.push(`   Definition lines: ${r.matchedSymbolLocations.join(", ")}`);
    lines.push("");
  }

  return lines.join("\n");
}

src/tools/semantic-search.ts:18-29 (schema)

Input options interface for the semantic_code_search tool.

export interface SemanticSearchOptions {
  rootDir: string;
  query: string;
  topK?: number;
  semanticWeight?: number;
  keywordWeight?: number;
  minSemanticScore?: number;
  minKeywordScore?: number;
  minCombinedScore?: number;
  requireKeywordMatch?: boolean;
  requireSemanticMatch?: boolean;
}

Context+