MinishLab/semble

Semble – AI 코딩 에이전트를 위한 빠르고 토큰 효율적인 코드 검색

무엇인가요 – Semble는 대규모 언어 모델 기반 코딩 어시스턴트(Claude Code, Cursor, Codex, OpenCode 등)가 리포지토리에서 필요한 코드 스니펫을 정확히 검색할 수 있도록 해주는 Python 라이브러리/CLI/MCP 호환 서버입니다. 이는 단순한 "grep + 전체 파일 읽기" 접근 방식과 비교해 약 99%의 토큰을 절약하면서도, 137M 파라미터의 코드 전용 트랜스포머와 동등한 검색 품질을 유지합니다.

왜 중요한가요 – 에이전트는 종종 낯선 코드베이스를 탐색해야 합니다. 모델의 컨텍스트에 전체 파일을 불러오는 것은 비용이 많이 들고 느립니다. Semble는 리포지토리를 약 0.5초 내에 인덱싱하고, CPU에서 자연어 질의를 약 1ms 내에 응답하므로, 에이전트는 API 키, GPU, 외부 서비스 없이 즉시 필요한 코드 조각을 얻을 수 있습니다.

주요 기능

속도 – 평균 리포지토리를 약 500ms 내에 인덱싱; 쿼리 지연은 약 1ms (CPU 전용). 유사한 트랜스포머 기반 리트리버보다 인덱싱이 340배 빠르고, 쿼리가 17배 빠릅니다.
정확도 – 저자들의 벤치마크에서 NDCG@10 = 0.854. 137M 파라미터 모델과 동등한 성능입니다.
토큰 효율성 – 필요한 스니펫만 반환하므로, 전체 파일을 읽는 데 소요되는 토큰의 약 99%를 절약합니다.
초기 설정 없음 – GPU 없이도 가능. API 키 없이 pip/uv 설치만으로 사용 가능.
MCP 서버 – 어떤 MCP 호환 에이전트라도 search와 find_related를 네이티브 도구로 사용할 수 있습니다.
로컬 및 원격 리포지토리 – 파일 시스템 경로 또는 Git URL을 지원합니다.
세밀한 제어 – .gitignore와 전용 .sembleignore를 통해 파일 및 확장자 포함/제외 가능합니다.
캐시 및 통계 – 인덱스와 토큰 절약 통계를 캐시. semble savings로 피한 토큰 수 확인 가능.

빠른 시작 (CLI)

# 도구 설치 (uv 필요)
uv tool install semble
semble install          # 인터랙티브 – 에이전트 및 통합 유형 선택

# 로컬 리포지토리에서 기본 검색
semble search "authentication flow" ./my-project

# 원격 리포지토리 검색 (필요 시 자동 클론)
semble search "save model to disk" https://github.com/MinishLab/model2vec

# 결과 제한, 스니펫 줄 수 제한, 문서/설정 파일 검색
semble search "deployment guide" ./my-project --content docs --top-k 5 --max-snippet-lines 10

semble uninstall로 통합 제거, semble clear ...로 캐시 삭제 가능.

Python 라이브러리로 사용하기

from semble import ContentType, SembleIndex

# 인덱스 생성 (처음에는 캐시됨)
idx = SembleIndex.from_path("./my-project", content=ContentType.CODE)
# 또는 문서/설정 포함
# idx = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# 자연어 또는 코드 쿼리
results = idx.search("save model to disk", top_k=3)
for r in results:
    print(r.chunk.file_path, r.chunk.start_line, r.chunk.content[:120])

# 특정 위치와 유사한 코드 찾기
related = idx.find_related(results[0], top_k=3)

이 라이브러리는 커스텀 툴 개발이나 자체 애플리케이션에 검색 기능을 직접 통합할 때 유용합니다.

MCP 서버 모드

MCP 도구로 설치하면 에이전트는 다음과 같은 도구를 호출할 수 있습니다:

도구	설명
`search`	로컬 경로 또는 Git URL의 리포지토리에서 자연어 또는 코드 쿼리 실행.
`find_related`	파일 경로와 줄 번호를 기반으로 의미적으로 유사한 코드 조각 반환.
설치 안내는 `docs/installation.md#mcp-server` 참조.

내부 동작 방식

체크닝 – tree-sitter를 사용해 코드 인식 체크닝으로 파일을 분할.
이중 리트리버 –
- Model2Vec 정적 임베딩(potion-code-16M-v2)으로 의미적 유사도 제공.
- BM25로 식별자 및 API 이름에 대한 빠른 어휘 매칭 제공.
융합 – 두 리트리버의 점수를 Reciprocal Rank Fusion으로 통합.
재순위 지정 – 적응형 가중치, 정의 우선순위, 식별자 스테밍 일치, 파일 일관성 보너스, 노이즈 페널티로 최종 순서 최적화.
캐시 – 인덱스는 디스크에 저장. 파일이 변경되면 인크리멘탈 업데이트로 전체 재빌드를 피함.
모델 유연성 – 원하는 경우 SEMBLE_MODEL_NAME을 사용해 커스텀 Model2Vec 모델로 지정 가능.

모든 처리는 단일 CPU 코어에서 밀리초 단위로 완료되며, 임베딩 모델이 정적(쿼리 시 트랜스포머 순전파 없음)이기 때문입니다.

벤치마크 (보고된 값)

품질 – 63개 리포지토리, 19개 언어에서 NDCG@10 = 0.854. 137M 파라미터의 CodeRankEmbed 모델과 유사.
속도 – 인덱싱이 340배 빠르고, 쿼리가 17배 빠릅니다. 트랜스포머 베이스라인과 비교.
토큰 절약 – grep+read 베이스라인과 비교해 약 99%의 토큰 절약. 2k 토큰에서 97% 리콜 달성. 반면 grep+read는 85% 리콜 달성에 약 100k 토큰 필요. 자세한 내용은 benchmarks/README.md 참조.

설치 및 캐시 위치

uv (uv tool install semble) 또는 pip install semble로 설치.
캐시 디렉터리 기본값은 OS 캐시 위치 (~/.cache/semble 등). SEMBLE_CACHE_LOCATION으로 재정의 가능.
모델 파일은 표준 Hugging-Face 캐시 (~/.cache/huggingface)에 저장.
1MiB 이상의 파일은 기본적으로 건너뜀. SEMBLE_MAX_FILE_BYTES로 조정 가능.

라이선스 및 인용

라이선스: MIT (허용성 높고 상용 사용 가능).
인용: 학술 작업에는 제공된 BibTeX 항목(젠도 DOI 10.5281/zenodo.19785932) 사용.

결론

Semble는 AI 코딩 에이전트에게 로컬, 빠르고 토큰 비용이 낮은 코드 검색 방법을 제공하여, 고비용 API 호출이나 대규모 컨텍스트 창의 필요성을 제거합니다. CLI, Python 라이브러리, MCP 서버로 즉시 사용 가능하며, LLM 기반 개발 워크플로우에 실용적인 추가 요소입니다.