AI 에이전트 토큰 비용 99% 절감 방법

codebase-memory-mcp: AI 코딩 에이전트의 코드베이스 기억 만들기

요약하자면: codebase-memory-mcp는 저장소를 영구적인 지식 그래프로 색인화해 코딩 에이전트가 grep과 파일 탐색 대신 구조적 질문에 답하도록 합니다. 프로젝트 자체 측정에 따르면 그래프를 사용한 다섯 가지 구조적 쿼리는 약 3,400 토큰을 사용한 반면, 파일별 탐색은 약 412,000 토큰을 사용해 99.2% 감소했습니다. C로 작성된 단일 네이티브 바이너리이며 런타임이나 API 키가 필요 없고, 160개 이상의 언어를 지원하며, 모든 처리가 사용자 머신에서 이루어집니다. 2026년 9월 1일 기준 41,536개의 별을 받았고 MIT 라이선스를 사용합니다. 2026년 에이전트 툴링 물결에서 하나만 설치한다면 우선 고려할 만한 도구입니다.

오늘 Apidog 사용해 보기

이 글은 2026년에 설치할 가치가 있는 다섯 가지 오픈 소스 AI 에이전트 도구에 대한 심층 분석의 일부입니다.

grep 기반 탐색의 문제

에이전트에게 함수 호출 위치를 물으면 보통 다음 과정을 반복합니다.

1. grep으로 검색
2. 여러 파일 읽기
3. 다른 패턴으로 재검색
4. 추가 파일 읽기
5. 컨텍스트를 채운 뒤 답변

후속 질문을 하면 이 과정을 다시 시작합니다. 긴 세션에서는 이 반복이 사용량 제한을 빠르게 소모하고, 파일 내용으로 가득 찬 컨텍스트는 추론할 공간을 줄입니다.

codebase-memory-mcp는 저장소 구조를 한 번 색인화해 이 문제를 줄입니다.

무엇을 하는가

이 도구는 저장소를 다음 요소로 구성된 영구 지식 그래프로 파싱합니다.

• 함수와 클래스
• 호출 체인
• HTTP 경로
• 서비스 간 연결
• 코드 구조와 영향 관계

파싱에는 160개 이상의 언어를 지원하는 tree-sitter AST 분석이 사용됩니다. 여기에 하이브리드 LSP 계층이 추가되어 README 배지에서 10가지 핵심 그룹으로 분류한 언어에 의미론적 타입 해결을 제공합니다.

• Python
• TypeScript 및 JavaScript 계열(JSX, TSX 포함)
• PHP
• C#
• Go
• C
• C++
• Java
• Kotlin
• Rust
• Perl

AST는 save 메서드가 호출되었다는 사실을 알려줍니다. 타입 해결은 그 메서드가 어느 클래스에 속하는지까지 알려줍니다.

분석 결과는 15가지 MCP 도구로 제공됩니다.

• 검색
• 호출 체인 추적
• 아키텍처 개요
• 영향 분석
• 인덱스 커버리지 확인
• Cypher 쿼리
• 데드 코드 탐지
• 서비스 간 HTTP 연결
• ADR 관리

Model Context Protocol을 사용하는 모든 클라이언트에서 사용할 수 있으며, 프로젝트는 Claude Code, Codex, Cursor, Windsurf, OpenCode, Gemini CLI, Aider, Kilocode를 포함한 45가지 에이전트 인터페이스를 지원한다고 설명합니다.

성능 수치

프로젝트에는 서로 다른 두 가지 측정 결과가 있습니다.

프로젝트 자체 측정

다섯 가지 구조적 쿼리 기준:

• 그래프 탐색: 약 3,400 토큰
• 파일별 grep 탐색: 약 412,000 토큰
• 감소율: 99.2%
• 토큰 사용량: 약 120배 감소

학술 평가

Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP는 31개 실제 저장소를 평가했습니다.

• 파일별 탐색 대비 답변 품질 83%
• 토큰 사용량 10배 감소
• 도구 호출 2.1배 감소

120배는 그래프의 강점과 정확히 맞는 다섯 가지 구조적 쿼리의 최적 사례입니다. 10배는 31개 저장소의 다양한 작업을 포함한 수치로, 일상적인 사용에 더 가까운 기준입니다. 실제 계획에는 10배를 사용하고 그보다 나은 결과는 추가 이점으로 보는 편이 현실적입니다.

속도도 빠릅니다.

• 2,800만 줄, 75,000개 파일의 Linux 커널 색인화: 약 3분
• 일반적인 저장소: 밀리초 단위
• 구조적 쿼리: 1밀리초 미만

파이프라인은 LZ4 압축, 인메모리 SQLite, 융합된 Aho-Corasick 패턴 매칭을 사용하는 RAM 우선 방식입니다. 색인화가 끝나면 메모리를 해제합니다.

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=로 설치 위치를 지정할 수 있습니다.

설치 프로그램은 설치된 코딩 에이전트를 자동으로 감지해 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로 볼 수 있습니다. 예상하지 못한 구조를 발견하거나 색인이 프로젝트를 제대로 커버했는지 확인할 때 유용합니다.

여러 저장소에서 작업한다면 다음 옵션도 고려하세요.

codebase-memory-mcp config set auto_watch false
codebase-memory-mcp config set watcher_enabled false

auto_watch false는 세션이 백그라운드 워처에 프로젝트를 등록하지 않도록 합니다. watcher_enabled false는 폴링 스레드를 완전히 끕니다. 후자는 데몬 시작 시 한 번만 읽으므로 변경 후 데몬을 다시 시작해야 합니다.

실행 전에 확인할 사항

프로젝트에 다음 내용이 문서화되어 있습니다.

Microsoft Defender 오탐 가능성

릴리스 바이너리가 Trojan:Script/Wacatac.B!ml로 탐지될 수 있습니다. 프로젝트는 이를 알려진 오탐으로 설명하며, 일반적으로 62개 엔진 중 약 61개가 깨끗한 결과를 보인다고 명시합니다. 같은 탐지 패밀리가 GitHub CLI, llama.cpp, Godot, Microsoft의 Go 툴체인에도 영향을 미친다고 설명합니다.

각 릴리스는 게시 전에 VirusTotal에서 검사되고 릴리스 노트에 결과 링크가 제공됩니다. 그래도 설치 스크립트를 bash로 파이프하기 전에 내용을 직접 확인하는 것이 좋습니다.

로컬 파일 접근 및 설정 변경

이 도구는 코드베이스를 읽고 에이전트 구성 파일에 씁니다. 이것은 핵심 기능이며 프로젝트도 이를 명확히 공개합니다.

완화 요소는 다음과 같습니다.

• 전체 소스 코드가 MIT 라이선스로 공개됨
• OpenSSF Scorecard와 SLSA 레벨 3 출처 제공
• 처리가 전적으로 로컬에서 수행됨
• 자체 네트워크 요청을 하지 않음
• 백그라운드에서 업데이트를 확인하지 않음
• 원격 서버로 정보를 전송하지 않음

업데이트는 실행 중인 프로세스가 아니라 바이너리 옆의 설치 스크립트에서 수행됩니다. 이는 README에 설명된 의도적인 설계입니다.

인기와 보안 감사는 다릅니다. 설치 스크립트를 읽고, 로컬 전용 동작이 중요하다면 소스 코드로 직접 확인하세요.

먼저 설치할 가치가 있는 이유

다른 에이전트 도구들은 프롬프트 방식, 병렬 작업 트리, 웹 접근 등 작업 흐름 자체를 바꿉니다. 반면 codebase-memory-mcp는 기존 작업 방식을 유지하면서 세션 비용을 줄입니다.

설치하고 프로젝트를 색인화하면 에이전트는 같은 구조를 매번 grep으로 재구성하지 않아도 됩니다. 긴 리팩터링 중 오후에 사용량 제한에 도달하는 상황을 줄일 수 있습니다.

품질 측면의 효과도 큽니다. 파일을 읽는 데 400,000 토큰을 사용하면 실제 문제를 추론할 공간과 앞서 읽은 내용을 기억할 능력이 줄어듭니다. 그래프에서 구조적 답변을 얻으면 컨텍스트가 더 여유로워집니다.

이는 에이전트 도구 응답 컨텍스트 창에서 설명하는 문제와도 같습니다. 과도한 API 응답이 에이전트 워크플로우를 비싸게 만드는 것처럼, 불필요한 파일 내용도 컨텍스트를 낭비합니다.

실제로 유용한 도구

15가지 도구를 모두 배울 필요는 없습니다. 에이전트가 적절한 도구를 선택하기 때문입니다. 다음 질문부터 습관화하면 됩니다.

• 영향 분석: 함수 시그니처를 변경하기 전에 어떤 호출자가 영향을 받는지 확인합니다. 동적 디스패치와 간접 호출을 놓치기 쉬운 grep보다 안전합니다.
• 호출 체인 추적: 실행이 특정 코드에 도달하는 경로를 확인합니다. 익숙하지 않은 저장소의 진입점을 찾을 때 유용합니다.
• 아키텍처 개요: 전체 트리를 읽지 않고 저장소의 구조적 지도를 얻습니다.
• 데드 코드 탐지: 호출되지 않는 코드를 찾아 정리 전에 검증합니다.
• 서비스 간 HTTP 연결: 한 서비스의 호출을 다른 서비스의 핸들러까지 추적합니다. 마이크로서비스 저장소에서 특히 중요합니다.
• Cypher 쿼리: 기본 도구가 다루지 않는 구체적인 그래프 질문을 직접 실행합니다.

핵심 변화는 질문의 비용입니다. 이전에는 비용 때문에 미뤘던 다음 질문을 리팩터링과 디버깅 과정에 포함할 수 있습니다.

• “이 함수는 무엇이 호출하는가?”
• “이 엔드포인트의 요청 경로는 어떻게 구성되는가?”
• “이 변경으로 어떤 서비스가 영향을 받는가?”

그래프가 아는 것과 모르는 것

그래프는 코드가 어디에 있고 어떻게 연결되는지는 잘 압니다. 하지만 API 계약이 무엇을 약속하는지까지는 알 수 없습니다.

예를 들어 다음은 소스 코드만으로 확실히 알기 어렵습니다.

• 멱등성 키 재사용 시 409 응답의 오류 엔벨로프
• status 필드의 정확한 유효 값 다섯 가지
• 커서가 오프셋이 아닌 불투명한 값인지 여부
• 다음 분기에 제거될 예정인 사용 중단 필드

/v1/invoices/{id} 경로와 해당 핸들러는 찾을 수 있지만, 위와 같은 계약 정보는 구현보다 팀의 합의와 사양에 의존합니다.

따라서 구조적 기억력이 뛰어난 에이전트도 계약을 추측할 수 있습니다. 그 결과 클라이언트와 목을 잘못 만들고, 스테이징 환경에 도달할 때까지 문제를 발견하지 못할 수 있습니다.

이 지점에서 Apidog와 codebase-memory-mcp는 서로 대체하기보다 보완합니다.

• 그래프는 어디에 있는지 답합니다: 어떤 핸들러, 어떤 호출 체인, 무엇이 깨지는지
• 사양은 무엇을 약속하는지 답합니다: 실제 스키마, 상태 코드, 오류 엔벨로프
• 목은 사양으로부터 생성됩니다: 에이전트가 누락하기 쉬운 오류 분기까지 포함
• 계약 테스트는 구현과 합의가 다를 때 CI에서 실패합니다

자세한 내용은 OpenAPI 사양을 에이전트 도구로 사용하는 것과 API 변경이 AI 에이전트를 망가뜨릴 때 발생하는 실패 모드를 참고하세요.

문서화되지 않은 형태로 API 클라이언트를 작성하고 있다면 Apidog를 다운로드하세요. 추가로 에이전트를 위한 API 도구 스키마 설계와 AI 에이전트 시대에도 API 도구가 필요한가요도 도움이 됩니다.

코드의 기억은 작업의 기억이 아니다

두 번째 한계는 조직적 기억입니다.

색인은 한 머신의 캐시 디렉터리에 한 계정으로 저장됩니다. 조정 데몬을 통해 해당 머신의 Claude Code, Codex, OpenCode 세션 간에 공유되지만, 머신의 경계를 넘지는 않습니다.

또한 그래프는 코드베이스를 기억할 뿐 작업의 맥락은 기억하지 못합니다. 예를 들어 재시도 헬퍼가 결제 클라이언트를 호출한다는 사실은 알 수 있지만, 다음 내용은 알 수 없습니다.

• 7월에 백오프가 변경된 이유
• 결정을 내린 사람
• 검토한 대안
• 변경 사항을 검토한 사람

이런 정보는 종료된 터미널 세션에 남아 있을 수 있습니다.

Sharkly는 프롬프트 대신 태스크를 영구적인 기록으로 만들어 이 간극을 보완합니다.

• 작업은 태스크로 존재하고 에이전트의 출력은 댓글로 남습니다.
• 진행 상황과 도구 호출은 태스크에 스트리밍됩니다.
• 지침, 런타임, 스킬, 저장소, 환경을 포함한 에이전트 설정을 재사용할 수 있습니다.
• 노트북, 서버, 컨테이너 같은 실행 환경을 연결해 이미 설치된 런타임을 사용할 수 있습니다.
• 태스크별 별도 작업 트리에서 실행해 병렬 작업 충돌을 줄입니다.
• 백로그 태스크는 준비가 끝날 때까지 실행되지 않습니다.
• 스페이스, 프로젝트, 스프린트, 태스크와 Jira 동기화를 지원합니다.

결국 두 도구는 서로 다른 기억을 제공합니다.

• codebase-memory-mcp: 에이전트가 저장소를 기억하도록 함
• Sharkly: 팀이 에이전트의 작업과 결정을 기억하도록 함

자주 묻는 질문

Cursor, Codex, OpenCode에서도 작동하나요?

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 도구가 필요한가에서 자세히 다룹니다.

마무리

codebase-memory-mcp는 2026년 에이전트 도구 중 가장 화려하지는 않지만, 기존 워크플로우를 바꾸지 않고도 높은 투자 수익을 제공합니다.

설치 순서는 간단합니다.

1. 바이너리와 설치 스크립트를 확인합니다.
2. 프로젝트를 색인화합니다.
3. auto_index를 설정합니다.
4. localhost:9749에서 그래프를 확인합니다.
5. 리팩터링과 디버깅 전에 구조적 질문을 먼저 합니다.

특히 여러 에이전트가 동시에 실행될 때 효과가 큽니다. 이는 Orca 같은 병렬 에이전트 환경에서도 마찬가지입니다.

다만 두 가지 한계를 기억해야 합니다.

• 그래프는 코드가 어디에 있는지 알지만 API가 무엇을 약속하는지는 모릅니다. 이 간극은 Apidog의 사양, 목, 테스트 스위트로 보완할 수 있습니다.
• 그래프는 저장소를 기억하지만 작업과 의사결정은 기억하지 못합니다. 이 간극은 Sharkly가 태스크를 영구 기록으로 남겨 보완합니다.

코드에 대한 완벽한 기억력은 강력한 기반입니다. 하지만 무엇이 진실인지, 그리고 무엇이 결정되었는지 아는 것과는 다릅니다.