Semble

Búsqueda de código rápida y precisa para agentes
_{Usa ~99% menos tokens que grep+read}

Semble es una biblioteca de búsqueda de código construida para agentes. Devuelve los fragmentos de código exactos que necesitan al instante, usando ~99% menos tokens que grep+read. Indexar y buscar un código completo de principio a fin toma menos de un segundo para la mayoría de los repositorios, igualando la calidad de recuperación de un transformador especializado en código mientras indexa ~380x más rápido y consulta ~17x más rápido (ver benchmarks). Todo se ejecuta en CPU sin claves API, GPU ni servicios externos. Úsalo como servidor MCP, herramienta CLI mediante AGENTS.md, o sub-agente dedicado, y cualquier agente de codificación (Claude Code, Cursor, Codex, OpenCode, etc.) obtiene acceso instantáneo a cualquier repositorio.

Inicio rápido

Tu agente consulta a Semble en lenguaje natural (p. ej. "How is authentication handled?") y recibe solo los fragmentos de código relevantes, sin hacer grep ni leer archivos completos.

La forma más rápida de empezar es el instalador interactivo. Instala uv y luego ejecuta:

uv tool install semble
semble install

semble install detecta agentes de codificación instalados como Claude Code, Codex y OpenCode, y luego te permite elegir qué integraciones habilitar:

• Servidor MCP: permite que el agente llame a Semble directamente como herramienta.
• Instrucciones: añade guía de uso de CLI a AGENTS.md / CLAUDE.md.
• Sub-agente: instala un sub-agente dedicado semble-search.

Para deshacer la configuración, ejecuta semble uninstall.

Para instrucciones de configuración manual (config MCP por agente, fragmento de AGENTS.md, archivos de sub-agente), consulta la documentación de instalación.

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

Características principales

• Rápido: indexa un repositorio promedio en ~500 ms y responde consultas en ~1 ms, todo en CPU.
• Preciso: NDCG@10 de 0.854 en nuestros benchmarks, a la par de modelos transformadores especializados en código, a una fracción del tamaño y costo.
• Eficiente en tokens: devuelve solo los fragmentos relevantes, usando ~99% menos tokens que grep+read.
• Cero configuración: se ejecuta en CPU sin claves API, GPU ni servicios externos requeridos.
• Servidor MCP: funciona con Claude Code, Cursor, Codex, OpenCode, VS Code y cualquier otro agente compatible con MCP.
• Local y remoto: pasa una ruta local o una URL de git, o varias de ellas para buscar repositorios relacionados juntos.

CLI

Semble también se distribuye como CLI independiente. Esto es útil en scripts o en cualquier lugar donde quieras resultados de búsqueda sin una sesión MCP. Los índices se construyen y cachean en la primera ejecución, y se invalidan automáticamente cuando los archivos cambian.

# 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 acepta code (predeterminado), docs, config o all. --format acepta json (predeterminado) o text. path se establece por defecto en el directorio actual cuando se omite; se aceptan URLs de git. Si semble no está en $PATH, usa uvx --from "semble[mcp]" semble en su lugar. semble --version (o -V) imprime la versión instalada.

Pasar varias rutas o URLs las busca como un solo corpus, de modo que una consulta del repositorio A puede encontrar un endpoint definido en el repositorio B. Cada índice se cachea por repositorio y se fusiona en el momento de la consulta. Las rutas de resultados se prefijan con el nombre del repositorio (service-b/api/invoices.py) y la salida incluye un mapa repos de prefijo a ruta absoluta o URL. Pasa la ruta prefijada a find-related para buscar en todos los repositorios desde una ubicación conocida.

# .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

Semble se ejecuta como servidor MCP para que los agentes puedan buscar cualquier código base directamente como una llamada de herramienta nativa. Los repositorios se indexan bajo demanda y se cachean; las rutas locales se reindexan automáticamente cuando los archivos cambian.

Para instrucciones de configuración por agente, consulta la documentación de instalación.

Benchmarks

Evaluamos calidad y velocidad en ~1,250 consultas sobre 63 repositorios en 19 idiomas (izquierda), y eficiencia de tokens contra grep+read en niveles de recuperación equivalentes (derecha).

El benchmark de calidad (izquierda) puntúa la calidad de recuperación (NDCG@10) contra la latencia total; semble iguala la calidad del CodeRankEmbed de 137M de parámetros mientras indexa 380x más rápido. El benchmark de eficiencia de tokens (derecha) mide cuántos tokens necesita cada método para alcanzar un nivel de recuperación dado; semble usa 99% menos tokens en promedio y alcanza 97% de recuperación con solo 2k tokens, mientras que grep+read necesita una ventana de contexto completa de 100k para alcanzar 85%. Consulta benchmarks para resultados por idioma, ablaciones y metodología completa.

Cómo funciona

Semble divide cada archivo en fragmentos conscientes del código usando tree-sitter, luego puntúa cada consulta contra los fragmentos con dos recuperadores complementarios: incrustaciones estáticas Model2Vec usando el modelo especializado en código potion-code-16M-v2 para similitud semántica, y BM25 para coincidencias léxicas en identificadores y nombres de API. Las dos listas de puntuaciones se fusionan con Reciprocal Rank Fusion (RRF).

Después de la fusión, los resultados se reordenan con un conjunto de señales conscientes del código:

Debido a que el modelo de incrustación es estático sin pase directo de transformador en el momento de la consulta, todo esto se ejecuta en milisegundos en CPU.

Los índices se cachean en disco automáticamente en la primera búsqueda. En ejecuciones posteriores, Semble recorre el árbol de archivos y compara los tiempos de modificación; los archivos añadidos, eliminados o modificados se reindexan incrementalmente, sin reconstruir el resto del índice. Una reconstrucción completa solo ocurre si cambian los ajustes de indexación (p. ej., después de una actualización de semble que cambie el modelo, la fragmentación o el formato de caché). En modo MCP, el índice se verifica y actualiza automáticamente a medida que los archivos cambian, de modo que los resultados se mantienen actualizados durante la sesión.

Usar un modelo personalizado

Si deseas usar otro modelo, puedes configurar tu variable de entorno SEMBLE_MODEL_NAME a una ruta local o repositorio de Hugging Face. Esta ruta se lee literalmente y debe contener un modelo compatible con Model2Vec. Esto es particularmente útil si no puedes acceder a Hugging Face en tiempo de ejecución.

Agradecimientos

Gracias a Greptile por proporcionar acceso gratuito a su plataforma de revisión de código con IA.

Licencia

MIT

Cómo citar

Si utilizas Semble en tu investigación, por favor cita lo siguiente:

@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}
}