개요
AI 코딩 도구에게 “이 기능 코드 어디 있어?”라고 물어보면, AI는 답을 모르는 상태에서 코드 전체를 검색하고 관련 있어 보이는 파일을 하나씩 열어 읽습니다. 프로젝트가 커질수록 열어야 할 파일이 늘어나고, 그만큼 토큰 비용이 새어 나갑니다. 이 글은 코드 전체를 미리 지도처럼 만들어 두어 파일 읽기에 드는 토큰을 개발사 측정 기준 99%까지 줄여준다는 codebase-memory-mcp를 소개합니다.
헤이제임스 – AI 쉽게 배우기 채널이 다룬 이 도구는, rtk나 Serena처럼 AI 코딩 토큰을 아끼는 도구들의 연장선에 있습니다. 코드가 많고 파일이 여기저기 흩어진 프로젝트를 다루는 개발자라면 끝까지 읽어볼 만합니다.
핵심 내용
AI가 파일을 하나씩 읽을 때 생기는 토큰 낭비
AI 코딩 도구에게 구조를 묻는 질문을 하나 던지면, AI는 코드 전체를 검색하고 관련 있어 보이는 파일을 하나씩 열어서 읽습니다. 프로젝트가 클수록 열어야 할 파일이 많아지고, 구조를 묻는 질문 하나에 파일 수십 개를 읽는 일이 예사입니다.
이를 처음 가본 도시에서 가게를 찾는 상황에 비유할 수 있습니다. 지도가 없으면 골목을 돌아다니며 집집마다 문을 두드려야 하지만, 지도 한 장이 있으면 펼쳐서 위치를 짚기만 하면 끝입니다. AI가 파일을 하나씩 읽는 게 문을 두드리는 것이라면, codebase-memory-mcp는 그 지도를 미리 만들어 두는 도구입니다.
codebase-memory-mcp의 작동 방식
이 도구는 코드 전체를 미리 한 번 훑어서 knowledge graph, 즉 코드 지도로 만들어 둡니다. 어떤 함수가 어디 있는지, 무엇이 무엇을 부르는지, 어떤 화면 주소로 연결되는지를 지도처럼 정리해 둡니다. 158개 언어를 지원하고, 무거운 설치 없이 작은 실행 파일 하나로 동작하며, 도구 자체에는 AI가 들어있지 않아 지도만 만들고 해석은 Claude Code 같은 AI가 담당합니다.
연결해 두면 AI가 평소처럼 코드를 검색할 때마다 이 도구가 중간에서 끼어들어 미리 만들어 둔 지도에서 관련된 부분을 함께 건네줍니다. 사용자가 따로 명령을 바꾸거나 외울 필요 없이, 평소처럼 일을 시키면 AI가 파일을 다 읽기 전에 지도에서 먼저 답을 찾는 구조입니다.
MCP는 AI에게 외부 도구를 꽂는 표준 단자입니다. 콘센트 규격이 통일돼 있으면 어떤 가전이든 꽂아 쓸 수 있듯이, MCP를 지원하는 도구는 Claude Code에 한 번에 연결됩니다.
데이터로 보는 토큰 절감 효과
개발사가 공개한 측정값에 따르면, 구조를 묻는 질문 5개를 처리할 때 파일을 하나씩 읽는 기존 방식은 약 412,000 토큰이 들었습니다. 같은 질문을 codebase-memory-mcp가 만든 코드 지도에 물어봤을 때는 약 3,400 토큰으로 끝났습니다. 99.2%, 약 120배의 토큰 절감입니다.
다만 이 절감 효과는 프로젝트 규모에 따라 달라집니다. 코드가 많고 파일이 여기저기 흩어져 있는 큰 프로젝트일수록 절감 효과가 크고, 파일 몇 개짜리 작은 프로젝트는 어차피 읽는 양이 적어 차이를 크게 느끼지 못할 수 있습니다.
오늘 바로 해볼 수 있는 것
영상에서 설명한 절차를 그대로 따라가면 다음과 같습니다.
- 터미널에 설치 명령 한 줄을 붙여넣어 codebase-memory-mcp를 설치합니다. 이 한 번의 설치로 Claude Code와의 연결(단자 등록)까지 자동으로 이뤄지므로 별도의 설정 파일 편집은 필요 없습니다. 정확한 설치 명령어는 원본 영상 설명란에서 확인할 수 있습니다.
- Claude Code에게 “이 프로젝트 인덱싱해줘”라고 요청합니다. 이 한마디로 코드 전체를 훑어 knowledge graph를 만드는 인덱싱 작업이 시작되며, 웬만한 프로젝트는 순식간에 끝납니다.
- 평소처럼 AI에게 코드 구조나 특정 기능의 위치를 질문합니다. 별도로 명령어를 바꾸지 않아도, AI가 파일을 하나씩 열기 전에 미리 만들어 둔 지도에서 관련 부분을 먼저 참고해 답하는지 확인하면 됩니다.
이 방식은 코드가 많고 파일이 여기저기 흩어져 있는 큰 프로젝트, 여러 모듈에 걸친 기능을 다루거나 오래돼 구조가 복잡해진 코드베이스에서 효과가 큽니다. 이런 프로젝트를 다루고 있다면 먼저 적용해 보는 것이 합리적입니다. 한 번 만든 지도는 대화를 새로 시작하거나 컴퓨터를 껐다 켜도 그대로 남아, 같은 프로젝트를 매번 처음부터 다시 파악하느라 토큰을 쓰는 일이 줄어듭니다.
한계와 주의할 점
이 도구는 지도만 그려 줄 뿐이고, 그 지도를 읽고 판단하는 것은 결국 AI의 몫입니다. 또한 코드의 구조를 기준으로 지도를 그리기 때문에, 실행 중에 그때그때 정해지는 부분은 지도에 다 담기지 않을 수 있습니다.
나온 지 오래된 도구가 아니므로, 중요한 작업에서는 결과를 한 번씩 확인하면서 사용하는 것이 좋습니다. 정확한 설치 명령어와 요금 정책은 영상 자막만으로는 확인되지 않으므로, 도입 전 원본 영상 설명란이나 공식 문서를 직접 확인하시기 바랍니다.
rtk(터미널 출력 축소), Serena(필요한 부분만 읽기), codebase-memory-mcp(구조 파악용 읽기 자체 축소)는 서로 아끼는 지점이 달라 함께 사용해도 부딪히지 않습니다.
핵심 요점
- AI가 코드 구조를 파악하려고 파일을 하나씩 여는 과정에서 토큰이 크게 소모되며, 프로젝트가 클수록 이 낭비가 커집니다.
- codebase-memory-mcp는 코드 전체를 미리 훑어 knowledge graph, 즉 코드 지도를 만들어 두고, AI가 검색할 때 이 지도에서 관련 부분을 먼저 제공합니다.
- 개발사 측정 기준으로 구조 질문 5개 처리 시 412,000 토큰에서 3,400 토큰으로, 약 99.2%(120배) 토큰이 절감됩니다.
- 설치는 한 줄, 이후 “이 프로젝트 인덱싱해줘” 한마디면 지도가 만들어지고, 한 번 만든 지도는 대화를 새로 시작하거나 컴퓨터를 재부팅해도 그대로 남습니다.
- 지도 해석은 결국 AI 몫이고 실행 중 동적으로 정해지는 부분은 지도에 다 담기지 않을 수 있다는 한계가 있으니, 중요한 작업에서는 결과를 확인하면서 사용하세요.
참고자료
- 원본 영상: https://www.youtube.com/watch?v=QOAJYkuX_-Y (헤이제임스 – AI 쉽게 배우기)
- 정확한 설치 명령어와 최신 정보는 영상 설명란을 참고하시기 바랍니다.