Работа ИИ-ассистентов с большими кодовыми базами упирается в одну и ту же проблему: агент не знает структуры проекта и вынужден искать нужный код через текстовый поиск. На монорепе с сотнями тысяч строк это означает серию grep-запросов с разными вариациями ключевых слов, чтение десятков файлов подряд и быстрое заполнение контекстного окна нерелевантным содержимым. Класс, который называется IdentityVerifier, а не AuthHandler, при таком подходе просто не найдётся.
SocratiCode — open-source MCP-сервер, который решает эту задачу через предварительную индексацию кодовой базы. Вместо того чтобы каждый раз заново обходить файлы, агент обращается к готовому индексу через набор инструментов: семантический поиск, анализ графа зависимостей, поиск по контекстным артефактам. Лицензия AGPL-3.0, есть коммерческий вариант. Всё работает локально — код не отправляется во внешние сервисы.
| Метрика | Результат (SocratiCode vs grep) |
|---|---|
| Объём контекста в LLM | -61% |
| Число вызовов инструментов | -84% |
| Время выполнения задачи | в 37 раз быстрее |
Технически сервер построен на четырёх компонентах. Qdrant хранит векторные индексы с HNSW-индексированием. Ollama обеспечивает локальные эмбеддинги по умолчанию, при желании можно подключить OpenAI или Gemini. Ast-grep отвечает за разбивку кода на чанки и анализ зависимостей для 18+ языков программирования. Docker — единственное обязательное требование: при первом запуске SocratiCode сам подтягивает нужные образы и поднимает контейнеры.
Гибридный поиск объединяет семантические dense-векторы и лексический BM25 через алгоритм RRF без ручной настройки весов.
Ключевая инженерная идея — гибридный поиск. На каждый чанк кода в Qdrant записывается не один вектор, а два: dense (семантический) и sparse BM25 (лексический). При запросе оба поиска выполняются параллельно в одном round-trip, результаты объединяются через алгоритм RRF — Reciprocal Rank Fusion. Формула простая: для каждого документа суммируется 1/(k+rank) по всем поисковикам, в которых он встретился. Это позволяет не настраивать веса вручную и при этом покрывать слепые зоны каждого метода: семантический поиск находит концептуально близкий код даже без точного совпадения слов, BM25 точно ловит конкретные идентификаторы и имена функций.
Чанкинг устроен нестандартно. Вместо разбивки по фиксированному числу строк файлы режутся по границам функций и классов через AST-парсинг. Это критично для качества семантического поиска: модель эмбеддингов работает значительно лучше, когда на входе законченный логический блок, а не случайный фрагмент с обрезанной серединой метода. Для языков без поддержки AST система переключается на построчное разбиение.
Отдельный инструмент — граф зависимостей. SocratiCode строит его через статический анализ импортов (import, require, use, include) и обновляет при изменениях файлов. Агент может запросить, какие модули зависят от конкретного файла, или найти циклические зависимости — последние визуализируются через Mermaid-диаграммы. Для рефакторинга это заменяет серию ручных grep-запросов одним структурным вызовом.
Функция контекстных артефактов позволяет индексировать не только код, но и схемы БД, OpenAPI-спецификации, Terraform-конфиги, архитектурные документы. Они хранятся в отдельном поисковом индексе и настраиваются через файл .socraticodecontextartifacts.json в корне проекта. После этого агент может отвечать на вопросы вроде «какие таблицы участвуют в авторизации» без явного указания файлов.
Авторы провели бенчмарк на репозитории VS Code — 2,45 млн строк кода — с использованием Claude Opus 4.6. По их данным, SocratiCode сокращает объём контекста, уходящего в LLM, на 61%, число вызовов инструментов — на 84%, а время выполнения задач — в 37 раз по сравнению с grep-based подходом. К этим цифрам стоит подходить осторожно: бенчмарк выполнен самими авторами на задачах, которые они выбрали. Разрыв в 37 раз характерен для архитектурных запросов, где агент без индекса вынужден рекурсивно обходить файлы. На точечных задачах — найти определение конкретной функции — grep по-прежнему эффективен и разрыв будет значительно меньше.
Практические наблюдения при тестировании на монорепе около 800 тысяч строк (Python + TypeScript + Go): заметное улучшение на концептуальных запросах вида «где обрабатывается валидация входных данных API». Без SocratiCode агент последовательно ищет «validation», «validate», «schema», затем начинает читать middleware. С индексом — один вызов возвращает несколько релевантных мест с разными формулировками. Первичная индексация 200 тысяч строк на M2 Pro заняла около минуты.
