[MCP 번역] codebase-memory-mcp

AI 코딩 에이전트를 위한 가장 빠르고 효율적인 코드 인텔리전스(Code Intelligence) 엔진입니다. 평균 규모의 저장소는 밀리초 단위로 완전히 인덱싱(Indexing)하며, 리눅스 커널(2,800만 LOC, 7만 5천 파일)도 3분이면 처리합니다. 구조적 쿼리(Query)에 1ms 이내로 응답합니다. macOS, Linux, Windows용 단일 정적 바이너리(Static Binary)로 제공되므로 — 다운로드 후 install 실행만으로 끝입니다.

tree-sitter AST 분석을 통해 158개 언어 전체에서 고품질 파싱(Parsing)을 수행하며, Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust에 대해서는 하이브리드 LSP(Hybrid LSP) 시맨틱 타입 해석 기능이 추가로 적용됩니다 — 이를 통해 함수, 클래스, 호출 체인, HTTP 라우트, 서비스 간 연결로 구성된 영속적인 지식 그래프(Knowledge Graph)를 생성합니다. 14개의 MCP 도구를 제공하며, 의존성이 전혀 없고, 11개 코딩 에이전트에서 바로 사용할 수 있습니다.

연구(Research) — 이 프로젝트의 설계와 벤치마크는 프리프린트 Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277)에 기술되어 있습니다. 31개의 실제 저장소를 대상으로 평가한 결과, 파일 단위 탐색 대비 83%의 답변 품질, 10배 적은 토큰 사용량, 2.1배 적은 도구 호출 횟수를 기록했습니다.

보안 및 신뢰(Security & Trust) — 이 도구는 여러분의 코드베이스를 읽고 에이전트 설정 파일에 씁니다. 이는 원래 의도된 동작입니다. 실행 전에 감사(Audit)하고 싶다면 전체 소스코드는 여기에 있습니다 — 모든 릴리스 바이너리는 서명되고, 체크섬(Checksum)이 확인되며, 70개 이상의 백신 엔진으로 스캔됩니다. 모든 처리는 100% 로컬에서 이루어지며, 여러분의 코드는 절대 기기 밖으로 나가지 않습니다. 보안 문제를 발견하셨나요? 저희에게 알려주세요 — SECURITY.md를 참고하세요. 보안은 저희의 최우선 순위입니다.

codebase-memory-mcp을 선택해야 하는 이유

• 압도적인 인덱싱 속도 — 리눅스 커널(2,800만 LOC, 7만 5천 파일)을 3분 만에 처리합니다. RAM 우선 파이프라인: LZ4 압축, 인메모리(In-memory) SQLite, 융합된 Aho-Corasick 패턴 매칭 방식을 사용합니다. 인덱싱 후에는 메모리가 해제됩니다.
• 플러그 앤 플레이(Plug and play) — macOS(arm64/amd64), Linux(arm64/amd64), Windows(amd64)용 단일 정적 바이너리입니다. Docker도, 런타임 의존성도, API 키도 필요 없습니다. 다운로드 → install → 에이전트 재시작 → 완료.
• 158개 언어 지원 — 바이너리에 내장(Vendored)된 tree-sitter 문법을 사용합니다. 설치할 것도, 고장 날 것도 없습니다.
• 120배 적은 토큰 사용량 — 5개의 구조적 쿼리 기준 약 3,400토큰 vs 파일 단위 검색 시 약 412,000토큰. 그래프 쿼리 하나가 수십 번의 grep/read 반복 작업을 대체합니다.
• 11개 에이전트, 명령어 하나로 — install 명령이 Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, Kiro를 자동으로 감지하여 각각에 MCP 항목, 지침 파일, 사전 도구 훅(Pre-tool hook)을 구성합니다.
• 내장 그래프 시각화 — localhost:9749에서 3D 인터랙티브 UI를 제공합니다(선택적 UI 바이너리 변형).
• 코드형 인프라(Infrastructure-as-code) 인덱싱 — Dockerfile, 쿠버네티스(Kubernetes) 매니페스트, Kustomize 오버레이가 상호 참조가 포함된 그래프 노드로 인덱싱됩니다. K8s 종류(kind)를 위한 Resource 노드, 참조된 리소스로 향하는 IMPORTS 엣지(Edge)가 있는 Kustomize 오버레이를 위한 Module 노드가 있습니다.
• 14개의 MCP 도구 — 검색, 추적, 아키텍처, 영향 분석, Cypher 쿼리, 데드 코드(Dead code) 탐지, 서비스 간 HTTP 연결, ADR 관리 등을 제공합니다.

빠른 시작

한 줄 설치(macOS / Linux):

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

Windows(PowerShell):

# 1. 설치 스크립트 다운로드
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

# 2. (선택사항이지만 권장) 스크립트 검토
notepad install.ps1

# 3. 다운로드한 파일의 차단 해제 (브라우저/Invoke-WebRequest가 추가한 Mark-of-the-Web 제한 제거)
Unblock-File .\install.ps1

# 4. 실행
.\install.ps1

참고: 스크립트 실행 정책 오류가 나타나면 먼저 Set-ExecutionPolicy -Scope Process Bypass를 실행하거나, PowerShell -ExecutionPolicy Bypass -File .\install.ps1로 실행하세요.

옵션: --ui(그래프 시각화), --skip-config(바이너리만 설치, 에이전트 설정 제외), --dir=<path>(사용자 지정 위치).

코딩 에이전트를 재시작하세요. "Index this project"(이 프로젝트를 인덱싱해줘)라고 말하면 — 끝입니다.

수동 설치

1. 최신 릴리스에서 플랫폼에 맞는 아카이브를 다운로드하세요:

2. codebase-memory-mcp-<os>-<arch>.tar.gz(macOS/Linux) 또는 .zip(Windows) — 표준 버전

3. codebase-memory-mcp-ui-<os>-<arch>.tar.gz / .zip — 그래프 시각화 포함 버전

4. 압축을 풀고 설치하세요(각 아카이브에는 install.sh 또는 install.ps1이 포함되어 있습니다):

   macOS / Linux:

   tar xzf codebase-memory-mcp-*.tar.gz
   ./install.sh

   Windows(PowerShell):

   Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
   Unblock-File .\install.ps1
   .\install.ps1

5. 코딩 에이전트를 재시작하세요.

install 명령은 macOS 격리(Quarantine) 속성을 자동으로 제거하고 바이너리에 애드혹(Ad-hoc) 서명을 하므로, 수동으로 xattr/codesign을 실행할 필요가 없습니다.

install 명령은 설치된 모든 코딩 에이전트를 자동으로 감지하고, 각각에 대해 MCP 서버 항목, 지침 파일, 스킬(Skill), 사전 도구 훅을 구성합니다.

그래프 시각화 UI

ui 변형 버전을 다운로드했다면:

codebase-memory-mcp --ui=true --port=9749

브라우저에서 http://localhost:9749를 열어보세요. 이 UI는 MCP 서버와 함께 백그라운드 스레드로 실행되므로, 에이전트가 연결되어 있는 동안 언제든지 이용할 수 있습니다.

자동 인덱싱(Auto-Index)

MCP 세션 시작 시 자동 인덱싱을 활성화하려면:

codebase-memory-mcp config set auto_index true

이 옵션을 활성화하면 새 프로젝트는 최초 연결 시 자동으로 인덱싱됩니다. 이미 인덱싱된 프로젝트는 지속적인 git 기반 변경 감지를 위해 백그라운드 워처(Watcher)에 등록됩니다. 자동 인덱싱 대상 파일 수 제한 설정: config set auto_index_limit 50000.

워처 등록은 auto_watch(기본값 true)로 별도 제어됩니다. 세션이 백그라운드 워처에 프로젝트를 등록하지 않게 하려면 config set auto_watch false를 설정하세요 — 여러 프로젝트를 넘나들며 작업할 때 각 세션을 명시적 인덱싱으로만 한정하고 싶은 경우에 유용합니다.

최신 버전 유지하기

codebase-memory-mcp update

MCP 서버는 시작 시에도 업데이트를 확인하며, 새로운 릴리스가 있으면 최초 도구 호출 시 알려줍니다.

제거

codebase-memory-mcp uninstall

모든 에이전트 설정, 스킬, 훅, 지침을 제거합니다. 바이너리와 SQLite 데이터베이스는 제거하지 않습니다.

기능

그래프 및 분석

• 아키텍처 개요: get_architecture는 언어, 패키지, 진입점, 라우트, 핫스팟(Hotspot), 경계, 계층, 클러스터를 한 번의 호출로 반환합니다
• 아키텍처 결정 기록(Architecture Decision Records): manage_adr은 세션 간에 아키텍처 결정 사항을 유지합니다
• Louvain 커뮤니티 탐지: 호출 엣지를 클러스터링하여 기능적 모듈을 발견합니다
• Git diff 영향 매핑: detect_changes는 커밋되지 않은 변경 사항을 위험도 분류와 함께 영향을 받는 심볼(Symbol)에 매핑합니다
• 호출 그래프(Call graph): 파일과 패키지 전반에 걸쳐 함수 호출을 해석합니다(import 인식, 타입 추론)
• 데드 코드 탐지: 진입점을 제외하고 호출자가 없는 함수를 찾습니다
• Cypher 유사 쿼리: MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

검색

• 시맨틱 검색(Semantic search)(semantic_query): 바이너리에 내장된 Nomic nomic-embed-code 임베딩(4만 토큰, 768차원 int8)으로 구동되는, 전체 그래프에 대한 벡터 검색입니다 — API 키도, Ollama도, Docker도 필요 없습니다. 11개 신호를 결합한 스코어링(TF-IDF, RRI, API/타입/데코레이터 시그니처, AST 프로필, 데이터 흐름, Halstead-lite, MinHash, 모듈 근접도, 그래프 확산)을 사용합니다.
• BM25 전문(Full-text) 검색: camelCase / snake_case를 인식하는 cbm_camel_split 토크나이저(Tokenizer)를 사용한 SQLite FTS5 기반
• 구조적 검색(Structural search)(search_graph): 정규식 이름 패턴, 라벨 필터, 최소/최대 차수, 파일 범위 지정
• 코드 검색(Code search)(search_code): 인덱싱된 파일에 대해서만 그래프로 보강된 grep

서비스 간 연결

• HTTP 라우트 ↔ 호출 지점 매칭(신뢰도 점수 포함)
• gRPC, GraphQL, tRPC 서비스 탐지 및 protobuf Route 추출
• Socket.IO, EventEmitter, 그리고 8개 언어 전반의 일반적인 pub-sub 패턴에 대한 상수 해석을 포함한 채널 탐지(EMITS / LISTENS_ON)

저장소 간(Cross-repo) 인텔리전스

• CROSS_* 엣지가 동일한 저장소(Store) 아래 인덱싱된 여러 저장소(Repo) 전반의 노드를 연결합니다
• 저장소 간 아키텍처 시각화를 위한 멀티 갤럭시(Multi-galaxy) 3D UI 레이아웃
• 인덱싱된 전체 프로젝트군에 걸친 서비스, 라우트, 의존성을 결합한 저장소 간 아키텍처 요약

엣지 유형(선택)

• CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS
• HTTP_CALLS, ASYNC_CALLS(서비스 간)
• EMITS, LISTENS_ON(채널)
• 인자-매개변수 매핑 + 필드 접근 체인을 포함한 DATA_FLOWS
• SIMILAR_TO(MinHash + LSH 기반 근사 클론 탐지, Jaccard 점수)
• SEMANTICALLY_RELATED(어휘 불일치, 동일 언어, 점수 ≥ 0.80)

인덱싱 파이프라인

• 바이너리에 내장된 158개의 벤더드(Vendored) tree-sitter 문법
• 범용 패키지 / 모듈 해석 — @myorg/pkg, github.com/foo/bar, use my_crate::foo와 같은 단순 지정자(Bare specifier)를 매니페스트(Manifest) 스캔(package.json, go.mod, Cargo.toml, pyproject.toml, composer.json, pubspec.yaml, pom.xml, build.gradle, mix.exs, *.gemspec)을 통해 해석합니다
• 코드형 인프라 인덱싱 — Dockerfile, 쿠버네티스 매니페스트, Kustomize 오버레이를 그래프 노드로 인덱싱합니다
• Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust를 위한 하이브리드 LSP 시맨틱 타입 해석 — tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer 등 주요 언어 서버(Language server)와 구조적으로 유사하며 호환되도록 만든, 언어 타입 해석 알고리즘의 경량 C 구현입니다(매개변수 바인딩, 반환 타입 추론, 제네릭(Generic) 치환, JSX 컴포넌트 디스패치, 순수 JS 파일을 위한 JSDoc 추론, PHP를 위한 네임스페이스 + 트레이트(Trait) + 후기 정적 바인딩(Late-static-binding) 해석, C#을 위한 파일 범위 네임스페이스 + 레코드(Record) + LINQ 메서드 문법, Java를 위한 클래스 계층 + 오버로드 + 람다(Lambda) 해석, Kotlin을 위한 확장 함수 + 스코프 함수 해석, Rust를 위한 트레이트 메서드 + UFCS 해석)
• RAM 우선 파이프라인: LZ4 압축, 인메모리 SQLite, 마지막에 한 번만 덤프(Dump)합니다. 이후 메모리는 해제됩니다.

배포 및 운영

• 단일 정적 바이너리, 인프라 불필요: SQLite 기반이며, ~/.cache/codebase-memory-mcp/에 저장됩니다
• 자동 동기화: 백그라운드 워처가 파일 변경을 감지하여 자동으로 재인덱싱합니다
• 라우트 노드: REST 엔드포인트가 일급(First-class) 그래프 엔티티로 취급됩니다
• CLI 모드: codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*"}'
• 제공 채널: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, go install

팀 공유 그래프 아티팩트(Team-Shared Graph Artifact)

압축된 단일 파일을 저장소에 커밋하면 팀원들은 재인덱싱을 건너뛸 수 있습니다.

.codebase-memory/graph.db.zst는 소스 코드 옆에 위치하는 지식 그래프의 zstd 압축 스냅샷입니다. 인덱싱을 수행하면 이 아티팩트가 작성되거나 갱신되며, 팀원이 저장소를 클론하여 codebase-memory-mcp를 처음 실행하면 이 아티팩트의 압축이 해제되고 증분(Incremental) 인덱싱이 로컬 diff를 채워 넣습니다.

• 형식: 인덱스가 제거되고 VACUUM INTO로 압축된 SQLite 데이터베이스를 zstd 1.5.7로 압축(일반적으로 8~13:1 비율)
• 두 가지 등급:
• 최상(Best)(zstd -9 + 인덱스 제거 + VACUUM INTO) — 명시적인 index_repository 실행 시 작성됨
• 빠름(Fast)(zstd -3) — 저지연 증분 업데이트를 위해 워처가 작성함
• 부트스트랩(Bootstrap): 로컬 DB가 없지만 아티팩트가 존재하는 경우, index_repository가 먼저 이 아티팩트를 임포트(Import)한 뒤 증분 인덱싱을 실행하여 — 전체 재인덱싱 비용을 피합니다
• 병합 문제 없음: 최초 내보내기 시 merge=ours가 포함된 .gitattributes 라인이 자동으로 생성되므로, 동시 편집으로 인해 바이너리 아티팩트에서 충돌이 발생하지 않습니다
• 선택사항: 원치 않으면 커밋되지 않습니다. 모든 팀원이 처음부터 재인덱싱하길 원한다면 .codebase-memory/를 .gitignore에 추가하세요.

이 결과물은 graphify의 graphify-out/ 디렉토리와 취지는 비슷하지만, 명시적인 2단계 내보내기, 무결성 검사가 이루어지는 임포트, 병합 마찰 없음을 갖춘 단일 압축 파일이라는 점이 다릅니다.

작동 방식

codebase-memory-mcp는 구조 분석 백엔드(Structural analysis backend)입니다 — 지식 그래프를 구축하고 쿼리합니다. LLM은 포함하지 않습니다. 대신 여러분의 MCP 클라이언트(Claude Code 또는 MCP 호환 에이전트)가 지능(Intelligence) 계층 역할을 하도록 의존합니다.

You: "what calls ProcessOrder?"

Agent calls: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: executes graph query, returns structured results

Agent: presents the call chain in plain English

왜 LLM을 내장하지 않았나요? 다른 코드 그래프 도구들은 자연어를 그래프 쿼리로 변환하기 위해 LLM을 내장합니다. 이는 추가 API 키, 추가 비용, 그리고 설정해야 할 또 다른 모델을 의미합니다. MCP를 사용하면 여러분이 이미 대화하고 있는 에이전트 _자체_가 쿼리 변환기가 됩니다.

성능

Apple M3 Pro 기준 벤치마크:

작업	시간	비고
리눅스 커널 전체 인덱싱	3분	2,800만 LOC, 7만 5천 파일 → 노드 481만 개, 엣지 772만 개
리눅스 커널 고속 인덱싱	1분 12초	노드 188만 개
Django 전체 인덱싱	약 6초	노드 4만 9천 개, 엣지 19만 6천 개
Cypher 쿼리	1ms 미만	관계 순회(Traversal)
이름 검색(정규식)	10ms 미만	SQL LIKE 사전 필터링
데드 코드 탐지	약 150ms	차수(Degree) 필터링을 포함한 전체 그래프 스캔
호출 경로 추적(깊이=5)	10ms 미만	BFS 순회

RAM 우선 파이프라인: 모든 인덱싱은 메모리 내에서 실행됩니다(LZ4 HC 압축 읽기, 인메모리 SQLite, 마지막에 한 번의 덤프). 인덱싱 완료 후 메모리는 OS로 반환됩니다.

토큰 효율성: 다섯 개의 구조적 쿼리는 codebase-memory-mcp를 통해 약 3,400토큰을 소비한 반면, 파일 단위 grep 탐색으로는 약 412,000토큰을 소비했습니다 — 99.2% 감소한 수치입니다.

문제 해결 및 진단

codebase-memory-mcp는 100% 로컬에서 실행되며 텔레메트리(Telemetry)를 전혀 수집하지 않습니다 — 여러분의 코드, 쿼리, 환경, 사용 내역은 절대 기기 밖으로 나가지 않습니다. 이러한 개인정보 보호 보장은 저희 측에서 재현할 수 없는 문제(수 시간에 걸친 완만한 메모리 증가, 성능 저하, 실제 사용 후 며칠이 지나야 나타나는 누수 등)를 겪게 되었을 때, 여러분이 직접 데이터를 보내주지 않는 한 저희에게는 아무런 데이터가 없다는 것을 의미하기도 합니다. 다음은 직접 데이터를 수집하는 방법입니다.

진단 로그 수집하기

MCP 서버가 시작되기 전에 CBM_DIAGNOSTICS=1을 설정한 다음 문제를 재현하세요(필요한 만큼 오래 실행하세요 — 완만한 누수는 추세로 나타나기까지 시간이 필요합니다). 서버는 시스템 임시 디렉토리(macOS/Linux는 $TMPDIR 또는 /tmp, Windows는 %TEMP%)에 두 개의 파일을 작성합니다:

파일	설명
cbm-diagnostics-<pid>.ndjson	메모리 추이(Trajectory) — rss, committed(Windows 커밋 용량), peak_*, page_faults, fd, queries를 담은 JSON 라인이 5초마다 하나씩 기록됩니다. 메모리/누수 리포트에 필요한 파일이 바로 이것입니다 — 누수를 짚어내는 것은 _시간에 따른 추세_이기 때문입니다. 서버가 종료된 후에도 디스크에 남아 있으므로(사후에 확보할 수 있음) 약 8MB를 넘으면 .ndjson.1로 로테이션됩니다.
cbm-diagnostics-<pid>.json	최신 스냅샷만 담고 있으며, 빠르게 실시간으로 확인할 때 유용합니다. 정상 종료 시 삭제됩니다.

시작 로그에는 두 경로가 모두 출력됩니다. 예:

level=info msg=diagnostics.start snapshot=/tmp/cbm-diagnostics-12345.json trajectory=/tmp/cbm-diagnostics-12345.ndjson interval=5s

에이전트의 MCP 서버 설정 중 env 블록에 해당 변수를 설정하거나, 서버를 실행하기 전에 export 하세요.

공유해야 할 내용

메모리/성능 관련 이슈를 등록할 때는 .ndjson 추이 파일을 첨부해 주세요 — 이 파일에는 소스 코드나 쿼리 텍스트는 전혀 없고 리소스 카운터만 포함되어 있습니다. 파일 첨부를 원하지 않는다면 (또는 에이전트가 요약한 내용을) 이슈에 붙여넣어 주세요. 여러분의 어시스턴트가 NDJSON을 직접 읽고 rss/committed가 단조롭게 증가하는지, 얼마나 빠르게 증가하는지, 쿼리 수 대비 어느 정도인지 알려줄 수 있으며 — 이는 저희가 원인을 찾는 데 정확히 필요한 정보입니다.

설치

사전 빌드된 바이너리

플랫폼	표준	그래프 UI 포함
macOS(Apple Silicon)	codebase-memory-mcp-darwin-arm64.tar.gz	codebase-memory-mcp-ui-darwin-arm64.tar.gz
macOS(Intel)	codebase-memory-mcp-darwin-amd64.tar.gz	codebase-memory-mcp-ui-darwin-amd64.tar.gz
Linux(x86_64)	codebase-memory-mcp-linux-amd64.tar.gz	codebase-memory-mcp-ui-linux-amd64.tar.gz
Linux(ARM64)	codebase-memory-mcp-linux-arm64.tar.gz	codebase-memory-mcp-ui-linux-arm64.tar.gz
Windows(x86_64)	codebase-memory-mcp-windows-amd64.zip	codebase-memory-mcp-ui-windows-amd64.zip

모든 릴리스에는 SHA-256 해시가 담긴 checksums.txt가 포함되어 있습니다. 모든 바이너리는 정적으로 링크되어 있으며 — 공유 라이브러리 의존성이 없습니다.

Windows 참고사항: SmartScreen이 서명되지 않은 소프트웨어에 대해 경고를 표시할 수 있습니다. "추가 정보" → "실행"을 클릭하세요. checksums.txt로 무결성을 확인하세요.

설치 스크립트

자동 다운로드 + 설치

macOS / Linux:

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

Windows(PowerShell):

irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex

AUR(Arch Linux)

yay -S codebase-memory-mcp-bin

paru -S codebase-memory-mcp-bin

codebase-memory-mcp-bin 패키지는 다음 위치에서 제공됩니다: https://aur.archlinux.org/packages/codebase-memory-mcp-bin

Claude Code로 설치하기

You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"

소스에서 빌드하기

사전 요구사항: C 컴파일러 + zlib

요구사항	확인 방법	설치 방법
C 컴파일러(gcc 또는 clang)	gcc --version 또는 clang --version	macOS: xcode-select --install, Linux: apt install build-essential
C++ 컴파일러	g++ --version 또는 clang++ --version	위와 동일
zlib	—	macOS: 기본 포함, Linux: apt install zlib1g-dev
Git	git --version	대부분의 시스템에 사전 설치되어 있음

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh                    # 표준 바이너리
scripts/build.sh --with-ui          # 그래프 시각화 포함
# 바이너리 위치: build/c/codebase-memory-mcp

수동 MCP 설정

install 명령을 사용하고 싶지 않은 경우

~/.claude/.mcp.json(전역) 또는 프로젝트의 .mcp.json에 추가하세요:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

에이전트를 재시작하세요. /mcp로 확인하면 — 14개의 도구를 가진 codebase-memory-mcp가 보일 것입니다.

다중 에이전트 지원

install은 설치된 모든 에이전트를 자동으로 감지하고 구성합니다:

에이전트	MCP 설정	지침	훅
Claude Code	.claude/.mcp.json	4개의 스킬	PreToolUse(Grep/Glob 그래프 보강, 비차단(Non-blocking))
Codex CLI	.codex/config.toml	.codex/AGENTS.md	SessionStart 알림
Gemini CLI	.gemini/settings.json	.gemini/GEMINI.md	BeforeTool(grep 알림) + SessionStart 알림
Zed	settings.json(JSONC)	—	—
OpenCode	opencode.json	AGENTS.md	—
Antigravity	.gemini/config/mcp_config.json(공유)	antigravity-cli/AGENTS.md	SessionStart 알림
Aider	—	CONVENTIONS.md	—
KiloCode	mcp_settings.json	~/.kilocode/rules/	—
VS Code	Code/User/mcp.json	—	—
OpenClaw	openclaw.json	—	—
Kiro	.kiro/settings/mcp.json	—	—

훅은 구조적으로 비차단입니다(모든 실패 경로에서 종료 코드 0).
Claude Code의 경우 PreToolUse 훅이 Grep/Glob을 가로챕니다(Read는 절대 가로채지 않습니다 —
Read를 차단하면 편집 전 읽기(Read-before-edit) 불변 조건이 깨지기 때문입니다). 그리고 검색
토큰이 인덱싱된 심볼과 일치하면 search_graph를 통해 이를 additionalContext로
주입하여, 에이전트가 일반 검색 결과와 함께 구조화된 컨텍스트도 얻을 수 있게 합니다.
Codex, Gemini CLI, Antigravity의 경우 SessionStart 훅이 한 줄짜리 코드 탐색
알림을 세션 컨텍스트로 주입합니다(Gemini CLI는 BeforeTool 알림도 함께 유지합니다).
설치된 Claude용 shim 파일은 기존 설치와의 하위 호환성을 위해
cbm-code-discovery-gate라는 이름을 유지하고 있지만, 이 이름과 달리
실제로는 아무것도 차단하거나 가로막지 않습니다.

CLI 모드

모든 MCP 도구는 커맨드 라인에서도 호출할 수 있습니다:

codebase-memory-mcp cli index_repository '{"repo_path": "/path/to/repo"}'
codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_path '{"function_name": "Search", "direction": "both"}'
codebase-memory-mcp cli query_graph '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'
codebase-memory-mcp cli list_projects
codebase-memory-mcp cli --raw search_graph '{"label": "Function"}' | jq '.results[].name'

MCP 도구

인덱싱

도구	설명
index_repository	저장소를 그래프로 인덱싱합니다. 이후 자동 동기화가 최신 상태를 유지합니다.
list_projects	노드/엣지 수와 함께 인덱싱된 모든 프로젝트를 나열합니다.
delete_project	프로젝트와 그 그래프 데이터를 모두 제거합니다.
index_status	프로젝트의 인덱싱 상태를 확인합니다.

쿼리

도구	설명
search_graph	라벨, 이름 패턴, 파일 패턴, 차수 필터를 통한 구조화된 검색. limit/offset을 통한 페이지네이션 지원.
trace_path	BFS 순회 — 어떤 함수를 누가 호출하고, 그 함수는 무엇을 호출하는지(별칭: trace_call_path). 깊이 1~5.
detect_changes	git diff를 위험도 분류가 포함된 영향받는 심볼 + 파급 범위(Blast radius)에 매핑합니다.
query_graph	Cypher 유사 그래프 쿼리를 실행합니다(읽기 전용).
get_graph_schema	라벨별 노드/엣지 수, 관계 패턴, 속성 정의. 가장 먼저 실행하세요.
get_code_snippet	정규화된 이름(Qualified name)으로 함수의 소스 코드를 읽습니다.
get_architecture	코드베이스 개요: 언어, 패키지, 라우트, 핫스팟, 클러스터, ADR.
search_code	인덱싱된 프로젝트 파일 내에서 grep과 유사한 텍스트 검색을 수행합니다.
manage_adr	아키텍처 결정 기록(Architecture Decision Records)에 대한 CRUD.
ingest_traces	HTTP_CALLS 엣지를 검증하기 위해 런타임 트레이스를 수집합니다.

그래프 데이터 모델

노드 라벨

Project, Package, Folder, File, Module, Class, Function, Method, Interface, Enum, Type, Route, Resource

엣지 유형

CONTAINS_PACKAGE, CONTAINS_FOLDER, CONTAINS_FILE, DEFINES, DEFINES_METHOD, IMPORTS, CALLS, HTTP_CALLS, ASYNC_CALLS, IMPLEMENTS, HANDLES, USAGE, CONFIGURES, WRITES, MEMBER_OF, TESTS, USES_TYPE, FILE_CHANGES_WITH

정규화된 이름(Qualified Names)

get_code_snippet은 정규화된 이름을 사용합니다: <project>.<path_parts>.<name>. 먼저 search_graph를 사용하여 이를 찾아보세요.

지원되는 Cypher(openCypher 읽기 서브셋)

query_graph는 읽기 전용 openCypher 서브셋입니다:

• 절(Clause): MATCH, OPTIONAL MATCH, 다중 MATCH, WHERE, WITH(+ WITH … WHERE), RETURN, ORDER BY, SKIP, LIMIT, DISTINCT, UNWIND, UNION / UNION ALL, CASE.
• 패턴: 라벨이 지정된 노드, 라벨 대안(Label alternation) (n:A|B), 관계 유형/방향, 가변 길이 경로 [*1..3], 인라인 속성 맵.
• WHERE: = <> < <= > >=, AND/OR/XOR/NOT, IN, CONTAINS, STARTS WITH, ENDS WITH, IS [NOT] NULL, 정규식 =~, 라벨 테스트 n:Label, 그리고 EXISTS { (n)-[:TYPE]->() }(단일 홉(Hop) 존재 여부 확인 — 데드 코드 탐지에 유용합니다. 예: WHERE NOT EXISTS { (f)<-[:CALLS]-() }).
• 집계 함수: count(+DISTINCT), sum, avg, min, max, collect.
• 함수: labels, type, id, keys, properties; toLower/toUpper/toString/toInteger/toFloat/toBoolean; size, length, trim/ltrim/rtrim, reverse; coalesce, substring, replace, left, right.

이 서브셋을 벗어나는 항목(쓰기/MERGE/CALL 절, 지원되지 않는 함수, 리스트/맵 리터럴, 컴프리헨션(Comprehension), 경로 함수, 매개변수)은 빈 결과를 반환하는 대신 명확한 unsupported … 오류로 실패합니다.

파일 무시하기

계층적으로 적용됩니다: 하드코딩된 패턴(.git, node_modules 등) → .gitignore 계층 → .cbmignore(프로젝트별, gitignore 문법). 심볼릭 링크는 항상 건너뜁니다.

.cbmignore의 전체 사용법(문법, 무시 계층 간 우선순위, 부정(Negation) 의미론)에 대해서는 docs/cbmignore.md를 참고하세요.

설정

codebase-memory-mcp config list                          # 모든 설정 보기
codebase-memory-mcp config set auto_index true           # 세션 시작 시 자동 인덱싱
codebase-memory-mcp config set auto_index_limit 50000    # 자동 인덱싱을 위한 최대 파일 수
codebase-memory-mcp config set auto_watch false          # 백그라운드 git 워처를 등록하지 않음(기본값: true)
codebase-memory-mcp config reset auto_index              # 기본값으로 초기화

환경 변수

변수	기본값	설명
CBM_CACHE_DIR	~/.cache/codebase-memory-mcp	데이터베이스 저장 디렉토리를 재정의합니다. 모든 프로젝트 인덱스와 설정이 여기에 저장됩니다.
CBM_DIAGNOSTICS	false	1 또는 true로 설정하면 /tmp/cbm-diagnostics-<pid>.json에 주기적인 진단 출력을 활성화합니다.
CBM_DOWNLOAD_URL	(GitHub 릴리스)	업데이트를 위한 다운로드 URL을 재정의합니다. 테스트 또는 자체 호스팅 배포에 사용됩니다.
CBM_LOG_LEVEL	info	최소 로그 레벨을 설정합니다. 허용 값(대소문자 구분 없음): debug, info, warn, error, none — 또는 내부 열거형(Enum)에 대응하는 숫자 0~4. 로그는 stderr로 출력되며, stdout은 MCP JSON-RPC 전용으로 예약되어 있습니다.
CBM_WORKERS	(자동 감지)	cbm_default_worker_count가 반환하는 병렬 인덱싱 워커 수를 재정의합니다. sysconf(_SC_NPROCESSORS_ONLN)가 cgroup의 유효 할당량이 아닌 호스트 CPU를 보고하는 컨테이너 환경에서 유용합니다. 범위는 1~256이며, 잘못된 값은 경고와 함께 무시됩니다.
CBM_DUMP_VERIFY_MIN_RATIO	0.5	인덱싱 후, 저장된 SQLite 노드 수를 인메모리 덤프 노드 수와 비교합니다. 저장된 노드 수가 커밋된 노드 수(그리고 커밋된 노드 수가 50 초과)의 이 비율 아래로 떨어지면, index_repository는 조용히 indexed를 반환하는 대신 status:"degraded"를 반환합니다. 범위는 0~1이며, 비활성화하려면 0으로 설정하세요. 잘못된 값은 경고와 함께 무시됩니다.

# 사용자 지정 디렉토리에 인덱스 저장
export CBM_CACHE_DIR=~/my-projects/cbm-data

사용자 지정 파일 확장자

JSON 설정 파일은 extra_extensions라는 단일 키를 지원하며, 이는 추가 파일 확장자를 지원되는 언어에 매핑합니다. .blade.php(Laravel)나 .mjs(ES 모듈)와 같은 프레임워크별 확장자에 유용합니다.(다른 설정 옵션은 환경 변수와 위의 config 서브커맨드를 참고하세요.)

전체 설정 파일 레퍼런스가 필요하신가요? docs/CONFIGURATION.md를 확인하세요.

프로젝트별(저장소 루트에):

// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}

전역(모든 프로젝트에 적용):

// ~/.config/codebase-memory-mcp/config.json  (또는 $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}}

각 항목은 확장자(반드시 .로 시작해야 함)를 언어 이름에 매핑합니다. 언어 이름은 대소문자를 구분하지 않고 매칭됩니다. 허용되는 값(괄호 안은 별칭)은 다음과 같습니다:

bash(sh), c, c++(cpp), c#(csharp), clojure, cmake, cobol, common lisp(commonlisp, lisp), css, cuda, dart, dockerfile, elixir, elm, emacs lisp(emacslisp), erlang, f#(fsharp), form, fortran, glsl, go, graphql, groovy, haskell, hcl(terraform), html, ini, java, javascript, json, julia, kotlin, lean, lua, magma, makefile, markdown, matlab, meson, nix, objective-c(objc), ocaml, perl, php, protobuf, python, r, ruby, rust, scala, scss, sql, svelte, swift, toml, tsx, typescript, verilog, vimscript, vue, wolfram, xml, yaml, zig.

프로젝트 설정은 충돌하는 확장자에 대해 전역 설정보다 우선합니다. 언어 이름을 알 수 없거나 확장자가 .로 시작하지 않는 항목은 건너뛰며, 경고가 stderr에 기록됩니다(기본 info 로그 레벨에서 표시됨). 설정 파일이 없으면 무시됩니다.

영속성(Persistence)

SQLite 데이터베이스는 ~/.cache/codebase-memory-mcp/에 저장됩니다. 재시작 후에도 유지됩니다(WAL 모드, ACID 안전). 초기화하려면: rm -rf ~/.cache/codebase-memory-mcp/.

문제 해결

문제	해결 방법
/mcp에 서버가 표시되지 않음	.mcp.json 경로가 절대 경로인지 확인하세요. 에이전트를 재시작하세요. 테스트: `echo '{}' \
index_repository가 실패함	절대 경로를 전달하세요: index_repository(repo_path="/absolute/path")
trace_path가 0개의 결과를 반환함	정확한 이름을 찾으려면 먼저 search_graph(name_pattern=".*PartialName.*")를 사용하세요.
쿼리가 잘못된 프로젝트 결과를 반환함	project="name" 매개변수를 추가하세요. 이름을 확인하려면 list_projects를 사용하세요.
설치 후 바이너리를 찾을 수 없음	PATH에 추가하세요: export PATH="$HOME/.local/bin:$PATH"
UI가 로드되지 않음	ui 변형 버전을 다운로드했는지, --ui=true로 실행했는지 확인하세요. http://localhost:9749를 확인하세요.

하이브리드 LSP

tree-sitter를 넘어선 시맨틱 타입 해석.

tree-sitter만으로는 구문적(Syntactic) AST만 얻을 수 있습니다. 이는 이름 지정, 구조, 호출 지점을 잘 처리하지만, user.profile.display_name()이 세 개의 모듈 떨어진 곳에 선언된 Profile.display_name으로 해석된다는 것은 알려주지 못합니다 — tree-sitter는 import, 제네릭, 상속, 표준 라이브러리 타입을 추적하지 않기 때문입니다.

codebase-memory-mcp는 주요 언어 서버(tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer)와 구조적으로 유사하며 호환되도록 만든, 언어 타입 해석 알고리즘의 경량 C 구현을 정적 바이너리에 직접 내장하여 제공합니다. 별도의 언어 서버 프로세스도, 프로젝트별 설정도, API 키도 필요 없습니다. 이 계층을 하이브리드 LSP라고 부릅니다: 이는 매 파싱마다 tree-sitter와 함께 실행되며 CALLS, USAGE, RESOLVED_CALLS 엣지를 타입 정보로 정교화하여, 결과적으로 생성되는 그래프가 IDE의 "정의로 이동(Go to Definition)"이 해석하는 결과를 그대로 반영하도록 합니다.

완전한 하이브리드 LSP를 지원하는 언어:

언어	처리 범위
Python (v0.7.0에서 신규 추가)	import + 점 표기 서브모듈 순회, 데이터클래스(Dataclass), Self 반환 타입, 제네릭, @property, match/case 클래스 패턴, SQLAlchemy 2.0 Mapped[T], Pydantic BaseModel, typing.Annotated / ClassVar / Final / InitVar, async/await, classmethod/staticmethod, 타입 좁히기(isinstance / is not None / 왈러스(Walrus) 연산자), typing.cast / assert_type, 일반적인 표준 라이브러리(logging, pathlib, json, functools). 관용적인(Idiomatic) 코드 기준 약 95% 해석률을 목표로 합니다.
TypeScript / JavaScript / JSX / TSX	제네릭, JSX 컴포넌트 디스패치, 순수 JS를 위한 JSDoc 추론, .d.ts 선언, 모듈 재내보내기(Re-export), 반환 타입 전파를 통한 메서드 체이닝, 공유되는 파일 간 레지스트리에 연결되는 파일별 오버레이
PHP (v0.7.0에서 신규 추가)	네임스페이스, 트레이트, 후기 정적 바인딩, PHPDoc 추론, 매개변수 바인딩, 반환 타입 추론
C# (v0.7.0에서 신규 추가)	전역 using, 파일 범위 네임스페이스, 레코드(C# 12의 기본 생성자(Primary constructor) 포함), LINQ 메서드 문법, async Task<T> / ValueTask<T> 언랩(Unwrap), 제네릭 메서드, this / base 디스패치, var 추론, 일반적인 BCL 표준 라이브러리
Go (v0.7.0에서 정교화)	패키지별로 미리 구축된 파일 간 레지스트리, 제네릭, 임베디드 구조체, 인터페이스 충족 여부, 패키지 인식 import 해석
C / C++ (v0.7.0에서 정교화)	C와 C++이 공유하는, 언어별로 미리 구축된 파일 간 레지스트리; C 쪽은 매크로 + typedef 체인 + 헤더-소스 연결을 처리하고, C++ 쪽은 템플릿, 네임스페이스, auto 추론, 클래스 계층을 통한 메서드 해석을 처리합니다
Java (v0.8.0에서 신규 추가)	import(단일 타입, on-demand, static), this / super 디스패치를 포함한 클래스 계층, 제네릭, 애노테이션, 인자 개수 및 매개변수 타입에 의한 오버로드 매칭, 함수형 인터페이스에 바인딩되는 람다 / 메서드 참조, 필드 타입 추론, 일반적인 JDK 표준 라이브러리
Kotlin (v0.8.0에서 신규 추가)	import + 동일 패키지 해석, 클래스 / 객체 / 컴패니언 객체(Companion object), 확장 함수, 데이터 클래스, nullable 타입 언랩, 스코프 함수(let / apply / run / also / with), 중위(Infix) 호출, 일반적인 표준 라이브러리
Rust (v0.8.0에서 신규 추가)	use 선언 + 모듈 경로, impl 블록 및 트레이트 메서드, 구조체 필드, 트레이트 바운드가 있는 제네릭, 연산자 트레이트 디슈가링(Desugaring), 파생 매크로(Derive macro) 메서드 합성, UFCS 정적 경로, 일반적인 std 프렐류드(Prelude)

2단계 아키텍처:

1. Tree-sitter 패스 — 빠르고 구문적이며, 158개 언어 전체에 대해 실행됩니다. 정의, 호출, import를 추출합니다.
2. 하이브리드 LSP 패스 — 타입을 인식하며, tree-sitter 패스 위에서 언어별로 실행됩니다. import 그래프와 파일별 또는 미리 구축된 파일 간 정의 레지스트리를 사용하여 호출 엣지를 정교화합니다. 아직 하이브리드 LSP 패스가 없는 언어는 텍스트 기반 해석으로 폴백(Fallback)되므로, 항상 어떤 형태로든 답을 얻을 수 있습니다.

그 결과물은 프로젝트당 언어 서버 프로세스를 비용으로 지불하지 않고도, 패키지, 상속 계층, 표준 라이브러리 호출 전반에 걸쳐 trace_path를 구동할 수 있을 만큼 정확한 지식 그래프입니다.

언어 지원

바이너리에 내장된 벤더드 tree-sitter 문법을 통해 파싱되는 158개 언어. 64개의 실제 오픈소스 저장소(78개에서 4만 9천 개 노드)를 대상으로 벤치마크했습니다:

등급	점수	언어
우수(Excellent)(90% 이상)		Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift, CSS, YAML, TOML, HTML, SCSS, HCL, Dockerfile
양호(Good)(75~89%)		Python, TypeScript, TSX, Go, Rust, Java, R, Dart, JavaScript, Erlang, Elixir, Scala, Ruby, PHP, C#, SQL
기능적(Functional)(75% 미만)		OCaml, Haskell

또한 지원됨(아직 벤치마크되지 않음): Ada, Agda, Apex, Assembly(NASM), Astro, AWK, Beancount, BibTeX, Bicep, Bitbake, Blade, Cairo, Cap'n Proto, Clojure, CMake, COBOL, Common Lisp, Crystal, CSV, CUDA, D, Devicetree, Diff, .env, Elm, Emacs Lisp, F#, Fennel, Fish, FORM, Fortran, FunC, GDScript, .gitattributes, .gitignore, Gleam, GLSL, GN, Go module, Go template, GraphQL, Hare, HLSL, Hyprlang, INI, ISPC, Janet, Jinja2, JSDoc, JSON, JSON5, Jsonnet, Julia, Just, Kconfig, KDL, Lean 4, Linker Script, Liquid, LLVM IR, Luau, Magma, Makefile, Markdown, MATLAB, Mermaid, Meson, Move, Nickel, Nim, Nix, Odin, Pascal, Pkl, PO(gettext), Pony, PowerShell, Prisma, .properties, Protobuf, Puppet, PureScript, Racket, Regex, requirements.txt, ReScript, RON, reStructuredText, Scheme, Slang, Smali, Smithy, Solidity, SOQL, SOSL, Squirrel, SSH config, Starlark, Svelte, Sway, SystemVerilog, TableGen, Tcl, Teal, Templ, Thrift, TLA+, Typst, Verilog, VHDL, Vim script, Vue, WGSL, WIT, Wolfram, XML, Zsh.

아키텍처

src/
  main.c              진입점(MCP stdio 서버 + CLI + install/update/config)
  mcp/                MCP 서버(14개 도구, JSON-RPC 2.0, 세션 감지, 자동 인덱싱)
  cli/                Install/uninstall/update/config(10개 에이전트, 훅, 지침)
  store/              SQLite 그래프 저장소(노드, 엣지, 순회, 검색, Louvain)
  pipeline/           다단계 인덱싱(구조 → 정의 → 호출 → HTTP 링크 → 설정 → 테스트)
  cypher/             Cypher 쿼리 렉서(Lexer), 파서, 플래너(Planner), 실행기
  discover/           파일 탐색(.gitignore, .cbmignore, 심볼릭 링크 처리)
  watcher/            백그라운드 자동 동기화(git 폴링, 적응형 간격)
  traces/             런타임 트레이스 수집
  ui/                 내장 HTTP 서버 + 3D 그래프 시각화
  foundation/         플랫폼 추상화(스레드, 파일시스템, 로깅, 메모리)
internal/cbm/         벤더드 tree-sitter 문법(158개 언어) + AST 추출 엔진

보안

모든 릴리스 바이너리는 배포 전 다단계 파이프라인을 통해 검증됩니다:

• VirusTotal — 모든 바이너리가 70개 이상의 백신 엔진으로 스캔됩니다(배포하려면 탐지 건수가 0이어야 함)
• SLSA 레벨 3 — GitHub Actions가 생성하는 암호학적 빌드 출처 증명(Provenance); gh attestation verify <file> --repo DeusData/codebase-memory-mcp로 검증 가능
• Sigstore cosign — 모든 아티팩트에 대한 키리스(Keyless) 서명; 모든 릴리스에 번들 포함
• SHA-256 체크섬 — 모든 릴리스와 함께 checksums.txt가 게시되며, 압축 해제 전 두 설치 스크립트 모두에서 검증됨
• CodeQL SAST — 미해결 경고가 하나라도 남아있으면 릴리스 파이프라인을 차단함
• 런타임 의존성 없음 — 전이적(Transitive) 공급망이 없으며, 모든 라이브러리는 컴파일 시점에 내장됨

v0.7.0 VirusTotal 스캔

바이너리	SHA-256	VirusTotal
linux-amd64	8e12bb2d6ead7f20a6d3...	0/72 ✅
linux-arm64	10f7136bfbf3950c6b2a...	0/72 ✅
darwin-arm64	7062a7408906344bf4f8...	0/72 ✅
darwin-amd64	28c6d640e1a0ac7bfcab...	0/72 ✅
windows-amd64	9c3ddcf78368fd4fa891...	0/72 ✅

모든 릴리스에 대한 스캔 링크는 GitHub 릴리스 노트에도 자동으로 포함됩니다.

라이선스

MIT

---

출처: https://github.com/DeusData/codebase-memory-mcp