How code-graph-rag Finds Functions by Name or Intent: A Technical Deep Dive

The code-graph-rag retrieval tool locates functions using two distinct pipelines: exact qualified-name lookups via Cypher graph queries, or semantic intent-based searches powered by UniXcoder embeddings and vector similarity.

This open-source project (vitali87/code-graph-rag) combines a Memgraph graph database with a vector store to enable both precise symbol resolution and natural-language code discovery. The dual-mode architecture ensures developers can find code whether they know the exact function name or only have a description of what the code should do.

Exact Name Retrieval: Qualified Name Lookups

When you know the function's location in the codebase, code-graph-rag provides deterministic retrieval through qualified-name matching.

How It Works

1. The tool receives a fully qualified name such as my_pkg.utils.calculate
2. CodeRetriever.find_code_snippet() in codebase_rag/tools/code_retrieval.py constructs CYPHER_FIND_BY_QUALIFIED_NAME
3. The Cypher query matches the node where qualified_name equals the input string
4. CYPHER_GET_FUNCTION_SOURCE_LOCATION resolves the node ID to a file path and line range
5. The source slice is read from disk and returned

The qualified_name property on every function node enables direct equality matching without fuzzy logic.

Code Example: Retrieve by Qualified Name

from codebase_rag.tools.code_retrieval import CodeRetriever

# Initialize with project root and Memgraph ingestor

code_retriever = CodeRetriever(
    project_root="/my/project",
    ingestor=memgraph_ingestor
)

# Exact lookup by qualified name

snippet = await code_retriever.find_code_snippet("my_pkg.utils.calculate")
print(snippet.source)   # Source text of the calculate function

Intent-Based Retrieval: Semantic Search

For natural-language queries, the tool employs UniXcoder embeddings and vector similarity to find semantically related functions.

The Semantic Pipeline

Step	Component	Action
1	semantic_code_search()	Receives query like "read a CSV file and return a pandas DataFrame"
2	embed_code() in codebase_rag/embedder.py	Converts query to 768-dimensional vector
3	search_embeddings() in codebase_rag/vector_store.py	Returns top-k matching node IDs with similarity scores
4	get_function_source_code()	Runs CYPHER_GET_FUNCTION_SOURCE_LOCATION for each hit
5	Source reader	Reads file slices and formats results by relevance

Code Example: Retrieve by Intent

from codebase_rag.tools.semantic_search import create_semantic_search_tool

semantic_tool = create_semantic_search_tool(ingestor=memgraph_ingestor)

# Natural language query

results = await semantic_tool.run({
    "query": "extract zip archives safely",
    "top_k": 5,
    "project": None  # Search across all indexed projects

})

for r in results:
    print(r["code"])  # Function snippets ordered by semantic relevance

Key Implementation Files

Understanding these source files clarifies how the retrieval system operates:

• codebase_rag/tools/code_retrieval.py: Contains CodeRetriever class and create_code_retrieval_tool() factory; handles qualified-name resolution
• codebase_rag/tools/semantic_search.py: Implements semantic_code_search() and create_semantic_search_tool()
• codebase_rag/cypher_queries.py: Houses CYPHER_FIND_BY_QUALIFIED_NAME and CYPHER_GET_FUNCTION_SOURCE_LOCATION query templates
• codebase_rag/embedder.py: UniXcoder wrapper with embed_code() and embed_code_batch() functions
• codebase_rag/vector_store.py: Embedding persistence and search_embeddings() similarity lookup

Why Both Approaches Exist

The unified architecture serves different developer needs:

• Exact name retrieval guarantees correctness when you know the symbol; no embedding drift or similarity thresholds to configure
• Intent-based retrieval bridges the vocabulary gap when you know what you need but not where it's named

Both paths converge on CYPHER_GET_FUNCTION_SOURCE_LOCATION, ensuring consistent source extraction regardless of discovery method. This design eliminates duplication while supporting complementary search strategies.

Summary

• CodeRetriever.find_code_snippet() performs exact qualified-name lookups via CYPHER_FIND_BY_QUALIFIED_NAME
• semantic_code_search() converts natural language to 768-dim UniXcoder embeddings for vector similarity search
• Both modes resolve to file path and line range through CYPHER_GET_FUNCTION_SOURCE_LOCATION
• The Memgraph graph database stores function nodes with qualified_name properties for precise matching
• The vector store enables embedding-based discovery when exact names are unknown

Frequently Asked Questions

What embedding model does code-graph-rag use for semantic search?

The project uses UniXcoder, a pre-trained model for code understanding and generation. embed_code() in codebase_rag/embedder.py generates 768-dimensional vectors that capture code semantics, enabling similarity matching between natural language queries and function implementations.

Can I search across multiple projects simultaneously?

Yes. Setting project=None in the semantic search tool (as shown in the intent example) searches across all indexed projects in the vector store. For qualified-name lookups, the project_root parameter in CodeRetriever scopes the search to a specific codebase.

How does the system handle name collisions?

The qualified_name property includes the full module path (e.g., my_pkg.utils.calculate), not just the function name. This namespace qualification prevents collisions. If the same name exists in different modules, the complete qualified name distinguishes them unambiguously.

Is the semantic search limited to function definitions?

The current implementation indexes function and method nodes stored in Memgraph. The vector store maintains embeddings for these nodes, so similarity search returns function-level results. The CYPHER_GET_FUNCTION_SOURCE_LOCATION query specifically targets function source locations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}