MinishLab/semble

Fast and Accurate Code Search for Agents
_{Uses ~98% fewer tokens than grep+read}

Semble 是一个为智能体构建的代码搜索库。它能在瞬间返回智能体所需的精确代码片段，使用的 token 比 grep+read 少约 98%。端到端索引和搜索整个代码库不到一秒，索引速度比代码专用 transformer 快约 200 倍，查询速度快约 10 倍，检索质量达到其 99%（参见[基准测试](#benchmarks)）。所有功能均在 CPU 上运行，无需 API 密钥、GPU 或外部服务。可作为 [MCP 服务器](#mcp-server)运行，或通过 [AGENTS.md](#agentsmd)从 shell 调用，任何智能体（Claude Code、Cursor、Codex、OpenCode 等）都能即时访问任何仓库。 ## 快速入门 你的智能体可以用自然语言查询 Semble（例如 `"身份验证是如何处理的？"`），仅返回相关代码片段，无需 grep 或读取完整文件。 Semble 有三种互补的补充设置路径。推荐同时使用全部三种方式（但你可以根据需求选择）： - **[MCP 服务器](#mcp-server)**：为你的智能体提供一个 MCP 服务器。 - **[AGENTS.md](#agentsmd)**：一段 AGENTS.md 代码片段，包含通过 CLI 调用 Semble 的说明。 - **[子智能体](#sub-agent-setup)**：一个专用的 `semble-search` 子智能体，适用于支持此功能的框架。 ### MCP 通过 MCP 将 Semble 作为原生工具暴露，使你的智能体可以直接调用。将其添加到 Claude Code（需要 [uv](https://docs.astral.sh/uv/getting-started/installation/))： ``` claude mcp add semble -s user -- uvx --from "semble[mcp]" semble ``` 其他框架（Cursor、Codex、OpenCode 等）的设置请参见下文 [MCP 服务器](#mcp-server)。 ### AGENTS.md 将 Semble 使用说明添加到智能体的上下文中，使其知道何时以及如何调用 CLI。安装 Semble CLI，然后将以下代码片段添加到你的 `AGENTS.md` 或 `CLAUDE.md`： ``` uv tool install semble # Install with uv (recommended) pip install semble # Or with pip ```

AGENTS.md / CLAUDE.md 代码片段

``` ## 代码搜索 Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of 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 ​``` If you anticipate doing more than one search, use `semble index` to create an index. ​```bash semble index ./my-project -o my_index ​``` You can then reuse this index later on: ​```bash semble search "save_pretrained" --index my_index ​``` An index is not automatically updated, so if the code changes significantly, reindex. If you notice stale results while resolving searches to files, reindex. Use `--content docs` to search documentation and prose, `--content config` for config files (yaml, toml, etc.), or `--content all` to search code, docs, and config: ​```bash semble search "deployment guide" ./my-project --content docs semble search "database host port" ./my-project --content config semble search "authentication" ./my-project --content all ​``` Use `semble find-related` to discover code similar to a known location (pass `file_path` and `line` from a prior search result): ​```bash semble find-related src/auth.py 42 ./my-project ​``` Like search, `find-related` also accepts an `--index` argument. `path` defaults to the current directory when omitted; git URLs are accepted. If `semble` is not on `$PATH`, use `uvx --from "semble[mcp]" semble` in its place. ### 工作流 1. Index the repo using `semble index -o cached_index`. 2. Start with `semble search` to find relevant chunks. Pass the index to achieve results faster. 3. Use `--content docs` for documentation, `--content config` for config files, or `--content all` for everything. 4. Inspect full files only when the returned chunk does not give enough context. 5. Optionally use `semble find-related` with a promising result's `file_path` and `line` to discover related implementations. 6. Use grep only when you need exhaustive literal matches or quick confirmation of an exact string. ```

### 子智能体 对于支持子智能体的框架，安装一个专用的 `semble-search` 子智能体，使搜索在独立的上下文中运行（需要 CLI）： ``` semble init # Claude Code → .claude/agents/semble-search.md ``` 其他框架（Cursor、Codex、OpenCode 等）的设置请参见下文[子智能体设置](#sub-agent-setup)。

更新 Semble

``` uv tool upgrade semble # with uv uv cache clean semble # for MCP users (restart your MCP client after) pip install --upgrade semble # with pip ```

## 主要功能 - **快速**：在 CPU 上平均约 250 毫秒完成仓库索引，约 1.5 毫秒回答查询。 - **准确**：在我们的[基准测试](#benchmarks)中 NDCG@10 达到 0.854，与代码专用 transformer 模型相当，而体积和成本仅为其一小部分。 - **节省 token**：仅返回相关代码块，使用的 token 比 [grep+read 少约 98%](#benchmarks)。 - **零配置**：在 CPU 上运行，无需 API 密钥、GPU 或外部服务。 - **MCP 服务器**：兼容 Claude Code、Cursor、Codex、OpenCode、VS Code 及其他任何 MCP 兼容智能体。 - **本地和远程**：可传入本地路径或 git URL。 ## MCP 服务器 Semble 可作为 MCP 服务器运行，使智能体能够直接搜索任何代码库。仓库按需克隆和索引，缓存在会话期间有效。本地路径会被监控文件变更并自动重新索引。 ### 设置

Claude Code

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

Cursor

添加到 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）： ``` { "mcpServers": { "semble": { "command": "uvx", "args": ["--from", "semble[mcp]", "semble"] } } } ```

Codex

添加到 `~/.codex/config.toml`： ``` [mcp_servers.semble] command = "uvx" args = ["--from", "semble[mcp]", "semble"] ```

OpenCode

添加到 `~/.opencode/config.json`： ``` { "mcp": { "semble": { "type": "local", "command": ["uvx", "--from", "semble[mcp]", "semble"] } } } ```

VS Code

添加到项目中的 `.vscode/mcp.json`（或用户配置文件的 `mcp.json`）： ``` { "servers": { "semble": { "command": "uvx", "args": ["--from", "semble[mcp]", "semble"] } } } ```

GitHub Copilot CLI

添加到 `~/.copilot/mcp-config.json`： ``` { "mcpServers": { "semble": { "command": "uvx", "args": ["--from", "semble[mcp]", "semble"] } } } ```

Windsurf

添加到 `~/.codeium/windsurf/mcp_config.json`： ``` { "mcpServers": { "semble": { "command": "uvx", "args": ["--from", "semble[mcp]", "semble"] } } } ```

Gemini CLI

添加到 `~/.gemini/settings.json`： ``` { "mcpServers": { "semble": { "command": "uvx", "args": ["--from", "semble[mcp]", "semble"] } } } ```

Kiro

添加到 `~/.kiro/settings/mcp.json`（或项目中的 `.kiro/settings/mcp.json`）： ``` { "mcpServers": { "semble": { "command": "uvx", "args": ["--from", "semble[mcp]", "semble"] } } } ```

Zed

添加到 `~/.config/zed/settings.json`（或项目中的 `.zed/settings.json`）： ``` { "context_servers": { "semble": { "command": "uvx", "args": ["--from", "semble[mcp]", "semble"] } } } ```

### 工具 | 工具 | 描述 | |------|-------------| | `search` | 使用自然语言或代码查询搜索代码库。`repo` 参数可传入本地目录路径或 https:// git URL。 | | `find_related` | 给定文件路径和行号，返回与该位置代码语义相似的代码块。 | 默认情况下，MCP 服务器仅索引代码文件。若要同时索引文档、配置文件或所有内容，可在服务器命令后追加 `--content docs`、`--content config` 或 `--content all`，或组合使用，例如 `--content code docs`。例如在 Claude Code 中：`claude mcp add semble -s user -- uvx --from "semble[mcp]" semble --content all`。 ## 子智能体设置 Claude Code、Gemini CLI、Cursor、OpenCode、GitHub Copilot CLI 和 Kiro 均支持专用的 semble 搜索子智能体。在你的项目根目录运行一次 `semble init`： ``` semble init # Claude Code → .claude/agents/semble-search.md semble init --agent gemini # Gemini CLI → .gemini/agents/semble-search.md semble init --agent cursor # Cursor → .cursor/agents/semble-search.md semble init --agent opencode # OpenCode → .opencode/agents/semble-search.md semble init --agent copilot # Copilot CLI → .github/agents/semble-search.md semble init --agent kiro # Kiro → .kiro/agents/semble-search.md ``` 如果 semble 不在 `$PATH` 中，请在命令前加上 `uvx --from "semble[mcp]"`。 ## CLI Semble 也提供独立的 CLI 工具。适用于脚本中或任何不需要 MCP 会话即可获取搜索结果的场景。 ``` # 搜索本地仓库 semble search "authentication flow" ./my-project # 先建立索引以加快重复搜索（--index 可与以下任何命令配合使用） semble index ./my-project -o my-index semble search "authentication flow" --index my-index # 搜索远程仓库（按需克隆） semble search "save model to disk" https://github.com/MinishLab/model2vec # 限制结果数量 semble search "save model to disk" ./my-project --top-k 10 # 搜索文档/配置/全部内容，而不仅仅是代码 semble search "deployment guide" ./my-project --content docs # or: config, all # 查找与已知位置相似的代码 semble find-related src/auth.py 42 ./my-project ``` `--content` 接受 `code`（默认）、`docs`、`config` 或 `all`。`path` 省略时默认为当前目录；支持 git URL。如果 `semble` 不在 `$PATH` 中，请使用 `uvx --from "semble[mcp]" semble` 替代。

节省统计

`semble savings` 显示 Semble 在所有搜索中节省的 token 数量： ``` semble savings # summary by period semble savings --verbose # also show breakdown by call type ``` ``` 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 也可用作 Python 库进行编程访问，适用于构建自定义工具或将搜索直接集成到你自己的代码中。 ``` from semble import ContentType, SembleIndex # 索引本地目录（仅限代码，默认） index = SembleIndex.from_path("./my-project") # 索引文档和文本（markdown、rst 等） index = SembleIndex.from_path("./my-project", content=ContentType.DOCS) # 索引所有内容（代码、文档和配置） index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS, ContentType.CONFIG]) # 同时索引代码和文档 index = SembleIndex.from_path("./my-project", content=[ContentType.CODE, ContentType.DOCS]) # 索引远程 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, ..." ```

## 基准测试 我们在 19 种语言的约 63 个仓库中的约 1,250 个查询上对质量和速度进行了基准测试（左图），并在等效召回率水平下与 grep+read 进行了 token 效率对比（右图）。 质量基准测试（左图）以总延迟评估检索质量（NDCG@10）；semble 在索引速度快 218 倍的情况下，达到了 1.37 亿参数 [CodeRankEmbed](https://huggingface.co/nomic-ai/CodeRankEmbed) Hybrid 99% 的质量。token 效率基准测试（右图）衡量每种方法达到给定召回率所需的 token 数；semble 平均少用 98% 的 token，仅用 2k token 就达到 94% 召回率，而 grep+read 需要完整的 100k 上下文窗口才能达到 85%。每种语言的结果、消融实验和完整方法论请参见[基准测试](benchmarks/README.md)。 ## 工作原理 Semble 使用 [tree-sitter](https://github.com/tree-sitter/py-tree-sitter) 将每个文件拆分为代码感知的代码块，然后通过两种互补的检索器对每个查询与代码块进行评分：静态 [Model2Vec](https://github.com/MinishLab/model2vec) 嵌入使用代码专用的 [potion-code-16M](https://huggingface.co/minishlab/potion-code-16M) 模型进行语义相似度计算，以及 [BM25](https://github.com/xhluca/bm25s) 用于标识符和 API 名称的词汇匹配。两个分数列表通过 Reciprocal Rank Fusion (RRF) 融合。 融合后，结果通过一组代码感知信号进行重排序：

排序信号

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

由于嵌入模型是静态的，查询时无需 transformer 前向传播，所有操作均在 CPU 上毫秒级完成。 ## 许可证 MIT ## 引用 如果你在研究中使用 Semble，请引用以下内容： ``` @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} } ```

标签：AGENTS.md, Claude Code, Codex, CPU推理, Cursor, grep替代, MCP Server, OpenCode, 代码上下文, 代码分析, 代码匹配, 代码向量, 代码导航, 代码嵌入, 代码库索引, 代码建议, 代码推荐, 代码提示, 代码搜索, 代码搜索工具, 代码智能, 代码查询, 代码检索, 代码片段, 代码片段提取, 代码理解, 代码生成, 代码相似性, 代码索引, 代码补全, 代码语义, 低Token消耗, 凭证管理, 开源, 快速索引, 无API Key, 无GPU, 智能搜索, 本地部署, 检索质量, 渗透测试工具, 端到端搜索, 自然语言查询, 语义搜索, 逆向工具