Vector Embeddings Engine
Relevant source files
The following files were used as context for generating this wiki page:
The Vector Embeddings Engine is an optional module within the code-review-graph project designed to enhance codebase exploration through semantic search. By converting code entities—specifically function signatures and class definitions—into high-dimensional numerical vectors, the engine enables developers and AI agents to find relevant code based on meaning and context rather than exact keyword matches. Sources: CLAUDE.md, code_review_graph/main.py:270-285
This engine supports multiple providers, ranging from local models for privacy-conscious environments to cloud-based LLM providers for high-performance inference. It integrates directly with the SQLite Graph Store to store and query these embeddings alongside structural code data. Sources: code_review_graph/embeddings.py:10-25, code_review_graph/tools/docs.py:25-45
Architecture and Components
The engine is structured around a central EmbeddingStore that manages the lifecycle of vector data. It abstracts the complexities of different embedding providers, ensuring a consistent interface for the rest of the application. Sources: code_review_graph/embeddings.py:220-250
Core Components
| Component | Description |
|---|---|
EmbeddingStore | The primary class managing the SQLite table for embeddings and provider interactions. |
EmbeddingProvider | An abstract interface implemented by local and cloud-based inference engines. |
embed_all_nodes | A utility function that iterates through the graph, generating signatures for nodes that lack up-to-date embeddings. |
semantic_search_nodes | The query entry point that performs cosine similarity searches against the vector store. |
Sources: code_review_graph/embeddings.py:17-45, code_review_graph/tools/docs.py:15-30
System Workflow
The following diagram illustrates the flow from code parsing to semantic search availability.
The engine transforms parsed nodes into vector representations stored in a dedicated database table. Sources: code_review_graph/embeddings.py:230-260, code_review_graph/tools/docs.py:50-70
Embedding Generation Process
Embedding generation is a multi-step process that prioritizes efficiency by only processing nodes that have changed or are missing vectors. The engine typically embeds function signatures (e.g., parse_file(path: str) -> Tree) rather than full bodies to conserve token usage. Sources: README.zh-CN.md (Context Summary), code_review_graph/embeddings.py:530-550
Signature Generation
The engine constructs a text signature for each node before sending it to the provider. This signature includes:
- The node kind (Function, Class, etc.)
- The entity name
- Parameters and return types (if available)
Sources: code_review_graph/embeddings.py:545-560
Provider Support
The engine supports the following providers via specific environment configurations:
| Provider | Requirement | Default Model |
|---|---|---|
| Local | pip install code-review-graph[embeddings] | all-MiniLM-L6-v2 |
| OpenAI | CRG_OPENAI_API_KEY | text-embedding-3-small |
GOOGLE_API_KEY | gemini-embedding-001 | |
| MiniMax | MINIMAX_API_KEY | Provider default |
Sources: code_review_graph/tools/docs.py:35-50, code_review_graph/embeddings.py:105-130
Semantic Search and Retrieval
Once embeddings are generated, the engine enables hybrid search capabilities. When a user or agent performs a search, the engine first attempts a vector-based similarity search; if embeddings are unavailable for the selected provider/model, it falls back to SQLite FTS5 keyword matching. Sources: code_review_graph/main.py:270-285, code_review_graph/tools/docs.py:55-65
Similarity Query Flow
The sequence below describes how a semantic search request is resolved.
The engine seamlessly switches between semantic similarity and keyword matching based on data availability. Sources: code_review_graph/embeddings.py:580-610, code_review_graph/main.py:280-290
Integration and Tooling
The Vector Embeddings Engine is exposed through two primary MCP tools:
embed_graph_tool: Computes or updates embeddings for all nodes in the repository. This is an asynchronous operation offloaded to a background thread to prevent blocking the MCP server. Sources: code_review_graph/main.py:295-325semantic_search_nodes_tool: The interface for executing queries. It accepts optional filters for nodekindand allows overriding themodelorprovider. Sources: code_review_graph/main.py:270-290
Visualization Support
The visualization module utilizes community IDs (often derived from or reinforced by embedding clusters) to colorize nodes in the D3.js interactive graph, providing a visual representation of semantic relationships. Sources: code_review_graph/visualization.py:105-125
Conclusion
The Vector Embeddings Engine transforms a structural code graph into a searchable semantic space. By supporting both local and cloud providers, it offers a flexible solution for intelligent codebase navigation, significantly reducing the token cost of context discovery for AI-driven development workflows. Sources: CLAUDE.md, code_review_graph/tools/docs.py:20-30