RANGER -- Repository-Level Agent for Graph-Enhanced Retrieval

TL;DR

RANGER introduces a repository-level retrieval agent that builds a persistent, semantically enriched knowledge graph from ASTs to support both code-entity and natural language queries. It couples Cypher-based fast lookups for code-entity queries with an MCTS-guided graph exploration that leverages a bi-encoder for expansion and a cross-encoder for scoring, balancing accuracy with efficiency. Evaluations across CodeSearchNet, RepoQA, RepoBench, and CrossCodeEval demonstrate that RANGER outperforms strong embedding baselines and several RAG approaches for repository-level retrieval and code completion. The work highlights practical gains in cross-file dependency reasoning while acknowledging limitations related to static graphs and retrieval latency, and proposes future work on incremental updates, learned reward models, and broader language support.

Abstract

General-purpose automated software engineering (ASE) includes tasks such as code completion, retrieval, repair, QA, and summarization. These tasks require a code retrieval system that can handle specific queries about code entities, or code entity queries (for example, locating a specific class or retrieving the dependencies of a function), as well as general queries without explicit code entities, or natural language queries (for example, describing a task and retrieving the corresponding code). We present RANGER, a repository-level code retrieval agent designed to address both query types, filling a gap in recent works that have focused primarily on code-entity queries. We first present a tool that constructs a comprehensive knowledge graph of the entire repository, capturing hierarchical and cross-file dependencies down to the variable level, and augments graph nodes with textual descriptions and embeddings to bridge the gap between code and natural language. RANGER then operates on this graph through a dual-stage retrieval pipeline. Entity-based queries are answered through fast Cypher lookups, while natural language queries are handled by MCTS-guided graph exploration. We evaluate RANGER across four diverse benchmarks that represent core ASE tasks including code search, question answering, cross-file dependency retrieval, and repository-level code completion. On CodeSearchNet and RepoQA it outperforms retrieval baselines that use embeddings from strong models such as Qwen3-8B. On RepoBench, it achieves superior cross-file dependency retrieval over baselines, and on CrossCodeEval, pairing RANGER with BM25 delivers the highest exact match rate in code completion compared to other RAG methods.

Figures (4)

• Figure 1: RANGER system architecture illustrated through a simple two-file repository example containing base.py and extended.py. The offline stage constructs a comprehensive knowledge graph from code repositories through AST parsing, LLM-assisted semantic description generation, and embedding computation. In the online stage RANGER first translates user queries into Cypher queries using an LLM. For code-entity queries, this Cypher query is sufficient and provides fast retrieval (Path 1). If retrieval results from the graph database return None, often in case of natural language queries, the system invokes MCTS-based graph exploration (Path 2) to generate the final response.
• Figure 2: The Monte Carlo Tree Search–based graph traversal algorithm. The diagram depicts iterations 2 and 3 of a Monte Carlo Tree Search–based graph traversal on the simple two-file code repository knowledge graph from Figure \ref{['fig:overall']} in response to the query “Where is the code for addition?” Iteration 2 expands the base module (adding precision and Calculator), simulates their rewards, and back-propagates values to update selection scores. Iteration 3 then adds the method node add and function node quick_add, both of which yield high rewards and are ultimately selected during the extraction and ranking phase as the answer to the user’s query.
• Figure 3: Performance metrics across MCTS iterations for natural language query datasets. Left shows CodeSearchNet NDCG@10, Recall@10, and the average MCTS runtime per iteration across repositories and queries. Right shows RepoQA NDCG@10, Recall@10, and corresponding average runtimes. Both datasets show monotonic improvement followed by convergence, indicating practical iteration ranges for deployment.
• Figure 4: The two-stage graph construction process