Semble

Busca de Código Rápida e Precisa para Agentes
_{Usa ~99% menos tokens do que grep+read}

Semble é uma biblioteca de busca de código construída para agentes. Ela retorna os trechos de código exatos que eles precisam instantaneamente, usando ~99% menos tokens do que grep+read. Indexar e buscar um codebase completo de ponta a ponta leva menos de um segundo para a maioria dos repositórios, igualando a qualidade de recuperação de um transformer especializado em código enquanto indexa ~380x mais rápido e consulta ~17x mais rápido (veja benchmarks). Tudo roda em CPU sem chaves de API, GPU ou serviços externos. Use como um servidor MCP, uma ferramenta CLI via AGENTS.md, ou um sub-agente dedicado, e qualquer agente de codificação (Claude Code, Cursor, Codex, OpenCode, etc.) terá acesso instantâneo a qualquer repositório.

Quickstart

Seu agente consulta o Semble em linguagem natural (ex.: "How is authentication handled?") e recebe de volta apenas os trechos de código relevantes, sem precisar usar grep ou ler arquivos completos.

A maneira mais rápida de começar é o instalador interativo. Instale o uv e então execute:

uv tool install semble
semble install

semble install detecta agentes de codificação instalados, como Claude Code, Codex e OpenCode, e então permite que você escolha quais integrações habilitar:

• Servidor MCP: permite que o agente chame o Semble diretamente como uma ferramenta.
• Instruções: adiciona orientações de uso da CLI ao AGENTS.md / CLAUDE.md.
• Sub-agente: instala um sub-agente semble-search dedicado.

Para desfazer a configuração, execute semble uninstall.

Para instruções de configuração manual (config MCP por agente, trecho AGENTS.md, arquivos de sub-agente), veja a documentação de instalação.

uv tool upgrade semble   # upgrade
uv cache clean semble    # for MCP users (restart your MCP client after)

semble install --agent claude --type mcp subagent --yes

Principais Recursos

• Rápido: indexa um repositório médio em ~500 ms e responde consultas em ~1 ms, tudo em CPU.
• Preciso: NDCG@10 de 0,854 em nossos benchmarks, no mesmo nível de modelos transformer especializados em código, a uma fração do tamanho e custo.
• Eficiente em tokens: retorna apenas os trechos relevantes, usando ~99% menos tokens do que grep+read.
• Zero configuração: roda em CPU sem chaves de API, GPU ou serviços externos necessários.
• Servidor MCP: funciona com Claude Code, Cursor, Codex, OpenCode, VS Code e qualquer outro agente compatível com MCP.
• Local e remoto: passe um caminho local ou uma URL git, ou vários deles para buscar repositórios relacionados juntos.

CLI

O Semble também é distribuído como uma CLI independente. Isso é útil em scripts ou em qualquer lugar onde você queira resultados de busca sem uma sessão MCP. Os índices são construídos e armazenados em cache na primeira execução e invalidados automaticamente quando os arquivos mudam.

# Search a local repo (index is built and cached automatically)
semble search "authentication flow" ./my-project

# Search a remote repo (cloned on demand)
semble search "save model to disk" https://github.com/MinishLab/model2vec

# Search several repos at once (results are prefixed with the repo name)
semble search "invoice endpoint" ./service-a ./service-b

# Limit results
semble search "save model to disk" ./my-project --top-k 10

# Search docs/config/everything instead of just code
semble search "deployment guide" ./my-project --content docs   # or: config, all

# Find code similar to a known location
semble find-related src/auth.py 42 ./my-project

# Show only the first N lines of each result's snippet (0 = path/line range only)
semble search "authentication flow" ./my-project --max-snippet-lines 10

--content aceita code (padrão), docs, config ou all. --format aceita json (padrão) ou text. path usa o diretório atual por padrão quando omitido; URLs git são aceitas. Se semble não estiver em $PATH, use uvx --from "semble[mcp]" semble em seu lugar. semble --version (ou -V) imprime a versão instalada.

Passar vários caminhos ou URLs os busca como um único corpus, então uma consulta do repositório A pode encontrar um endpoint definido no repositório B. Cada índice é armazenado em cache por repositório e mesclado no momento da consulta. Os caminhos dos resultados são prefixados com o nome do repositório (service-b/api/invoices.py) e a saída inclui um mapa repos de prefixo para caminho absoluto ou URL. Passe o caminho prefixado para find-related para buscar em todos os repositórios a partir de um local conhecido.

# .sembleignore
generated/     # exclude generated dir
*.pb.go.       # exclude Go protobuf files

# .sembleignore
!*.proto       # include Protobuf files
!*.cob         # include COBOL files

semble savings

  Semble Token Savings
  ════════════════════════════════════════════════════════════════════════

  Total saved:  ~714.2M tokens  (94%)
  Total calls:  14.3k
  Efficiency:  ███████████████████████░  94%

  By Period
  ────────────────────────────────────────────────────────────────────────
  Period             Calls           Saved  Ratio
  ────────────────────────────────────────────────────────────────────────
  Today                198    ~1.4M tokens  ███████████████████████░  95%
  Last 7 days        13.1k  ~707.2M tokens  ███████████████████████░  94%
  All time           14.3k  ~714.2M tokens  ███████████████████████░  94%

  By Call Type
  ────────────────────────────────────────────────────────────────────────
  #     Call type            Calls  Share
  ────────────────────────────────────────────────────────────────────────
  1.    search               14.1k  ████████████████    99%
  2.    find_related           205  █░░░░░░░░░░░░░░░     1%
  ════════════════════════════════════════════════════════════════════════

from semble import ContentType, SembleIndex

# Index a local directory (code only, the default)
index = SembleIndex.from_path("./my-project")

# Index docs and prose (markdown, rst, etc.)
index = SembleIndex.from_path("./my-project", content=ContentType.DOCS)

# Index everything (code, docs, and config)
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS, ContentType.CONFIG])

# Index code and docs together
index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# Index a remote git repository
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# Merge indexes from several repos into one (chunk paths are prefixed with the repo name)
index = SembleIndex.merge([("./service-a", SembleIndex.from_path("./service-a")), ("./service-b", SembleIndex.from_path("./service-b"))])

# Search the index with a natural-language or code query
results = index.search("save model to disk", top_k=3)

# Find code similar to a specific result
related = index.find_related(results[0], top_k=3)

# Each result exposes the matched chunk
result = results[0]
result.chunk.file_path   # "model2vec/model.py"
result.chunk.start_line  # 127
result.chunk.end_line    # 150
result.chunk.content     # "def save_pretrained(self, path: PathLike, ..."

Servidor MCP

O Semble roda como um servidor MCP para que agentes possam buscar em qualquer codebase diretamente como uma chamada de ferramenta nativa. Repositórios são indexados sob demanda e armazenados em cache; caminhos locais são reindexados automaticamente quando os arquivos mudam.

Para instruções de configuração por agente, veja a documentação de instalação.

Benchmarks

Avaliamos qualidade e velocidade em ~1.250 consultas em 63 repositórios em 19 linguagens (esquerda), e eficiência de tokens contra grep+read em níveis de recall equivalentes (direita).

O benchmark de qualidade (esquerda) pontua a qualidade de recuperação (NDCG@10) contra a latência total; o semble iguala a qualidade do CodeRankEmbed de 137M de parâmetros enquanto indexa 380x mais rápido. O benchmark de eficiência de tokens (direita) mede quantos tokens cada método precisa para atingir um determinado nível de recall; o semble usa 99% menos tokens em média e atinge 97% de recall com apenas 2k tokens, enquanto grep+read precisa de uma janela de contexto completa de 100k para atingir 85%. Veja benchmarks para resultados por linguagem, ablações e metodologia completa.

Como funciona

O Semble divide cada arquivo em trechos cientes de código usando tree-sitter, então pontua cada consulta contra os trechos com dois recuperadores complementares: embeddings estáticos Model2Vec usando o modelo potion-code-16M-v2 especializado em código para similaridade semântica, e BM25 para correspondências lexicais em identificadores e nomes de API. As duas listas de pontuação são fundidas com Reciprocal Rank Fusion (RRF).

Após a fusão, os resultados são reordenados com um conjunto de sinais cientes de código:

Como o modelo de embeddings é estático, sem passagem direta de transformer no momento da consulta, tudo isso roda em milissegundos em CPU.

Os índices são armazenados em cache no disco automaticamente na primeira busca. Em execuções subsequentes, o Semble percorre a árvore de arquivos e compara os tempos de modificação; arquivos adicionados, removidos ou alterados são reindexados incrementalmente, sem reconstruir o resto do índice. Uma reconstrução completa só acontece se as configurações de indexação mudarem (ex.: após uma atualização do semble que altere o modelo, a divisão em trechos ou o formato do cache). No modo MCP, o índice é verificado e atualizado automaticamente conforme os arquivos mudam, então os resultados permanecem atuais durante a sessão.

Usando um modelo personalizado

Se você quiser usar outro modelo, pode definir sua variável de ambiente SEMBLE_MODEL_NAME para um caminho local ou repositório Hugging Face. Este caminho é lido literalmente e deve conter um modelo compatível com Model2Vec. Isso é particularmente útil se você não puder acessar o Hugging Face em tempo de execução.

Agradecimentos

Agradecemos à Greptile por fornecer acesso gratuito à sua plataforma de revisão de código com IA.

Licença

MIT

Citação

Se você usar o Semble em sua pesquisa, por favor cite o seguinte:

@software{minishlab2026semble,
  author       = {{van Dongen}, Thomas and Stephan Tulkens},
  title        = {Semble: Fast and Accurate Code Search for Agents},
  year         = {2026},
  publisher    = {Zenodo},
  doi          = {10.5281/zenodo.19785932},
  url          = {https://github.com/MinishLab/semble},
  license      = {MIT}
}