AI 코딩 에이전트가 전체 레포지토리를 grep하게 만들지 마세요 — codebase-memory-mcp를 사용해 보세요

만약 당신이 Claude Code, Codex CLI, Gemini CLI, Cursor, Zed, Aider 등 어떤 것이든 AI 코딩 에이전트를 사용하고 있다면, 함수를 누가 호출하는지 또는 라우트(route)가 어디에 정의되어 있는지 알아내기 위해 수만 개의 토큰을 낭비하는 모습을 본 적이 있을 것입니다. 에이전트는 grep을 수행하고, 파일을 읽고, 다시 grep을 하고, 더 많은 파일을 읽습니다. 결국 질문에 답은 하지만, 이를 위해 엄청난 양의 토큰과 여러 번의 도구 호출(tool calls)이 소모됩니다.

codebase-memory-mcp는 바로 이 문제를 해결하기 위해 구축된 오픈 소스 MCP 서버입니다. 이 서버는 함수, 클래스, 호출 체인(call chains), HTTP 라우트, 서비스 간 링크 등 코드베이스를 지속 가능한 지식 그래프(knowledge graph)로 인덱싱하여, 에이전트가 파일 시스템을 일일이 읽는 대신 구조적인 질문을 직접 던질 수 있게 해줍니다.

이것이 당신에게 실제로 주는 이점은 다음과 같습니다.

한 문단 요약

단일 정적 바이너리(static binary)를 설치하기만 하면 됩니다. 에이전트에게 "이 프로젝트를 인덱싱해줘"라고 말하세요. 몇 초에서 몇 분 후(네, 2,800만 줄의 코드로 구성된 Linux 커널조차 약 3분이 걸립니다), 에이전트는 수십 개의 파일을 grep하고 읽는 대신 "ProcessOrder를 호출하는 것이 무엇인가요?" 또는 "이 서비스의 아키텍처를 보여줘"와 같은 질문을 던지고 1밀리초 미만 안에 답변을 얻을 수 있습니다. Docker도, API 키도, 별도로 실행할 데이터베이스도 필요 없습니다. 그저 MCP와 통신하는 바이너리 하나면 충분합니다.

이것이 중요한 이유: 토큰 계산법

이 수치는 당신의 주의를 끌기에 충분합니다. 프로젝트 자체 벤치마크에 따르면, 일반적인 5개의 구조적 쿼리를 수행할 때 codebase-memory-mcp를 통하면 약 3,400 토큰이 소모되는 반면, 파일별로 grep 및 읽기 탐색을 수행하면 약 412,000 토큰이 소모됩니다. 이는 99%의 감소율입니다. 탐색에 소모되는 컨텍스트(context)가 줄어든다는 것은 에이전트가 실제로 당신의 문제를 추론하는 데 사용할 수 있는 예산이 더 많이 남는다는 것을 의미하며, 눈에 띄게 더 빠르고 저렴한 세션을 보장합니다.

실제로 하는 일

실제로 하는 일

핵심적으로 codebase-memory-mcp는 또 다른 LLM 래퍼(wrapper)가 아니라, 구조적 분석 백엔드(structural analysis backend)입니다. 이 도구는 tree-sitter를 사용하여 코드를 파싱하고, 모든 요소가 어떻게 연결되는지에 대한 그래프(graph)를 구축하며, 14개의 MCP 도구를 통해 해당 그래프를 노출합니다. 여러분의 에이전트는 여전히 두뇌 역할을 수행하지만, 매 세션마다 코드베이스(codebase)를 처음부터 다시 탐색해야 하는 수고를 덜게 됩니다.

전형적인 상호작용은 다음과 같습니다:

사용자: "ProcessOrder를 호출하는 게 뭐야?"
에이전트 호출: trace_call_path(function_name="ProcessOrder", direction="inbound")
codebase-memory-mcp: 그래프 쿼리(graph query)를 실행하고 구조화된 결과 반환
...

추가적인 LLM, 추가적인 API 키, 추가적인 비용 계층이 필요하지 않습니다. 여러분이 이미 비용을 지불하고 있는 에이전트가 자연어를 그래프 쿼리로 변환하는 작업을 수행합니다.

일상적으로 정말 중요한 기능들

거대한 레포지토리(repo)에서도 빠릅니다. RAM 우선 인덱싱 파이프라인(LZ4 압축, 인메모리(in-memory) SQLite, 마지막에 단일 덤프 수행)을 사용합니다. Apple M3 Pro에서 벤치마크를 수행한 결과, Linux 커널은 약 3분 만에 인덱싱을 완료하며, Django와 같은 중간 규모의 프로젝트는 약 6초가 소요됩니다. 인덱싱이 완료되면 메모리는 OS로 다시 반환됩니다.

155개의 언어를 지원합니다. 모든 언어에 대한 tree-sitter 문법(grammars)이 바이너리에 직접 포함되어 있어 별도로 설치할 것이 없습니다. Go, C, C++, 그리고 TypeScript/JavaScript/JSX/TSX 제품군은 추가로 LSP 스타일의 하이브리드 타입 해석(hybrid type resolution) 기능을 제공합니다. 여기에는 적절한 매개변수 바인딩(parameter binding), 반환 타입 추론(return-type inference), 제네릭 치환(generic substitution), 그리고 일반 JS 파일을 위한 JSDoc 추론이 포함됩니다.

11개의 코딩 에이전트에 자동으로 연결됩니다. 설치 프로그램을 실행하면 Claude Code, Codex CLI, Gemini CLI, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, Kiro를 자동으로 감지하며, 설치된 에이전트에 맞춰 MCP 항목, 지침 파일(instruction files), 훅(hooks)을 구성합니다.

단순한 애플리케이션 코드 그 이상을 이해합니다. Dockerfile, Kubernetes 매니페스트(manifests), Kustomize 오버레이(overlays) 또한 그래프 노드(graph nodes)로 인덱싱되며 이들 간의 상호 참조(cross-references)가 생성됩니다. 이는 에이전트가 애플리케이션 로직뿐만 아니라 인프라(infrastructure)에 대해서도 추론해야 할 때 매우 유용합니다.

데드 코드(dead code)를 찾고, 영향 범위(blast radius)를 추적하며, 유사 코드(near-duplicates)를 감지합니다. 단순한 검색을 넘어, 기능적 모듈을 발견하기 위한 Louvain 커뮤니티 탐지(community detection), 커밋되지 않은 변경 사항에 대한 리스크를 분류하는 git-diff 영향 매핑(impact mapping), 엔트리 포인트(entry points)를 제외한 데드 코드 감지, 그리고 MinHash 기반의 유사 클론(near-clone) 감지 기능을 제공합니다.

그래프를 시각화할 수 있습니다. 선택 사항인 UI 바이너리 변체(variant)에는 내장된 3D 그래프 시각화 도구가 포함되어 있으며, MCP 서버와 함께 백그라운드 스레드로 실행되어 브라우저의 localhost:9749에서 열 수 있습니다.

팀원 모두가 각자 따로 재인덱싱(reindex)할 필요가 없습니다. 소스 코드와 함께 .codebase-memory/graph.db.zst 아티팩트(artifact)를 커밋할 수 있는데, 이는 그래프의 zstd 압축 스냅샷(snapshot)입니다. 팀원이 저장소를 클론(clone)하고 처음으로 인덱서(indexer)를 실행하면, 전체 재인덱싱 대신 해당 스냅샷을 가져온 뒤 로컬에서 증분 차이(incremental diff)만 수행합니다. 이는 완전히 선택 사항이며, 모든 사람이 새로 시작하기를 원한다면 gitignore에 추가하여 제외할 수도 있습니다.

시작하기

macOS 또는 Linux에서의 한 줄 설치 방법:

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

그래프 시각화를 포함하고 싶다면 끝에 -s -- --ui를 추가하세요.

Windows에서는 install.ps1을 다운로드하여 PowerShell에서 실행하세요. 모든 것을 먼저 검토하고 싶다면 수동 경로도 있습니다: 최신 릴리스(latest release)에서 플랫폼별 아카이브를 다운로드하여 압축을 풀고, 포함된 설치 스크립트를 실행하면 됩니다.

설치가 완료되면 코딩 에이전트를 재시작하고 다음과 같이 말하기만 하면 됩니다:

"Index this project"

이것으로 설정이 끝납니다. 새 프로젝트를 열 때마다 인덱싱이 자동으로 수행되기를 원한다면, 자동 인덱싱(auto-index)을 켜세요:

codebase-memory-mcp config set auto_index true

초기 인덱싱 이후에는 백그라운드 워처(watcher)가 git 변경 사항에 맞춰 그래프를 동기화하므로, 커밋할 때마다 수동으로 재인덱싱할 필요가 없습니다.

질문할 수 있는 내용들

프로젝트 인덱싱이 완료되면, 14개의 MCP 도구(tools)를 통해 다음과 같은 작업들을 수행할 수 있습니다:

• search_graph — 레이블(label), 이름 패턴(name pattern), 파일 패턴(file pattern) 또는 차수 필터(degree filters)를 이용한 구조화된 검색
• trace_call_path — 함수를 호출하는 대상과 함수가 호출하는 대상을 최대 깊이 5까지 보여주는 BFS(너비 우선 탐색) 트래버설(traversal)
• get_architecture — 언어, 패키지, 엔트리 포인트(entry points), 라우트(routes), 핫스팟(hotspots) 및 클러스터(clusters)에 대한 단일 호출 개요
• detect_changes — 현재 git diff를 영향을 받는 심볼(symbols)에 매핑하고 위험 등급(risk classification) 분류
• query_graph — Cypher 스타일의 쿼리, 예: MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name
• semantic_query — 내장된 임베딩(embeddings)을 사용하여 전체 그래프에 대해 벡터 검색(vector search) 수행, API 키 불필요
• manage_adr — 아키텍처 결정 기록(Architecture Decision Records, ADR)에 대한 CRUD 작업, 설계 결정 사항이 세션 간에 유지되도록 지원
• get_code_snippet, search_code, ingest_traces 및 기타 여러 도구

스크립트를 작성하고 싶다면 모든 기능을 명령줄(command line)에서 직접 호출할 수도 있습니다:

codebase-memory-mcp cli search_graph '{"name_pattern": ".*Handler.*", "label": "Function"}'
codebase-memory-mcp cli trace_call_path '{"function_name": "Search", "direction": "both"}'

신뢰 및 보안에 대하여

전체 코드베이스를 읽는 도구라면 당연히 가질 수 있는 의문이 있습니다. 모든 릴리스 바이너리는 배포 전 VirusTotal에서 70개 이상의 안티바이러스 엔진으로 스캔되며, gh attestation verify로 검증 가능한 SLSA 레벨 3 빌드 출처(build provenance)를 보유하고, Sigstore cosign으로 서명되었으며, SHA-256 체크섬(checksums)을 함께 제공합니다. 런타임 의존성(runtime dependencies)은 전혀 없습니다. 모든 라이브러리는 컴파일 시점에 벤더링(vendored)되므로 걱정해야 할 전이적 공급망(transitive supply chain) 문제가 없습니다. 모든 처리는 로컬에서 이루어지며, 코드는 사용자의 컴퓨터를 떠나지 않습니다.

사용해야 할까요?

만약 에이전트 세션이 반복적인 파일 탐색으로 인해 컨텍스트 (context)를 과도하게 소모하고 있거나, "이게 어디서 사용되지?"라는 질문이 끊이지 않는 대규모 모노레포 (monorepo)에서 작업하고 있다면, 이것은 적은 노력으로 높은 효율을 낼 수 있는 설정 추가 방법입니다. 단일 바이너리 (single binary) 형태이며, 설치는 명령어 하나로 끝납니다. 최악의 경우라도 그냥 삭제하면 원래 상태로 돌아갈 뿐입니다. codebase-memory-mcp uninstall 명령어를 사용하면 바이너리나 데이터베이스를 건드리지 않고 설정, 훅 (hooks), 지침 (instructions)을 깔끔하게 제거합니다.

더 자세히 파고들거나 실행 전에 소스 코드를 확인하고 싶다면 저장소는 여기 있습니다: github.com/DeusData/codebase-memory-mcp