CodeGraph: как локальный семантический граф на Rust дает AI-агентам хирургическую контекстную память

CodeGraph: как локальный семантический граф на Rust дает AI-агентам хирургическую контекстную память

Автономные кодинг-ассистенты и AI-агенты изменили разработку, однако их работа с крупными проектами упирается в архитектурный барьер. Когда модели нужно изучить проект, ответить на вопрос или внести правку, она исследует код медленно: запускает строковый поиск, сканирует папки и считывает файлы целиком. На каждый шаг сгорают токены, а контекстное окно модели — лимит объема данных, удерживаемых в оперативной памяти за один диалог, — засоряется посторонним кодом.

В итоге агент тратит время и бюджет не на задачу, а на повторное воссоздание карты вызовов, которую среда разработки могла бы отдать сразу. Открытый проект CodeGraph предлагает принципиально иной подход: вместо чтения сырых файлов строится предопределенный семантический граф знаний кодовой базы. Ядро на Rust в фоне разбирает репозиторий, извлекает связи между сущностями и передает агенту точечный срез кода через открытый протокол.

Анатомия проблемы: почему строковый поиск ломает рассуждения моделей

В типичном сценарии работы автономного агента в средах Claude Code, Cursor или Codex изучение репозитория превращается в череду вызовов инструментов. Чтобы понять, как обработчик запроса обращается к базе данных, модель ищет имя функции, открывает файл, натыкается на интерфейс, делает новый поиск, открывает файл реализации и повторяет цепочку.

Такой подход порождает три проблемы:

1. Расход токенов. Загружая файлы целиком ради пары строк, агент передает в контекст сотни строк комментариев, типов и нерелевантной логики.
2. Потеря фокуса и галлюцинации. Чем больше лишнего текста оседает в контексте, тем выше риск упустить деталь бизнес-логики или перепутать одноименные функции.
3. Слепота к динамическим связям. Строковый поиск не понимает полиморфизма и внедрения зависимостей через интерфейсы, поэтому заходит в тупик на абстракциях.

CodeGraph устраняет эту проблему, заменяя перебор файлов навигацией по графу, где узлами служат символы (функции, классы, интерфейсы, маршруты), а ребрами — вызовы, импорты и наследование.

Архитектура ядра: Rust, синтаксический анализ и масштабирование

В основе системы лежит ядро codegraph-kernel на Rust. Для разбора текстов применяется синтаксический анализ на базе абстрактных синтаксических деревьев (AST — структурированное представление кода, отражающее его синтаксис без лишних деталей оформления).

Парсер поддерживает более 20 языков, включая TypeScript, JavaScript, Python, Go, Rust, Java, C, C++, C#, Ruby, PHP, Swift и Kotlin. Обработка файлов происходит в скомпилированном коде, что исключает накладные расходы интерпретаторов.

Архитектура ядра автоматически адаптируется к аппаратным ресурсам:

• Многопоточный конвейер на мощных станциях. Пул воркеров задействует реальное число ядер процессора с учетом доступной памяти. Репозиторий компилятора Swift (~27 000 файлов) индексируется с нуля примерно за 100 секунд.
• Отказоустойчивость на слабых машинах. На серверах с 2 ядрами и 6 ГБ памяти конвейер переходит в режим сбережения ресурсов. Репозиторий ядра Linux (70 000 файлов, 2 миллиона символов и 6,4 миллиона связей) индексируется за 12 минут, тогда как наивные анализаторы аварийно завершаются по нехватке памяти.

Инкрементальная синхронизация на лету

Статические анализаторы прошлого требовали ручной переиндексации после изменений кода. В агентной разработке, где модель непрерывно правит файлы и генерирует тесты, любая задержка синхронизации делает индекс неактуальным.

CodeGraph решает задачу через системные наблюдатели: inotify в Linux, FSEvents в macOS и ReadDirectoryChangesW в Windows. При сохранении файла запускается таймер задержки на 300 миллисекунд. После паузы анализатор обновляет граф только для измененного файла. На проекте из 4 400 файлов точечное обновление занимает около 0,3 секунды, поэтому агент всегда видит актуальный код.

Протокол MCP: точечный срез кода вместо сотен файлов

Чтобы открыть модели доступ к графу, CodeGraph реализует сервер протокола Model Context Protocol (MCP) — открытого стандарта для подключения инструментов к языковым моделям.

Вместо примитивного чтения диска модель получает специализированные функции:

• Поиск вызывающих и вызываемых сущностей. Агент может одним вызовом запросить всех потребителей функции или узнать, к каким сервисам она обращается.
• Определение радиуса поражения (blast radius). Перед правкой метода агент видит зависимые модули и тесты на глубину до трех шагов вызовов, предотвращая регрессии.
• Поиск сквозных путей выполнения. Запрос пути между сущностями возвращает цепочку вызовов с номерами строк и контекстом связывания интерфейсов.

Замеры эффективности и парадокс остаточного контекста

Замеры производительности проводились на семи открытых репозиториях: VS Code, Excalidraw, Django, Tokio, OkHttp, Gin и Alamofire. В роли исполнителя выступала модель Claude при ответе на архитектурные вопросы.

Результаты бенчмарка зафиксировали устойчивый выигрыш:

• Сокращение числа вызовов инструментов: в среднем на 88% (в VS Code число вызовов упало с 28 до 2, а в Excalidraw — с 43 до 2).
• Ускорение времени ответа: задачи решались в 1,5–3,6 раза быстрее за счет отсутствия циклов ожидания ввода-вывода.
• Экономия токенов и стоимости: потребление токенов на этапе исследования сократилось на 62%, а финансовые затраты на API снизились на 44%.
• Исключение чтения сырых файлов: во всех тестах число прямых обращений к файлам упало до нуля.

При этом разработчикам важно учитывать компромисс остаточного контекста. Текстовый агент просматривает множество мелких фрагментов файлов, которые быстро вытесняются из памяти. CodeGraph возвращает один плотный ответ со связями, остающийся в диалоге до конца сессии. В итоге в длительных беседах остаточный объем занятого контекста у графового агента может оказаться на 80% выше. Это осознанный размен: сокращение общего потока обрабатываемых токенов в пользу стабильного знания внутри рабочего окна.

Визуальный интерфейс для разработчика

Инструмент включает веб-интерфейс codegraph ui по адресу http://127.0.0.1:4747. Он позволяет человеку увидеть структуру проекта: трехпанельный инспектор символов (вызывающие функции слева, исходный код по центру, вызываемые сущности справа), карту точек входа веб-маршрутов и воркеров, а также экспорт схем в формате SVG для комментариев к Pull Request.

Практическое подключение: пошаговый чеклист

Развертывание CodeGraph полностью автономно и не требует внешних сервисов: данные хранятся локально в директории репозитория в формате SQLite.

1. Установка утилиты. Скрипт скачивает бинарный файл под используемую операционную систему:
   • В Linux и macOS: curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
   • В Windows PowerShell: irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
   • Через менеджер пакетов: npm i -g @colbymchenry/codegraph
2. Интеграция с агентами. Команда автоконфигурации связывает утилиту со средами разработки: codegraph install Программа находит установленные среды (Claude Code, Cursor, Codex, Gemini CLI, Antigravity IDE, Kiro, VS Code Copilot) и настраивает локальный сервер MCP.
3. Инициализация графа. В корневом каталоге проекта выполняется команда: codegraph init Она создает папку .codegraph/ и строит синтаксический граф.
4. Проверка работы. Для визуального контроля запускается веб-панель: codegraph ui После этого подключенный агент сможет обращаться к инструментам графа при первой необходимости. Команда codegraph uninstall при необходимости удаляет конфигурации агентов.

Переход от текстового поиска к семантическим графам знаний становится стандартом агентной разработки. Локальная индексация на Rust превращает кодинг-ассистентов в системы с глубоким пониманием архитектуры проекта, экономя время инженера и токены вычислительных моделей.