요약하자면: codebase-memory-mcp는 저장소를 영구적인 지식 그래프로 색인화하여 코딩 에이전트가 grep하고 파일을 읽는 대신 그래프에서 구조적 질문에 답하도록 합니다. 이 프로젝트는 그래프를 통해 약 3,400 토큰으로 다섯 가지 구조적 쿼리를 처리하는 반면, 파일별 탐색으로는 약 412,000 토큰이 소요되어 99.2%의 감소율을 보입니다. C로 작성되었으며, 런타임이나 API 키 없이 단일 네이티브 바이너리로 제공되고, 160개 이상의 언어를 지원하며, 전적으로 사용자 머신에서 실행됩니다. 2026년 9월 1일 현재 41,536개의 별을 받았고 MIT 라이선스입니다. 2026년 에이전트 툴링 물결에서 단 하나를 설치한다면 이것을 선택하세요.
이것은 2026년에 설치할 가치가 있는 다섯 가지 오픈 소스 AI 에이전트 도구에 대한 심층 분석 중 하나입니다.
에이전트에게 함수가 어디에서 호출되는지 물어보면 어떤 일이 발생하는지 지켜보세요. grep하고, 세 파일을 읽고, 다른 패턴으로 다시 grep하고, 네 파일을 더 읽습니다. 결국 세션이 끝나는 순간 잊어버릴 소스 코드로 컨텍스트를 채우느라 수만 개의 토큰을 소모한 후 정확하게 답변합니다.
그리고 후속 질문을 하면 에이전트는 이 모든 과정을 다시 반복합니다.
그 반복은 긴 세션에서 대부분의 사용량 제한을 소모하는 부분이며, 오후 내내 답변 품질이 저하되는 이유이기도 합니다. 파일 내용으로 가득 찬 컨텍스트 창은 추론할 공간이 부족합니다. codebase-memory-mcp는 동일한 방식으로 두 가지 문제를 모두 해결합니다.
무엇을 하는가
이 도구는 저장소를 함수, 클래스, 호출 체인, HTTP 경로 및 서비스 간 링크에 대한 영구적인 지식 그래프로 파싱한 다음, 해당 그래프에서 구조적 질문에 답합니다.
파싱은 160개 이상의 언어에 걸쳐 tree-sitter AST 분석을 통해 이루어지며, 하이브리드 LSP 계층이 README 배지에서 10가지로 분류하는 핵심 그룹(Python, JSX 및 TSX를 포함한 TypeScript 및 JavaScript 계열, PHP, C#, Go, C, C++, Java, Kotlin, Rust, Perl)에 의미론적 타입 해결을 추가합니다. 이 구분은 중요합니다. AST 파싱은 `save`라는 메서드가 호출되었음을 알려주지만, 타입 해결은 해당 메서드가 어느 클래스에 속하는지 알려줍니다.
그 결과는 검색, 호출 체인 추적, 아키텍처 개요, 영향 분석, 인덱스 커버리지 확인, 그래프에 대한 Cypher 쿼리, 데드 코드 탐지, 서비스 간 HTTP 연결, ADR 관리를 포괄하는 15가지 MCP 도구로 노출됩니다. Model Context Protocol을 사용하는 모든 클라이언트가 이 도구를 사용할 수 있으며, 프로젝트는 Claude Code, Codex, Cursor, Windsurf, OpenCode, Gemini CLI, Aider, Kilocode를 포함하여 45가지 지원되는 에이전트 인터페이스를 나열합니다.
수치
두 가지 독립적인 수치 세트가 있으며, 둘 다 주의 깊게 읽어볼 가치가 있습니다.
프로젝트 자체 측정: 다섯 가지 구조적 쿼리가 그래프를 통해 약 3,400 토큰을 소모한 반면, 파일별 grep 탐색으로는 약 412,000 토큰이 소모되었습니다. 이는 99.2% 감소이며, 동일한 답변에 대해 약 120배 적은 토큰이 사용된 것입니다.
학술 버전은 31개의 실제 저장소를 대상으로 평가된 사전 인쇄물인 Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP에 있습니다. 이 보고서에 따르면 파일별 탐색 대비 83%의 답변 품질, 10배 적은 토큰, 2.1배 적은 도구 호출이 기록되었습니다.
120배와 10배 사이의 차이는 솔직한 부분입니다. 120배는 그래프의 최적 사례인 다섯 가지 구조적 쿼리 수치입니다. 구조적 질문은 그래프의 목적과 정확히 일치하기 때문입니다. 10배는 31개 저장소에 걸쳐 더 넓은 혼합을 나타내며, 일상적인 사용에서 볼 수 있는 것에 더 가깝습니다. 둘 다 큰 수치입니다. 10배를 계획 기준으로 삼고, 그보다 좋은 결과는 이점으로 간주하십시오.
속도는 나머지 절반입니다. 75,000개 파일에 걸친 2,800만 줄의 Linux 커널을 색인화하는 데 3분이 걸립니다. 평균적인 저장소는 밀리초 단위로 색인화됩니다. 구조적 쿼리는 1밀리초 미만으로 응답합니다. 파이프라인은 LZ4 압축, 인메모리 SQLite, 융합된 Aho-Corasick 패턴 매칭을 사용하는 RAM 우선 방식이며, 색인화 후 메모리는 해제됩니다.
TypeScript나 Python 대신 C로 작성되었기 때문에 이러한 수치가 가능하며, 런타임을 설치할 필요가 없는 이유도 여기에 있습니다.
설치
macOS 및 Linux:
curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
Windows의 경우, 프로젝트가 권장하는 단계에 따라 설치하세요. 맹목적인 한 줄 명령 대신:
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
notepad install.ps1 # read it first
Unblock-File .\install.ps1
.\install.ps1
옵션에는 에이전트 설정 없이 바이너리만 설치하는 --skip-config와 사용자 지정 위치를 위한 --dir=<path>가 있습니다. 설치 프로그램은 설치된 코딩 에이전트를 자동으로 감지하고 문서화된 MCP 항목, 지침, 스킬, 클라이언트가 지원하는 경우 라이프사이클 훅을 작성합니다. macOS에서는 격리 속성을 제거하고 바이너리를 임시 서명하므로 수동으로 xattr 또는 codesign 작업을 할 필요가 없습니다.
그런 다음 에이전트를 다시 시작하고 프로젝트를 색인화하도록 지시하십시오.
첫날에 설정할 가치가 있는 두 가지 구성 플래그:
# index new projects automatically on first connection
codebase-memory-mcp config set auto_index true
codebase-memory-mcp config set auto_index_limit 50000
# graph visualization, built into the binary
codebase-memory-mcp --ui=true --port=9749
localhost:9749의 UI는 지식 그래프를 3D로 렌더링합니다. 이것은 몰랐던 구조를 발견하는 데 진정으로 유용하며, 인덱스가 예상한 것을 제대로 커버했는지 확인하는 좋은 건전성 검사 역할을 합니다.
여러 저장소에서 작업하는 경우, auto_watch false는 세션이 백그라운드 워처에 프로젝트를 등록하는 것을 방지하고, watcher_enabled false는 폴링 스레드를 완전히 끕니다. 두 번째 옵션은 데몬이 시작될 때 한 번 읽히므로, 변경 후에는 데몬을 중지해야 합니다.
실행 전에 확인할 두 가지 사항
두 가지 모두 프로젝트에 문서화되어 있어 좋은 신호이며, 둘 다 30초의 주의를 기울일 가치가 있습니다.
Microsoft Defender는 릴리스 바이너리를 Trojan:Script/Wacatac.B!ml로 플래그할 수 있습니다. 프로젝트는 이를 알려진 오탐으로 문서화하고 있으며, 일반적으로 62개 엔진 중 약 61개가 깨끗하게 나온다고 명시하고, 동일한 탐지 패밀리가 GitHub CLI, llama.cpp, Godot, 그리고 Microsoft 자체 Go 툴체인에도 영향을 미친다고 지적합니다. 모든 릴리스는 게시 전에 VirusTotal에서 스캔되며 릴리스 노트에는 결과 링크가 포함되어 있습니다. 이는 대부분의 프로젝트보다 투명한 태도이며, 근본적인 문제는 서명되지 않은 작은 네이티브 바이너리에 대한 잘 알려진 휴리스틱 문제입니다.
이 도구는 코드베이스를 읽고 에이전트 구성 파일에 씁니다. 이것이 바로 이 도구의 역할이며, 프로젝트는 이를 숨기지 않고 명확하게 명시하고 있습니다. 완화 조치도 확실합니다: 전체 소스 코드는 MIT 라이선스 하에 제공되며, 릴리스에는 OpenSSF Scorecard와 SLSA 레벨 3 출처가 포함되어 있고, 처리는 전적으로 로컬에서 이루어집니다. 프로젝트는 자체적으로 네트워크 요청을 하지 않으며, 백그라운드에서 업데이트를 확인하지 않고, 원격 서버에 정보를 보내지 않는다고도 밝히고 있습니다. 업데이트는 실행 중인 프로세스 내부가 아니라 바이너리 옆에 위치한 설치 스크립트에서 실행되며, 이는 README에서 상세히 설명된 의도적인 설계 선택입니다.
두 가지 모두에 대한 올바른 대응은 동일합니다. 설치 스크립트를 bash로 파이프하기 전에 읽어보고, 로컬 전용 주장이 중요하다고 생각되면 직접 확인하십시오. 많은 별점은 인기를 나타낼 뿐, 감사를 의미하지는 않습니다.
이것을 먼저 설치해야 하는 이유
현재 에이전트 물결의 다른 모든 도구는 워크플로우를 변경합니다. 페르소나는 프롬프트 방식에 변화를 주고, 병렬 작업 트리는 작업 구성 방식을 바꾸며, 웹 접근은 요청 내용을 바꿉니다.
이 도구는 작업 방식에 아무런 변화를 주지 않으면서도 모든 세션을 더 저렴하고 좋게 만듭니다. 새로운 습관을 배울 필요가 없습니다. 설치하고 프로젝트를 색인화하면 에이전트가 grep 루프에서 컨텍스트를 소모하는 것을 멈춥니다. 긴 리팩토링 과정에서 오후 2시에 한계에 도달하는 것과 하루 작업을 마치는 것의 차이는 미미하지 않습니다.
품질 효과는 저평가된 절반입니다. 파일을 읽는 데 400,000 토큰을 소비하는 에이전트는 실제로 문제에 대해 생각할 공간이 그만큼 적고, 세션 초기에 읽었던 내용을 기억하는 능력이 저하됩니다. 그래프에서 답변하면 컨텍스트가 자유롭게 유지됩니다. 동일한 원리가 도구가 해당 컨텍스트로 반환하는 내용에도 적용되는데, 이는 에이전트 도구 응답 컨텍스트 창의 주제이며, 에이전트 워크플로우에서 과도한 API 응답이 비싼 이유와 동일한 실패 지점입니다.
실제로 사용하게 될 도구들
15가지 MCP 도구는 배우기 많은 것처럼 들릴 수 있습니다. 실제로는 에이전트가 선택하기 때문에 아무것도 배울 필요가 없습니다. 중요한 것은 이제 어떤 질문이 저렴한 답변을 가졌는지 아는 것이므로, 그런 질문을 시작하면 됩니다.
- 영향 분석은 가장 가치가 높지만 가장 적게 사용되는 도구입니다. 함수 시그니처를 변경하기 전에 어떤 부분이 손상될지 물어보세요. 그래프는 리포지토리 전체의 모든 호출자를 1밀리초 미만으로 추적하며, grep 방식은 동적 디스패치를 놓치고 간접적인 모든 것을 포기합니다. 이는 “안전하다고 생각한다”를 목록으로 바꿔줍니다.
- 호출 체인 추적은 실행이 코드 조각에 실제로 어떻게 도달하는지 답해줍니다. 익숙하지 않은 리포지토리에서 유용하며, 진입점을 찾기 위해 다섯 개 파일을 거슬러 올라가며 읽는 것보다 훨씬 좋습니다.
- 아키텍처 개요는 에이전트가 전체 트리를 읽지 않고도 구조적 맵을 제공합니다. 이것은 알 수 없는 코드베이스에 온보딩하는 경험을 다르게 만들며, 읽기 전용 탐색 페르소나와 잘 어울립니다.
- 데드 코드 탐지는 아무것도 호출하지 않는 코드를 찾습니다. 정리 스프린트 전에 논쟁하는 대신 이 도구를 실행하세요.
- 서비스 간 HTTP 연결은 한 서비스의 호출을 다른 서비스의 핸들러로 추적합니다. 마이크로서비스 코드베이스에서 이것은 하나의 저장소를 이해하는 에이전트와 시스템 전체를 이해하는 에이전트의 차이입니다. 또한, 아래에서 설명할 계약(contract) 격차가 정확히 드러나는 부분이기도 합니다.
- Cypher 쿼리는 비상 탈출구입니다. 다른 도구들이 다루지 않는 특정 항목을 원할 때 그래프에 직접 쿼리할 수 있습니다.
실질적인 변화는 프롬프트 방식에 있습니다. 예전에는 50,000 토큰과 2분의 비용 때문에 피했던 질문들이 이제는 거의 무료이므로, 주저하지 말고 질문하세요. 모든 리팩토링 전에 “이것을 무엇이 호출하는가?”, 디버깅 전에 “이 엔드포인트의 요청 경로는 어떻게 생겼는가?”와 같은 질문을 할 수 있습니다. 이 도구는 호기심의 경제학을 변화시키며, 이는 어떤 단일 기능보다 중요합니다.
그래프가 아는 것과 모르는 것
여기에는 한계가 있으며, 이 도구를 과신하기 전에 이해할 가치가 있는 명확한 한계입니다.
그래프는 코드로부터 구축됩니다. 그래프는 코드가 무엇인지 압니다. 15가지 도구 중에는 한 서비스의 호출을 다른 서비스의 핸들러로 추적하는 서비스 간 HTTP 연결 기능이 있으며, 이는 에이전트가 알아야 할 진정으로 유용한 정보입니다.
이 도구가 알려줄 수 없는 것은 계약(contract)이 무엇을 말하는지입니다. /v1/invoices/{id} 경로가 존재하고 어떤 함수가 이를 처리하는지는 압니다. 하지만 멱등성 키가 재사용될 때 엔드포인트가 다른 오류 엔벨로프와 함께 409를 반환하는지, status 필드에 정확히 다섯 가지 유효한 값이 있는지, 커서가 오프셋이 아닌 불투명한 값인지, 또는 필드가 사용 중단되어 다음 분기에 사라지는지 등은 모릅니다. 이 중 어느 것도 핸들러 소스에서 도출할 수 없는데, 대부분 구현보다는 합의에 관한 것이기 때문입니다.
따라서 완벽한 구조적 기억을 갖춘 에이전트도 여전히 계약을 추측합니다. 추론된 형태에 맞춰 클라이언트를 작성하고, 직접 만든 목(mock)을 대상으로 테스트하며, 스테이징 단계까지 모든 것이 정상으로 보입니다.
이것이 Apidog와 이와 같은 도구가 겹치기보다는 서로 잘 맞는 이유입니다:
- 그래프는 "어디에"를 답합니다. 어떤 핸들러, 어떤 호출 체인, 이 시그니처가 변경되면 무엇이 깨지는지.
- 사양은 "무엇을" 답합니다. 실제 스키마, 실제 상태 코드, 실제 오류 엔벨로프를 재구성하는 대신 에이전트가 직접 읽습니다. 그 이유는 OpenAPI 사양을 에이전트 도구로 사용하는 것에 있습니다.
- 목은 사양으로부터 생성됩니다. 에이전트가 위조할 생각조차 하지 못할 오류 분기까지 포함해서 말이죠.
- 계약 테스트는 CI에서 실패합니다. 구현과 합의가 다를 때, 이는 API 변경이 AI 에이전트를 망가뜨릴 때 발생하는 실패 모드에 설명된 바와 같습니다.
여기에는 만족스러운 대칭이 있습니다. codebase-memory-mcp는 구조적 질문에 답하기 위해 소스 코드를 읽는 것이 비용이 많이 들고 신뢰할 수 없기 때문에 존재합니다. 계약을 추론하기 위해 소스 코드를 읽는 것도 마찬가지이며, 그 답은 동일합니다. 질문에 맞는 형태로 한 번만 색인화하는 것입니다. 아무도 문서화하지 않은 형태로 API 클라이언트를 작성하는 에이전트가 있다면 Apidog를 다운로드하세요. 관련: 에이전트를 위한 API 도구 스키마 설계 및 AI 에이전트 시대에도 API 도구가 필요한가요.
코드의 기억은 작업의 기억이 아니다
두 번째 한계는 조직적 측면입니다.
색인(index)은 한 머신의 캐시 디렉토리에 한 계정으로 저장됩니다. 이는 로컬 Claude Code, Codex, OpenCode 세션 간에 조정 데몬을 통해 공유되며, 이는 훌륭한 엔지니어링이지만 해당 머신의 경계에서 멈춥니다.
더 중요하게는, 이 그래프는 코드베이스의 기억이지 작업의 기억이 아닙니다. 재시도 헬퍼가 결제 클라이언트를 호출한다는 것은 알려줄 수 있습니다. 하지만 왜 7월에 백오프가 변경되었는지, 누가 그렇게 결정했는지, 대안이 무엇이었는지, 또는 누군가가 이를 검토했는지 등은 알려줄 수 없습니다. 그러한 이력은 이미 사라진 터미널 세션에 존재했습니다.
팀은 이를 이상한 간극으로 느낍니다. 에이전트는 팀의 어떤 사람보다 코드에 대한 기억력이 뛰어나지만, 코드를 생성한 결정에 대해서는 전혀 기억하지 못합니다.
Sharkly는 프롬프트 대신 태스크를 영구적인 기록으로 만들어 나머지 절반을 커버합니다:
- 작업은 태스크로 존재하며, 에이전트의 출력은 답장할 수 있는 댓글로 나타납니다. 진행 상황과 도구 호출은 태스크로 스트리밍됩니다. 추론은 세션 종료 후에도 유지됩니다.
- 에이전트는 저장된 구성입니다. 지침, 런타임, 스킬, 저장소, 환경을 포함합니다. 에이전트가 인덱스, 사양 및 올바른 권한을 갖는 설정은 머신별로 다시 구축하는 대신 재사용됩니다.
- 실행은 자체적으로 제공됩니다. 노트북, 서버 또는 컨테이너가 될 수 있는 컴퓨터를 연결하면 Sharkly는 이미 설치된 런타임을 사용합니다. 이는 인덱스가 머신별로 존재하기 때문에 직접적으로 관련이 있습니다. 색인된 저장소를 어떤 컴퓨터가 가지고 있는지 아는 것은 따뜻한 그래프와 3분간의 콜드 스타트 사이의 차이입니다.
- 저장소 작업은 태스크별로 별도의 작업 트리에서 실행됩니다. 따라서 동일한 저장소에 대한 병렬 태스크가 충돌하지 않습니다.
- 백로그의 태스크는 실행을 시작하지 않습니다. 따라서 작업은 아무것도 실행되기 전에 준비됩니다.
- 팀이 이미 이해하는 구조: Jira 동기화를 포함한 스페이스, 프로젝트, 스프린트, 태스크.
코드 기억력과 작업 기억력이 결합된 것입니다. 한 도구는 에이전트에게 저장소에 대한 기억을 주고, 다른 도구는 팀에게 에이전트가 그 안에서 수행한 작업에 대한 기억을 제공합니다.
자주 묻는 질문
- Cursor, Codex, OpenCode와도 작동하나요, 아니면 Claude Code만 되나요? 이것은 MCP 서버이므로 모든 MCP 클라이언트에서 작동합니다. 프로젝트는 45가지 지원되는 에이전트 인터페이스를 나열하며 설치 프로그램은 사용자에게 설치된 것을 자동으로 감지합니다. API 작업을 위한 에이전트 클라이언트를 고려하고 있다면, Cursor와 Copilot의 API 클라이언트에 대한 우리의 분석을 참조하세요.
- 제 코드가 제 머신을 벗어나나요? 아니요. 처리는 전적으로 로컬에서 이루어지며, 프로젝트는 자체적으로 네트워크 요청을 하지 않고 백그라운드에서 업데이트를 확인하지 않는다고 명시하고 있습니다. 믿음으로 받아들이기보다 직접 확인하고 싶다면 소스는 MIT 라이선스입니다.
- 99% 토큰 절감 효과가 제 저장소에도 현실적인가요? 99.2% 수치는 그래프의 가장 강력한 사례인 다섯 가지 구조적 쿼리입니다. 31개 저장소에 걸쳐 동료 검토된 수치는 10배 적은 토큰과 2.1배 적은 도구 호출입니다. 10배를 기준으로 계획하십시오. 구조적 질문이 많은 작업은 이 수치를 능가할 것입니다.
- 얼마나 큰 저장소를 처리할 수 있나요? 명시된 최대 사례는 2,800만 줄과 75,000개 파일로 구성된 Linux 커널을 3분 만에 처리하는 것입니다. 기본 자동 색인 제한은 50,000개 파일로 구성 가능합니다. 일반적인 애플리케이션 저장소는 밀리초 단위로 색인화됩니다.
- 왜 Defender가 이를 플래그하나요? 작고 서명되지 않은 네이티브 바이너리에서 발생하는 알려진 머신러닝 오탐입니다. 프로젝트는 이를 문서화하고 있으며, 62개 엔진 중 약 61개가 깨끗하게 나온다고 명시하고, 각 릴리스별 VirusTotal 결과를 링크합니다. 동일한 탐지 패밀리가 GitHub CLI와 Microsoft 자체 Go 툴체인에도 영향을 미칩니다.
- 이것이 코드 읽기를 대체하나요? 구조적 질문에 대해서는 그렇습니다. 이는 에이전트가 묻는 대부분의 질문입니다. 동작, 예외 사항, 의도에 대해서는 아닙니다. 그리고 API가 무엇을 반환하는지에 대해서는 둘 중 어느 것도 아닌 사양이 필요하며, 이는 AI 에이전트 시대에도 API 도구가 필요한가라는 질문에서 주장하는 바입니다.
마무리
이것은 2026년 에이전트 물결에서 가장 화려하지 않은 도구이지만 최고의 투자 수익률을 제공합니다. 워크플로우 변경도, 새로운 습관도 필요 없으며, 단일 네이티브 바이너리로, 에이전트가 grep할 필요 없는 질문에 답변하는 데 소모하는 토큰을 측정 가능한 수준으로 대폭 줄여줍니다. 여러 에이전트가 동시에 실행될 때 가장 큰 효과를 발휘하며, 이는 Orca의 경우에도 마찬가지입니다. 이 도구를 설치하고 프로젝트를 색인화하고 auto_index를 설정한 다음, 그래프 뷰어를 한 번 열어 무엇을 구축했는지 확인하십시오.
그런 다음 두 가지 한계를 명확히 이해하십시오. 그래프는 코드가 어디에 있는지는 알지만, API가 무엇을 약속하는지는 모릅니다. 이 간극을 Apidog가 사양, 목(mock), 테스트 스위트로 메웁니다. 그리고 이 도구는 저장소를 기억하지 작업을 기억하지는 않는데, 이 간극을 Sharkly가 프롬프트 대신 태스크를 기록으로 만들어 메웁니다.
코드에 대한 완벽한 기억력은 강력한 기반입니다. 하지만 무엇이 진실인지 또는 무엇이 결정되었는지 아는 것과는 다릅니다.