Что такое Archex и зачем он нужен
Archex - это инструмент с открытым исходным кодом под лицензией Apache 2.0, который преобразует репозиторий в ранжированный пакет контекста с контролем токенов. Он решает конкретную боль: AI-агенты кодинга часто получают нерелевантные файлы, что ведёт к ошибкам и галлюцинациям. Archex гарантирует, что в контекст попадут только нужные файлы, причём локально и без внешних зависимостей.
Инструмент использует гибридный подход: BM25F для ранжирования по ключевым словам, локальные эмбеддинги для семантического поиска и графовое расширение, которое подтягивает файлы, связанные через импорты, типы и вызывающие функции. Поддерживаются 26 языков программирования. Результат - recall нужных файлов 0.95 на тестовом наборе из 19 задач. Холодный старт занимает 0 мс. Никаких API-ключей, телеметрии или внешнего хостинга.
Если вы уже экспериментировали с личными ИИ-агентами и сталкивались с тем, что модель «забывает» ключевые модули проекта, Archex закрывает этот разрыв на уровне инфраструктуры контекста.
Почему контекст репозитория - это критично для AI-кодинга
AI-агенты кодинга работают по простой схеме: получают запрос, отбирают фрагмент кодовой базы и отправляют его вместе с промптом в модель. Если контекст неполный, модель не видит определения типов или сигнатуры функций. Если избыточный - выходит за лимит токенов или теряет фокус. Проблема «мусор на входе - мусор на выходе» здесь проявляется особенно остро.
Традиционные подходы дают сбои. Простой grep находит строки, но не понимает семантику. Эмбеддинги захватывают смысл, но пропускают точные совпадения по названиям. Ни один из методов по отдельности не обеспечивает полноты. Archex предлагает принципиально иной подход - гибридное ранжирование с графовым расширением, где каждый компонент компенсирует слабости другого.
Эта проблема хорошо знакома тем, кто разбирал архитектуру самописных AI-агентов: качество контекста прямо влияет на reliability агента сильнее, чем смена модели.
Как Archex достигает recall 0.95: архитектура и алгоритмы
Archex выстраивает трёхступенчатый конвейер. Первая ступень - BM25F - ранжирует файлы по релевантности запросу, учитывая структуру документа: имя файла, код, комментарии. Вторая - локальные эмбеддинги - находит семантически близкий код, даже если точного совпадения слов нет. Третья - графовое расширение - добавляет файлы, связанные с уже найденными через импорты, определения типов и граф вызовов.
На тестовом наборе из 19 задач Archex показал recall 0.95. Для сравнения: cocoindex-code - 0.32, Graphify - 0.70. Холодный старт Archex - 0 мс, тогда как cocoindex-code требует 4.7 секунды, а Graphify - 937 мс. Разрыв объясняется архитектурой: Archex не загружает тяжёлые модели при старте и не требует предварительной индексации облачных сервисов.
BM25F и локальные эмбеддинги: гибридный поиск
BM25F - модификация классического BM25 для структурированных документов. В отличие от обычного BM25, который считает документ «мешком слов», BM25F назначает разные веса полям: совпадение в имени файла или сигнатуре функции важнее, чем в теле комментария. Это повышает точность ранжирования на 15-20% по сравнению с обычным BM25 на кодовых базах.
Локальные эмбеддинги добавляют семантическое измерение. Они находят код, который делает то же самое, но написан иначе - например, реализацию паттерна «фабрика» под разными именами. Гибридный подход объединяет результаты обоих методов, переранжируя выдачу так, чтобы точные и семантические совпадения дополняли друг друга.
Графовое расширение: импорты, типы и вызывающие функции
После ранжирования Archex строит граф зависимостей и расширяет контекст. Если найденный файл импортирует модуль - этот модуль добавляется. Если использует тип - файл с определением типа включается. Если вызывает функцию - её определение попадает в контекст автоматически. Это гарантирует, что модель получит все файлы, необходимые для компиляции и понимания кода.
Пример: агент ищет «как обрабатывается ошибка подключения к базе данных». BM25F находит файл с вызовом handle_db_error(). Графовое расширение добавляет файл с определением этой функции и файл с типами исключений. Без этого шага модель видела бы только вызов и была вынуждена гадать о реализации.
Сравнение с аналогами: cocoindex-code и Graphify
Прямое сравнение на едином наборе задач выявляет архитектурные различия. cocoindex-code полагается на эмбеддинги без графового расширения - отсюда recall 0.32. Graphify использует графы, но ограниченно - вероятно, только для импортов, без анализа типов и вызовов, что даёт 0.70. Archex комбинирует все три метода и получает 0.95.
| Метрика | Archex | cocoindex-code | Graphify |
|---|---|---|---|
| Recall нужных файлов | 0.95 | 0.32 | 0.70 |
| Холодный старт | 0 мс | 4.7 с | 937 мс |
| Поддержка языков | 26 | ограничена | ограничена |
| Лицензия | Apache 2.0 | проприетарная | проприетарная |
| Требует API-ключей | нет | да | да |
| Детерминированность | полная | нет | нет |
Разница в холодном старте критична для сценариев, где агент запускается под каждую задачу. 4.7 секунды cocoindex-code на каждом запуске быстро складываются в минуты простоя при активной работе.
Приватность и автономность: никаких API-ключей и телеметрии
Archex работает полностью локально. Код не покидает машину. Нет регистрации, нет API-ключей, нет телеметрии. Это принципиально для корпоративных сред с чувствительным кодом и офлайн-контуров без доступа в интернет.
Детерминированность - второе ключевое свойство. Одинаковый запрос и версия индекса всегда дают одинаковый результат. Это означает воспроизводимую отладку: если агент ошибся, можно точно восстановить, какой контекст он получил. Лицензия Apache 2.0 разрешает коммерческое использование без ограничений.
Для команд, которые уже строят пайплайны вокруг настольных AI-агентов, локальность Archex означает отсутствие юридических рисков при работе с проприетарным кодом.
Интеграция в рабочий процесс: MCP-сервер, CLI, Python API и Docker
Archex предлагает четыре способа интеграции, от бесшовной работы с современными AI-инструментами до встраивания в кастомные пайплайны. Все варианты поддерживают 26 языков программирования и контроль лимита токенов.
MCP-сервер: 17 инструментов для AI-агентов
MCP (Model Context Protocol) - открытый протокол для взаимодействия AI-моделей с внешними инструментами. Archex предоставляет MCP-сервер с 17 инструментами: запрос контекста, поиск файлов, получение зависимостей, навигация по графу вызовов и другие. Агент получает не статический сниппет, а динамический интерфейс к кодовой базе.
Интеграция с Cursor, Copilot и другими MCP-совместимыми агентами происходит через стандартную конфигурацию протокола. Агент сам решает, какие инструменты вызвать и в каком порядке, чтобы собрать релевантный контекст под задачу.
CLI и Python API: гибкость для автоматизации
CLI даёт две основные команды: archex index для индексации репозитория и archex query 'как работает функция X' для получения контекста. Результат - структурированный набор файлов с ранжированием, готовый к передаче в модель.
Python API позволяет встроить Archex в скрипты: from archex import Archex; ar = Archex(repo_path); context = ar.query('запрос', max_tokens=8000). Это удобно для CI/CD пайплайнов, где контекст собирается автоматически перед запуском агента. Docker-образ обеспечивает изолированное развертывание без конфликта зависимостей.
Ограничения и когда Archex может не подойти
Тестовый набор из 19 задач покрывает типовые сценарии, но на очень больших или нестандартных репозиториях recall может снижаться. Инструмент требует индексации - хотя она быстрая, это дополнительный шаг перед первым использованием. Некоторые редкие языки за пределами 26 поддерживаемых не распознаются.
Archex не заменяет полноценный IDE-анализ. Он поставляет контекст, но не проверяет типы, не выполняет статический анализ за пределами графа зависимостей и не понимает рантайм-поведения. Проект молодой - API может меняться, а документация дополняться.
Опыт внедрения ИИ-агентов в regulated-индустриях показывает: инструменты контекста критичны, но их выбор должен проверяться на реальных задачах команды, а не только на бенчмарках.
Выводы: стоит ли переходить на Archex
Archex даёт три неоспоримых преимущества: высочайший recall 0.95, мгновенный холодный старт и полную автономность без внешних сервисов. Для разработчиков, активно использующих AI-агентов в больших проектах или средах с требованиями безопасности, это инструмент, который напрямую повышает качество ответов модели.
Противопоказаний немного: нестандартные кодовые базы и редкие языки могут снизить эффективность. Но для 26 мейнстримных языков и типовых проектов цифры говорят сами за себя. Лицензия Apache 2.0 снимает юридические барьеры для коммерческого использования. MCP-сервер с 17 инструментами делает интеграцию бесшовной.
Если вы следите за развитием автономных ИИ-агентов и ищете инфраструктурные компоненты, которые делают их надёжнее, Archex стоит протестировать на своём репозитории уже сегодня.