DeusData/codebase-memory-mcp

AI 코딩 에이전트를 위한 가장 빠르고 효율적인 코드 인텔리전스 엔진. 평균적인 저장소를 밀리초(ms) 단위로 전체 인덱싱하며, Linux 커널(28M LOC, 75K 파일)을 3분 만에 완료합니다. 구조적 질의(structural queries)에 1ms 미만으로 응답합니다. macOS, Linux, Windows용 단일 정적 바이너리(single static binary)로 제공되어, 다운로드 후 install을 실행하면 바로 완료됩니다.

158개 모든 언어에 걸친 tree-sitter AST 분석을 통한 고품질 파싱을 제공하며, Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust를 위한 Hybrid LSP 시맨틱 타입 분해(semantic type resolution)로 강화되었습니다. 이를 통해 함수, 클래스, 호출 체인(call chains), HTTP 경로(routes), 서비스 간 링크(cross-service links)의 지속적인 지식 그래프(knowledge graph)를 생성합니다. 14개의 MCP 도구를 제공하며, 의존성이 전혀 없습니다(Zero dependencies). 11개의 코딩 에이전트에서 즉시 사용 가능합니다(Plug and play).

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

보안 및 신뢰— 이 도구는 사용자의 코드베이스를 읽고 에이전트 설정 파일에 내용을 작성합니다. 이는 도구의 설계 목적입니다. 실행 전 감사를 원하신다면 전체 소스 코드가 여기에 있습니다. 모든 릴리스 바이너리는 서명(signed) 및 체크섬(checksummed) 처리가 되어 있으며, 70개 이상의 안티바이러스 엔진으로 스캔되었습니다. 모든 프로세싱은 100% 로컬에서 이루어지며, 코드는 절대 사용자의 기기를 떠나지 않습니다. 보안 문제를 발견하셨나요? 저희에게 알려주세요 — SECURITY.md를 참조하십시오. 보안은 저희의 최우선 순위입니다.

내장된 3D 그래프 시각화(UI 변형) — localhost:9749에서 지식 그래프를 탐색하세요.

극한의 인덱싱 속도— Linux 커널(28M LOC, 75K 파일)을 3분 만에 완료합니다. RAM 우선 파이프라인(RAM-first pipeline): LZ4 압축, 인메모리 SQLite(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개의 구조적 쿼리(structural queries)를 통해, 파일별 검색 시 약 412,000개의 토큰이 소모되는 것에 비해 약 3,400개의 토큰만 사용합니다. 단 한 번의 그래프 쿼리가 수십 번의 grep/read 사이클을 대체합니다.11개 에이전트, 단 하나의 명령— install 명령어가 Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, Kiro를 자동으로 감지하여 각 에이전트에 맞는 MCP 엔트리, 지침 파일(instruction files), 프리-툴 훅(pre-tool hooks)을 구성합니다.내장 그래프 시각화— localhost:9749에서 제공되는 3D 인터랙티브 UI (선택 사항인 UI 바이너리 변체 사용 시).코드형 인프라 (Infrastructure-as-code) 인덱싱— Dockerfile, Kubernetes 매니페스트(manifests), Kustomize 오버레이(overlays)를 상호 참조가 포함된 그래프 노드로 인덱싱합니다. K8s kind를 위한 Resource 노드, 참조된 리소스로 향하는 IMPORTS 엣지(edges)를 가진 Kustomize 오버레이를 위한 Module 노드가 생성됩니다.14개의 MCP 도구— 검색(search), 추적(trace), 아키텍처(architecture), 영향 분석(impact analysis), Cypher 쿼리, 데드 코드 탐지(dead code detection), 서비스 간 HTTP 연결(cross-service HTTP linking), 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. (선택 사항이지만 권장) 스크립트 검토
...

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

코딩 에이전트를 재시작하세요. **"Index this project"**라고 말하면 — 완료됩니다.

수동 설치

• 최신 릴리스에서 사용자의 플랫폼에 맞는 아카이브를 다운로드하세요: codebase-memory-mcp-<os>-<arch>.tar.gz (macOS/Linux) 또는 .zip (Windows) — 그래프 시각화가 포함된 버전은 codebase-memory-mcp-ui-<os>-<arch>.tar.gz / .zip 입니다.

압축 해제 및 설치 (각 아카이브에는 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 .
.\install.ps1

**코딩 에이전트 (coding agent)**를 재시작하세요.

install 명령은 macOS의 격리 속성 (quarantine attributes)을 자동으로 제거하고 바이너리에 ad-hoc 서명 (ad-hoc signs)을 수행하므로, 수동으로 xattr 또는 codesign을 실행할 필요가 없습니다.

install 명령은 설치된 모든 코딩 에이전트를 자동으로 감지하고, 각 에이전트에 대한 MCP 서버 항목, 지침 파일 (instruction files), 스킬 (skills), 그리고 프리-툴 훅 (pre-tool hooks)을 구성합니다.

ui 버전을 다운로드한 경우:

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

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

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

codebase-memory-mcp config set auto_index true

활성화되면, 새로운 프로젝트는 첫 연결 시 자동으로 인덱싱됩니다. 이전에 인덱싱된 프로젝트는 지속적인 git 기반 변경 감지를 위해 백그라운드 와처 (background watcher)에 등록됩니다. 설정 가능한 파일 제한: config set auto_index_limit 50000.

codebase-memory-mcp update

MCP 서버는 시작 시 업데이트를 확인하며, 더 새로운 릴리스가 있는 경우 첫 번째 도구 호출 (tool call) 시 알림을 보냅니다.

codebase-memory-mcp uninstall

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

아키텍처 개요 (Architecture overview):
get_architecture는 단 한 번의 호출로 언어, 패키지, 엔트리 포인트 (entry points), 라우트 (routes), 핫스팟 (hotspots), 경계 (boundaries), 레이어 (layers), 클러스터 (clusters)를 반환합니다.

아키텍처 결정 기록 (Architecture Decision Records):
manage_adr은 세션 전반에 걸쳐 아키텍처 결정을 유지합니다.

Louvain 커뮤니티 탐지 (Louvain community detection): 호출 엣지 (call edges)를 클러스터링하여 기능적 모듈을 발견합니다.

Git diff 영향 매핑 (Git diff impact mapping):
detect_changes

커밋되지 않은 변경 사항을 위험 분류와 함께 영향을 받는 심볼(symbols)에 매핑합니다.

호출 그래프 (Call graph): 파일 및 패키지 전반에 걸친 함수 호출을 해결합니다 (import 인식, 타입 추론).

데드 코드 탐지 (Dead code detection): 엔트리 포인트(entry points)를 제외하고 호출자가 없는 함수를 찾습니다.

Cypher 스타일 쿼리 (Cypher-like queries):
MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

시맨틱 검색 (Semantic search) (semantic_query):
바이너리에 컴파일된 번들형 Nomic nomic-embed-code 임베딩(40K 토큰, 768d int8)을 사용하여 전체 그래프에 대해 벡터 검색을 수행합니다 — API 키, Ollama, Docker가 필요 없습니다. 11가지 시그널 결합 점수(TF-IDF, RRI, API/Type/Decorator 시그니처, AST 프로필, 데이터 흐름, Halstead-lite, MinHash, 모듈 근접성, 그래프 확산)를 사용합니다.

BM25 전체 텍스트 검색 (BM25 full-text search):
cbm_camel_split 토크나이저(camelCase / snake_case 인식)를 사용하는 SQLite FTS5를 통한 검색

구조적 검색 (Structural search) (search_graph):
정규 표현식 이름 패턴, 레이블 필터, 최소/최대 차수(degree), 파일 범위 지정

코드 검색 (Code search) (search_code):
인덱싱된 파일에 대해서만 그래프가 보강된 grep 수행

HTTP: 신뢰도 점수와 함께 라우트(route) ↔ 호출 지점(call-site) 매칭

gRPC, GraphQL, tRPC: protobuf 라우트 추출을 통한 서비스 탐지

채널 탐지 (Channel detection) (EMITS / LISTENS_ON): 8개 언어에 걸쳐 Socket.IO, EventEmitter 및 일반적인 pub-sub 패턴에 대해 상수 해결(constant resolution)을 수행합니다.

동일한 스토어 아래 인덱싱된 여러 리포지토리 간의 노드를 연결하는 CROSS_* 엣지(edges)

멀티 갤럭시 3D UI 레이아웃 (Multi-galaxy 3D UI layout): 교차 리포지토리 아키텍처 시각화용

교차 리포지토리 아키텍처 요약 (Cross-repo architecture summary): 인덱싱된 플릿(fleet) 전체의 서비스, 라우트 및 의존성을 결합

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 문법 (grammars)**이 바이너리에 컴파일됨
범용 패키지 / 모듈 해석 (Generic package / module resolution) — @myorg/pkg, github.com/foo/bar, use my_crate::foo와 같은 순수 지정자 (bare specifiers)가 매니페스트 스캐닝 (package.json, go.mod, Cargo.toml, pyproject.toml, composer.json, pubspec.yaml, pom.xml, build.gradle, mix.exs, *.gemspec)을 통해 해석됨
코드형 인프라 (Infrastructure-as-code) 인덱싱 — Dockerfiles, Kubernetes 매니페스트 (manifests), Kustomize 오버레이 (overlays)를 그래프 노드로 처리
하이브리드 LSP 의미론적 타입 해석 (Hybrid LSP semantic type resolution) — Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust 지원 — tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer를 포함한 주요 언어 서버(language servers)에서 구조적 영감을 얻고 호환되는 언어 타입 해석 알고리즘의 경량 C 구현 (매개변수 바인딩 (parameter binding), 반환 타입 추론 (return-type inference), 제네릭 치환 (generic substitution), JSX 컴포넌트 디스패치 (JSX component dispatch), 일반 JS 파일을 위한 JSDoc 추론 (JSDoc inference), PHP를 위한 네임스페이스 + 트레이트 + 후기 정적 바인딩 (namespace + trait + late-static-binding) 해석, C#을 위한 파일 범위 네임스페이스 + 레코드 + LINQ 메서드 구문 (file-scoped namespaces + records + LINQ method syntax), Java를 위한 클래스 계층 구조 + 오버로드 + 람다 해석 (class-hierarchy + overload + lambda resolution), Kotlin을 위한 확장 함수 + 스코프 함수 해석 (extension-function + scope-function resolution), Rust를 위한 트레이트 메서드 + UFCS 해석 (trait-method + UFCS resolution))
RAM 우선 파이프라인 (RAM-first pipeline): LZ4 압축, 인메모리 SQLite (in-memory SQLite), 종료 시 단일 덤프 (single dump). 이후 메모리 해제.

단일 정적 바이너리, 제로 인프라 (Single static binary, zero infrastructure): SQLite 기반, ~/.cache/codebase-memory-mcp/에 영구 저장
자동 동기화 (Auto-sync): 백그라운드 워처 (watcher)가 파일 변경을 감지하고 자동으로 재인덱싱
경로 노드 (Route nodes): REST 엔드포인트는 일급 그래프 엔티티 (first-class graph entities)
CLI 모드: codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*"}'

사용 가능 채널: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, go install

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

.codebase-memory/graph.db.zst

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

포맷 (Format): SQLite 데이터베이스, 인덱스 제거 (indexes stripped), VACUUM INTO를 통한 압축, 그 후 zstd 1.5.7로 압축 (일반적으로 8–13:1 비율)

두 가지 계층 (Two tiers):

• 최적 (Best) (zstd -9 + 인덱스 제거 + VACUUM INTO): 명시적인 index_repository 명령 시 작성됨
• 빠름 (Fast) (zstd -3): 저지연 증분 업데이트를 위해 와처 (watcher)에 의해 작성됨

부트스트랩 (Bootstrap): 로컬 DB는 없지만 아티팩트가 존재하는 경우, index_repository는 먼저 아티팩트를 임포트 (import)한 다음 증분 인덱싱을 실행하여 전체 재인덱싱 비용을 방지합니다.

병합 문제 없음 (No merge pain): 첫 번째 내보내기 (export) 시 merge=ours 설정이 포함된 .gitattributes 라인이 자동으로 생성되므로, 동시 편집 시에도 바이너리 아티팩트에 대한 충돌 (conflict)이 발생하지 않습니다.

선택 사항 (Optional): 원하지 않는 한 절대 커밋되지 않습니다. 모든 사람이 처음부터 다시 인덱싱하기를 원한다면 .gitignore에 .codebase-memory/를 추가하세요.

그 결과는 graphify의 graphify-out/ 디렉토리와 정신적으로 유사하지만, 명시적인 2단계 내보내기, 무결성이 검증된 임포트, 그리고 병합 마찰이 전혀 없는 단일 압축 파일 형태를 띱니다.

codebase-memory-mcp는 **구조적 분석 백엔드 (structural analysis backend)**입니다. 즉, 지식 그래프를 구축하고 쿼리 (query)합니다. 이 도구는 LLM을 포함하지 않습니다. 대신, 귀하의 MCP 클라이언트 (Claude Code 또는 기타 MCP 호환 에이전트)가 지능 계층 (intelligence layer) 역할을 하도록 합니다.

사용자: "ProcessOrder를 호출하는 것이 무엇인가요?"
에이전트 호출: trace_path(function_name="ProcessOrder", direction="inbound")
codebase-memory-mcp: 그래프 쿼리 실행, 구조화된 결과 반환
...

왜 내장 LLM이 없나요? 다른 코드 그래프 도구들은 자연어에서 그래프 쿼리로의 번역을 위해 LLM을 내장합니다. 이는 추가적인 API 키, 추가 비용, 그리고 구성해야 할 또 다른 모델을 의미합니다. MCP를 사용하면, 귀하가 이미 대화하고 있는 에이전트가 바로 그 쿼리 번역기 역할을 수행합니다.

Apple M3 Pro 기반 벤치마크:

작업 (Operation)	시간 (Time)	비고 (Notes)
Linux 커널 전체 인덱싱 (Linux kernel full index)	3분	2,800만 LOC, 75,000개 파일 → 481만 개 노드, 772만 개 엣지
Linux 커널 빠른 인덱싱 (Linux kernel fast index)	1분 12초	188만 개 노드
Django 전체 인덱싱 (Django full index)	약 6초	4.9만 개 노드, 19.6만 개 엣지
Cypher 쿼리 (Cypher query)	1ms 미만	관계 탐색 (Relationship traversal)
...

RAM 우선 파이프라인 (RAM-first pipeline): 모든 인덱싱은 메모리 내에서 실행됩니다 (LZ4 HC 압축 읽기, 인메모리 SQLite, 종료 시 단일 덤프). 인덱싱이 완료되면 메모리는 운영체제(OS)로 반환됩니다.

토큰 효율성 (Token efficiency): 5개의 구조적 쿼리를 수행할 때, 파일별 grep 탐색을 통한 방식은 약 412,000개의 토큰을 소비한 반면, codebase-memory-mcp를 통한 방식은 약 3,400개의 토큰만을 소비했습니다. 이는 99.2%의 감소를 의미합니다.