Semble

Semble is a code search library developed by MinishLab, designed for AI agents to efficiently navigate codebases without wasting context windows. It employs a dual-path hybrid retrieval architecture: a semantic path using Model2Vec + potion-code-16M static embedding model (16M params, zero Transformer inference overhead), a lexical path using bm25s BM25 retrieval, with results fused via RRF and reranked using code-aware signals (adaptive weighting, definition boosting, identifier stem matching, file coherence, noise penalization). All computation runs on CPU — indexing an average repository takes ~250ms, queries ~1.5ms. In a benchmark of ~1,250 queries across 63 repos and 19 languages, it achieves NDCG@10 of 0.854, matching 99% of a 137M-parameter model's retrieval quality. Compared to grep+read, it reduces token usage by ~98% and achieves 94% recall at just 2k token budget. Available as Python API (SembleIndex class), CLI tool, and native MCP server, integrated with Claude Code, Cursor, Codex, and OpenCode. Supports local directories and remote Git repos with file watch and session-level caching. Current version v0.1.3, Beta status, MIT licensed.

Installation & Quick Start#

pip install semble
uv add semble

MCP server installation (Claude Code example):

claude mcp add semble -s user -- uvx --from "semble[mcp]" semble

Python API example:

from semble import SembleIndex
index = SembleIndex.from_path("./my-project")
results = index.search("save model to disk", top_k=3)
related = index.find_related(results[0], top_k=3)

CLI example:

semble search "authentication flow" ./my-project
semble find-related src/auth.py 42 ./my-project
semble init   # Generate Claude Code sub-agent template

Core Dependencies#

• model2vec>=0.4.0 — Static embedding generation
• vicinity>=0.4.4 — Vector similarity search
• bm25s>=0.2.0 — BM25 lexical retrieval
• chonkie[code]!=1.6.3 — Code-aware chunking
• numpy>=1.24.0 — Numerical computation
• pathspec>=0.12 — File path matching

Optional dependency groups: mcp (mcp>=1.0,<2.0, watchfiles>=0.21), benchmark, dev.

Unconfirmed Information#

• First release date: CITATION.cff date-released is 2026-04-26, possibly a placeholder
• Maximum supported repository scale: README does not specify upper limits
• Training data details for potion-code-16M: HuggingFace model card not reviewed
• MCP server session cache lifecycle: documented only as "cached for the lifetime of the session"
• Full list of 19 supported languages: not enumerated in documentation
• find_related implementation mechanism: unclear whether direct vector retrieval or additional computation