DeusData/codebase-memory-mcp

codebase-memory-mcp

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

158개 언어에 걸쳐 tree-sitter AST 분석을 통한 고품질 파싱과 Hybrid LSP 의미론적 타입 해석(Python, TypeScript/JavaScript/JSX/TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust 지원)이 결합되어 함수, 클래스, 호출 체인, HTTP 라우트, 서비스 간 링크로 구성된 지속적 지식 그래프를 생성합니다. 14개의 MCP 도구. 제로 의존성. 11개 코딩 에이전트에서 플러그 앤 플레이.

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

보안 및 신뢰 — 이 도구는 코드베이스를 읽고 에이전트 설정 파일에 씁니다. 이것이 설계된 목적입니다. 실행 전에 감사를 원한다면 전체 소스가 여기에 있습니다 — 모든 릴리스 바이너리는 서명되고, 체크섬이 확인되며, 70개 이상의 안티바이러스 엔진으로 검사됩니다. 모든 처리는 100% 로컬에서 이루어집니다. 코드가 머신을 떠나지 않습니다. 보안 문제를 발견하셨나요? 알려주시기 바랍니다 — SECURITY.md를 참조하세요. 보안은 우리의 최우선 과제입니다.

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

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

• 극한의 인덱싱 속도 — Linux 커널(28M LOC, 75K 파일)을 3분 만에 인덱싱. RAM 우선 파이프라인: LZ4 압축, 인메모리 SQLite, 융합 Aho-Corasick 패턴 매칭. 인덱싱 후 메모리 해제.
• 플러그 앤 플레이 — macOS(arm64/amd64), Linux(arm64/amd64), Windows(amd64)용 단일 정적 바이너리. Docker, 런타임 의존성, API 키 불필요. 다운로드 → install → 에이전트 재시작 → 완료.
• 158개 언어 — 바이너리에 컴파일된 벤더드 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 항목, 명령 파일, 사전 도구 훅을 설정.
• 내장 그래프 시각화 — localhost:9749에서 3D 대화형 UI (선택적 UI 바이너리 변형).
• Infrastructure-as-code 인덱싱 — Dockerfile, Kubernetes 매니페스트, Kustomize 오버레이가 참조와 함께 그래프 노드로 인덱싱됨. K8s 종류에 대한 Resource 노드, 참조된 리소스에 대한 IMPORTS 에지를 가진 Kustomize 오버레이용 Module 노드.
• 14개의 MCP 도구 — 검색, 추적, 아키텍처, 영향 분석, Cypher 쿼리, 데드 코드 감지, 서비스 간 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. 실행.\install.ps1

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

코딩 에이전트를 재시작하세요. "Index this project" 라고 말하면 끝.

수동 설치

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

• codebase-memory-mcp--.tar.gz (macOS/Linux) 또는 .zip (Windows) — 표준
• codebase-memory-mcp-ui--.tar.gz / .zip — 그래프 시각화 포함

1. 압축 풀고 설치 (각 아카이브에는 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

1. 코딩 에이전트 재시작.

install 명령어는 macOS 격리 속성을 자동으로 제거하고 바이너리에 임시 서명을 수행합니다 — 수동 xattr/codesign 불필요.

install 명령어는 설치된 모든 코딩 에이전트를 자동 감지하고 각각에 대해 MCP 서버 항목, 명령 파일, 스킬, 사전 도구 훅을 설정합니다.

그래프 시각화 UI

ui 변형을 다운로드한 경우:

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

브라우저에서 http://localhost:9749를 여세요. UI는 MCP 서버와 함께 백그라운드 스레드로 실행됩니다 — 에이전트가 연결되어 있을 때 항상 사용 가능합니다.

자동 인덱싱

MCP 세션 시작 시 자동 인덱싱 활성화:

codebase-memory-mcp config set auto_index true

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

업데이트 유지

codebase-memory-mcp update

MCP 서버는 시작 시 업데이트를 확인하고, 최신 릴리스가 있는 경우 첫 번째 도구 호출 시 알림을 표시합니다.

제거

codebase-memory-mcp uninstall

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

기능

그래프 및 분석

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

검색

• 의미론적 검색 (semantic_query): 번들된 Nomic nomic-embed-code 임베딩(40K 토큰, 768d int8)으로 구동되는 그래프 전체 벡터 검색 — API 키, Ollama, Docker 불필요. 11-신호 결합 점수(TF-IDF, RRI, API/Type/Decorator 시그니처, AST 프로파일, 데이터 흐름, Halstead-lite, MinHash, 모듈 근접성, 그래프 확산).
• BM25 전문 검색: cbmcamelsplit 토크나이저(camelCase/snake_case 인식)를 사용하는 SQLite FTS5 기반
• 구조적 검색 (search_graph): 정규식 이름 패턴, 레이블 필터, 최소/최대 차수, 파일 범위 지정
• 코드 검색 (search_code): 인덱싱된 파일에 대한 그래프 보강 grep

서비스 간 링크

• HTTP 라우트 ↔ 호출 사이트 매칭 (신뢰도 점수 포함)
• gRPC, GraphQL, tRPC 서비스 탐지 (protobuf 라우트 추출 포함)
• 채널 탐지 (EMITS / LISTENS_ON): Socket.IO, EventEmitter 및 일반 pub-sub 패턴을 8개 언어에서 상수 해석과 함께 탐지

저장소 간 인텔리전스

• CROSS_* 에지: 동일 저장소 아래 인덱싱된 여러 저장소의 노드 연결
• 다중 은하 3D UI 레이아웃: 저장소 간 아키텍처 시각화
• 저장소 간 아키텍처 요약: 인덱싱된 전체에서 서비스, 라우트, 의존성 결합

에지 유형 (선택)

• CALLS, IMPORTS, DEFINES, IMPLEMENTS, INHERITS
• HTTPCALLS, ASYNCCALLS (서비스 간)
• EMITS, LISTENS_ON (채널)
• DATA_FLOWS (인자-매개변수 매핑 + 필드 접근 체인 포함)
• SIMILAR_TO (MinHash + LSH 근접 복제 탐지, Jaccard 점수)
• SEMANTICALLY_RELATED (어휘 불일치, 동일 언어, 점수 ≥ 0.80)

인덱싱 파이프라인

• 158개의 벤더드 tree-sitter 문법이 바이너리에 컴파일됨
• 일반 패키지/모듈 해석 — @myorg/pkg, github.com/foo/bar, use my_crate::foo와 같은 베어 지정자를 매니페스트 스캐닝(package.json, go.mod, Cargo.toml, pyproject.toml, composer.json, pubspec.yaml, pom.xml, build.gradle, mix.exs, *.gemspec)을 통해 해석
• Infrastructure-as-code 인덱싱 — Dockerfile, Kubernetes 매니페스트, Kustomize 오버레이를 그래프 노드로 인덱싱
• Hybrid LSP 의미론적 타입 해석: Python, TypeScript/JavaScript/JSX/TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust 지원 — 언어 타입 해석 알고리즘의 경량 C 구현으로, tsserver/typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer를 포함한 주요 언어 서버와 구조적으로 영감을 받았으며 호환됨 (매개변수 바인딩, 반환 타입 추론, 제네릭 치환, JSX 컴포넌트 디스패치, 일반 JS 파일용 JSDoc 추론, PHP용 네임스페이스 + 트레이트 + 지연 정적 바인딩 해석, C#용 파일 범위 네임스페이스 + 레코드 + LINQ 메서드 구문, Java용 클래스 계층 + 오버로드 + 람다 해석, Kotlin용 확장 함수 + 범위 함수 해석, Rust용 트레이트 메서드 + UFCS 해석)
• RAM 우선 파이프라인: LZ4 압축, 인메모리 SQLite, 마지막에 단일 덤프. 이후 메모리 해제.

배포 및 운영

• 단일 정적 바이너리, 제로 인프라: SQLite 기반, ~/.cache/codebase-memory-mcp/에 유지
• 자동 동기화: 백그라운드 감시자가 파일 변경을 감지하고 자동으로 재인덱싱
• 라우트 노드: REST 엔드포인트가 일급 그래프 엔티티
• CLI 모드: codebase-memory-mcp cli searchgraph '{"namepattern": ".Handler."}'
• 사용 가능: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, go install

팀 공유 그래프 아티팩트

단일 압축 파일을 저장소에 커밋하면 팀원이 재인덱싱을 건너뜁니다.

.codebase-memory/graph.db.zst는 소스 옆에 위치하는 지식 그래프의 zstd 압축 스냅샷입니다. 인덱싱할 때 아티팩트가 작성되거나 새로고침됩니다. 팀원이 저장소를 클론하고 처음으로 codebase-memory-mcp를 실행하면 아티팩트가 압축 해제되고 증분 인덱싱이 로컬 diff를 채웁니다.

• 형식: SQLite 데이터베이스, 인덱스 제거, VACUUM INTO로 압축, zstd 1.5.7 압축 (일반적으로 8–13:1 비율)
• 두 가지 계층:
• 최상 (zstd -9 + 인덱스 제거 + VACUUM INTO) — 명시적 index_repository 시 작성
• 빠름 (zstd -3) — 감시자가 저지연 증분 업데이트를 위해 작성
• 부트스트랩: 로컬 DB가 없지만 아티팩트가 있는 경우, index_repository가 먼저 아티팩트를 가져온 다음 증분 인덱싱을 실행 — 전체 재인덱싱 비용 회피
• 병합 문제 없음: 첫 내보내기 시 merge=ours가 포함된 .gitattributes 줄이 자동 생성되므로 동시 편집이 바이너리 아티팩트에 충돌을 일으키지 않음
• 선택 사항: 원하지 않으면 커밋되지 않음. 모든 사람이 처음부터 재인덱싱하길 원한다면 .codebase-memory/를 .gitignore에 추가

결과는 graphify의 graphify-out/ 디렉토리와 정신적으로 유사하지만, 명시적인 2계층 내보내기, 무결성 검사 가져오기, 제로 병합 마찰을 갖춘 단일 압축 파일입니다.

작동 방식

codebase-memory-mcp는 구조적 분석 백엔드입니다 — 지식 그래프를 구축하고 쿼리합니다. LLM을 포함하지 않습니다. 대신 MCP 클라이언트(Claude Code 또는 MCP 호환 에이전트)가 인텔리전스 계층 역할을 합니다.

사용자: "ProcessOrder를 호출하는 것은?"

에이전트 호출: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: 그래프 쿼리 실행, 구조화된 결과 반환

에이전트: 호출 체인 제시

[...truncated...]