Semble: локальный поиск по коду для ИИ-агентов, который тратит на 98% меньше токенов, чем grep — VogueTech

Что нового

Semble — это локальная библиотека и CLI для поиска по коду, заточенная под ИИ-агентов (Claude Code, Cursor, Codex, OpenCode и другие MCP-клиенты).

Главные цифры:

~98% меньше токенов, чем классическая схема grep + чтение файлов.
Индексирование репозитория в среднем за ~250 мс на CPU.
Ответ на запрос — ~1,5 мс на CPU.
Скорость индексирования ~200× выше, чем у специализированного кодового трансформера.
Запросы ~10× быстрее, чем у такого же трансформера.
При этом Semble даёт 99% качества извлечения по метрике NDCG@10 относительно гибридного метода CodeRankEmbed Hybrid.
Качество поиска: NDCG@10 = 0,854 на ~1250 запросах по 63 репозиториям на 19 языках.
Всё работает локально на CPU, без API-ключей, GPU и внешних сервисов.

Semble:

Умеет работать как MCP‑сервер для Claude Code, Cursor, Codex, OpenCode и других MCP‑клиентов.
Умеет работать как CLI через Bash и через файл AGENTS.md / CLAUDE.md.
Принимает локальный путь к проекту или git‑URL (репозиторий клонируется по запросу).
Ведёт статистику экономии токенов и показывает её командой semble savings.

Для разработчика это означает: агент больше не читает целые файлы через LLM, а получает только релевантные куски кода и тратит гораздо меньше контекста и времени.

Как это работает

Под капотом Semble использует комбинацию семантического и лексического поиска, плюс набор ранжирующих сигналов, специально заточенных под код.

Разбиение кода

Semble разбивает файлы на кодовые чанки с помощью инструмента Chonkie.
Каждый чанк содержит фрагмент кода с привязкой к файлу и номерам строк.

Два типа ретриверов

Semble считает релевантность каждого чанка по двум независимым методам и потом их объединяет:

Семантические эмбеддинги (Model2Vec)
- Используется статическая модель potion-code-16M, обученная на коде.
- Для каждого чанка заранее считается вектор.
- При запросе агент получает вектор запроса и сравнивает его с векторами чанков.
BM25
- Классический лексический поиск.
- Хорошо ловит совпадения по идентификаторам, API‑именам, символам.

Semble объединяет ранги двух поисков с помощью Reciprocal Rank Fusion (RRF) — это метод, который берёт два списка результатов и даёт общий рейтинг, учитывая позиции результатов в каждом списке.

Реранжирование с кодовыми сигналами

После фьюжна Semble ещё раз упорядочивает результаты с учётом структуры кода:

Адаптивное распределение веса между семантическим и лексическим поиском.
- Если запрос похож на символ (Foo::bar, _private, getUserById), Semble сильнее опирается на лексический слой.
- Если запрос в естественном языке ("как устроена аутентификация"), веса семантики и лексики сбалансированы.
Буст определений символов.
- Чанки, где символ определяется (класс, def, функция и т.п.), поднимаются выше, чем чанки, где он только используется.
Работа с основами идентификаторов.
- Semble стеммит токены запроса и ищет совпадения с основами идентификаторов в чанке.
- Например, запрос parse config поднимет чанки с parseConfig, ConfigParser, config_parser.
Когерентность файла.
- Если несколько чанков из одного файла хорошо матчатся с запросом, весь файл получает дополнительный вес.
- В топе оказывается файл, который релевантен в целом, а не случайный фрагмент.
Штраф за "шумовые" файлы.
- Тесты, compat/, legacy/, шимирующие модули, примеры, .d.ts‑заглушки опускаются ниже.
- На первом месте оказываются основные реализации.

Ключевой момент: эмбеддинги статичны, на запросе нет прогона трансформера, поэтому всё работает за миллисекунды на CPU.

Что это значит для вас

Когда Semble помогает

Semble особенно полезен, если вы:

Активно пользуетесь Claude Code, Cursor, Codex, OpenCode или другими агентами, которые:
- часто делают grep по репозиторию;
- читают файлы целиком через LLM;
- упираются в лимит контекста.
Работаете с большими кодовыми базами, где "читать глазами" или grep уже не помогают быстро понять:
- как устроена аутентификация;
- где сохраняется модель на диск;
- как реализован конкретный сервис или адаптер.
Хотите уменьшить стоимость и задержку при работе с LLM‑агентами:
- Semble возвращает только нужные чанки, а не весь файл;
- агент тратит на порядок меньше токенов на контекст;
- вы платите меньше за запросы к GPT‑5, Claude 3.7 и другим моделям.
Пишете свои инструменты поверх LLM и хотите встроить быстрый локальный поиск по коду через Python API.

Когда Semble не подойдёт

Если вы не используете ИИ‑агентов и вам достаточно ripgrep + IDE, выгода будет меньше. Semble всё равно удобен как умный поиск, но ключевой профит в экономии токенов.
Если вы строите пайплайн, который обязан просканировать каждый символ в репозитории (строгий статический анализ, массовые рефакторинги), Semble не заменит grep или специализированные анализаторы.
Если ваш процесс завязан на полностью удалённой инфраструктуре без доступа к локальным машинам, придётся интегрировать Semble либо через удалённый сервер, либо не использовать его.

Доступность из России

Semble — это локальный инструмент на Python, без привязки к внешним API. Для установки через pip или uv обычно не нужен VPN, если у вас есть доступ к PyPI. Но сами агенты, с которыми вы будете его использовать (Claude Code, Cursor, Codex), могут требовать VPN или обходные пути — это зависит от их политики и вашего провайдера.

Место на рынке

Semble напрямую конкурирует не с LLM, а с системами поиска по коду и вспомогательными агентами.

По результатам бенчмарка (~1250 запросов, 63 репозитория, 19 языков):

| Метод | NDCG@10 | Время индексации | p50 запроса | |------------------------|---------|-------------------|-------------| | CodeRankEmbed Hybrid | 0,862 | 57 с | 16 мс | | Semble | 0,854 | 263 мс | 1,5 мс | | CodeRankEmbed | 0,765 | 57 с | 16 мс | | ColGREP | 0,693 | 5,8 с | 124 мс | | BM25 | 0,673 | 263 мс | 0,02 мс | | grepai | 0,561 | 35 с | 48 мс | | probe | 0,387 | — | 207 мс | | ripgrep | 0,126 | — | 12 мс |

Ключевые выводы:

Semble даёт 99% качества гибридного CodeRankEmbed Hybrid (0,854 против 0,862 по NDCG@10).
При этом индексирует код в 218 раз быстрее (263 мс против 57 секунд).
И отвечает на запросы примерно в 11 раз быстрее (1,5 мс против 16 мс).
По сравнению с grep/ripgrep Semble намного лучше понимает смысл запроса, но остаётся достаточно быстрым для интерактивного использования.

По токен‑эффективности:

Semble в среднем использует на 98% меньше токенов, чем стратегия grep + чтение файлов.
При бюджете 2k токенов Semble достигает 94% recall.
Для сравнения, grep + чтение файлов требует 100k токенов, чтобы выйти только на 85% recall.

Semble занимает нишу "умного локального ретривера" для агентов: почти трансформерное качество поиска, но с задержками и стоимостью классического поиска по тексту.

Установка

Semble можно поставить через pip или uv.

pip install semble          # Установка через pip
uv tool install semble      # Или установка через uv

Для обновления до последней версии:

pip install --upgrade semble   # Обновление через pip
uv tool upgrade semble         # Обновление через uv
uv cache clean semble          # Для MCP-пользователей (после — перезапустите MCP-клиент)

Как запустить: MCP‑сервер

Semble может работать как MCP‑сервер. В этом режиме агенты напрямую ищут по любому репозиторию.

Репозитории по git URL клонируются и индексируются по запросу.
Индексы кешируются на время сессии.
Локальные пути отслеживаются на изменения и переиндексируются автоматически.

Требование: установлен uv.

Claude Code

claude mcp add semble -s user -- uvx --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 " ] } } }

Cursor

Добавьте в ~/.cursor/mcp.json (или .cursor/mcp.json в корне проекта):

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

MCP‑инструменты

Semble предоставляет два MCP‑инструмента:

search — поиск по коду по естественному языку или фрагменту кода. Параметр repo принимает локальный путь или https:// git‑URL.
find_related — по file_path и номеру строки возвращает чанки, семантически похожие на код вокруг этой строки.

Как запустить: Bash / AGENTS.md

Если агент не умеет напрямую вызывать MCP (например, суб‑агенты в Claude Code или Codex CLI), Semble можно подключить через Bash.

Установите Semble (см. раздел "Установка").
Добавьте в 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:
```bash
semble search "authentication flow" ./my-project
semble search "save_pretrained" ./my-project
semble search "save model to disk" ./my-project --top-k 10
```
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
```
` 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.

## Workflow
1 . Start with ` semble search ` to find relevant chunks.
2 . Inspect full files only when the returned chunk is not enough context.
3 . Optionally use ` semble find-related ` with a promising result's ` file_path ` and ` line ` to discover related implementations.
4 . Use grep only when you need exhaustive literal matches or quick confirmation of an exact string.

Sub‑агент Claude Code

Claude Code поддерживает отдельный суб‑агент для Semble. В корне проекта выполните:

semble init
# или, если semble не в $PATH:
uvx --from " semble[mcp] " semble init

Эта команда создаст файл .claude/agents/semble-search.md.

CLI: использование без MCP

Semble можно запускать как обычную CLI‑утилиту — удобно для скриптов и CI.

# Поиск по локальному репо
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 считает, сколько токенов вы сэкономили, и показывает статистику:

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 считает суммарное число символов во всех файлах, где есть возвращённые чанки.
И количество символов в самих чанках, которые он вернул.
Оценка токенов: (символы в файлах − символы в чанках) / 4 (приблизительно 4 символа на токен).

Это консервативная оценка: базовый сценарий — агент читает все совпавшие файлы целиком, что часто и происходит в реальной работе.

Статистика хранится в ~/.semble/savings.jsonl.

Python API

Если вы строите свои инструменты, Semble можно использовать как библиотеку.

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 в свои агенты, IDE‑плагины или внутренние сервисы поиска по коду.

Итог: кому стоит попробовать

Semble имеет смысл поставить, если:

вы активно используете Claude Code, Cursor, Codex, OpenCode и хотите, чтобы агенты меньше тратили токенов и быстрее находили нужный код;
у вас есть средние и крупные репозитории, в которых классический grep уже не даёт удобной картины;
вы строите свои LLM‑инструменты и вам нужен быстрый локальный ретривер по коду с Python API.

Если вы пишете небольшие проекты в одиночку и почти не пользуетесь ИИ‑агентами, Semble может оказаться избыточным. В остальных сценариях это сильный кандидат на роль основного "глаза" агента в вашем коде.