Semble — MinishLab 为 AI Agent 打造的极速代码搜索库

来源: https://github.com/MinishLab/semble

日期: 2026-05-19

评分: ⭐⭐⭐⭐⭐ (5/5)

一句话版本

Semble 是一个专门给 AI Agent 用的代码搜索工具——你说一句自然语言（比如"这项目怎么处理认证？"），它立刻返回相关的代码片段，不用 grep 扫全文、不用读取整个文件。比 grep+read 省 98% 的 token，全部在 CPU 上跑，零外部依赖。

核心内容

这是什么？

Semble（命名自 "semantic" + "bemble"）是 MinishLab 开源的代码搜索库，专为 AI 编码 Agent 设计。核心思想极其简单：不要让 Agent 为了找一个函数而读取整个文件。

安装方式


pip install semble        # pip 安装
uv tool install semble    # uv 安装

快速上手

MCP 方式（推荐，支持 Claude Code/Cursor/Codex/OpenCode）：


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

AGENTS.md 方式（支持子 Agent）：

在 AGENTS.md 或 CLAUDE.md 中添加：


## Code Search

Use `semble search` to find code by describing what it does or naming a symbol/identifier, instead of grep:

semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project

Use `semble find-related` to discover code similar to a known location:

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

核心性能数据

指标数据
**索引速度**~250 ms（平均仓库）
**查询速度**~1.5 ms
**检索质量**NDCG@10 = 0.854
**变换器对比**99% 质量，218x 更快索引
**Token 节省**比 grep+read 省 ~98%
**召回率**2k tokens 达到 94% recall
**对比**grep+read 需要 100k tokens 才到 85% recall
**运行环境**纯 CPU，无 API key/GPU
**覆盖语言**19 种语言，63 个仓库，~1,250 个查询

工作原理

Semble 的架构分三层：

1. 分块（tree-sitter）

2. 双检索器（Hybrid）

3. 代码感知重排序

三种使用方式

方式适合场景
**MCP Server**主 Agent 直接调用，支持所有 MCP 兼容工具
**AGENTS.md**子 Agent 也支持，Claude Code/Codex CLI 都能用
**Python 库**自定义工具集成

MCP 工具

工具说明
**search**自然语言或代码查询搜索仓库（本地路径或 git URL）
**find_related**给定文件路径和行号，返回语义相似的代码

附加功能：Token 节省统计

semble savings 命令会统计所有搜索节省的 token 数量，存储在 ~/.semble/savings.jsonl：


  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%)

团队

MinishLab 之前以 Model2Vec（静态嵌入框架）和 potion 系列嵌入模型闻名。Semble 实际上是把这些技术应用到代码搜索场景。

已有 fork/port

分析

为什么重要

1. 解决了 Agent 编码的一个核心痛点：编码 Agent 要理解代码库，传统做法是 grep 找位置 → read 读文件。这对于大仓库来说 token 消耗巨大。Semble 直接命中式返回相关片段，省 98% token

2. 零配置、全本地：不需要 API key、不需要 GPU、不依赖网络——这对注重隐私/自托管的开发环境至关重要

3. 技术选型精巧：用 tree-sitter 做代码感知分块 + Model2Vec 做静态嵌入 + BM25 做词法匹配。不需要大模型的前向传播，所以查询只需要 1.5ms

4. 生态兼容性好：Claude Code / Cursor / Codex / OpenCode 全部原生支持，AGENTS.md 和 MCP 两种方式

5. "Token 节省统计"是个好设计：让用户直观感受到价值——不只是一句"节省 98%"，而是实实在在每天省多少 token

与竞品对比

项目方法Token 节省速度需要 GPU？
**Semble**tree-sitter + BM25 + Model2Vec~98%~250ms 索引❌
**grep+read**全文搜索+读文件0%慢❌
**CodeRankEmbed**137M transformer~类似慢 218x✅
**ripgrep**正则搜索~部分极快❌
**probe**代码搜索???

Semble 的独特定位是语义理解 + 极速 + 零依赖的三合一。

潜在不足

与 OpenClaw 场景的关联

OpenClaw 本身就大量使用代码搜索和读取：

评分表

维度评分说明
创新性⭐⭐⭐⭐☆Model2Vec + tree-sitter 代码搜索不是全新概念，但集成得非常好
实用性⭐⭐⭐⭐⭐即装即用，零配置，省 98% token，所有主流 Agent 都支持
技术实现⭐⭐⭐⭐⭐双检索器 + 代码感知重排序，设计精巧
Token 效率⭐⭐⭐⭐⭐2k tokens = 94% recall，数据太漂亮了
与我们关联⭐⭐⭐⭐⭐直接适用于我们所有涉及代码理解的 deep research 任务

关键链接