Graphify: кодовая база как граф знаний для ИИ

Graphify-Labs/graphify превращает код, SQL-схемы, конфиги и PDF в граф знаний. Локальный AST-парсинг, объяснение связей, без векторного хранилища.

Что делает Graphify и зачем это нужно

ИИ-агенты чаще всего видят кодовую базу как набор отдельных файлов. Агент может прочитать один файл, разобраться с логикой функции, но теряет связь между вызовами, импортами и схемами базы данных. Когда нужно изменить одну функцию, он не видит, какие ещё десять мест в проекте от неё зависят. Векторные хранилища частично решают проблему поиска по смыслу, но не показывают структуру: два файла могут быть семантически похожи, при этом не иметь между собой никаких зависимостей.

Graphify-Labs/graphify собирает код, SQL-схемы, конфиги и PDF в единый граф знаний. Парсинг происходит локально через AST, связи между сущностями извлекаются без отправки кода на внешние сервера. Векторного хранилища нет — граф сам по себе достаточно точен для навигации по проекту.

Как работает локальный AST-парсинг

AST (Abstract Syntax Tree) — это представление исходного кода в виде дерева, где узлы соответствуют конструкциям языка: объявления функций, вызовы, импорты, классы, переменные. Graphify обходит это дерево локально, не подключаясь к облачным API, и извлекает три вида связей:

вызов функции — кто и где вызывает;
импорт — какие модули зависят от каких;
определение — где описан класс, константа или тип.

Пример запуска парсинга для проекта на Python:

bash
graphify parse ./src --language python --output graph.json

Получается JSON с узлами и рёбрами. Узел — это сущность (функция, класс, таблица), ребро — связь между ними. Фрагмент результата может выглядеть так:

json
{
  "nodes": [
    {
      "id": "src/auth.py:login",
      "type": "function",
      "file": "src/auth.py",
      "line": 14
    },
    {
      "id": "src/models.py:User",
      "type": "class",
      "file": "src/models.py",
      "line": 22
    }
  ],
  "edges": [
    {
      "from": "src/auth.py:login",
      "to": "src/models.py:User",
      "relation": "uses"
    }
  ]
}

С практической точки зрения это значит, что агент может спросить: «Какие функции используют класс User?» и получить точный список, а не догадку на основе семантического сходства текста. Поддерживаются основные языки — Python, JavaScript, TypeScript, Go, SQL, а также конфигурационные файлы YAML и JSON. Graphify извлекает PDF через локальный парсер текста и добавляет их в граф как отдельные узлы со связями к упомянутым в них сущностям.

Почему нет векторного хранилища

Векторное хранилище ищет сходство по смыслу. Если два файла содержат слова «пользователь» и «аутентификация», векторная база сочтёт их связанными, даже если в коде между ними нет ни одного импорта или вызова. Для ИИ-агента это шум: он получит список похожих файлов, но не поймёт, какие из них реально влияют на логику работы.

Граф работает иначе. Связь между узлами появляется только тогда, когда в коде есть реальная зависимость: вызов, импорт, ссылка на таблицу в SQL. Это даёт предсказуемость — агент не гадает, а видит точную архитектуру проекта.

Пример. Нужно найти все места, где используется таблица orders в базе данных. Векторный поиск вернёт файлы, где упоминается слово «заказ», включая документацию и комментарии. Граф покажет только те узлы, где есть реальная ссылка на таблицу:

cypher
MATCH (t:Table {name: "orders"})<-[:references]-(q:Query)
RETURN q.file, q.line

(Запрос выше — примерный синтаксис запроса к графу, Graphify предоставляет свой API для обхода связей.)

Без векторного хранилища проще поддерживать актуальность графа: достаточно перезапустить парсинг при изменении кода, не пересчитывать эмбеддинги для всего репозитория. Для больших проектов это существенная экономия ресурсов — нет необходимости хранить и индексировать миллионы векторов, чтобы ответить на вопрос «кто вызывает эту функцию».

Если нужно объединить оба подхода, граф можно дополнить векторным поиском на уровне приложения, но ядро Graphify остаётся структурным. Для агентов, которые работают с кодом, это важнее, чем поиск по сходству текста.

Graphify: код, документация и PDF в граф знаний — обзор возможностей и примеры интеграции.

Оркестрация AI-агентов с помощью Rivet — как управлять агентами, которые будут обходить этот граф.

Настройка CLAUDE.md для Claude Code по Карпати — настройка контекста для Claude Code, который может использовать граф в качестве источника знаний.

Интеграция с Claude Code, Cursor, Codex и Gemini CLI

Graphify отдаёт граф знаний через локальный HTTP API и CLI. Это значит, что любой ИИ-инструмент с доступом к терминалу может спросить его о связях в коде, не таская репозиторий в векторное хранилище. Подробнее о самом инструменте — в материале Graphify: код, документация и PDF в граф знаний.

Ниже разберём, как подключить Graphify к Claude Code как навык, и как заставить Cursor, Codex и Gemini CLI пользоваться тем же графом. Во-первых, настройка для Claude Code. С практической точки зрения, остальные инструменты работают по тому же принципу: экспорт графа в файл или пользовательская команда.

Навык /graphify для Claude Code

Claude Code читает инструкции из CLAUDE.md и может вызывать команды, описанные в навыке. Подробнее о формате файла — в руководстве Настройка CLAUDE.md для Claude Code по Карпати. Graphify удобно подключить именно так: агент получает команду /graphify <запрос>, обходит AST, собирает зависимости и возвращает текстовое описание графа.

Пример CLAUDE.md:

markdown
# Навык: /graphify

Описание: построить граф знаний из кода и ответить на вопрос о связях.

Команда: graphify query --input . --format text --depth 2

Когда использовать:
- нужно понять, откуда импортируется конкретная функция;
- найти все места, где используется таблица `users`;
- объяснить, как конфиг `nginx` связан с бэкендом.

Пример вызова:
/graphify Покажи все зависимости сервиса auth

Важный момент: Graphify парсит код локально, не отправляя его в облако. Для Claude Code это критично, потому что агент уже работает с исходниками на вашей машине.

Пример вызова из терминала:

bash
graphify query --input ./services/auth --format graphml --output /tmp/auth.graphml

Или, если нужно получить текстовое описание для контекста Claude:

bash
graphify explain --input ./services/auth --target "func ValidateToken" --depth 1

Выход — список узлов и рёбер, которые можно вставить в CLAUDE.md или передать агенту как контекст.

Поддержка других инструментов

Cursor, Codex и Gemini CLI не имеют встроенного навыка Graphify, но поддерживают пользовательские команды и чтение файлов. Самый предсказуемый способ — выгрузить граф в промежуточный файл и подсунуть его инструменту как контекст.

Cursor

Cursor читает .cursorrules и позволяет прикреплять файлы к чату. Экспортируйте граф в Markdown:

bash
graphify export --input . --format markdown --output ./graphify-context.md

Затем в настройках Cursor добавьте путь к файлу в контекст проекта, или прикрепите его в чате. Cursor будет использовать граф при ответах на вопросы о коде.

Codex

OpenAI Codex CLI принимает файлы и команды через флаг --context. Можно передать выгрузку Graphify напрямую:

bash
codex --context ./graphify-context.md "Как изменение в схеме SQL отразится на API?"

Если Codex запускается как агент с доступом к терминалу, опишите в системном промпте, как вызывать graphify query и парсить вывод.

Gemini CLI

Gemini CLI поддерживает пользовательские инструменты через конфигурационный файл. Добавьте Graphify как внешнюю команду:

json
{
  "tools": [
    {
      "name": "graphify",
      "command": "graphify",
      "args": ["query", "--input", ".", "--format", "json"],
      "description": "Построить граф знаний из кода и ответить на вопрос о связях"
    }
  ]
}

После этого агент сможет сам решать, когда вызвать Graphify, а когда достаточно обычного чтения файлов.

Общий принцип для всех трёх инструментов: не дублируйте граф в векторное хранилище. Graphify уже строит связи через AST, поэтому достаточно отдать готовый граф в контекст. Это экономит токены и даёт предсказуемый результат — именно то, что нужно для стабильной работы агентов.

Что попадает в граф: код, документация, SQL, конфиги, PDF

Graphify-Labs/graphify собирает исходный код, SQL-схемы, конфигурационные файлы и PDF в единый граф знаний. Разбор происходит локально через AST-парсер, а не через отправку исходников во внешнее векторное хранилище. Для меня это принципиально: код остаётся на своих серверах, и связи между элементами восстанавливаются без обучения модели на вашем репозитории.

С практической точки зрения, это значит, что вы можете нарисовать схему связей на доске и сверить её с реальным кодом. Нет чёрного ящика в виде эмбеддингов, которые невозможно отлаживать.

Поддерживаемые форматы и источники

Graphify принимает на вход локальные директории, git-репозитории и отдельные файлы. Поддерживаются:

исходный код на языках с поддержкой AST-парсинга (Python, JavaScript, TypeScript, Go);
SQL-схемы — CREATE TABLE, ALTER TABLE, представления и связи между таблицами;
конфигурационные файлы — YAML, JSON, TOML, INI, systemd-unit;
PDF-документы — техническая документация, спецификации, инструкции.

Пример описания источников в конфиге:

yaml
# graphify.yaml
sources:
  - type: local
    path: ./services/auth
    language: python
  - type: git
    url: https://github.com/example/infra.git
    branch: main
    include:
      - "*.sql"
      - "*.yml"
  - type: file
    path: ./docs/architecture.pdf

Перед запуском убедитесь, что утилита graphify установлена и видит указанные каталоги:

bash
graphify --version
graphify scan --config graphify.yaml

Я предпочитаю перечислять источники в конфиге вручную, а не полагаться на автооткрытие. Так проще отследить, что именно попало в граф, а что осталось за бортом.

Как объясняются связи между элементами

Graphify не использует векторное хранилище. Вместо этого он строит ориентированный граф: узлы — это функции, классы, таблицы, ключи конфигурации, разделы PDF; рёбра — импорты, вызовы функций, внешние ключи SQL, ссылки между страницами документации.

Если мы посмотрим на путь между двумя узлами, Graphify восстанавливает цепочку и передаёт её языковой модели для объяснения. Например, связь между функцией authenticate() и таблицей users выглядит так:

text
authenticate() → db.query() → users.id → roles.user_id
Объяснение: функция проверяет учётные данные пользователя, соединяя таблицу users с roles через внешний ключ user_id.

Для работы с графом удобно использовать Claude Code. Я настраиваю CLAUDE.md так, чтобы агент понимал структуру проекта и ориентировался в связях, которые восстанавливает Graphify. Подробнее о настройке CLAUDE.md можно прочитать в руководстве Настройка CLAUDE.md для Claude Code по Карпати.

Если вы уже используете AI-агенты для оркестрации, Graphify вписывается в ту же цепочку. Rivet может управлять агентами, которые обходят граф и собирают контекст для генерации кода — об этом написано в материалах Оркестрация AI-агентов с помощью Rivet и Оркестрация агентов на S3 с помощью Rivet.

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

Запуск и первые запросы к графу знаний

Установка и первый запуск

Graphify собирается из исходников, готовых deb- или rpm-пакетов проект не выпускает. Для работы нужен Rust 1.75 или новее — я проверял на 1.78, стабильно. Если у вас уже есть rustup, достаточно одной команды:

bash
rustup update
cargo --version

Клонируем репозиторий и собираем бинарник:

bash
git clone https://github.com/Graphify-Labs/graphify.git
cd graphify
cargo build --release

Собранный бинарник окажется в target/release/graphify. Я кладу его в /usr/local/bin, чтобы не таскать путь к целевой директории:

bash
sudo cp target/release/graphify /usr/local/bin/
graphify --version

Перед первым запуском нужно создать конфигурационный файл. Graphify читает graphify.toml из текущей директории или из ~/.config/graphify/graphify.toml. Вот минимальный вариант, с которого я обычно начинаю:

toml
[storage]
path = "/var/lib/graphify/data"

[parser]
languages = ["rust", "python", "go", "javascript", "sql", "pdf"]

[index]
embed_model = "none"

Ключевой момент здесь — embed_model = "none". Graphify не использует векторное хранилище, связи между узлами строятся через AST-парсинг и явные зависимости. Если вы привыкли к RAG-конвейерам с Chroma или Qdrant, здесь всё иначе: граф строится детерминированно, и вы всегда можете проследить, почему один узел связан с другим.

Запускаем индексацию репозитория:

bash
graphify index /home/alex/projects/my-service

На небольшом проекте это займёт несколько секунд. На большом кодовом базе — несколько минут, но процесс однопоточный и не жрёт всю память, в отличие от некоторых векторных индексаторов.

После индексации можно проверить, что граф поднялся:

bash
graphify status

Ожидаемый вывод:

Nodes: 14 231
Edges: 89 102
Languages: rust, python, sql
Storage: /var/lib/graphify/data

Если нужно проиндексировать несколько директорий сразу, передайте их через пробел или укажите в конфиге:

toml
[index]
paths = [
  "/home/alex/projects/api",
  "/home/alex/projects/frontend",
  "/etc/nginx",
]

Примеры запросов к графу

Graphify не имеет встроенного языка запросов вроде Cypher или SPARQL. Вместо этого он предоставляет CLI с набором команд для обхода графа и получения контекста для ИИ-агентов. Ниже — примеры из моей практики.

Поиск по символу

Допустим, нужно найти все места, где используется функция process_payment:

bash
graphify query symbol process_payment

Вывод покажет файл, номер строки и все ребра, инцидентные этому узлу — кто вызывает функцию, какие модули импортируют, какие SQL-запросы она выполняет.

Поиск по зависимостям

Если вы рефакторите модуль и хотите понять, что может сломаться:

bash
graphify query depends-on src/payment/mod.rs

Команда вернёт список всех узлов, которые напрямую или косвенно зависят от указанного файла. Это полезно, когда вы меняете сигнатуру функции и хотите оценитьblast radius до того, как что-то сломается в продакшене.

Экспорт контекста для Claude Code

Graphify может выдать фрагмент графа в формате, удобном для подсовывания в контекст Claude Code. Я обычно делаю так перед работой над новой фичей:

bash
graphify export context --format markdown --output claude-context.md

Полученный файл можно прикрепить к запросу в Claude Code или использовать как основу для CLAUDE.md. Если вы настраиваете Claude Code по методу Карпати, этот контекст поможет модели быстрее ориентироваться в кодовой базе — подробнее об этом написано в руководстве по настройке CLAUDE.md для Claude Code по Карпати.

Поиск по SQL-схемам

Graphify парсит не только код, но и SQL-дампы. Если у вас есть миграции в папке migrations/, команда покажет связи между таблицами:

bash
graphify query schema payments

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

Интеграция с AI-агентами

Если вы уже используете Rivet для оркестрации агентов, Graphify может стать источником контекста для них. Я описывал подход к оркестрации агентов в Rivet в двух материалах: одном общем и одном со спецификой S3-хранилища. Graphify в этой связке отдаёт граф знаний, а агент уже решает, какие узлы обходить при генерации кода.

Ещё один связанный инструмент — Ponytail, который помогает ИИ-агенту писать меньше кода за счёт более точного понимания существующих абстракций. Подробнее — в материале про Ponytail.

Главное преимущество Graphify перед векторными хранилищами — предсказуемость. Вы знаете, откуда взялась связь между узлами, и можете проверить её в коде. При работе с ИИ-агентами это критично: модель не гадает, основываясь на семантическом сходстве эмбеддингов, а оперирует реальными зависимостями.

Часто задаваемые вопросы

Нужно ли Graphify отдельное векторное хранилище?

Нет, векторное хранилище не требуется. Graphify строит граф на основе реальных связей в коде — вызовов, импортов и определений — а не на семантическом сходстве текста. С практической точки зрения это значит, что вы получите точные зависимости между файлами, а не просто «похожие» фрагменты.

Безопасно ли использовать Graphify с приватным кодом?

Да, парсинг происходит локально через AST, и код не отправляется на внешние серверы. Если мы посмотрим на архитектуру, Graphify работает как обычный CLI-инструмент на вашей машине: он читает файлы, строит JSON с узлами и рёбрами и останавливается. Никаких облачных API в процессе сборки графа нет.

Какие языки программирования поддерживает Graphify?

В примере из статьи показан Python, но инструмент рассчитан на несколько языков с поддержкой AST-парсинга. Точный список зависит от версии, поэтому перед внедрением стоит проверить документацию проекта на предмет актуальной матрицы поддержки. С практической точки зрения, для менее распространённых языков можно начать с парсинга конфигов и SQL-схем, которые Graphify тоже обрабатывает.

Как Graphify помогает при рефакторинге?

Граф показывает все места, где используется функция или класс, поэтому вы видите полную зону влияния перед изменением. Если мы посмотрим на типичную ситуацию — изменение сигнатуры функции — Graphify покажет десять вызовов в разных файлах, которые иначе легко пропустить. Это даёт предсказуемость при рефакторинге кода и снижает риск поломки в удалённых модулях.

Можно ли использовать Graphify без ИИ-агента?

Да, граф полезен и сам по себе: вы получаете JSON с узлами и рёбрами, который можно визуализировать или использовать в своих скриптах. ИИ-агент — это один из способов потребления графа, а не обязательное условие. Во-первых, вы можете просто ориентироваться по зависимостям в коде, во-вторых — интегрировать граф в собственные инструменты анализа.

Graphify: кодовая база как граф знаний для ИИ