code-graph-rag 자연어 쿼리 그래프 RAG

코드베이스가 커질수록 "이 함수는 어디서 호출되나", "이 클래스가 어떤 인터페이스를 상속하나" 같은 질문에 답하는 시간이 늘어납니다. grep과 find로는 한계가 있고, LLM에 전체 파일을 밀어넣으면 토큰 비용이 눈덩이처럼 불어납니다. 이 문제를 "코드를 지식 그래프로 만들고 거기에 LLM을 붙이는" 방식으로 해결하려는 도구가 몇 가지 등장했습니다.

이 글에서는 그중 하나인 Code-Graph-RAG (vitali87/code-graph-rag, ★2,974)의 설치와 사용법을 소개하고, 같은 카테고리에서 가장 인기 있는 codegraph (colbymchenry/codegraph, ★65,581)와의 차이를 자세히 비교합니다.

핵심 요약

• Code-Graph-RAG는 Tree-sitter로 코드베이스를 AST 파싱 → Memgraph 지식 그래프 → 자연어 질문을 Cypher 쿼리로 변환해 코드를 검색·수정하는 도구입니다.
• 설치 의존성: Python + Docker(Memgraph+Qdrant) + cmake + ripgrep. uv tool install "code-graph-rag[treesitter-full,semantic]"로 설치합니다.
• 13개 언어를 완전 지원하며, MCP 서버로 Claude Code에 연결할 수 있습니다. 하루 2개 릴리즈(v0.0.584/586, 2026-08-09)로 활발히 개발 중입니다.
• 더 인기 있는 codegraph는 C+SQLite+FTS5 기반으로 설치가 간단(curl 원라이너)하고 벤치마크에서 44% 비용 절감을 실측했습니다.
• 핵심 차이: Code-Graph-RAG는 "쿼리형 그래프 RAG"(자연어→Cypher, 수동 동기화), codegraph는 "상주형 코드 인텔리전스"(자동 동기화, 에이전트 직접 통합)입니다.

왜 지금 주목받나 — 1년 전 생성, 최근 폭발

Code-Graph-RAG는 2025년 6월에 생성됐습니다. 하지만 별 2,974개 대부분이 최근 몇 달간 붙었습니다. 그 배경에는 세 가지 변화가 있습니다.

① 개발 속도가 2026년 7월부터 급증했습니다. GitHub 릴리즈 기준으로 2026년 6월까지 월 1건 수준이던 릴리즈가, 7월에 6건, 8월(9일 기준)에 이미 3건으로 늘었습니다. 프로젝트 규모가 커지거나 개발자가 풀타임으로 전환한 것으로 보입니다.

② GraphRAG가 2026년에 주류 기술로 올라왔습니다. 2025년 11월, 데이터 사이언스 인플루언서 Avi Chawla(21K+ X 팔로워)가 "RAG vs Graph RAG" 비교에서 이 프로젝트를 언급하며 "코드에 RAG를 적용한 실용적 사례"로 소개했습니다. 이후 "I Was Wrong About GraphRAG: Here's What Won in 2026" 같은 영상이 나올 만큼 GraphRAG가 주목받았고, 자연스럽게 코드 그래프 도구로 관심이 이동했습니다.

③ AI 코딩 에이전트의 MCP 표준화가 시장을 열었습니다. Claude Code, Codex CLI, Cursor 등이 MCP(Model Context Protocol)를 통해 도구 연결을 표준화하면서, 코드베이스 지식 그래프를 MCP 서버로 제공하는 접근이 현실적인 선택지가 됐습니다. Code-Graph-RAG도 MCP 서버(cgr mcp-server)를 제공하며 이 흐름에 탑승했습니다.

요약하면: GraphRAG 붐 + MCP 표준화 + 개발 가속화가 1년 된 프로젝트를 갑자기 인기 레포로 만든 배경입니다.

Code-Graph-RAG란 무엇인가

GitHub 저장소 기준 한 줄 정의는 "The ultimate RAG for your monorepo"입니다. Python으로 작성된 MIT 라이선스 오픈소스입니다. 실측 기준(2026-08-09) 별 2,968개, 포크 519개, 오픈 이슈 25개입니다. 2025년 6월에 생성되어 1년여 동안 꾸준히 개발됐습니다.

작동 방식은 두 단계입니다:

1. Tree-sitter 기반 파서가 코드베이스의 함수·클래스·메서드·모듈과 그 관계를 추출해 Memgraph에 지식 그래프로 저장합니다.
2. RAG 시스템(codebase_rag/)이 자연어 질문을 Cypher 쿼리로 변환해 그래프에서 결과를 가져오고, AI 모델로 편집·최적화합니다.

Source Code → Tree-sitter Parser → AST 분석 → Memgraph 지식 그래프
                                                    ↑
User Query → AI (Cypher 생성) → Cypher 쿼리 → 그래프 결과 → 응답

지원 언어는 Python, TypeScript/TSX, JavaScript, Rust, Go, Java, C, C++, C#, PHP, Lua, Dart (이상 완전 지원), Scala(개발 중), Ruby(구조적 지원, ast-grep 플러그인). 14개 가까운 언어를 하나의 언어 독립적 그래프 스키마로 통합합니다.

최근 주요 업데이트:

• ast-grep 구조 검색/치환: AST 패턴으로 코드베이스 전체에서 구조를 찾고 변환
• FLOWS_TO 데이터 플로우 추적: C#, Java, C, Go에서 값이 할당→호출→I/O싱크까지 이동하는 taint edge 추적

설치 및 실행

1) 시스템 요구사항 Docker(내장 Memgraph + Qdrant), cmake, ripgrep이 필요합니다.

# uv로 설치 (권장)
uv tool install "code-graph-rag[treesitter-full,semantic]"

# 또는 pipx
pipx install "code-graph-rag[treesitter-full,semantic]"

2) 그래프 DB 실행

cgr daemon up          # Memgraph + Qdrant 스택 시작

3) 코드베이스 파싱

cgr start --repo-path /path/to/repo --update-graph   # 첫 파싱
cgr start --repo-path /path/to/repo                   # 이후 쿼리만

4) 리포지토리 변경 --update-graph는 해당 리포지토리만 갱신하며, 다른 리포지토리를 건드리지 않습니다. 모든 데이터를 초기화하려면 --clean을 추가합니다(공유 그래프의 모든 프로젝트가 삭제되며, 확인 프롬프트가 뜹니다).

5) MCP 연결 (Claude Code 등)

cgr mcp-server

MCP 서버로 실행하면 Claude Code가 직접 코드베이스를 쿼리·편집할 수 있습니다.

엔터프라이즈 옵션

Code-Graph-RAG는 오픈소스이지만, 추가로 유료 엔터프라이즈 서비스를 제공합니다: 클라우드 호스팅(관리형 인프라)과 온프레미스/에어갭 배포(규제 산업 대상). code-graph-rag.com/enterprise에서 가격 확인.

codegraph(colbymchenry, ★65,581)와의 비교

비교표

차이점 1: 설계 철학 — "쿼리형" vs "상주형"

가장 근본적인 차이는 도구의 사용 방식입니다.

Code-Graph-RAG는 "쿼리형"입니다. 사용자가 자연어로 질문하면 시스템이 그걸 Cypher로 변환해 그래프를 조회합니다. 즉, 질문이 있을 때만 그래프가 개입합니다. 이 방식은 분석적 질문(데드 코드 탐색, 데이터 플로우 추적)에 강하고, Cypher를 직접 다룰 수 있는 사용자에게는 매우 유연합니다.

codegraph는 "상주형"입니다. MCP 서버가 에이전트(Claude Code 등)에 항상 연결되어 있고, codegraph_explore 하나로 소스+호출 흐름+영향 범위를 한 번에 반환합니다. 에이전트가 파일을 읽기 전에 그래프가 답을 주는 구조라, 에이전트의 탐색 비용을 없애는 데 특화돼 있습니다.

차이점 2: 설치와 운영 부담

codegraph는 "설치하면 끝"에 가깝습니다. C로 작성된 자체 런타임을 번들로 배포해서 Python 환경·Docker·빌드 도구가 필요 없습니다. Code-Graph-RAG는 Docker로 Memgraph+Qdrant를 띄워야 하므로 인프라 운영 부담이 큽니다. CI 환경이나 에어갭 환경에서는 codegraph가 훨씬 간단합니다.

차이점 3: 성능 벤치마크 존재 여부

codegraph는 공개 벤치마크가 있습니다. Claude Opus 4.8로 7개 레포를 측정(2026-08-05 재측정)한 결과:

• 도구 호출 88% 감소
• 토큰 62% 감소
• 비용 44% 절감
• 파일 읽기 0건 (모든 레포)

그래프가 있을 때 에이전트는 한 번의 codegraph_explore로 답하고 끝내지만, 그래프가 없으면 find/grep/read 탐색에 예산을 태웁니다. 그래프 유무만으로 88% 더 적은 도구 호출이 나온다는 실측입니다.

Code-Graph-RAG는 공개 벤치마크 수치가 없습니다. 기능(ast-grep 구조 검색, FLOWS_TO)은 명확하지만, "코드 그래프 RAG로 토큰을 X% 줄였다"는 수치는 공식 문서에서 찾을 수 없습니다. 성능을 검증하려면 직접 측정해야 합니다.

차이점 4: 데이터 플로우 추적 vs 토큰 최적화

Code-Graph-RAG의 차별점은 FLOWS_TO taint edge입니다. 값이 할당 → 함수 호출 → I/O 싱크까지 흐르는 경로를 그래프에 저장해서, 보안 분석(입력이 어디까지 전파되는지)이나 영향 범위 추적에 쓸 수 있습니다. 이건 codegraph에 없는 기능입니다.

codegraph의 차별점은 토큰 절감의 정밀함입니다. 응답 하나가 "질문에 딱 맞는 소스+호출 흐름"을 한 번에 반환해, 에이전트가 여러 번 파일을 읽는 대신 한 번에 답을 얻습니다.

주의사항

• Memgraph는 Docker가 필요합니다. Code-Graph-RAG는 내장 Memgraph+Qdrant 스택을 Docker로 실행하므로, Docker가 없는 환경에서는 바로 사용할 수 없습니다.
• codegraph의 컨텍스트 윈도우 이슈: 비용은 44% 저렴하지만, 응답에 약 80% 더 많은 잔여 컨텍스트를 세션 끝에 남깁니다(VS Code: 67K vs 18K 토큰). 롱 세션에서 윈도우가 좁으면 예산을 고려해야 합니다.
• codegraph는 "탐색" 최적화: 데이터 플로우 추적이나 구조 검색 같은 분석적 작업은 codegraph가 아니라 그래프 쿼리형 도구가 더 적합할 수 있습니다.

언제 어느 도구를 선택할까

Code-Graph-RAG를 선택할 때:

• Cypher 쿼리를 직접 다룰 수 있고 분석적 질문(데드 코드, 데이터 플로우)이 많을 때
• Memgraph 기반 인프라가 이미 있고 Docker 운영이 부담이 아닐 때
• 구조 검색(ast-grep)과 taint 추적(FLOWS_TO)이 필요할 때
• Python 생태계에 익숙할 때

codegraph를 선택할 때:

• 설치 부담을 최소화하고 싶을 때 (curl 한 줄, 의존성 없음)
• 에이전트(Claude Code 등)의 탐색 비용을 줄이는 것이 목표일 때
• 벤치마크로 검증된 실측 성능(44% 비용↓)을 우선할 때
• 파일 변경 시 실시간 자동 동기화가 필요할 때

참고 자료

• Code-Graph-RAG 저장소 (GitHub)
• codegraph 저장소 (GitHub)
• Code-Graph-RAG 설치 문서
• codegraph 벤치마크 문서