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

> Explore how code-graph-rag finds functions by name or intent using Cypher queries and UniXcoder embeddings. Learn about its powerful code retrieval pipelines.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: deep-dive
- Published: 2026-08-16

---

**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`](https://github.com/vitali87/code-graph-rag/blob/main/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

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py) | Converts query to 768-dimensional vector |
| 3 | `search_embeddings()` in [`codebase_rag/vector_store.py`](https://github.com/vitali87/code-graph-rag/blob/main/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

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/tools/semantic_search.py)**: Implements `semantic_code_search()` and `create_semantic_search_tool()`
- **[`codebase_rag/cypher_queries.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/cypher_queries.py)**: Houses `CYPHER_FIND_BY_QUALIFIED_NAME` and `CYPHER_GET_FUNCTION_SOURCE_LOCATION` query templates
- **[`codebase_rag/embedder.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/embedder.py)**: UniXcoder wrapper with `embed_code()` and `embed_code_batch()` functions
- **[`codebase_rag/vector_store.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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.