TL;DR

이 프로젝트는 단일 정적 바이너리로 로컬 코드베이스를 빠르게 구조적 지식 그래프로 색인해 에이전트 기반 워크플로에 서브밀리초 수준의 쿼리 응답을 제공하는 MCP 서버이다. 구현은 tree-sitter로 158개 언어를 파싱하고 Hybrid LSP 레이어로 타입·심볼 연결을 보강한 뒤 RAM-우선 파이프라인(LZ4 + in-memory SQLite)으로 인덱싱하여 대형 리포지토리도 수분 내에 처리하도록 설계되었다. README의 벤치마크는 Linux 커널 전체 색인을 3분에 완료하고 Cypher 쿼리는 1ms 미만, 구조적 쿼리 다섯 건으로 파일 단위 탐색 대비 토큰 사용을 99.2% 줄였음을 보고하고 있다. 에이전트 통합용 자동 install 및 11개 에이전트용 훅, 로컬 3D 시각화, 팀 공유용 압축 그래프 스냅샷 등 운영 편의성 기능을 포함하나, 이 도구는 LLM을 내장하지 않고 MCP 클라이언트에 의존하므로 자연어→그래프 쿼리 변환은 외부 에이전트에 위임된다는 한계가 있다.

주요 기능

• 빠르게 전체 저장소를 인덱싱한다. Linux 커널(28M LOC, 75K 파일)은 3분, 중간 규모 웹앱은 수초 내에 색인 완료된 사례가 README에 제시되어 있다. 인덱싱은 RAM-우선 파이프라인과 LZ4 압축, 인메모리 SQLite 덤프를 결합해 수행된다.
• 정밀한 의미 해석을 수행한다. vendored tree-sitter 파싱 결과에 Hybrid LSP 레이어를 적용해 import·제네릭·상속·오버로드 같은 의미적 연결을 복원하며 그 결과 CALLS·RESOLVED_CALLS 엣지가 그래프에 포함된다. 이 과정은 별도 LSP 프로세스 없이 바이너리 내부에서 실행된다.
• 다양한 검색·분석 도구를 제공한다. 그래프 기반 구조 검색, semantic vector search(nomic-embed-code 번들 임베딩), Cypher 스타일 쿼리, dead code detection, trace_path 같은 BFS 기반 호출 추적 기능을 포함한다. 각 도구는 CLI와 MCP 툴로 노출되어 에이전트 통합 및 자동화가 가능하다.
• 에이전트 통합을 자동화한다. install 커맨드는 설치 후 Claude Code, Codex CLI, Gemini CLI 등 11개 에이전트를 자동으로 감지해 MCP 설정과 pre-tool 훅을 등록한다. 훅은 비차단 방식으로 동작해 정상 툴 흐름을 방해하지 않는다.

어떻게 동작하는가

프로젝트는 tree-sitter로 158개 언어의 AST를 추출한 뒤 Hybrid LSP 레이어로 타입·심볼 연결을 보강해 지식 그래프 노드와 엣지를 생성한다. 인덱싱 파이프라인은 RAM-우선 방식으로 LZ4 압축을 사용해 인메모리 SQLite에 데이터를 적재한 뒤 작업 완료 시 단일 덤프를 디스크에 저장한다. 쿼리 시에는 그래프 탐색과 벡터 검색이 조합되어 서브밀리초 수준의 응답으로 호출체인, 아키텍처 요약, 영향도 분석 같은 구조적 결과를 반환한다.

해결 문제

대형 코드베이스에서 파일 단위 탐색이 비효율적이고 LLM과의 연동 시 토큰·툴 호출 비용이 급증하는 문제가 존재한다. 이 프로젝트는 코드베이스를 구조적 지식 그래프로 변환해 단일 그래프 쿼리로 수십~수백 파일에 걸친 정보를 집계함으로써 반복적인 grep/파일 리딩을 대체한다. 그 결과 structural query 다섯 번으로 파일 단위 탐색 대비 토큰 수를 크게 줄이고 호출 횟수를 감소시키는 것이 README에서 제시된 목표이다.

지금 주목받는 이유

arXiv 예비논문과 대형 리포지토리(예: Linux 커널) 색인 벤치마크를 통해 구조적 색인 방식의 실효성이 제시된 점과 수만 개 스타를 얻은 오픈소스 인기도가 결합해 주목받고 있다.

차별점

• 단일 정적 바이너리로 배포된다. macOS, Linux, Windows용으로 정적 링킹된 바이너리를 제공해 런타임 의존성이 전혀 없으며 설치 스크립트가 무결성 검증과 서명 확인 절차를 포함한다. 이 설계는 별도의 런타임·컨테이너·데몬 없이 즉시 사용 가능하도록 만든다.
• Hybrid LSP를 내장해 의미적 연결을 복원한다. tree-sitter의 구문 분석 결과 위에 언어별 타입·심볼 해석을 C로 구현해 import·제네릭·오버로드·상속 등을 해석하고 이를 그래프 엣지에 반영한다. 이 방식은 별도 LSP 프로세스나 외부 서비스 없이 IDE 수준의 정의 탐색 정밀도를 제공한다.
• 광범위한 언어 지원과 번들링된 임베딩을 제공한다. 158개 언어의 grammar를 바이너리에 포함하고 nomic-embed-code 임베딩을 내장해 벡터 검색을 API 키 없이 수행한다. 결과적으로 멀티랭귀지 리포지토리에서도 별도 설정 없이 바로 동작한다.
• 팀 수준의 그래프 아티팩트 공유 워크플로를 지원한다. 압축된 SQLite 스냅샷(.codebase-memory/graph.db.zst)을 리포지토리에 커밋하면 팀원들이 재색인 비용 없이 스냅샷을 불러와 증분 색인으로 작업을 이어갈 수 있다. 자동으로 `.gitattributes` merge 전략을 설정해 바이너리 병합 충돌을 회피한다.

사용 사례

• AI 기반 코드 어시스턴트의 컨텍스트 공급원으로 사용한다. 에이전트가 natural language 질의를 MCP 프로토콜로 번역하면 그래프는 호출체인·관련심볼·아키텍처 요약을 구조화된 결과로 반환해 LLM이 토큰을 절감한 채 정밀한 응답을 생성할 수 있다. 이 흐름은 도구 호출 수와 네이티브 파일 리딩을 크게 줄이는 방향으로 설계되었다.
• 리포지토리 아키텍처 분석과 영향도 평가에 활용한다. Louvain 클러스터링과 detect_changes 도구를 통해 기능적 모듈과 변경의 blast radius를 자동 계산해 코드 리팩터링·릴리스 위험 평가에 필요한 데이터를 제공한다. Cypher 쿼리로 맞춤형 영향 분석을 자동화할 수 있다.
• 교차 리포지토리 의존성 및 서비스 맵 작성에 사용한다. CROSS_* 엣지와 멀티-갤럭시 UI 레이아웃으로 다중 저장소에 걸친 라우트·서비스 의존성을 시각화하고 gRPC/GraphQL/tRPC 같은 인터페이스를 자동 감지해 교차 서비스 링크를 구성한다. 이 기능은 마이크로서비스 포트폴리오를 문서화하고 서지컬 변경의 범위를 파악하는 데 유용하다.

시작하기

사전빌드 바이너리를 사용하는 경우 제공된 설치 스크립트를 curl로 받아 실행하면 플랫폼에 맞는 정적 바이너리와 기본 에이전트 구성이 설치된다. UI가 필요한 경우 설치 시 --ui 플래그를 전달하거나 codebase-memory-mcp --ui=true --port=9749로 실행하면 브라우저에서 그래프를 탐색할 수 있다. 수동 설치를 선호하면 릴리스 페이지에서 플랫폼 아카이브를 내려받아 압축 해제 후 ./install.sh 또는 PowerShell 스크립트를 실행하면 된다.

요구사항

• 사전빌드 바이너리는 macOS(arm64/amd64), Linux(arm64/amd64), Windows(am64)를 지원하며 런타임 의존성이 전혀 없다.
• 소스에서 빌드하려면 C 컴파일러(gcc 또는 clang)와 zlib 개발 헤더가 필요하며 표준 빌드 스크립트(scripts/build.sh)를 통해 빌드된다.
• 디스크에 인덱스를 저장하는 기본 경로는 ~/.cache/codebase-memory-mcp이며 환경변수 CBM_CACHE_DIR로 변경 가능하다.

벤치마크

이미지 분석