Semble — 에이전트를 위한
초고속 코드 검색 라이브러리

먼저, "에이전트의 코드 검색"이 왜 문제인가?

grep+read 시대가 끝나가는 이유.

2024~2026년 사이 Claude Code, Cursor, Codex 같은 AI 코딩 에이전트가 폭발적으로 늘었다. 그런데 이 에이전트들이 "이 함수 어디 있어?"를 찾기 위해 보통 grep으로 전체 파일을 훑고 read_file로 통째로 읽어들인다. 이 방식은 토큰을 폭식하고 응답이 느리다.

웹 검색 초창기와 비슷한 상황이다. 단순 키워드 grep만으로는 한계가 명확하고, 그렇다고 트랜스포머 임베딩 검색을 도입하면 GPU·API 키·수십 초의 색인 시간이 따라온다. Semble은 두 세계의 좋은 점만 골라 CPU에서 1.5ms 만에 동작하는 하이브리드 검색기를 내놓는다.

이 프로젝트의 핵심 메시지

한 문장으로 줄이면.

2026년 5월, 트렌딩에 오른 이유

시대적 배경 + 경쟁 우위.

시대적 배경 — 에이전트 토큰 경제학

Claude Code/Cursor가 일상화되면서 "에이전트당 월 토큰비"가 실제 비용으로 잡히기 시작했다. 한 번의 코드 탐색에 grep+read 패턴은 수만 토큰을 태우고, 응답도 느리다. Semble은 같은 질의를 토큰 98% 절감 + 응답 10배 빠르게 해결한다. ROI가 명확하니 채택이 빠르다.

또 하나 — MCP 표준이 무르익었다. claude mcp add semble -s user -- uvx --from "semble[mcp]" semble 한 줄로 Claude Code·Cursor에 즉시 붙는다. "그래서 어떻게 써?"라는 마찰이 사실상 0이라는 것이 트렌딩의 또 다른 이유.

경쟁 비교 — grep vs 트랜스포머 vs Semble

전체 기술 지도

코어 의존성 · 개발 도구 · 배포.

코어 의존성 (pyproject.toml 기반)

개발 / 품질 도구

배포 / 실행

전체 데이터 흐름과 5가지 설계 패턴

시스템 구조도 → 핵심 패턴 하나하나.

전체 데이터 흐름

              ┌──────────────────────────────────────┐
              │     사용자 / AI 에이전트              │
              │  ("save model to disk" 라고 질의)     │
              └──────────────┬───────────────────────┘
                             │ MCP Tool: search(repo, query)
                             ▼
        ┌──────────────────────────────────────────────┐
        │              SembleIndex (코어)               │
        │                                              │
        │   ┌──────────┐    ┌────────────────────┐    │
        │   │ from_path│ ── │ TreeSitter 자체 청킹 │   │
        │   │ from_git │    │  (src/semble/chunking)│  │
        │   └──────────┘    └─────────┬──────────┘    │
        │                             │ chunks         │
        │                             ▼                │
        │         ┌───────────────────────────────┐    │
        │         │  병렬 색인 (한 번만 실행)       │   │
        │         │                               │    │
        │         │  [A] Model2Vec               │    │
        │         │      potion-code-16M         │    │
        │         │      → 시맨틱 벡터            │    │
        │         │                               │    │
        │         │  [B] BM25 (bm25s)             │    │
        │         │      → 어휘 인덱스             │    │
        │         └─────────────┬─────────────────┘    │
        │                       │                      │
        │                       ▼                      │
        │   ┌──────────────────────────────────────┐  │
        │   │      질의(query) 처리 ~1.5ms          │  │
        │   │                                      │  │
        │   │  1) 두 검색기 점수 → RRF 융합          │  │
        │   │  2) 코드 인지 리랭킹:                  │  │
        │   │     · 적응형 가중치 (심볼 vs 자연어)    │  │
        │   │     · 정의 부스트 (def/class)          │  │
        │   │     · 식별자 stem 매칭                 │  │
        │   │     · 파일 일관성 부스트                │  │
        │   │     · 노이즈 페널티 (test/, legacy/)   │  │
        │   └──────────────┬───────────────────────┘  │
        └──────────────────┼──────────────────────────┘
                           │ Top-K 청크
                           ▼
                ┌──────────────────────┐
                │  결과 (Chunk 객체)    │
                │  · file_path         │
                │  · start_line/end    │
                │  · content           │
                └──────────────────────┘

패턴 1 — 정적 임베딩 (Static Embedding)

일반 임베딩 모델은 질의마다 트랜스포머의 forward pass를 돌린다 (수십~수백 ms). Model2Vec은 미리 계산된 단어 임베딩을 그저 lookup + pooling 하기 때문에 0.02ms 단위로 끝난다. "느린 트랜스포머의 99% 품질을 1/200 시간에" 라는 Semble의 슬로건이 가능한 이유.

패턴 2 — 하이브리드 검색 (RRF 융합)

시맨틱(의미)만으로는 getUserById 같은 정확한 심볼명을 놓치고, 어휘(BM25)만으로는 "사용자 정보 가져오기" 같은 자연어 질의를 못 푼다. Semble은 두 점수 리스트를 RRF로 합쳐 양쪽 약점을 메운다.

# RRF 핵심 공식 (개념)
score(doc) = sum_over_retrievers( 1 / (k + rank_r(doc)) )
# k=60이 일반적. rank가 작을수록(상위일수록) 점수가 큼.
# 점수 스케일이 다른 검색기들도 공정하게 섞임.

패턴 3 — 적응형 가중치 (Adaptive Weighting)

질의가 Foo::bar, _private, getUserById처럼 심볼 모양이면 BM25 비중을 키우고, "데이터베이스 연결 풀 설정" 같은 자연어면 시맨틱 비중을 키운다. 질의를 보고 동적으로 가중치를 조절하는 self-tuning 패턴.

패턴 4 — 코드 인지 리랭킹 (Code-Aware Reranking)

융합 점수만으로는 "정의가 들어있는 청크"가 항상 1등이 되지 않는다. Semble은 class/def/func 키워드가 들어 있고 질의 식별자와 매칭되는 청크를 부스트하고, test_ 디렉토리·legacy/·.d.ts는 깎는다. "개발자가 원하는 것은 보통 정의이지 사용 예시가 아니다"라는 휴리스틱이 코드에 박혀 있는 셈.

패턴 5 — tree-sitter 기반 코드 인지 청킹 (자체 구현)

단순 줄 단위 분할이 아니라 tree-sitter로 AST를 파싱해 함수/클래스 경계를 살린 채로 청크를 나눈다. 외부 청킹 라이브러리에 의존하지 않고 src/semble/chunking/에 자체 구현되어 있다. 결과 청크가 "잘려 있지 않아" 에이전트가 그대로 컨텍스트에 넣어도 의미가 통한다.

레포 구조 해부

어디에 뭐가 있는지.

semble/
├── src/semble/                  # 패키지 소스 (src-layout)
│   ├── __init__.py              # public API (SembleIndex 등 export)
│   ├── cache.py           4.7KB # 인덱스 캐싱
│   ├── cli.py             8KB   # `semble` 명령어 진입점
│   ├── mcp.py             9.9KB # MCP 서버 (search / find_related 툴)
│   ├── search.py          5KB   # 핵심 검색 로직 (RRF + 리랭킹)
│   ├── stats.py           8.5KB # 코퍼스 통계 (BM25 정규화 등)
│   ├── tokens.py          1.5KB # 토크나이저 / stem
│   ├── types.py           1.6KB # Chunk, SearchResult dataclass
│   ├── utils.py           1.5KB # 경로 유틸 / git clone 등
│   ├── version.py               # setuptools_scm 버전 attr
│   ├── chunking/                # tree-sitter 기반 코드 인지 청킹 (자체 구현)
│   ├── index/                   # 색인 구축 (Model2Vec + BM25)
│   ├── installer/               # 설치 관련 유틸
│   ├── ranking/                 # 리랭킹 신호 (definition boost, stem, ...)
│   └── agents/                  # agents/*.md 패키지 데이터 (MCP 프롬프트)
│
├── benchmarks/                  # 63 레포 · 1,250 질의 벤치마크 스크립트
├── tests/                       # pytest 단위 테스트
├── assets/images/               # 로고, 벤치마크 그래프
├── .github/workflows/           # GitHub Actions CI
│
├── pyproject.toml               # 패키지 메타 + 의존성 + ruff/mypy 설정
├── uv.lock                      # uv 잠금 파일 (재현 가능 빌드)
├── Makefile                     # lint, test, benchmark 명령
└── README.md                    # 사용법 + 벤치마크 표

분야별 배울 것

기술 영역마다 무엇을 가져갈지.

Model2Vec / 정적 임베딩

BM25 (어휘 검색)

tree-sitter 코드 인지 청킹 (자체 구현)

MCP (Model Context Protocol)

Python 패키징 모범

벤치마킹 / 평가

하드웨어·시스템 요구사항

CPU만 있으면 어디서든.

직접 해볼 수 있는 5단계

난이도별 실습 — Easy → Hard.

실습 1 — 5분 만에 첫 검색Easy

from semble import SembleIndex
idx = SembleIndex.from_git("https://github.com/MinishLab/semble")
for r in idx.search("how does reranking work", top_k=3):
    print(r.chunk.file_path, r.chunk.start_line)

실습 2 — Claude Code에 MCP로 꽂기Easy

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

실습 3 — 사내 레포 벤치마크Medium

실습 4 — 한국어 식별자 부스트 PRMedium

실습 5 — 인덱스 영속화 + watchfiles 핫리로드Hard

8주 심화 학습 로드맵

주차별로 따라가면 검색 시스템 한 사이클.

핵심 용어 한눈에

자주 마주칠 단어들.

더 깊이 파고들 자료

공식 · 핵심 라이브러리 · 표준.

공식 자료

• MinishLab/semble (GitHub)
• TrendShift 페이지
• potion-code-16M (HuggingFace)

핵심 라이브러리

• Model2Vec — 정적 임베딩 distillation
• vicinity — 경량 nearest-neighbor
• bm25s — numpy 기반 빠른 BM25
• tree-sitter — incremental parser

표준 · 학습 리소스

• Anthropic MCP 사양
• uv 패키지 매니저
• BM25 (Wikipedia)
• NDCG (Wikipedia)