MinishLab/semble

Semble – Fast, token‑efficient code search for AI coding agents

What it is – Semble is a Python library / CLI / MCP‑compatible server that lets large‑language‑model‑based coding assistants (Claude Code, Cursor, Codex, OpenCode, etc.) retrieve the exact code snippets they need from a repository. It does this with ~99 % fewer tokens than a naïve “grep + read‑full‑file” approach, while keeping retrieval quality on par with a 137 M‑parameter code‑specialised transformer.

Why it matters – Agents often have to explore unfamiliar code bases. Pulling whole files into the model’s context is expensive and slow. Semble indexes a repo in ~0.5 s and answers a natural‑language query in ~1 ms on a CPU, so the agent can get just the relevant chunk instantly, without any API keys, GPUs, or external services.

Key features

Speed – Index an average repo in ~500 ms; query latency ~1 ms (CPU only). 340× faster indexing and 17× faster querying than a comparable transformer‑based retriever.
Accuracy – NDCG@10 = 0.854 on the authors’ benchmark, matching a 137 M‑parameter model.
Token efficiency – Returns only the needed snippets, saving ~99 % of the tokens that would be spent reading full files.
Zero‑setup – No GPU, no API keys, just pip/uv install.
MCP server – Exposes search and find_related as native tools for any MCP‑compatible agent.
Local & remote repos – Accepts a filesystem path or a Git URL.
Fine‑grained control – .gitignore and a dedicated .sembleignore let you include/exclude files and extensions.
Cache & stats – Indexes and token‑savings statistics are cached; semble savings shows how many tokens have been avoided.

Quick start (CLI)

# install the tool (requires uv)
uv tool install semble
semble install          # interactive – picks agents & integration type

# basic search in a local repo
semble search "authentication flow" ./my-project

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

# limit results, show only a few snippet lines, or search docs/config
semble search "deployment guide" ./my-project --content docs --top-k 5 --max-snippet-lines 10

Use semble uninstall to remove the integration, or semble clear … to wipe caches.

Using as a Python library

from semble import ContentType, SembleIndex

# build an index (cached on first use)
idx = SembleIndex.from_path("./my-project", content=ContentType.CODE)
# or include docs/config
# idx = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS])

# natural‑language or code query
results = idx.search("save model to disk", top_k=3)
for r in results:
    print(r.chunk.file_path, r.chunk.start_line, r.chunk.content[:120])

# find code similar to a location
related = idx.find_related(results[0], top_k=3)

The library is useful for building custom tooling or embedding search directly in your own applications.

MCP server mode

When installed as an MCP tool, agents can call:

Tool	Description
`search`	Natural‑language or code query over a repo (local path or Git URL).
`find_related`	Given a file path + line number, return semantically similar chunks.
Setup instructions are in `docs/installation.md#mcp-server`.

How it works under the hood

Chunking – Files are split into code‑aware chunks using tree‑sitter.
Dual retrievers –
- Model2Vec static embeddings (potion‑code‑16M‑v2) give semantic similarity.
- BM25 provides fast lexical matching on identifiers and API names.
Fusion – Scores from both retrievers are combined with Reciprocal Rank Fusion.
Reranking – Adaptive weighting, definition boosts, identifier‑stem matches, file‑coherence bonuses, and noise penalties refine the final order.
Caching – Indexes are stored on disk; incremental updates occur when files change, avoiding full rebuilds.
Model flexibility – Set SEMBLE_MODEL_NAME to point at a custom Model2Vec model if desired.

All of this runs in milliseconds on a single CPU core because the embedding model is static (no transformer forward pass at query time).

Benchmarks (as reported)

Quality – NDCG@10 = 0.854 across 63 repos, 19 languages, comparable to the 137 M‑parameter CodeRankEmbed model.
Speed – Indexing 340× faster, querying 17× faster than the transformer baseline.
Token savings – ~99 % fewer tokens than a grep‑plus‑read baseline; at 2 k tokens the system reaches 97 % recall, whereas grep‑plus‑read needs ~100 k tokens for 85 % recall. Full benchmark details are in benchmarks/README.md.

Installation & cache locations

Install via uv (uv tool install semble) or pip install semble.
Cache directory defaults to the OS cache location (~/.cache/semble on Linux, etc.). Override with SEMBLE_CACHE_LOCATION.
Model files are cached in the standard Hugging‑Face cache (~/.cache/huggingface).
Files larger than 1 MiB are skipped by default; adjust with SEMBLE_MAX_FILE_BYTES.

License & citation

License: MIT (permissive, commercial‑friendly).
Citation: Use the provided BibTeX entry (Zenodo DOI 10.5281/zenodo.19785932) for academic work.

Bottom line

Semble gives AI coding assistants a local, fast, and token‑cheap way to retrieve exactly the code they need, eliminating the need for costly API calls or large context windows. It works out‑of‑the‑box as a CLI, a Python library, or an MCP server, making it a practical addition to any LLM‑powered development workflow.