AI 에이전트 토큰 사용량 98% 줄이는 코드 검색 도구 'Semble' 실전 분석 (github.com)

한줄 요약

GPU·API 키 없이 CPU만으로 토큰 98% 절감, AI 에이전트용 코드 검색 도구 Semble 등장.

무엇이 달라지나?

Semble은 AI 에이전트가 코드베이스를 탐색하는 방식 자체를 바꾸는 코드 검색 라이브러리다. 기존 방식의 문제는 명확하다. Claude Code, Cursor, Codex 같은 코딩 에이전트들은 코드를 찾을 때 주로 grep으로 키워드를 검색한 뒤 해당 파일 전체를 읽어 들이는 패턴을 반복한다. 파일 하나가 수백, 수천 줄이라면 정작 필요한 코드 10줄을 찾기 위해 나머지 900줄을 모두 컨텍스트 창에 밀어 넣는 셈이다.

Semble은 이 구조를 정면으로 공략한다. 자연어 쿼리(예: "인증 로직은 어디에 있나?")를 입력하면 관련 코드 청크만 정확히 추출해 돌려준다. 결과적으로 grep+read 방식 대비 토큰 사용량이 평균 98% 줄어든다. 수치로 보면 더 직관적이다. 동일한 85% 리콜을 달성하는 데 grep+read는 100k 토큰 컨텍스트 창이 필요하지만, Semble은 2k 토큰만으로 94% 리콜을 달성한다.

속도 측면에서도 기존 코드 특화 트랜스포머 모델과 비교가 된다. 벤치마크 기준으로 인덱싱 속도는 약 200배 빠르고 쿼리 응답은 약 10배 빠르다. 평균 저장소 인덱싱에 약 250ms, 쿼리 응답에 약 1.5ms가 소요된다. 검색 품질(NDCG@10)은 0.854로, 137M 파라미터짜리 CodeRankEmbed Hybrid(0.862)의 99% 수준을 유지한다. GPU도, 외부 API도, 별도 서버도 필요 없다.

내부 구조를 보면 단순 임베딩 검색이 아니다. 파일을 코드 인식 방식으로 청크 단위로 분할한 뒤, 정적 임베딩 기반 의미 검색(Model2Vec의 potion-code-16M 모델)과 식별자·API명에 강한 BM25 어휘 검색을 병렬로 수행하고, Reciprocal Rank Fusion(RRF)으로 결과를 통합한다. 여기에 심볼 정의 여부 부스팅, 식별자 어간 매칭, 테스트 파일·레거시 코드 하향 랭킹 같은 코드 특화 재랭킹 시그널이 추가로 적용된다. 트랜스포머 포워드 패스가 없기 때문에 이 모든 과정이 CPU에서 밀리초 단위로 끝난다.

실무에서 어떤 의미인가?

토큰 비용은 단순히 API 요금의 문제가 아니다. 컨텍스트 창이 불필요한 코드로 가득 차면 에이전트의 추론 품질 자체가 떨어진다. 관련 없는 코드가 노이즈로 작용해 정작 필요한 로직을 제대로 처리하지 못하는 상황이 생긴다. Semble이 해결하는 건 비용만이 아니라 에이전트의 실질적인 성능이기도 하다.

통합 방식도 실용적이다. MCP 서버로 등록하면 Claude Code, Cursor, Codex, OpenCode 등 MCP 호환 에이전트가 즉시 사용할 수 있다. Claude Code나 Codex CLI의 서브에이전트처럼 MCP를 직접 호출하지 못하는 경우에는 AGENTS.md 또는 CLAUDE.md에 bash 통합 스니펫을 추가하는 방식으로 우회할 수 있다. 로컬 경로뿐 아니라 git URL을 직접 넘기면 원격 저장소도 온디맨드로 클론해서 인덱싱한다.

semble savings 명령어로 누적 토큰 절감량을 확인할 수 있는 점도 인상적이다. 실제 사용 데이터를 기반으로 오늘, 최근 7일, 전체 기간별로 절감된 토큰 수를 시각화해준다. 도입 효과를 수치로 보여줄 수 있다는 건, 팀 내 설득이나 의사결정 과정에서도 유용하다.

---

Python API도 제공되므로 에이전트 하네스를 직접 구축하거나 커스텀 툴링에 Semble을 내장하는 것도 어렵지 않다. SembleIndex.from_path() 또는 SembleIndex.from_git()으로 인덱스를 생성하고, search()와 find_related()로 결과를 조회하는 구조다. 라이선스는 MIT이므로 상업적 활용에도 제약이 없다.

도입 전 체크포인트

Semble이 모든 상황에 최적은 아니다. 몇 가지 현실적인 고려 사항이 있다.

의미 검색 vs. 완전 일치 검색: Semble 자체 워크플로우에서도 명시하듯, 정확한 문자열을 빠짐없이 찾아야 할 때는 grep을 병행하는 것이 권장된다. Semble은 "관련 코드 탐색"에 강하지만 "특정 문자열 전수 조회"는 grep이 더 적합하다.

인덱스 갱신 정책: 로컬 경로는 파일 변경을 감지해 자동으로 재인덱싱된다. 반면 MCP 세션 단위로 캐싱되므로, 세션을 넘나드는 사용 패턴에서는 인덱스 상태를 확인할 필요가 있다.

uv 의존성: MCP 방식으로 사용하려면 uv가 사전 설치되어 있어야 한다. pip 방식의 직접 설치도 가능하지만, 팀 환경에서 일관된 설정을 위해 uv 기반 워크플로우를 먼저 정비하는 것이 좋다.

대형 모노레포 적용 시 청크 전략 검토: 평균 저장소 기준 250ms 인덱싱이지만, 수십만 파일 규모의 모노레포에서의 실측치는 별도로 검증해볼 필요가 있다.