Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP

1. 문제 정의 (Problem Statement)

대형 언어 모델 (LLM) 기반 코딩 에이전트 (Claude Code, Cursor, Aider 등) 는 현재 코드베이스 탐색을 위해 반복적인 파일 읽기와 grep 검색에 의존하고 있습니다. 이 방식에는 다음과 같은 근본적인 비효율성이 존재합니다.

• 구조적 이해의 부재: 에이전트가 비구조화된 텍스트를 처리하는 반면, 개발자의 질문 (함수 변경 시 영향 분석, 의존성 체인, 모듈 경계 등) 은 본질적으로 구조적입니다.
• 높은 토큰 비용 및 지연 시간: 구조적 관계를 파악하기 위해 참조를 따라가는 반복적인 탐색 과정에서 수천 개의 토큰이 소모되고, 컨텍스트 손실 위험이 증가합니다.
• 기존 솔루션의 한계: 기존 그래프 기반 코드 표현 (Code Property Graph, CodeQL 등) 은 강력한 정적 분석이 가능하지만, 특수한 데이터베이스와 쿼리 언어가 필요하여 LLM 에이전트가 직접 활용하기에는 무겁고 복잡합니다.
• MCP 의 미활용: 모델 컨텍스트 프로토콜 (MCP) 은 에이전트와 외부 도구를 연결하는 표준이지만, 이를 통해 구조적 코드 쿼리를 경량화된 도구로 노출하는 솔루션은 부재했습니다.

2. 방법론 (Methodology)

저자들은 Codebase-Memory라는 오픈소스 시스템을 제안합니다. 이는 코드베이스를 구조화된 지식 그래프로 변환하여 LLM 에이전트에 경량 도구로 제공하는 시스템입니다.

A. 시스템 아키텍처 및 파이프라인

• 구현: 단일 정적 링크된 C 바이너리로, 런타임 의존성이 전혀 없습니다 (Zero-dependency). macOS, Linux, Windows 지원.
• 파싱 엔진: 66 개 이상의 프로그래밍 언어를 지원하는 Tree-Sitter를 사용하여 AST(추상 구문 트리) 를 파싱합니다.
• 데이터 저장: 추출된 그래프를 SQLite에 저장하며, 단일 파일로 관리됩니다.
• 인터페이스: **MCP(Model Context Protocol)**를 통해 14 가지 타입화된 구조적 쿼리 도구를 LLM 에이전트에 노출합니다.

B. 핵심 기술적 요소

1. 멀티-페이즈 파이프라인 (Multi-Phase Pipeline):
   • 병렬 워커 풀을 사용하여 구조 추출, 정의 추출, 호출 해결, enrichment(보강) 단계를 수행합니다.
   • 대량 삽입 시 SQLite 오버헤드를 줄이기 위해 메모리 버퍼를 경유한 후 일괄 저장 (Bulk INSERT) 합니다.
2. 고급 호출 해결 (Call Resolution):
   • 6 단계 전략 캐스케이드: 임포트 맵, 동일 모듈, 고유 이름, 접미사 일치, 퍼지 매칭 등을 통해 호출 관계를 해결합니다.
   • 하이브리드 타입 해결 (LSP 스타일): Go, C, C++ 의 경우 메서드 리시버, 포인터 간접 참조, 템플릿 등을 처리하기 위해 Tree-Sitter 추출 후 추가적인 타입 해결 패스를 수행하여 호출 그래프의 정확도를 높입니다.
3. 커뮤니티 탐지 (Community Detection):
   • Louvain 알고리즘을 적용하여 호출 그래프를 기능적 커뮤니티로 분할합니다. 이는 아키텍처 요약 및 모듈 간 의존성 파악에 활용됩니다.
4. 증분 동기화 (Incremental Synchronization):
   • 파일 변경 감지 (File Watcher) 와 XXH3 콘텐츠 해시를 사용하여 변경된 파일만 재파싱하고 그래프를 업데이트합니다.
5. 보안 강화 (Security Hardening):
   • MCP 서버가 호스트 권한을 가지는 점을 고려하여, CI/CD 파이프라인에 8 단계 감사 스위트 (정적 허용 목록, 네트워크_egress_모니터링, 바이러스 스캔, SLSA 증명 등) 를 도입하여 공급망 보안을 강화했습니다.

3. 주요 기여 (Key Contributions)

1. 경량 지식 그래프 아키텍처: 66 개 언어를 파싱하고, 6 가지 전략으로 호출을 해결하며, Louvain 알고리즘으로 커뮤니티를 탐지하는 그래프를 단일 SQLite 파일에 저장하는 시스템을 구축했습니다.
2. MCP 기반 도구 인터페이스: LLM 에이전트가 즉시 호출할 수 있는 14 가지 구조적 쿼리 도구 (호출 경로 추적, 영향 분석, 허브 탐지 등) 를 표준 MCP 프로토콜로 노출했습니다.
3. 포괄적인 평가: 31 개 언어와 31 개 실제 저장소를 대상으로 한 벤치마크를 통해 기존 파일 탐색 에이전트와의 정량적 비교를 수행했습니다.

4. 평가 결과 (Results)

31 개 언어의 다양한 오픈소스 저장소를 대상으로 한 벤치마크 결과, Codebase-Memory 는 다음과 같은 성과를 보였습니다.

• 품질 (Quality): 파일 탐색 에이전트 (92%) 대비 **83%**의 답변 품질을 달성했습니다. (구조적 질문에서는 동등하거나 더 나은 성능)
• 토큰 효율성: 에이전트당 토큰 소모량을 10 배 감소시켰습니다 (약 1,000 토큰 vs 10,000 토큰).
• 도구 호출 횟수: 질문당 도구 호출 횟수를 2.1 배 감소시켰습니다 (2.3 회 vs 4.8 회).
• 속도: 쿼리 응답 시간이 1ms 미만으로, 파일 기반 탐색 (10~30 초) 보다 100 배 이상 빠릅니다.
• 언어별 성능: 함수형 언어 (Haskell, OCaml 등) 에서 가장 높은 성능 차이를 보였으며, 매크로가 많은 C 언어에서는 AST 기반의 한계로 인해 성능이 상대적으로 낮았습니다.

5. 의의 및 결론 (Significance & Conclusion)

• 패러다임 전환: 코드 탐색을 '텍스트 검색'에서 '구조적 그래프 쿼리'로 전환함으로써, 에이전트의 토큰 비용과 지연 시간을 획기적으로 줄이면서도 구조적 이해도를 유지할 수 있음을 증명했습니다.
• 실용성: 단일 바이너리로 배포되어 인프라 오버헤드가 없으며, MCP 표준을 준수하여 어떤 MCP 호환 에이전트와도 통합 가능합니다.
• 보안 표준 제시: MCP 생태계에서 에이전트가 실행하는 도구의 신뢰성 문제를 해결하기 위해, 자동화된 0-허용 (zero-tolerance) 릴리스 검증 파이프라인을 제안하여 공급망 보안의 새로운 기준을 제시했습니다.
• 미래 전망: 의료 정보학 (Health Informatics) 과 같은 도메인 특화 언어 (DSL) 에 대한 확장 가능성을 제시하며, 구조적 컨텍스트가 필요한 복잡한 데이터 매핑 작업에서 LLM 의 능력을 극대화할 수 있음을 시사합니다.

요약하자면, Codebase-Memory 는 LLM 에이전트가 코드베이스를 이해하는 방식을 비효율적인 텍스트 스캐닝에서 효율적인 구조적 그래프 쿼리로 전환시키는 획기적인 솔루션으로, 비용 절감과 성능 향상을 동시에 달성했습니다.