# What Is Semantic Search in code-review-graph and How Does It Work?

> Discover semantic search in code-review-graph. Learn how this MCP tool combines keyword matching and vector embeddings to find relevant code functions and classes efficiently.

- Repository: [Tirth Kanani/code-review-graph](https://github.com/tirth8205/code-review-graph)
- Tags: how-to-guide
- Published: 2026-08-13

---

**Semantic search in code-review-graph is an MCP tool that locates relevant functions and classes by combining full-text keyword matching with vector embedding similarity to rank code nodes by relevance.**

The `semantic_search_nodes` tool is a core component of the [tirth8205/code-review-graph](https://github.com/tirth8205/code-review-graph) repository, designed to bridge the gap between natural language queries and code navigation. Unlike traditional regex-based search, this semantic search implementation leverages both lexical and contextual understanding to identify relevant code entities. It enables developers and automated agents to discover functions, classes, and other graph nodes using intuitive descriptions rather than exact identifier matches.

## What Is Semantic Search in code-review-graph?

Semantic search refers to the `semantic_search_nodes` MCP tool that indexes and queries code entities using dual search modalities. The system treats your codebase as a searchable knowledge graph where each node represents a function, class, or module with associated metadata and embeddings.

The tool generates structured results containing node identifiers, file paths, line numbers, and a **provenance** field that indicates whether each match originated from keyword matching, vector similarity, or both signals.

## How Semantic Search Works: The Two-Strategy Engine

The implementation combines complementary search strategies to maximize recall and precision.

### Full-Text Search (FTS)

The **Full-Text Search** strategy scans indexed source code and documentation for literal keyword matches. This component acts as a fast filter that retrieves nodes containing the query terms in their source text, docstrings, or comments. FTS provides high confidence for exact terminology but may miss conceptually related code using different vocabulary.

### Vector Similarity Search

The **Embedding (vector) similarity** strategy encodes both the natural language query and pre-computed node embeddings into dense vectors. Using the embedding model defined in [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py) (approximately line 1403 in the `semantic_search` function), the system calculates cosine similarity between the query vector and each node's stored vector. This captures semantic relationships beyond exact keyword matches, identifying functions that implement related concepts even when naming conventions differ.

### Result Merging and Ranking

The engine constructs a **candidate set** from both FTS hits and embedding similarity scores, then merges and deduplicates the results. Each node receives a combined relevance score weighted to favor matches appearing in both search modes. The final ranked list includes provenance metadata indicating which strategies contributed to each result, allowing downstream agents to calibrate confidence levels appropriately.

## Implementation Details and Source Code References

The semantic search architecture spans several key files in the repository:

- In [`code_review_graph/tools/query.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/query.py) (approximately line 699), the `semantic_search_nodes` function implements the core orchestration logic, coordinating between text search and vector comparison.
- The vector similarity computation resides in [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py) (around line 1403) within the `semantic_search` function, which handles embedding generation and similarity scoring.
- The CLI wrapper exposing this functionality lives in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) (lines 322-374), registering the tool as `semantic_search_nodes_tool`.
- Tool registration for the MCP framework occurs in [`code_review_graph/tools/__init__.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/__init__.py), making the function discoverable by the server.
- User-facing documentation and usage guidance appear in [`code_review_graph/skills.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/skills.py) (around line 1165).

## How to Use Semantic Search in code-review-graph

You can invoke semantic search through three primary interfaces depending on your integration needs.

### Command-Line Interface

Start the MCP server with the query tool enabled to access semantic search via CLI:

```bash

# Serve with the semantic search tool available

crg serve --tools query_graph_tool,semantic_search_nodes_tool

# Execute a search query

> semantic_search_nodes(query="user authentication")

```

This interface is defined in [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) within the `semantic_search_nodes_tool` wrapper implementation.

### Programmatic Python API

Import and call the function directly for custom scripts or agent implementations:

```python
from code_review_graph.tools.query import semantic_search_nodes

# Execute semantic search with a natural language query

result = semantic_search_nodes("database connection pooling")
top_matches = result["nodes"][:5]  # Access top 5 results

sources = result["provenance"]     # Review match sources (FTS, embedding, or both)

```

This direct API is tested in [`tests/test_tools.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_tools.py) (lines 156-171) and provides full access to the provenance metadata without server overhead.

### Tool Chaining

Combine semantic search with other graph analysis tools for complex workflows:

```python
from code_review_graph.tools.query import semantic_search_nodes, query_graph

# First identify relevant function via semantic search

search_result = semantic_search_nodes("error handling middleware")
target = search_result["nodes"][0]

# Then retrieve its call relationships

call_graph = query_graph(node=target["id"])

```

This chaining pattern appears in integration tests at [`tests/test_main.py`](https://github.com/tirth8205/code-review-graph/blob/main/tests/test_main.py) (lines 428-462), demonstrating how to bridge discovery and analysis operations.

## Summary

- **Semantic search in code-review-graph** combines Full-Text Search and vector embedding similarity to locate code entities using natural language.
- The `semantic_search_nodes` tool returns structured results with **provenance metadata** indicating whether matches came from keyword matching, semantic similarity, or both.
- Implementation spans [`code_review_graph/tools/query.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/tools/query.py) (orchestration), [`code_review_graph/embeddings.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/embeddings.py) (vector operations), and [`code_review_graph/main.py`](https://github.com/tirth8205/code-review-graph/blob/main/code_review_graph/main.py) (CLI exposure).
- Available via **CLI**, **direct Python API**, or **MCP tool chaining** for flexible integration into review workflows.
- The dual-strategy approach balances exact keyword recall with conceptual semantic understanding.

## Frequently Asked Questions

### What is the difference between FTS and embedding search in code-review-graph?

Full-Text Search (FTS) looks for literal keyword matches in source code and documentation, providing exact lexical matches. Embedding search converts queries and code into dense vectors to measure conceptual similarity, capturing related functionality even with different terminology. The provenance field in results indicates which method contributed to each match.

### How does semantic search handle result ranking when both strategies find the same node?

When a node appears in both FTS and embedding results, the system assigns a higher combined relevance score, prioritizing these dual-signal matches in the final ranking. This weighting reflects increased confidence that the node is genuinely relevant to the query intent.

### Can I use semantic search without running the MCP server?

Yes. While the CLI requires the server (`crg serve`), you can import `semantic_search_nodes` directly from `code_review_graph.tools.query` and execute searches programmatically without starting the server infrastructure, as demonstrated in the test suite.

### What information does the provenance field provide?

The provenance field records whether each result originated from Full-Text Search, embedding similarity, or both sources. This metadata allows calling agents to filter results—accepting only embedding-confirmed matches or requiring both signals for high-stakes code review decisions.