Codebase Memory MCP — 코드베이스를 지식 그래프로 색인하는 로컬 코드 분석 서버

AI 요약

Codebase Memory MCP는 코드를 직접 생성하는 LLM이 아니라, 코딩 에이전트가 코드베이스의 구조를 질의하도록 돕는 분석 백엔드입니다. 저장소를 함수, 클래스, 호출 관계, HTTP 경로 등의 지식 그래프로 색인하고, MCP(Model Context Protocol) 도구로 검색과 영향 분석 결과를 돌려줍니다. 자연어를 질의로 바꾸는 역할은 Claude Code 같은 MCP 클라이언트에 맡깁니다. 자체 LLM이나 API 키, 호스팅 서비스는 필요하지 않습니다.

색인과 그래프 구성

Tree-sitter AST 분석으로 여러 언어의 구문 구조를 파악하고, Python, TypeScript, JavaScript, PHP, C#, Go, C/C++, Java, Kotlin, Rust, Perl 등에는 Hybrid LSP 방식의 의미 분석을 더합니다. 이 과정에서 함수 호출, import, 상속, 데이터 흐름을 관계로 기록합니다. HTTP 경로와 호출 지점을 연결하고, Dockerfile·Kubernetes 매니페스트·Kustomize 오버레이도 그래프 노드로 다룹니다. README는 지원 언어를 한 곳에서 162개라고 소개하고, 다른 곳에서는 바이너리에 포함된 Tree-sitter 문법을 158개라고 적습니다.

검색 수단은 구조 검색, BM25 전문 검색, 의미 검색으로 나뉩니다. 호출 경로 추적, 사용되지 않는 함수 탐지, Git 변경 사항의 영향 범위 분석, 아키텍처 요약, Cypher 유사 질의도 제공합니다. 총 17개 MCP 도구를 내세우며, 결과에는 색인 범위와 누락 여부를 확인하는 기능도 포함합니다. 다만 깨끗한 범위 확인 결과가 코드 전체를 빠짐없이 분석했다는 증거는 아니라고 문서에서 선을 긋습니다.

성능과 토큰 사용량

프로젝트가 공개한 Apple M3 Pro 측정치에 따르면 Linux 커널은 2,800만 줄, 파일 7만 5천 개를 전체 색인하는 데 3분이 걸렸고, 그래프에는 노드 481만 개와 간선 772만 개가 생성됐습니다. 빠른 색인은 1분 12초에 노드 188만 개를 만들었습니다. Django는 약 6초에 색인했고, 관계 탐색 질의는 1ms 미만, 깊이 5의 호출 경로 추적은 10ms 미만으로 보고했습니다.

색인 파이프라인은 LZ4 압축과 메모리 내 SQLite를 사용하고, 작업을 마친 뒤 결과를 한 번에 저장합니다. 프로젝트 측정에서는 구조 질의 다섯 번에 약 3,400토큰을 사용했습니다. 파일을 하나씩 grep하고 읽는 방식은 약 41만 2천 토큰이 들었다며 99.2% 감소를 제시합니다. 별도 연구 설명에는 실제 저장소 31개를 평가해 답변 품질 83%, 토큰 10분의 1, 도구 호출 2.1분의 1을 기록했다고 적혀 있습니다. README는 수치 재현에 원래 입력과 원시 산출물이 필요하다고 덧붙입니다.

설치, 로컬 실행과 운영

macOS, Linux, Windows용 네이티브 실행 파일을 제공하며, README는 언어 런타임·Docker·API 키 없이 설치할 수 있다고 설명합니다. 설치 스크립트는 감지한 코딩 에이전트의 MCP 설정과 지원되는 기술 자료, 훅 등을 구성합니다. 지원 클라이언트는 자동 또는 조건부 설정을 합쳐 45개라고 소개합니다. 그래프 시각화 UI도 바이너리에 포함하며, 로컬 9749번 포트에서 실행합니다.

색인 데이터는 기본적으로 사용자의 캐시 디렉터리에 저장됩니다. 선택적으로 압축된 SQLite 그래프 파일을 저장소에 커밋하면 팀원이 처음 실행할 때 이를 가져와 증분 색인을 수행합니다. 다만 매번 갱신되는 파일을 자주 커밋하면 Git 이력이 커질 수 있다고 경고합니다. 한 팀에서 약 350회 커밋 후 해당 경로가 약 6GB를 차지한 사례도 문서에 제시합니다.

여러 에이전트 세션은 계정 단위 데몬을 공유합니다. 같은 시점에 실행되는 프로세스는 버전, 바이너리 빌드, 조정 ABI, 캐시 경로가 일치해야 합니다. 설치·업데이트·삭제는 작업 중인 세션을 정리하고 제한 시간 안에 프로세스를 종료한 뒤 바이너리를 교체합니다. 일반 색인이나 질의는 데몬 연결 없이 실행하는 CLI 모드도 제공합니다.

모든 처리는 로컬에서 이뤄지고 원격 측정 데이터를 수집하지 않는다고 밝힙니다. 대신 성능 문제를 제보하려면 사용자가 진단을 켜고 자원 사용 기록을 직접 첨부해야 합니다. 설치 도구는 에이전트 설정 파일을 수정하므로, 프로젝트는 실행 전 소스와 설치 스크립트를 확인하라고 안내합니다. Microsoft Defender가 일부 바이너리를 오탐할 수 있다는 경고와 SHA-256 체크섬 확인 방법도 제공합니다.

원문: GitHub / 번역·요약: Trawling