길리랩blog

codebase-memory-mcp로 코드 지식 그래프를 구축하는 방법

codebase-memory-mcp의 지식 그래프 인덱싱 구조와 MCP 도구, 증분 업데이트, AI 코딩 에이전트 통합 방법을 다룬다.

2026-08-14 · 최초 발행 2026-08-02

텍스트 검색만으로는 코드 구조를 따라갈 수 없다

2026년 현재 AI 에이전트 기반 코딩 도구가 빠르게 확산되고 있지만, 대규모 코드베이스를 정확히 이해하는 일은 여전히 병목으로 남아 있다. 파일이나 코드 스니펫 단위의 분석은 수십만 줄 이상인 프로젝트에서 한계가 뚜렷하다. LLM의 컨텍스트 윈도우가 유한하므로 전체 코드를 한 번에 넣어 구조를 파악하게 할 수도 없다.

임베딩 유사도에 의존하는 RAG(Retrieval-Augmented Generation) 역시 구조적 질문에는 약하다. 특정 API 함수를 호출하는 모든 경로를 찾거나, 한 클래스를 변경했을 때 영향을 받는 모듈을 추적하는 작업은 텍스트가 얼마나 비슷한지만으로 정확히 처리하기 어렵다.

codebase-memory-mcp는 이 문제를 코드베이스 전체의 지식 그래프(Knowledge Graph)로 다룬다. 함수·클래스·변수·모듈 같은 심볼은 노드가 되고, 호출·임포트·상속·구현 관계는 엣지가 된다. AI 에이전트는 필요한 파일을 무작정 수집하는 대신 그래프를 질의하며 코드 구조를 탐색할 수 있다.

소스 코드가 MCP 도구가 되기까지

codebase-memory-mcp의 처리 과정은 파싱, 심볼 추출, 그래프 구성, MCP 도구 노출로 이어진다. 코드 변경이 발생하면 증분 인덱싱 엔진이 같은 그래프 빌더를 통해 영향을 받은 부분을 갱신한다.

⤢✕코드베이스 소스파싱 레이어tree-sitter AST 파싱Language Server ProtocolImport/Export 분석심볼 추출 엔진함수/클래스/변수 심볼모듈/패키지 심볼타입 정의 심볼지식 그래프 빌더호출 그래프 엣지의존성 그래프 엣지상속/구현 엣지그래프 DB 인덱스MCP 도구 레이어symbol_lookup 도구find_callers 도구dependency_graph 도구impact_analysis 도구AI 에이전트코드 변경 감지증분 인덱싱 엔진

AST와 LSP를 함께 사용하는 파싱

파싱 레이어는 소스 코드를 구조화된 표현으로 바꾼다. tree-sitter를 이용해 Python, TypeScript, JavaScript, Go, Rust, Java 등 주요 언어의 AST(Abstract Syntax Tree)를 만들고, LSP(Language Server Protocol)에서 얻은 타입 정보와 심볼 해석 결과를 보강한다. 단순히 문자열을 나누는 것이 아니라 각 언어의 시맨틱을 반영하는 분석 단계다.

심볼을 고유한 개체로 식별하기

AST에서는 함수, 클래스, 메서드, 변수, 상수, 타입 별칭, 인터페이스를 추출한다. 각 심볼은 FQN(Fully Qualified Name)으로 식별하며 파일 경로, 라인 번호, public/private 가시성, 언어별 메타데이터를 함께 기록한다.

코드 관계를 그래프 엣지로 변환하기

추출한 심볼 사이에는 다음 관계를 설정한다.

  • CALLS: 함수 A가 함수 B를 호출한다.
  • IMPORTS: 모듈 A가 모듈 B를 임포트한다.
  • INHERITS: 클래스 A가 클래스 B를 상속한다.
  • IMPLEMENTS: 클래스 A가 인터페이스 B를 구현한다.
  • USES_TYPE: 함수 A가 타입 B를 사용한다.
  • DEFINED_IN: 심볼이 특정 모듈에 정의되어 있다.

이 관계가 호출 그래프와 의존성 그래프의 기반이 된다. 구축된 그래프는 MCP(Model Context Protocol) 도구 레이어를 통해 AI 에이전트에 노출된다.

에이전트가 코드 구조를 질의하는 방식

symbol_lookup은 특정 심볼의 정의 위치와 타입, 문서 주석, 연관 심볼을 반환한다. 에이전트는 함수를 찾기 위해 여러 파일을 순차적으로 읽지 않고도 정의와 시그니처를 확인할 수 있다.

{
  "tool": "symbol_lookup",
  "input": { "name": "UserAuthService.validateToken" },
  "output": {
    "fqn": "src/auth/UserAuthService.validateToken",
    "file": "src/auth/UserAuthService.ts",
    "line": 142,
    "signature": "(token: string) => Promise<AuthResult>",
    "doc": "JWT 토큰 유효성 검증. 만료·서명 오류 시 AuthError throw.",
    "related": ["AuthResult", "AuthError", "JwtService.verify"]
  }
}

find_callers는 해당 함수를 호출하는 모든 함수를, find_callees는 해당 함수가 호출하는 모든 함수를 찾는다. 리팩토링 전에 진입 경로와 후속 호출을 함께 확인할 때 필요한 질의다.

dependency_graph는 모듈의 직접·간접 의존성을 반환한다. 순환 의존성을 찾거나 계층 사이의 경계 위반을 점검하는 데 쓸 수 있다. impact_analysis는 심볼을 변경했을 때 영향을 받는 심볼과 파일을 추적하므로 수정 범위를 산정하는 데 활용된다.

전체 재인덱싱을 피하는 변경 반영

대규모 코드베이스를 변경할 때마다 처음부터 인덱싱하면 비용이 커진다. codebase-memory-mcp는 파일 시스템 변경 감지(inotify/FSEvents)와 git diff 분석을 결합한 증분 인덱싱(Incremental Indexing)을 제공한다.

변경된 파일만 다시 파싱한 뒤 관련 그래프 노드와 엣지를 선택적으로 갱신한다. 이를 통해 10만 줄 이상의 코드베이스에서도 변경 반영 지연이 수 초 이내로 유지된다. CI/CD에서는 PR 머지 이벤트에 훅을 연결해 그래프 업데이트를 자동화할 수 있다.

초기 인덱싱 범위와 품질 관리

처음부터 전체 코드베이스를 대상으로 삼으면 시간과 리소스 부담이 커질 수 있다. AI 에이전트가 자주 접근하는 핵심 모듈을 우선 선택하고, 모노레포라면 패키지 단위로 범위를 나누는 방식이 적합하다.

인덱싱을 실행할 때는 병렬 파싱 워커 수를 CPU 코어 수에 맞춘다. 100만 줄 규모 코드베이스의 초기 인덱싱에는 약 15~30분이 소요된다. 작업이 끝나면 심볼 커버리지 리포트에서 해석하지 못한 심볼의 비율을 확인하며, 권장 기준은 5% 이하다.

Claude Code, Cursor, Copilot Chat 같은 AI 코딩 도구와 통합하면 프롬프트 컨텍스트도 달라진다. 파일 전체를 넣는 대신 태스크와 관련된 그래프 질의 결과를 전달할 수 있다. 컨텍스트 토큰 소비가 평균 40~60% 감소하면서도 관련도는 오히려 높아지는 효과가 보고된다.

CI/CD에서 그래프를 계속 최신 상태로 유지하기

GitHub Actions, GitLab CI, Jenkins 같은 CI/CD 플랫폼에서는 코드 변경 목록을 전달해 지식 그래프를 업데이트할 수 있다. 다음은 GitHub Actions 연동 예시다.

# .github/workflows/update-codebase-graph.yml
on:
  push:
    branches: [main, develop]
jobs:
  update-graph:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2
      - name: Update codebase knowledge graph
        run: |
          npx codebase-memory-mcp update \
            --changed-files "$(git diff --name-only HEAD~1 HEAD)" \
            --server-url ${{ secrets.CMM_SERVER_URL }}

도입 효과는 컨텍스트 정확도(Context Precision), 리팩토링 완전성(Refactoring Completeness), 첫 시도 성공률(First-Attempt Success Rate)로 측정할 수 있다. 컨텍스트 정확도는 수집된 심볼 중 실제 태스크와 관련된 비율이고, 리팩토링 완전성은 변경 영향을 받는 파일을 빠짐없이 식별한 비율이다. 첫 시도 성공률은 에이전트가 생성한 첫 번째 코드가 컴파일과 테스트를 통과한 비율을 뜻한다.

초기 도입 사례에서는 리팩토링 완전성이 기존 RAG 대비 28~45% 향상된 결과가 보고되었다.

임베딩 인덱싱과 AST 파싱 사이에서 비교하기

항목 codebase-memory-mcp GitHub Copilot 인덱싱 tree-sitter 직접 파싱
인덱싱 방식 지식 그래프 (그래프 DB) 임베딩 벡터 + 파일 청크 AST 파싱만 (그래프 없음)
호출 그래프 지원 완전 지원 부분 지원 (파일 내) 미지원
크로스 파일 관계 완전 추적 임베딩 유사도 의존 미지원
증분 업데이트 실시간 (파일 단위) 백그라운드 배치 수동 재파싱 필요
MCP 통합 네이티브 지원 MCP 미지원 별도 구현 필요
프라이버시 온프레미스 가능 클라우드 전송 필수 온프레미스
다국어 지원 12개 언어 주요 언어 지원 언어별 파서 필요
초기 설정 복잡도 중 낮음 낮음

GitHub Copilot 인덱싱은 설정이 간단하지만 클라우드 전송이 필수이고, 코드 구조보다 텍스트 유사도에 의존한다. 금융·의료처럼 보안 규제가 엄격한 환경에서는 적용이 제한된다.

tree-sitter를 직접 사용하면 빠르고 가볍게 AST를 얻을 수 있다. 다만 파일 간 관계를 추적하는 그래프가 없으므로 코드베이스 전체의 의존 구조를 이해하는 데는 한계가 있다. 개별 파일 분석이나 신택스 하이라이팅에는 적합하지만 대규모 의존성 분석에는 부족하다.

codebase-memory-mcp는 초기 설정 복잡도가 다소 높은 대신 그래프 기반의 구조 탐색과 MCP 네이티브 통합을 제공한다. 100만 줄 이상의 모노레포나 엄격한 보안 요구사항이 있는 엔터프라이즈 환경에서 이 차이가 두드러진다.

정적 분석이 닿지 못하는 영역

Python이나 Ruby 같은 동적 언어의 런타임 바인딩은 정적 분석만으로 완전히 포착하기 어렵다. 메타프로그래밍과 리플렉션을 폭넓게 사용하는 코드베이스에서도 심볼 커버리지가 낮아질 수 있다.

그래프 DB가 사용하는 초기 메모리도 고려해야 한다. 100만 줄 코드베이스에는 약 2~4GB의 RAM이 필요하다. 향후 버전에서는 압축 그래프 표현과 온디맨드 서브그래프 로딩으로 이 문제를 완화할 계획이다.

로드맵에는 코드 의미론적 분석(Semantic Analysis)과 런타임 프로파일링 데이터를 결합하는 하이브리드 인덱싱, 여러 저장소를 연결하는 멀티레포 연합 그래프(Federated Graph) 지원이 포함되어 있다.

codebase-memory-mcp의 역할은 코드 검색 결과를 더 많이 가져오는 데 그치지 않는다. 심볼의 위치와 관계를 그래프로 제공해 AI 에이전트가 호출 경로, 의존성, 변경 영향을 구조적으로 추적하게 한다. 코드베이스 지식 그래프 인덱싱은 컨텍스트 품질과 리팩토링 정확도를 높이면서 온프레미스 운영을 통해 보안 요구사항에도 대응할 수 있는 AI 코딩 인프라다.

Sources

MCP지식 그래프코드 인텔리전스AI 코딩 에이전트증분 인덱싱