codebase-memory-mcp는 코딩 에이전트가 파일을 반복적으로 읽고 grep하는 대신, 코드베이스를 로컬 지식 그래프로 인덱싱해 구조 질의를 수행하게 하는 MCP 서버다. Tree-Sitter 기반 AST 분석, 일부 언어의 Hybrid LSP 타입 해석, SQLite 기반 그래프 저장을 조합한다.

핵심 기능

• 158개 언어 Tree-Sitter grammar를 포함한 단일 정적 바이너리
• Python, TypeScript/JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, Rust에 대한 Hybrid LSP 의미 해석
• 함수, 클래스, 호출 관계, HTTP route, cross-service link를 그래프 노드/엣지로 구성
• architecture overview, impact analysis, dead code detection, Cypher-like query, ADR 관리 등 14개 MCP 도구
• Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider 등 여러 코딩 에이전트 설정 자동 감지
• 선택적으로 localhost:9749의 3D 그래프 UI 제공

연구 결과

연구 논문 Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP는 31개 실제 저장소 평가를 보고한다. 논문 초록 기준으로 Codebase-Memory는 파일 탐색 에이전트 대비 10배 적은 토큰과 2.1배 적은 도구 호출로 83% answer quality를 기록했다. graph-native 질의에서는 일부 언어에서 file-exploration 방식과 같거나 더 나은 결과를 냈다.

저장소 README는 5개 구조 질의가 약 3,400 토큰을 소비한 반면 파일 단위 탐색은 약 412,000 토큰을 소비했다고 설명한다. 이 수치는 코드 이해 작업에서 “읽을 파일을 고르는 비용” 자체가 큰 병목임을 보여준다.

설치

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

그래프 UI 포함:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash -s -- --ui

설치 후 코딩 에이전트에서 “Index this project” 같은 요청으로 저장소를 인덱싱하는 흐름을 전제로 한다.

사용 대상 및 케이스

• 대형 코드베이스를 다루는 코딩 에이전트 사용자: 반복 파일 탐색 비용을 줄이고 구조 질의를 빠르게 하고 싶을 때
• 플랫폼 팀: 여러 에이전트가 같은 코드 그래프 artifact를 공유하도록 만들 때
• 아키텍처 리뷰어: route, call graph, dead code, 변경 영향 범위를 빠르게 훑어야 할 때

주의점

도구는 로컬에서 동작하지만 코드베이스를 읽고 에이전트 설정 파일을 수정한다. 설치 스크립트를 바로 실행하기 전에는 조직 보안 정책에 맞게 소스와 release artifact 신뢰 모델을 확인하는 편이 좋다.

관련 문서

• mcp — 모델 컨텍스트 프로토콜
• codegraph — 코드베이스 그래프 기반 분석 도구
• claude-code-tips-large-codebases — 큰 코드베이스에서 컨텍스트와 검색 범위 관리하기
• agent-harness — 코딩 에이전트 하네스 설계

참고 자료

• DeusData/codebase-memory-mcp — GitHub 공식 저장소
• Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP — arXiv 2603.27277 (2026-03-28)