Semble은 AI 코딩 에이전트를 위해 설계된 로컬 코드 검색 라이브러리다. 자연어 쿼리나 심볼 이름으로 코드베이스를 검색하면 전체 파일을 읽게 하는 대신 관련 코드 청크만 반환한다. GitHub 저장소 설명 기준으로 grep+read 대비 약 98% 적은 토큰을 사용하며, CPU에서 동작하고 API 키나 GPU가 필요 없다.
왜 필요한가
코딩 에이전트는 보통 rg로 후보 파일을 찾고, 관련 파일을 통째로 읽은 뒤, 그 안에서 필요한 함수나 클래스를 골라낸다. 이 방식은 정확한 문자열 확인에는 강하지만 다음 비용이 크다.
- 파일 전체가 컨텍스트에 들어가 토큰을 낭비한다
- 자연어 질문과 코드 구현 사이의 의미적 연결을 놓칠 수 있다
- 대형 저장소에서 같은 파일을 반복해서 읽는다
- 서브에이전트가 MCP 도구를 직접 쓰지 못하는 환경에서는 검색 품질이 떨어진다
Semble은 “인증 흐름은 어디서 처리하나?”, “save_pretrained 구현은 어디 있나?”처럼 자연어와 심볼 쿼리를 모두 받아 관련 청크만 반환하는 쪽에 초점을 둔다.
핵심 기능
| 기능 | 설명 |
|---|---|
| 로컬 인덱싱 | 평균 저장소를 약 250ms 수준에서 인덱싱한다고 주장한다 |
| 빠른 쿼리 | README 벤치마크 기준 p50 약 1.5ms |
| 하이브리드 검색 | 코드 특화 Model2Vec 임베딩 + BM25를 RRF로 결합 |
| 코드 신호 리랭킹 | 정의 위치, 식별자 어간, 파일 일관성, 테스트·legacy 파일 패널티 반영 |
| MCP 서버 | Claude Code, Cursor, Codex, OpenCode 등 MCP 클라이언트 연결 |
| CLI·Python API | 셸 도구와 라이브러리로 직접 사용 가능 |
설치와 사용
Claude Code에서 MCP 서버로 붙이는 기본 명령:
claude mcp add semble -s user -- uvx --from "semble[mcp]" sembleCodex에서는 ~/.codex/config.toml에 다음 구성을 추가한다.
[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]MCP 대신 CLI로도 쓸 수 있다.
pip install semble
# 또는
uv tool install semble
semble search "authentication flow" ./my-project
semble search "save model to disk" https://github.com/MinishLab/model2vec
semble find-related src/auth.py 42 ./my-projectClaude Code나 Codex의 서브에이전트는 상위 에이전트처럼 MCP 스키마를 직접 호출하지 못하는 경우가 있으므로, 저장소의 AGENTS.md나 CLAUDE.md에 CLI 사용 지침을 넣는 방식도 제공한다.
검색 방식
Semble은 파일을 코드 구조에 맞춰 청크로 나눈 뒤 두 종류의 검색기를 결합한다.
- Model2Vec 임베딩 검색: 코드 특화
potion-code-16M계열 정적 임베딩으로 의미 유사도를 계산한다. - BM25 검색: 식별자, API 이름, 정확한 심볼명을 잘 잡는다.
- RRF 결합: 두 검색 결과를 Reciprocal Rank Fusion으로 합친다.
- 코드 신호 리랭킹: 정의 위치, 심볼형 쿼리, 파일 단위 일관성, 테스트 파일 노이즈를 반영한다.
이 구조는 순수 벡터 검색보다 심볼 매칭에 강하고, 순수 grep보다 자연어 질문에 강하다.
벤치마크 해석
README 벤치마크는 63개 저장소, 19개 언어, 약 1,250개 쿼리에서 Semble을 비교한다.
| 방법 | NDCG@10 | 인덱스 시간 | 쿼리 p50 |
|---|---|---|---|
| CodeRankEmbed Hybrid | 0.862 | 57s | 16ms |
| Semble | 0.854 | 263ms | 1.5ms |
| BM25 | 0.673 | 263ms | 0.02ms |
| ripgrep | 0.126 | – | 12ms |
핵심 주장은 Semble이 CodeRankEmbed Hybrid 검색 품질의 99% 수준에 접근하면서도 인덱싱은 200배 이상 빠르고, 쿼리는 10배 이상 빠르다는 것이다. 또한 grep+read 대비 반환 청크가 작아 에이전트 컨텍스트 비용을 크게 줄인다고 설명한다.
언제 쓰면 좋은가
Semble은 다음 상황에 적합하다.
- 대형 코드베이스에서 에이전트가 반복적으로 파일을 읽어 컨텍스트를 낭비한다
- 자연어로 “이 기능이 어디 구현됐나”를 자주 묻는다
- MCP 클라이언트와 CLI를 모두 지원해야 한다
- 로컬 실행, CPU-only, API 키 없는 검색 도구가 필요하다
반대로 정확한 문자열 전체 검색, 리팩터링 전 영향 범위 전수 확인, 보안상 모든 매치를 빠짐없이 확인해야 하는 경우에는 여전히 rg 같은 리터럴 검색이 필요하다. Semble은 rg를 대체한다기보다, 에이전트가 먼저 볼 만한 코드 청크를 고르는 전처리 레이어에 가깝다.
라이선스
MIT
관련 문서
- context-mode — AI 코딩 에이전트 컨텍스트 창 절약 MCP 서버
- claude-code — Claude Code 에이전트 개요
- codex — OpenAI Codex 코딩 에이전트
- qmd — BM25·벡터·LLM 리랭킹 기반 문서 검색 도구
참고 자료
- MinishLab/semble — GitHub 공식 저장소