Molayo

© 2026 Molayo

HN분석2026. 05. 19. 00:26

에이전트를 위한 코드 검색 라이브러리 Semble 소개

요약

Semble은 AI 에이전트를 위해 설계된 고성능 코드 검색 라이브러리로, 기존 grep 방식 대비 토큰 사용량을 약 98% 절감합니다. CPU 환경에서 별도의 GPU 없이도 매우 빠른 인덱싱과 쿼리 속도를 제공하며, Claude Code나 Cursor와 같은 도구와 쉽게 연동할 수 있습니다.

핵심 포인트

  • 기존 grep+read 방식 대비 토큰 사용량을 약 98% 절약하여 비용 효율성 극대화
  • 코드 특화 트랜스포머 모델 대비 인덱싱은 200배, 쿼리는 10배 빠르며 99%의 검색 품질 유지
  • GPU나 외부 서비스 없이 CPU만으로 실행 가능한 가벼운 라이브러리
  • MCP server 지원 및 AGENTS.md/CLAUDE.md 설정을 통해 다양한 AI 코딩 에이전트와 즉시 연동 가능

Semble은 에이전트(agents)를 위해 구축된 코드 검색 라이브러리입니다. grep+read보다 약 98% 적은 토큰을 사용하여 필요한 정확한 코드 스니펫을 즉시 반환합니다. 전체 코드베이스의 인덱싱 및 검색 과정은 1초 미만으로 완료되며, 코드 특화 트랜스포머(code-specialized transformer) 대비 인덱싱 속도는 약 200배 빠르고 쿼리 속도는 약 10배 빠르면서도 검색 품질은 99%에 달합니다 (자세한 내용은 benchmarks 참조). 모든 기능은 API 키, GPU 또는 외부 서비스 없이 CPU에서 실행됩니다. Semble을 MCP server로 실행하거나 AGENTS.md를 통해 쉘(shell)에서 호출할 수 있으며, Claude Code, Cursor, Codex, OpenCode 등 모든 에이전트가 어떤 레포지토리에도 즉시 접근할 수 있게 됩니다.

Quickstart

에이전트는 Semble에 자연어(

Codex, OpenCode 또는 Cursor를 사용 중이신가요? 설정 방법은 MCP Server를 참조하세요.

Bash / AGENTS.md

Semble을 설치한 다음, 아래 스니펫(snippet)을 AGENTS.md 또는 CLAUDE.md에 추가하세요:

pip install semble       # pip로 설치
uv tool install semble   # 또는 uv로 설치
<details> <summary>AGENTS.md / CLAUDE.md 스니펫</summary> 
## 코드 검색 (Code Search)

grep 대신 `semble search`를 사용하여 기능에 대한 설명이나 심볼(symbol)/식별자(identifier)의 이름을 입력해 코드를 찾으세요:
...
```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10

semble find-related를 사용하여 이미 알고 있는 위치와 유사한 코드를 찾아보세요 (이전 검색 결과에서 file_path와 line을 전달하세요):

semble find-related src/auth.py 42 ./my-project

path를 생략하면 현재 디렉토리가 기본값으로 설정되며, git URL도 허용됩니다.

...


</details>

설치가 완료되면 `semble savings`를 실행하여 Semble이 얼마나 많은 토큰(token)을 절약해 주었는지 확인하세요. Claude Code 또는 Codex에서 서브 에이전트(sub-agent)를 지원하려면 아래의 전체 [Bash / AGENTS.md](#bash-agentsmd) 설정을 완료해야 합니다.

<details>
<summary>Semble 업데이트하기</summary>

```bash
pip install --upgrade semble   # pip 사용 시
uv tool upgrade semble         # uv 사용 시
uv cache clean semble          # MCP 사용자용 (완료 후 MCP 클라이언트를 재시작하세요)
</details>

주요 기능 (Main Features)

주요 기능 (Main Features)

  • Fast (빠름): 평균적인 저장소(repo)를 약 250ms 내에 인덱싱하고, 쿼리에 약 1.5ms 내에 응답하며, 이 모든 과정은 CPU에서 수행됩니다.
  • Accurate (정확함): 당사의 benchmarks에서 0.854의 NDCG@10을 기록하였으며, 이는 코드 특화 Transformer 모델들과 대등한 수준이면서 크기와 비용은 훨씬 적습니다.
  • Token-efficient (토큰 효율적): 관련 있는 청크(chunks)만 반환하여, grep+read 방식보다 약 98% 적은 토큰을 사용합니다.
  • Zero setup (설정 불필요): API 키, GPU 또는 외부 서비스 없이 CPU에서 바로 실행됩니다.
  • MCP server (MCP 서버): Claude Code, Cursor, Codex, OpenCode 및 기타 모든 MCP 호환 에이전트와 함께 작동합니다.
  • Local and remote (로컬 및 원격): 로컬 경로 또는 git URL을 전달할 수 있습니다.

MCP Server

Semble은 MCP 서버로 실행될 수 있어 에이전트가 모든 코드베이스를 직접 검색할 수 있습니다. 저장소는 요청 시 클론(clone) 및 인덱싱되며, 인덱스는 세션이 유지되는 동안 캐싱됩니다. 로컬 경로는 파일 변경 사항을 감시(watch)하며 자동으로 재인덱싱됩니다.

Setup (설정)

uv 설치가 필요합니다.

Claude Code

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

Codex

~/.codex/config.toml에 추가:

[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]

OpenCode

~/.opencode/config.json에 추가:

{
  "mcp": {
    "semble": {
...

Cursor

~/.cursor/mcp.json (또는 프로젝트 내의 .cursor/mcp.json)에 추가:

{
  "mcpServers": {
    "semble": {
...

Tools (도구)

ToolDescription
search자연어 또는 코드 쿼리로 코드베이스를 검색합니다. repo를 로컬 디렉토리 경로 또는 https:// git URL로 전달합니다.
find_related파일 경로와 줄 번호가 주어지면, 해당 위치의 코드와 의미론적으로 유사한 청크(chunks)를 반환합니다.

<a id="bash-agentsmd"></a>

Bash / AGENTS.md

MCP의 대안은 Bash를 통해 Semble을 호출하는 것입니다. Claude Code 및 Codex CLI의 경우, 이는 MCP 도구를 직접 호출할 수 없는 서브 에이전트(sub-agents)를 위한 유일한 옵션이지만, 최상위 에이전트(top-level agent)를 위해 MCP와 함께 사용할 수도 있습니다.

Bash 지원을 추가하려면 AGENTS.md 또는 CLAUDE.md에 다음 내용을 추가하세요:

## Code Search

`grep` 대신 `semble search`를 사용하여 기능에 대한 설명이나 심볼/식별자(symbol/identifier) 이름을 입력해 코드를 찾으세요:
...
```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10

semble find-related를 사용하면 이미 알고 있는 위치와 유사한 코드를 찾을 수 있습니다(이전 검색 결과에서 file_path와 line을 전달하세요):

semble find-related src/auth.py 42 ./my-project

path를 생략하면 현재 디렉토리가 기본값으로 설정되며, git URL도 허용됩니다.

...


**Claude Code 서브 에이전트**: Claude Code는 전용 서브 에이전트도 지원합니다. 프로젝트 루트에서 다음을 한 번 실행하세요:

```bash
semble init
# 또는, semble이 $PATH에 없는 경우:
uvx --from "semble[mcp]" semble init

이렇게 하면 .claude/agents/semble-search.md 파일이 작성됩니다.

CLI

Semble은 독립형 CLI로도 제공됩니다. 이는 스크립트 내에서 사용하거나 MCP 세션 없이 검색 결과가 필요한 모든 곳에서 유용합니다.

# 로컬 저장소 검색
semble search "authentication flow" ./my-project

...

path를 생략하면 현재 디렉토리가 기본값으로 설정되며, git URL도 허용됩니다. 만약 semble이 $PATH에 없다면, 대신 uvx --from "semble[mcp]" semble를 사용하세요.

<details> <summary>Savings (절약량)</summary>

semble savings는 모든 검색을 통해 Semble이 절약한 토큰(tokens) 수를 보여줍니다:

semble savings           # 기간별 요약
semble savings --verbose # 호출 유형별 상세 내역도 표시

  Semble Token Savings
  ════════════════════════════════════════════════════════════════
  Period        Calls   Savings
...
</details>

절감액(Savings)은 다음과 같이 계산됩니다: 각 호출(call)에 대해, Semble은 반환된 청크(chunks)를 포함하는 고유 파일들의 총 글자 수와 반환된 스니펫(snippets)의 글자 수를 기록합니다. 추정된 절감 토큰(Estimated tokens saved)은 (파일 글자 수 − 스니펫 글자 수) / 4 (토큰당 4글자)입니다. 이는 보수적인 추정치입니다. 기준점(baseline)은 매칭된 파일을 전체적으로 읽는 것이며, 이는 코딩 에이전트(coding agents)가 익숙하지 않은 코드를 탐색할 때 흔히 사용하는 방식입니다.

통계 데이터는 ~/.semble/savings.jsonl에 저장됩니다.

</details> <details> <summary>라이브러리 사용법 (Library usage)</summary>

Semble은 프로그래밍 방식의 접근을 위한 Python 라이브러리로도 사용할 수 있으며, 이는 커스텀 도구를 구축하거나 검색 기능을 자신의 코드에 직접 통합할 때 유용합니다.

from semble import SembleIndex

# 로컬 디렉토리 인덱싱
...
</details>

벤치마크 (Benchmarks)

우리는 19개 언어에 걸친 63개 저장소(repositories)에서 약 1,250개의 쿼리(queries)를 통해 품질과 속도를 벤치마크하였으며(왼쪽), 동일한 재현율(recall) 수준에서 grep+read 대비 토큰 효율성(token efficiency)을 측정하였습니다(오른쪽).

<table> <tr> <td><img src="https://raw.githubusercontent.com/MinishLab/semble/main/assets/images/speed_vs_ndcg_cold.png" alt="Speed vs quality"></td> <td><img src="https://raw.githubusercontent.com/MinishLab/semble/main/assets/images/token_efficiency.png" alt="Token efficiency: recall vs. retrieved tokens"></td> </tr> </table>

품질 벤치마크(왼쪽)는 전체 지연 시간(latency) 대비 검색 품질(NDCG@10)을 점수화합니다. Semble은 137M 파라미터 규모의 CodeRankEmbed Hybrid보다 218배 빠르게 인덱싱하면서도 해당 모델 품질의 99%를 달성합니다. 토큰 효율성 벤치마크(오른쪽)는 각 방법이 주어진 재현율(recall) 수준에 도달하기 위해 얼마나 많은 토큰이 필요한지를 측정합니다. Semble은 평균적으로 98% 적은 토큰을 사용하며 단 2k 토큰만으로 94%의 재현율을 달성하는 반면, grep+read는 85%에 도달하기 위해 100k의 전체 컨텍스트 윈도우(context window)가 필요합니다. 언어별 결과, 절제 연구(ablations) 및 전체 방법론은 벤치마크를 참조하십시오.

작동 원리 (How it works)

Semble은 tree-sitter를 사용하여 각 파일을 코드 인지적 청크 (code-aware chunks)로 분할한 다음, 두 가지 상호 보완적인 검색기 (retrievers)를 사용하여 모든 쿼리를 청크와 대조하여 점수를 매깁니다. 하나는 의미론적 유사성 (semantic similarity)을 위해 코드 특화 모델인 potion-code-16M을 사용하는 정적 Model2Vec 임베딩 (embeddings)이며, 다른 하나는 식별자 (identifiers) 및 API 이름에 대한 어휘적 일치 (lexical matches)를 위한 BM25입니다. 두 점수 목록은 상호 순위 결합 (Reciprocal Rank Fusion, RRF)을 통해 통합됩니다.

통합 후, 결과는 다음과 같은 일련의 코드 인지적 신호 (code-aware signals)를 통해 재순위화 (reranked)됩니다.

<details> <summary><b>순위 신호 (Ranking signals)</b></summary>
  • 적응형 가중치 (Adaptive weighting). 심볼 형태의 쿼리 (Foo::bar, _private, getUserById)는 더 높은 어휘적 가중치를 부여받는 반면, 자연어 쿼리는 의미론적 검색기와 어휘적 검색기 사이에서 균형을 유지합니다.
  • 정의 부스트 (Definition boosts). 쿼리된 심볼을 정의하는 청크 (class, def, func 등)는 단순히 이를 참조하는 청크보다 높은 순위로 지정됩니다.
  • 식별자 어근 (Identifier stems). 쿼리 토큰은 어근 추출 (stemming) 과정을 거쳐 청크 내의 식별자 어근과 매칭되며, 이를 포함하는 청크에 추가 가중치를 부여합니다. 예를 들어, parse config를 쿼리하면 parseConfig, ConfigParser 또는 config_parser를 포함하는 청크의 순위가 높아집니다.
  • 파일 일관성 (File coherence). 동일한 파일에서 여러 청크가 쿼리와 일치할 경우, 해당 파일에 부스트를 부여하여 최상위 결과가 문맥을 벗어난 단일 청크가 아닌 광범위한 파일 수준의 관련성을 반영하도록 합니다.
  • 노이즈 페널티 (Noise penalties). 테스트 파일, compat//legacy/ 심 (shims), 예제 코드, 그리고 .d.ts 선언 스텁 (declaration stubs)은 순위가 낮아져 표준 구현 (canonical implementations)이 먼저 나타나도록 합니다.
</details>

임베딩 모델은 정적이며 쿼리 시점에 트랜스포머 (transformer) 순전파 (forward pass)를 수행하지 않기 때문에, 이 모든 과정은 CPU에서 밀리초 (milliseconds) 단위로 실행됩니다.

라이선스 (License)

MIT

인용 (Citing)

연구에 Semble을 사용하는 경우, 다음을 인용해 주세요:

라이선스 (License)

MIT

인용 (Citing)

연구에 Semble을 사용하는 경우, 다음을 인용해 주세요:

@software{minishlab2026semble,
  author       = {van Dongen, Thomas and Stephan Tulkens},
  title        = {Semble: Fast and Accurate Code Search for Agents},
...

AI 자동 생성 콘텐츠

본 콘텐츠는 HN AI Posts의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
1

댓글

0