Semble发布：面向AI代理的极简高效代码搜索库

Semble 是一个专为智能体构建的代码搜索库。它能即时返回智能体所需的精确代码片段，相比 grep+read 方法节省约 98% 的 token，并减少每一步的延迟。对整个代码库进行端到端的索引和搜索只需不到一秒，与专门的代码 Transformer 模型相比，索引速度快约 200 倍，查询速度快约 10 倍，同时保持其 99% 的检索质量（参见基准测试）。一切都在 CPU 上运行，无需 API 密钥、GPU 或外部服务。你可以将其作为 MCP 服务器运行，或通过 AGENTS.md 从 shell 调用，任何智能体（Claude Code、Cursor、Codex、OpenCode 等）都能立即访问任何仓库。

快速入门

你的智能体在需要查找代码时会自动使用 Semble。它不再使用关键字进行 grep 并读取整个文件，而是用自然语言进行查询（例如“身份验证是如何处理的？”），并只返回相关的上下文。Semble 可以设置为 MCP 服务器或 bash 工具：

MCP

将 Semble 添加到 Claude Code（需要 uv）：

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

使用其他智能体框架？请参阅 MCP 服务器部分，了解 Codex、OpenCode、Cursor 和其他 MCP 客户端的设置说明。

Bash / AGENTS.md

首先安装 Semble，然后将代码搜索片段添加到你的 AGENTS.md 或 CLAUDE.md 文件中：

`bash
pip install semble # 使用 pip 安装
uv tool install semble # 或使用 uv 安装
`

注意：对于 Claude Code 或 Codex CLI 的子智能体，请使用 bash 集成，而不是 MCP，或与 MCP 一起使用。

要更新 Semble，请参阅更新部分。

想知道 Semble 为你节省了多少 token 吗？运行 semble savings 查看。详情请参阅节省部分。

主要特性

- 快速：在 CPU 上，平均约 250 毫秒即可索引一个仓库，约 1.5 毫秒即可回答查询。
- 准确：在我们的基准测试中，NDCG@10 达到 0.854，与专门的代码 Transformer 模型性能相当，但体积和成本却小得多。
- Token 高效：仅返回相关的代码块，比 grep+read 方法节省约 98% 的 token。
- 零设置：在 CPU 上运行，无需 API 密钥、GPU 或外部服务。
- MCP 服务器：可直接用于 Claude Code、Cursor、Codex、OpenCode 以及任何其他兼容 MCP 的智能体。
- 本地和远程：支持本地路径或 git URL。

MCP 服务器

Semble 可以作为 MCP 服务器运行，这样智能体就可以直接搜索任何代码库。仓库会根据需要被克隆和索引，并且在会话期间索引会被缓存。本地路径会被监视文件更改并自动重新索引。

设置

需要安装 uv。

#### Claude Code

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

#### Codex

添加到 ~/.codex/config.toml：

`toml
[mcp_servers.semble]
command = "uvx"
args = ["--from", "semble[mcp]", "semble"]
`

#### OpenCode

添加到 ~/.opencode/config.json：

`json
{
"mcp": {
"semble": {
"type": "local",
"command": ["uvx", "--from", "semble[mcp]", "semble"]
}
}
}
`

#### Cursor

添加到 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

`json
{
"mcpServers": {
"semble": {
"command": "uvx",
"args": ["--from", "semble[mcp]", "semble"]
}
}
}
`

工具

Bash 集成

MCP 的替代方案是通过 Bash 调用 Semble。对于 Claude Code 和 Codex CLI，这是子智能体的唯一选择，因为它们无法直接调用 MCP 工具（两者仅在顶层智能体处延迟加载 MCP 模式）。

要添加 Bash 支持，请将以下内容附加到你的 AGENTS.md 或 CLAUDE.md 文件中：

`markdown
## 代码搜索

使用 semble search 通过描述代码功能或命名符号/标识符来查找代码，而不是使用 grep：

`bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10
`

使用 semble find-related 来发现与已知位置相似的代码（从之前的搜索结果中传递 file_path 和 line）：

`bash
semble find-related src/auth.py 42 ./my-project
`

省略时，path 默认为当前目录；接受 git URL。

如果 semble 不在 $PATH 中，请使用 uvx --from "semble[mcp]" semble 代替。

工作流程

1. 从 semble search 开始，找到相关的代码块。
2. 仅在返回的代码块上下文不足时，检查完整文件。
3. 可选地，使用 semble find-related 并传入一个有希望结果的 file_path 和 line，以发现相关的实现。
4. 仅在你需要穷举的字面匹配或快速确认确切字符串时使用 grep。
`

Claude Code 子智能体：Claude Code 也支持专用的子智能体。在你的项目根目录下运行一次此命令：

`bash
semble init
# 或者，如果 semble 不在 $PATH 中：
uvx --from "semble[mcp]" semble init
`

这将写入 .claude/agents/semble-search.md 文件。

CLI

Semble 也作为独立的 CLI 工具提供，用于 MCP 之外的环境。这在脚本中或任何你希望在没有 MCP 会话的情况下获得搜索结果时非常有用。

`bash
# 搜索本地仓库
semble search "authentication flow" ./my-project

# 搜索符号或标识符
semble search "save_pretrained" ./my-project

# 搜索远程仓库（按需克隆）
semble search "save model to disk" https://github.com/MinishLab/model2vec

# 查找与已知位置相似的代码（来自先前搜索结果的 file_path 和 line）
semble find-related src/auth.py 42 ./my-project
`

省略时，path 默认为当前目录；接受 git URL。

如果 semble 不在 $PATH 中，请使用 uvx --from "semble[mcp]" semble 代替。

节省

semble savings 显示 Semble 在你所有搜索中节省的 token 数量：

`bash
semble savings # 按时间段汇总
semble savings --verbose # 同时显示按调用类型的细分
`

`
Semble Token Savings
════════════════════════════════════════════════════════════════
Period Calls Savings
────────────────────────────────────────────────────────────────
Today 42 [███████████████░] ~58.4k tokens (95%)
Last 7 days 287 [██████████████░░] ~312.4k tokens (90%)
All time 1.4k [██████████████░░] ~1.2M tokens (89%)
`

节省的计算方式：对于每次调用，semble 会记录包含返回代码块的唯一文件的总字符数以及返回的代码片段的字符数。估计节省的 token 数为（文件字符数 - 片段字符数）/ 4（每 token 4 个字符）。这是一个保守的估计：基准是完整读取匹配的文件，这也是编码智能体探索不熟悉代码的常见方式。

统计数据存储在 ~/.semble/savings.jsonl 文件中。

更新

要将 Semble 更新/升级到最新版本：

`bash
pip install --upgrade semble # 使用 pip
uv tool upgrade semble # 使用 uv
uv cache clean semble # 对于 MCP 用户（之后重启你的 MCP 客户端）
`

Python API

Semble 也可以作为 Python 库用于编程访问，这在构建自定义工具或将搜索直接集成到你自己的代码中时非常有用。

`python
from semble import SembleIndex

# 索引本地目录
index = SembleIndex.from_path("./my-project")

# 索引远程 git 仓库
index = SembleIndex.from_git("https://github.com/MinishLab/model2vec")

# 使用自然语言或代码查询搜索索引
results = index.search("save model to disk", top_k=3)

# 查找与特定结果相似的代码
related = index.find_related(results[0], top_k=3)

# 每个结果都公开匹配的代码块
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, ..."
`

工作原理

Semble 使用 Chonkie 将每个文件分割成代码感知的代码块，然后使用两个互补的检索器对每个查询与代码块进行评分：使用代码专用模型 potion-code-16M 进行语义相似性匹配的静态 Model2Vec 嵌入，以及用于标识符和 API 名称词法匹配的 BM25。两个分数列表使用倒数排名融合（RRF）进行融合。

融合后，结果会使用一组代码感知信号进行重新排序：

排序信号

- 自适应加权。类似符号的查询（Foo::bar、_private、getUserById）获得更多的词法权重，而自然语言查询则在语义和词法检索器之间保持平衡。
- 定义提升。定义了查询符号（类、def、func 等）的代码块排名高于仅引用它的代码块。
- 标识符词干。查询 token 被提取词干并与代码块中的标识符词干进行匹配，为包含它们的代码块提供额外的权重。例如，查询 parse config 会提升包含 parseConfig、ConfigParser 或 config_parser 的代码块。
- 文件一致性。当来自同一文件的多个代码块匹配查询时，该文件会被提升，以便顶部结果反映广泛的文件级相关性，而不是单个脱离上下文的代码块。
- 噪声惩罚。测试文件、compat//legacy/ 垫片、示例代码和 .d.ts 声明存根会被降级，以便规范实现优先显示。

由于嵌入模型是静态的，在查询时没有 Transformer 前向传递，所有这些都在 CPU 上以毫秒级完成。

基准测试

我们在 19 种语言的 63 个仓库上，对约 1250 个查询的所有方法进行了质量和速度基准测试。x 轴是总延迟（索引 + 首次查询）；y 轴是 NDCG@10。标记大小反映模型参数数量。

Semble 实现了 137M 参数的 CodeRankEmbed Hybrid 99% 的性能，同时索引速度快 218 倍，查询速度快 11 倍。请参阅基准测试部分，了解按语言划分的结果、消融研究和详细方法。

Token 效率

使用 grep+read 的智能体将其大部分上下文预算浪费在不相关的代码上。Semble 只返回匹配的代码块，即使在高召回率下也能保持较低的 token 使用量。

Semble 平均使用 98% 更少的 token，并且仅需 2k token 的预算即可达到 94% 的召回率，而 grep+read 需要完整的 100k 上下文窗口才能达到 85% 的召回率。详情请参阅基准测试部分。

许可

MIT

引用

如果你在研究中使用 Semble，请引用以下内容：

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