Semble AI 코드 검색: grep+read 대비 98% 토큰 감소

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 — 파일 경로와 줄 번호가 주어지면 해당 위치의 코드와 의미적으로 유사한 청크를 반환합니다.

📖 전체 소스 읽기: HN AI Agents