2015xli/clangd-graph-rag

This project builds a Neo4j graph RAG (Retrieval-Augmented Generation) for a C/C++ software project based on clang/clangd, which can be queried for deep software project analysis. It works well with large and complex codebases like the Linux, llvm, llama.cpp, etc.
The project includes an example MCP server and an AI expert agent. You can also develop your own MCP servers and agents around the graph RAG for your specific purposes, such as:
Software Analysis
Analyze project organization (folders, files, modules)
Analyze code patterns and structures
Understand call chains and class relationships
Examine architectural design and workflows
Trace dependencies and interactions
Expert Assistance
Code Refactoring Advice: Provide guidance on design improvements and optimizations
Bug Analysis: Help identify root causes of bugs or race conditions
Documentation: Assist with software design documentation
Feature Implementation: Guide on implementing features based on requirements
Architecture Review: Analyze and suggest improvements to system architecture
### Current Schema
Here is a simplified version of the current neo4j schema for AI agent to use.
### A benchmark: The Linux Kernel
When building a code graph for the Linux kernel (WSL2 release) on a workstation (12 cores, 64GB RAM), it takes about ~4 hours using 10 parallel worker processes, with peak memory usage at ~32GB. Note this process does not include the LLM summary generation, so the total time (and cost) may vary based on your LLM provider. Local LLM API with Ollama is supported.
## Table of Contents
Why This Project?
Why Clang instead of Tree-sitter?
Key Features & Design Principles
Prerequisites
Primary Usage
Full Graph Build
Incremental Graph Update
Common Options
Interacting with the Graph: MCP and Agent
Supporting Scripts
Rebuild or Clean Up Graph
Documentation & Contributing
## Why This Project?
For C/C++ project, Clangd language server has been very useful for developers using an IDE. The symbols in the code are represented in an intermediate data format from Clangd-indexer containing detailed syntactical information used by language servers for code navigation and completion. However, while powerful for IDEs, the raw index data doesn't expose the full graph structure of a codebase (e.g., the call graph, header dependence graph, macro expansion graph, etc.) or integrate the semantic understanding that Large Language Models (LLMs) can leverage.
This project fills that gap. It reconciles the Clangd index data and Clang parsing data, and ingests them into a Neo4j graph database, reconstructing the complete file, symbol, and relationship hierarchy. It then enriches this structure with AI-generated summaries and vector embeddings, transforming the raw compiler index into a semantically rich knowledge graph. In essence, clangd-graph-rag extends Clangd's powerful foundation into an AI-ready code graph, enabling LLMs to reason about a codebase's structure and behavior for advanced tasks like in-depth code analysis, refactoring, and automated reviewing.
Another powerful feature is that this project supports building the graphRAG incrementally, which means it can update the graph based on the diff of git commits without rebuilding the entire graph from scratch. This significantly reduces the time and cost of maintaining the graphRAG.