Semble: grep+read보다 98% 적은 토큰을 사용하는 AI 에이전트용 코드 검색

Semble은 Claude Code, Cursor, Codex, OpenCode와 같은 AI 코딩 에이전트를 위해 특별히 제작된 빠르고 토큰 효율적인 코드 검색 라이브러리입니다. 자연어나 코드 쿼리에서 관련 코드 스니펫을 반환하며, 일반적인 grep+read 대비 약 98% 적은 토큰을 사용합니다.

작동 방식

Semble은 정적 Model2Vec 임베딩(자체 potion-code-16M 모델 사용)과 BM25를 결합하고, RRF로 융합한 후 코드 인식 신호로 재순위화합니다. 모든 계산은 CPU에서 실행되며 GPU, API 키, 외부 서비스가 필요하지 않습니다. 평균 저장소 인덱싱은 약 250ms, 쿼리는 CPU에서 약 1.5ms에 완료됩니다.

주요 특징

• 토큰 효율적: grep+read보다 98% 적은 토큰 사용 — 관련 청크만 반환합니다.
• 빠름: 일반 저장소를 약 250ms에 인덱싱, 쿼리당 약 1.5ms (매우 큰 저장소는 더 오래 걸릴 수 있음).
• 정확함: 63개 저장소와 19개 언어에 걸친 약 1250개 쿼리/문서 쌍의 벤치마크에서 0.854 NDCG@10 — 최고의 트랜스포머 설정(1억 3700만 파라미터)의 99% 품질을 약 200배 빠른 인덱싱과 약 10배 빠른 쿼리로 달성합니다.
• 설정 불필요: API 키, GPU, 외부 서비스가 필요하지 않습니다.
• MCP 서버: Claude Code, Cursor, Codex, OpenCode 및 모든 MCP 호환 에이전트에 바로 사용 가능합니다.
• 로컬 및 원격: 로컬 경로 또는 git URL을 전달할 수 있습니다. 인덱스는 세션별로 캐시되며 파일 변경 시 자동 업데이트됩니다.

설치 및 설정

MCP 서버 (에이전트 권장)

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": {
      "type": "local",
      "command": ["uvx", "--from", "semble[mcp]", "semble"]
    }
  }
}

Cursor의 경우 ~/.cursor/mcp.json 또는 .cursor/mcp.json에 추가:

{
  "mcpServers": {
    "semble": {
      "command": "uvx",
      "args": ["--from", "semble[mcp]", "semble"]
    }
  }
}

Bash 통합 (대안)

pip 또는 uv로 설치한 후 AGENTS.md 또는 CLAUDE.md에 코드 검색 스니펫을 추가합니다:

pip install semble
uv tool install semble

그런 다음 AGENTS.md에 추가:

## Code Search
`grep` 대신 `semble search`를 사용하여 기능 설명이나 기호/식별자 이름으로 코드를 검색하세요:
```bash
semble search "authentication flow" ./my-project
```

MCP 도구

MCP 서버는 두 가지 도구를 제공합니다:

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