Semble - busca de código para agentes que usa 98% menos tokens que o grep

• Semble é uma biblioteca de busca de código criada para que agentes encontrem imediatamente apenas os trechos de código necessários por meio de consultas em linguagem natural ou código
• Em comparação com grep+read, usa cerca de 98% menos tokens e retorna apenas os chunks relevantes em vez de ler arquivos inteiros
• Indexa um repositório médio em cerca de 250 ms e responde a consultas em cerca de 1,5 ms, funcionando em CPU sem chave de API, GPU ou serviços externos
• O benchmark foi realizado com cerca de 1.250 consultas em 63 repositórios de 19 linguagens, e o Semble foi apresentado como alcançando 99% da qualidade do híbrido CodeRankEmbed com indexação 218 vezes mais rápida
• No benchmark de eficiência de tokens, o Semble usou em média 98% menos tokens e atingiu 94% de recall com apenas 2k tokens, enquanto grep+read chegou a 85% de recall com uma janela de contexto de 100k
• Pode ser usado como servidor MCP no Claude Code, Cursor, Codex, OpenCode e agentes compatíveis com MCP; os repositórios são clonados e indexados quando necessário, e o índice fica em cache durante a sessão
• Também oferece suporte a uso baseado em Bash, permitindo inserir os fluxos semble search e semble find-related em AGENTS.md ou CLAUDE.md; essa abordagem é necessária para subagentes do Claude Code e do Codex CLI
• A CLI aceita tanto caminhos locais quanto URLs Git https://, e se path for omitido, o diretório atual é usado como padrão
• Também pode ser usado como biblioteca Python, permitindo integrar a busca em ferramentas personalizadas com SembleIndex.from_path, SembleIndex.from_git, search e find_related
• Internamente, usa tree-sitter para dividir arquivos em chunks com reconhecimento de código, combina embeddings potion-code-16M do Model2Vec com BM25 e une as pontuações com Reciprocal Rank Fusion
• O ranking usa peso lexical para consultas simbólicas, boost para chunks de definição, correspondência por radical de identificadores, relevância dentro do mesmo arquivo e rebaixamento para testes, legacy, exemplos e .d.ts
• Como usa um modelo de embeddings estático, não há transformer forward pass no momento da consulta, o que permite buscas em milissegundos na CPU
• semble savings estima a economia de tokens em cada busca comparando o total de caracteres dos arquivos únicos aos quais os chunks retornados pertencem com os caracteres dos snippets retornados, e as estatísticas são salvas em ~/.semble/savings.jsonl
• O pacote pode ser instalado pelo PyPI como semble, e para uso com MCP utiliza-se uvx --from "semble[mcp]" semble
• A licença é MIT

[GN⁺]

Comentários no Hacker News

• Quando uso ferramentas assim, vejo que, do mesmo jeito que programadores ficam mais burros ao depender demais de ferramentas de IA, a própria IA também fica mais burra
  IAs agenticas já são inteligentes o bastante para encontrar caminhos bem otimizados de exploração e busca em código, mas quando você acopla uma ferramenta dessas, ela tende a agir de forma agressiva demais porque os resultados de busca quase sempre entregam só ponteiros, e não os detalhes completos
  Testei rapidamente com o Pi, mandando rastrear o caminho completo de coleta e busca em um projeto de complexidade razoável, e o codebase-memory-mcp usou 85k/4.4k tokens de entrada/saída, minha configuração normal usou 67k/3.2k, e sem ferramenta nenhuma ficou em 80k/3.2k
  A qualidade do resultado e a quantidade de informação foram as mesmas, e com essa ferramenta ficou um pouco pior, embora não muito
  Minha configuração normal é colocar só uma linha em AGENTS.md e CLAUDE.md: “leia PROJECT.md primeiro”
  Em PROJECT.md, deixo apenas uma descrição do projeto em 2 ou 3 linhas, os arquivos relevantes com uma linha de explicação, pontos de atenção e uma instrução para LLM do tipo “se valer a pena mudar isto, atualize este arquivo. O objetivo deste arquivo é dar uma noção geral do projeto e permitir exploração adicional se necessário”

  • A afirmação de que “IAs agenticas já são inteligentes o bastante para encontrar caminhos altamente otimizados para exploração e busca de código” não bate com a minha experiência
    No trabalho eu usava Augment Code, que tinha um Context Engine parecido com MCP, respondendo consultas em linguagem natural sobre código previamente indexado
    Depois mudei para o Claude Code, e por algum motivo, mesmo tendo ferramenta de leitura por intervalo, ele tenta ler arquivos com sed com base em intervalos de linha que estão na própria memória
    Não sei se isso realmente significa um caminho altamente otimizado
  • codebase-memory-mcp e semble não são exatamente a mesma coisa, mas é uma comparação interessante, então vou colocar na minha lista para verificar e, se possível, incluir nos benchmarks
    Se você tiver a chance de fazer a mesma comparação com semble, isso seria um feedback realmente útil. Esses cenários “reais” são difíceis de medir em benchmark ou reproduzir

• Interessante. Eu também estou trabalhando nessa área, mas segui uma abordagem diferente
  Em vez de criar um índice, fiz um grep mais inteligente para código e texto em geral, com ranqueamento e noção da estrutura do código, e passei a maior parte do tempo lidando com problemas de desempenho, então ele roda muito rápido
  Vou adicionar uma comparação com https://github.com/boyter/cs para ver o que os LLMs preferem para o tipo de pergunta que eu faço
  Isso também oferece MCP, mas não cria índice de busca. Como usa uma variante semântica de código em vez de BM25 puro, estou curioso para ver como o ranqueamento vai sair
  Essa ferramenta parece mais adequada para consultas como “como a autenticação funciona”, enquanto o cs faz authenticate --only-declarations e depois pondera os resultados com base no conteúdo do arquivo, ou seja, se a ocorrência está em código ou comentário, e na complexidade geral do arquivo
  Já dei estrela e vou acompanhar

• Sei que essa ferramenta é voltada para IA, mas o que mais me interessa é usá-la diretamente para explorar um codebase novo ou até o meu próprio
  Parece útil quando quero refatorar algo e preciso ver o panorama geral de onde mexer
  LSP já ajuda nisso, mas essa ferramenta parece poder ir um passo além

• Fiz algumas avaliações com Pi e GPT 5.5
  Testei RTK ligado / headroom ligado / ambos ligados / ambos desligados, todos usando as instruções padrão de sistema do Pi, e sem AGENTS.md
  Não lembro exatamente quais testes eram, mas eram alguns benchmarks padrão de agentes que o pessoal usa, um em Python e outro em TypeScript, que são as linguagens com que trabalho
  Não vou dizer que foi um teste rigoroso ou mesmo um bom teste. Talvez, se eu tivesse passado um dia ajustando AGENTS.md e as instruções de prompt e ferramentas do sistema do Pi, teria conseguido resultados melhores. Uma coisa que aprendi rodando avaliações é que diferenças sutis assim podem mudar muito o resultado
  Mas com ambos desligados ficou claramente melhor, a ponto de eu parar o teste já depois de 3 rodadas
  O problema é que, embora o uso de contexto às vezes caísse, o número de turnos até concluir aumentava, então o custo total da conversa acabava maior
  Isso me fez perceber ainda mais como há muita gente compartilhando ferramentas desse tipo sem avaliação nenhuma, ou com avaliações suspeitamente difíceis de reproduzir, ou, como neste caso, fazendo muitos benchmarks mas medindo a coisa errada
  É verdade que essa ferramenta usa menos tokens do que grep, e o benchmark prova isso, mas isso não é o que importa. O que importa é se o agente consegue fazer o mesmo trabalho com a mesma qualidade, mais rápido e mais barato, usando essa ferramenta

  • Hoje falta teste em toda a indústria de IA
    Não é um problema só desta ferramenta, e sim de tudo que tenta acoplar IA a codebases ou fluxos de desenvolvimento
    Já antes da IA não havia testes para medir “quão rápido e bem isso foi desenvolvido”, e agora também não adicionaram isso
  • Em IA, parece que o “dava para fazer, então não pensamos se deveríamos” vai acontecer com muita frequência

• Eu gostaria de ver benchmarks de agentes reais. Por exemplo, tirar o grep do Claude Code ou do Copilot CLI e colocar essa ferramenta no lugar
  Dei uma olhada em RTK e em várias implementações de LSP, e os modelos foram treinados com reforço tão fortemente em grep que não confiam em outros formatos de resultado e continuam tentando de novo ou relendo
  Aí toda a economia de tokens desaparece porque o modelo não confia na saída da outra ferramenta

  • Coloquei no CLAUDE.md global (~/.Claude) para usar LSP em vez de grep, e depois disso o problema sumiu
  • O Codex CLI roda RTK razoavelmente bem. Pelo menos foi assim com GPT 5.5 xhigh
    Só me incomoda que, quando ele não oferece suporte a certas flags específicas de CLI do find, em vez de mandar a saída completa do comando ele mostra uma mensagem de erro
    Aí o agente desperdiça tokens tentando de novo ou, pior, fica com medo por causa do prompt de que não deve executar o comando sem RTK e nem tenta
  • Também temos interesse nesse tipo de benchmark, e isso está no roadmap junto com otimização de prompts e descrições para facilitar o uso pelo modelo
    É anedótico, mas nós obviamente também usamos essa ferramenta internamente, e até agora ela vem funcionando bem
    Os modelos da Anthropic parecem chamar a ferramenta e confiar no resultado
  • Economizar tokens está ficando cada vez mais importante, mas também importa se o agente confia no resultado e para de procurar
    Não basta olhar a saída da busca; é preciso medir o loop completo do agente
  • Pelo menos o Codex obedece se você disser para usar rg porque grep às vezes é lento demais, mas se você adicionar RTK ele passa a usar grep via RTK, o que é meio irritante

• A ideia parece boa, então fui brincar um pouco com ela
  Fiz o teste no repositório browsercode(https://github.com/browser-use/browsercode) e o prompt foi: “use apenas a CLI do semble; responda quais ferramentas o Browsercode oferece ao agente além das ferramentas padrão do OpenCode. Inclua o schema exato de entrada e saída de cada ferramenta e um breve resumo do que fazem e como funcionam”
  Colei junto um trecho de AGENTS.md de https://github.com/MinishLab/semble#bash-integration
  No teste sem Semble, troquei a pergunta para usar apenas as CLIs rg e fd
  Nos dois casos usei Pi e gpt-5.4 medium, e o resto da configuração foi bem mínima. Também confirmei que em um caso ele realmente só usou rg e fd, e no outro só semble
  Sem Semble, usou 10,9% do contexto do modelo e US$ 0,144 em créditos de API; com Semble, usou 9,8% e US$ 0,172
  As respostas finais também foram quase iguais, então ficou bem próximo
  Fiz outro teste no repositório OpenCode, e a pergunta foi: “rastreie o caminho desde o ponto em que a variável de ambiente OPENCODE_EXPERIMENTAL_EXA é definida como 1 até o efeito disso no prompt de sistema ou nas ferramentas oferecidas ao agente OpenCode”
  Incluí as mesmas instruções e documentos de antes
  A versão sem Semble foi um pouco mais detalhada e também tratou se o caminho de chamada da ferramenta invoca Exa dependendo de Exa ou Parallel estarem ativados como provedores de busca na web, mas ambas as versões responderam corretamente à pergunta em si
  A versão com Semble usou 14,7% de contexto / US$ 0,282 de custo de API, enquanto a versão sem Semble usou 19,0% / US$ 0,352
  Em eficiência de contexto, o Semble venceu com clareza, mas vale notar que a versão sem Semble terminou cerca de duas vezes mais rápido
  Claro, isso foi só uma mexida rápida minha, então os resultados podem variar

• Esse negócio de “usa 98% menos tokens que grep” quer dizer que eu deveria acreditar que o grep é tão desperdiçador assim, a ponto de o modelo estar lendo 98% de lixo inútil toda vez?
  Essa afirmação parece pouco representativa, ou então vocês estão deixando escapar outra coisa ao jogar fora a maior parte do contexto que seria dado ao modelo

  • Os 98% não são comparados só com a saída do grep, mas com o loop grep+read
    Quando o agente encontra um codebase desconhecido, normalmente primeiro faz cat file ou lê o arquivo inteiro. Pelo menos essa tem sido a minha experiência
    Se você está conseguindo fazer o agente ficar só no grep -C N e parar por aí de forma estável, tenho muita curiosidade sobre essa configuração. Na minha opinião, a qualidade do resultado fica baixa demais para servir como contexto útil
  • Tive problema com o Claude lendo centenas de kilobytes de saída por causa de ocorrências em node_modules
    Como o ripgrep ajuda, faz sentido adicionar uma linha em algum arquivo de memória mandando usar isso
  • O grep imprime todas as linhas correspondentes
    Quando um LLM faz algum tipo de busca, pode sair muito ruído, e pode ser necessário fazer isso justamente porque ele não conseguiu procurar de forma mais específica
    Busca orientada por objetivo pode reduzir a quantidade de tokens
    Mas essa comparação parece ser entre receber só os trechos necessários e ler o codebase inteiro

• Como feedback, o codex-cli trava ao chamar isso via MCP
  O processo semble também fica preso como zumbi e trava para sempre. Não sei por quê, e não aparece nada nos logs
  Quando chamo pelo modo de CLI via skill, o GPT 5.5 parece tão acostumado com ripgrep que tenta jogar um monte de consultas de busca diferentes
  Não sei quão eficaz isso é, e com a documentação curta do GitHub e as instruções de agente não fica claro qual é o ideal
  Por fim, também tive algumas falhas de conexão externa ao instalar para bash fora do GitHub. Não sei se isso tem relação com o travamento
  Além disso, meu agente ainda tenta usar ripgrep depois, então parece redundante. Ele age como se tivesse problema de confiança
  Se houvesse uma descrição mais detalhada da skill do agente, acho que daria para guiá-lo melhor para o uso correto

  • Obrigado pelo feedback detalhado
    Seria ótimo se você pudesse abrir uma issue com os detalhes da configuração para esse bug. Com certeza é algo que queremos investigar e corrigir
    Esse comportamento de disparar várias consultas também é um feedback muito bom, e vamos tentar atualizar os prompts e as instruções para evitar isso, além de adicionar testes relacionados
    Quanto aos erros de conexão externa na instalação, parece que vieram do uv buscando dependências no PyPI, e provavelmente não são a causa do travamento

• Parece uma boa ideia
  Um problema relacionado é que, em codebases pequenos, o Claude às vezes poderia simplesmente colocar o projeto inteiro no contexto de uma vez e processar tudo com muito poucos tokens, mas em vez disso gasta bastante tempo procurando coisa
  Uma gambiarra aceitável é usar um hook de início para jogar o diretório inteiro no contexto
  Aí o Claude pula aquela fase de “tatear no escuro” em cada tarefa
  Também já vi um ótimo projeto que dava ao modelo uma visão geral com stubs em repositórios maiores, mas esqueci o nome

  • Talvez seja o aider? https://aider.chat/2023/10/22/repomap.html
  • Faz sentido. Agentes não têm muita noção do que estão vendo, como quantidade de arquivos ou tamanho dos arquivos
    Mesmo assim, em codebases pequenos, também é mais fácil encontrar o que se procura, então a busca ainda pode ajudar a reduzir custo

• O problema maior dessas soluções é que a maioria das IAs já usa grep e busca muito bem por causa do treinamento
  Dar uma ferramenta nova para a IA faz com que ela perca parte da própria capacidade cognitiva
  Humanos em geral “aprenderiam” a usar esse tipo de ferramenta, mas o aprendizado dos LLMs é fixo, e eles já têm proficiência muito profunda em ferramentas existentes como grep
  Por exemplo, a IA já sabe explorar codebases com comandos Linux como tree, e isso também foi amplamente aprendido
  Outro problema é que é fácil criar exemplos que mostrem utilidade para esse tipo de ferramenta, mas é difícil provar de fato que, em execuções longas, a perda cognitiva que ela provoca é compensada pelo ganho de utilidade
  Minha intuição inicial é que, no longo prazo, haverá perda líquida de inteligência implantável, deixando o agente pior do que quando usa ferramentas já existentes
  Provar o contrário não é uma questão trivial, mas talvez seja um desafio que valha a pena enfrentar