面向 AI Agent 的极速代码搜索库，通过混合检索与代码感知重排序，比 grep+read 节省约 98% token。
Semble 是由 MinishLab 开发的面向 AI Agent 的代码搜索库，旨在解决 Agent 在代码导航中上下文窗口浪费严重的问题。其核心采用双路混合检索架构：语义路基于 Model2Vec + potion-code-16M 静态嵌入模型（16M 参数，无 Transformer 推理开销），词法路基于 bm25s 的 BM25 检索，两路结果通过 RRF 融合后经代码感知重排序（自适应权重、定义提升、标识符词干匹配、文件连贯性、噪声惩罚）。全部运算在 CPU 上完成，索引平均仓库约 250ms，查询约 1.5ms。在约 1,250 条查询、63 个仓库、19 种语言的基准测试中 NDCG@10 达 0.854，接近 137M 参数模型 99% 的检索质量；相比 grep+read 平均减少约 98% token，2k token 预算下 recall 达 94%。提供 Python API（SembleIndex 类）、CLI 工具和原生 MCP 服务器三种使用形态，已适配 Claude Code、Cursor、Codex、OpenCode 等 Agent 平台。支持本地目录和远程 Git 仓库索引，内置文件变更监听与会话级缓存。当前版本 v0.1.3，开发状态为 Beta，采用 MIT 许可证。
安装与快速开始#
pip install semble
uv add semble
MCP 服务器安装（Claude Code 示例）：
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble
Python API 示例：
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 示例：
semble search "authentication flow" ./my-project
semble find-related src/auth.py 42 ./my-project
semble init # 生成 Claude Code 子 Agent 模板
核心依赖#
model2vec>=0.4.0— 静态嵌入生成vicinity>=0.4.4— 向量相似度搜索bm25s>=0.2.0— BM25 词法检索chonkie[code]!=1.6.3— 代码感知分块numpy>=1.24.0— 数值计算pathspec>=0.12— 文件路径匹配
可选依赖组：mcp（mcp>=1.0,<2.0、watchfiles>=0.21）、benchmark、dev。
待确认信息#
- 首次发布日期：CITATION.cff 中
date-released为 2026-04-26，可能为占位或未来日期 - 最大支持仓库规模：README 未明确给出支持的代码库规模上限
- 嵌入模型 potion-code-16M 的训练数据详情：HuggingFace 模型卡未在本次调查中查阅
- MCP 服务器会话级缓存的具体生命周期管理：文档仅提及 "cached for the lifetime of the session"
- 多语言支持的具体列表：提及 19 种语言但未列出完整清单
find_related的实现机制：文档未明确是直接向量检索还是额外计算