Если корпус большой — десятки файлов, сотни PDF, длинная кодовая база — у LLM-агента появляется знакомая боль: каждый запрос он снова тащит одни и те же куски текста в контекст. Токены утекают, ответы расплываются, а понимания «общей картины» всё равно нет.
Андрей Карпати описывал это как личный workflow: «складываю PDF, скриншоты, твиты в одну папку, потом LLM собирает из этого вики, навигирую через Obsidian». И добавлял: «здесь напрашивается продукт вместо набора костыльных скриптов». Сафи Шамси услышал — и через несколько дней выпустил Graphify.
Идея простая и сильная: один раз тяжёлый разбор — потом много раз лёгкие запросы по графу. По замерам автора, на смешанном корпусе (репозитории + attention papers + диаграммы, ~52 файла / ~92k слов) стоимость запроса падает с ~123k токенов «наивно» до ~1.7k токенов через граф — это сокращение в 71.5 раза.
Суть: один раз дороже — потом много раз дешевле. Graphify делает разбор корпуса один раз, складывает результат в персистентный граф на диске, а дальше каждый запрос агента ходит по графу, а не перечитывает файлы.
Что это
Graphify — это open-source skill (лицензия MIT) для AI-кодинг-ассистентов. Под капотом он превращает любую папку с кодом, документацией, PDF, картинками и видео в queryable knowledge graph. Граф лежит на диске, его можно открыть в браузере или опросить через CLI.
Технологически это связка из трёх китов:
Tree-sitter— статический анализ кода. Извлекает AST, граф вызовов, docstrings для 36+ языков (Python, JS/TS, Go, Java, Rust и др.). Работает локально, без API.- LLM-извлечение — семантический разбор prose, Markdown, PDF, кода. Достаёт «концепты» и связи между ними.
- Vision-модели — читают диаграммы, схемы, whiteboard-фото. Превращают рисунки в узлы графа.
- Leiden-кластеризация — без векторных embeddings находит смысловые сообщества узлов. Это «рубрики», но построенные автоматически.
Поддерживается из коробки в Claude Code, OpenAI Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot CLI, Aider, OpenClaw, Hermes, Google Antigravity и ещё нескольких ассистентах. Основной интерфейс — slash-команда
/graphify в диалоге ассистента.
Какие форматы читает Graphify
| Тип контента | Что именно | Как обрабатывается |
|---|---|---|
| Код | Python, JS/TS, Go, Java, Rust, ещё 30+ языков | Tree-sitter: AST, граф вызовов, docstrings. Локально, без API. |
| Markdown / документация | .md, .mdx, .qmd, .html, .txt, .rst | LLM-извлечение концептов и ссылок, включая [[wikilinks]]. |
| статьи, research papers | LLM-извлечение (нужен extras pdf). | |
| Картинки | .png, .jpg, .webp, .gif | Vision-модели читают схемы и диаграммы. |
| Видео и аудио | .mp4, .mov, .mp3, .wav + YouTube | faster-whisper + yt-dlp (нужен extras video). |
| Office | .docx, .xlsx | Через extras office. |
| SQL-схемы, Terraform | PostgreSQL live, .tf/.tfvars/.hcl | Через extras sql, postgres, terraform. |
| MCP-конфиги | .mcp.json, claude_desktop_config.json | Извлекает серверы, переменные окружения, пакеты. |
| Package manifests | pyproject.toml, go.mod, pom.xml | Один canonical-узел на пакет + depends_on рёбра. |
Это не просто «индексация». Каждое ребро графа размечено одним из трёх типов:
EXTRACTED— пришло напрямую из источника (AST, явная ссылка, docstring).INFERRED— дорисовано моделью на основе смысла.AMBIGUOUS— модель не уверена, требует проверки человеком.
Эта разметка — не косметика. Она показывает, где граф можно читать как факт, а где надо смотреть руками.
Зачем нужно
Главная проблема: контекстное окно не масштабируется линейно. Чем больше файлов вы закидываете в агента, тем больше токенов — и тем хуже модель держит общую картину. На маленьком проекте (30–50 файлов) «прочитать всё» ещё работает. На 500+ файлах это уже не работает: дорого, медленно, и агенту всё равно не хватает контекста на весь корпус.
Что вы получаете на выходе
graph.html— интерактивная визуализация графа в браузере. Клик по узлу показывает, где этот концепт встречается и с чем связан.graph.json— queryable граф. Узлы, рёбра, метаданные. Можно опрашивать скриптами или прямо из ассистента.GRAPH\_REPORT.md— читаемый человеком аудит-отчёт: god nodes (самые связанные концепты), неожиданные мосты, висячие узлы, 4–5 предложенных вопросов, на которые граф умеет отвечать.
Где это даёт максимальный эффект
- Большое репо (500+ файлов) — главный сценарий. На маленьких проектах overhead на построение графа не окупается.
- Живой корпус — Obsidian-волт, экспорт статей сайта, личный архив PDF. Граф один раз построили — потом обновляем через
--updateпри добавлении файлов. - Смешанный корпус — код + документы + диаграммы. Именно здесь Karpathy mixed corpus даёт те самые 71.5× — 285 узлов, 340 рёбер, 53 сообщества.
- Контентная база сайта — статьи + блог + база знаний. Graphify даёт второй слой смысловых связей поверх ручной разметки тегами.
Как устроено
Архитектура — многоступенчатый pipeline, где каждая ступень изолирована и расширяется отдельно:
detect— собрать файлы (с учётом .gitignore и опционального .graphifyignore).extract— AST + LLM: достать узлы и рёбра.build— собрать граф в NetworkX.cluster— Leiden-сообщества поверх графа.analyze— найти god nodes и «сюрпризы» (неожиданные связи между далёкими узлами).report— сгенерировать GRAPH_REPORT.md.export— отдать HTML/JSON/Obsidian-совместимый экспорт.
Поддерживающие модули:
ingest.py— загрузка URL с валидацией (только http/https, лимиты размера и таймаутов).cache.py— семантический кэш для инкрементальных обновлений.security.py— валидация входов, path containment, HTML-escape лейблов.watch.py— live-обновления графа при изменениях в корпусе.serve.py— MCP-stdio сервер для интеграции с ассистентами.
Ключевой архитектурный приём: стоимость переносится «влево». Тяжёлый разбор делается один раз, при первом проходе. Дальше агент общается с графом, а не с файлами. На повторных запросах разница в токенах — драматическая.
Установка и запуск
Минимальные требования: Python 3.10+. По умолчанию всё работает локально — наружу уходят только семантические описания документов, сырой код не отправляется.
Шаг 1. Поставить пакет
Официальное имя пакета в PyPI — graphifyy (с двойным y). CLI-команда остаётся graphify. Установка через uv tool install даёт изолированное окружение и PATH сразу:
# Рекомендуемый способ (изолированное окружение)
uv tool install graphifyy
# Альтернативы
pipx install graphifyy
pip install graphifyy
# Если 'graphify' не находится в PATH после установки (часто на macOS + zsh):
uv tool update-shell
# или откройте новый терминалШаг 2. Зарегистрировать skill в ассистенте
graphify install
# Только в текущий проект (а не в user profile):
graphify install --project
graphify install --project --platform codexШаг 3. Построить граф
В Claude Code, Cursor и большинстве других ассистентов команда вызывается прямо в диалоге. В Codex используется
$graphify — у Codex свой синтаксис вызова skills.
# В Claude Code / Cursor / OpenCode / Gemini CLI:
/graphify .
# В Codex (в диалоге):
$graphify .
# Инкрементальное обновление (только изменённые файлы):
/graphify ./docs --update
# Только пересчитать кластеры (без переизвлечения):
/graphify . --cluster-only
# Без HTML, только report + JSON:
/graphify . --no-vizПосле прогона появляется каталог
graphify-out/ с тремя ключевыми артефактами:
graphify-out/
├── graph.html # интерактивная визуализация
├── GRAPH_REPORT.md # god nodes, сюрпризы, предложенные вопросы
└── graph.json # полный граф — можно опрашивать без чтения файловПолезные команды
Запросы к графу
# Задать вопрос по графу
/graphify query "what connects auth to the database?"
# Найти смысловой путь между двумя узлами
/graphify path "UserService" "DatabasePool"
# Объяснить, что такое концепт и где встречается
/graphify explain "RateLimiter"
# Добавить PDF или YouTube в граф
/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>Обслуживание и PR-ревью
# Git-хук для авто-пересборки графа при коммите
graphify hook install
# Слить два графа
graphify merge-graphs a.json b.json
# PR-дашборд: статус CI, ревью, маппинг на worktree
graphify prs
graphify prs 42 # глубокий разбор PR #42
graphify prs --triage # AI-ранжирование очереди ревью
graphify prs --conflicts # PR, затрагивающие одни сообщества — риск конфликтовБезопасность и приватность
Skill ставится в
~/.claude/skills/ (или в
.claude/skills/, .agents/skills/, .codex/skills/ — зависит от платформы) и по сути является промптом, который выполняется в вашей среде. Это нормальная модель Claude/Agent skills, но это и поверхность атаки: prompt injection через SKILL.md теоретически возможен. Ставьте только из доверенного источника, проверяйте обновления.
Что хорошо в дизайне Graphify
- Граф остаётся локально на диске — повторные запросы не отправляют сырые файлы наружу.
- Строгая валидация входов — только http/https URL, лимиты размера и таймаутов, path containment, HTML-escape лейблов узлов.
EXTRACTED / INFERRED / AMBIGUOUS— разметка рёбер не косметика. Это реальный инструмент: всегда видно, что пришло из источника, а что дорисовала модель.- Никакой телеметрии — нет скрытых запросов к внешним сервисам. Единственный исходящий вызов — семантическое извлечение через ваш собственный API-ключ модели.
Что нужно держать в голове
- Первичный проход всё-таки использует LLM — какие-то фрагменты текста уходят в модель на этапе извлечения концептов. Если у вас sensitive-данные, выбирайте провайдера и режим осознанно (Ollama extras или on-prem).
- Сырой код не отправляется, но описания — да — модель видит семантические описания функций, docstrings, имена. Для публичных проектов это не проблема, для закрытого кода — учитывайте.
Когда использовать
| Сценарий | Подходит ли | Почему |
|---|---|---|
| Большое репо (500+ файлов) | Да | Главный сценарий, экономия токенов максимальная. |
| Личный архив (Obsidian, заметки, PDF) | Да | Реализует workflow, который описывал Карпати. |
| Контентная база сайта (статьи + блог + KB) | Да | Строит смысловые связи поверх отдельных текстов. |
| Корпус research papers по теме | Да | Особенно сильно с PDF-парсингом и Leiden-кластеризацией. |
| Смешанный корпус (код + документы + диаграммы) | Да | Главный бенчмарк автора: 71.5× сокращение на Karpathy corpus. |
| Маленький проект на 30 файлов | Скорее нет | Обычное чтение файлов будет проще и сопоставимо по цене. |
| Sensitive-данные без on-prem LLM | Осторожно | Извлечение концептов — это LLM-проход. Сырой код не уходит, но описания — да. |
| Одноразовая задача «прочитать один файл» | Нет | Overhead на построение графа не окупится. |
Пример: что показывает GRAPH_REPORT.md
После прогона на смешанном корпусе (3 репозитория GPT-фреймворков + 5 attention papers + 4 диаграммы, ~52 файла / ~92k слов) GRAPH_REPORT.md содержит:
| Артефакт | Значение |
|---|---|
| Узлов в графе | 285 |
| Рёбер | 340 |
| Сообществ (Leiden) | 53 |
| Средняя стоимость запроса через граф | ~1.7k токенов |
| Средняя стоимость «наивно» (прочитать всё) | ~123k токенов |
| Сокращение | ≈ 71.5× |
| God nodes | Attention, Multi-Head Attention, LayerNorm |
| Сюрприз | Edge между Positional Encoding и KV-cache (связь, которой нет в исходниках напрямую) |
На корпусе httpx (6 Python-файлов, модель HTTP-транспорта) результат противоположный по масштабу, но такой же по структуре:
| Артефакт | Значение |
|---|---|
| Узлов | 144 |
| Рёбер | 330 |
| Сообществ | 6 |
| God nodes | Client, AsyncClient, Response, Request |
| Сюрприз-ребро | DigestAuth → Response |
Главное в GRAPH_REPORT.md — не цифры, а «сюрпризы»: неожиданные связи, которые вы бы не увидели, читая файлы по очереди. Это самое ценное, что даёт Graphify.
Связка с собственным контентным графом
Если у вас уже есть сайт с тегами, рубриками и внутренними ссылками, Graphify даёт второй слой смысловых связей поверх ручной разметки.
Два взгляда на один корпус
- Сайтовый граф — «как я хочу, чтобы это было связано». Теги, рубрики, описания.
- Graphify-граф — «как это связано на самом деле, по тексту». Автоматически извлечённые концепты и связи.
Расхождения между ними — самая ценная информация. Они показывают, где в архиве есть скрытые связи, которые ещё не вынесены в навигацию.
Что это даёт на практике
- Карта дыр — если в Graphify-графе устойчиво всплывает концепт, который у вас не оформлен как отдельный материал, это кандидат в новую публикацию.
- Скрытые мосты — Graphify часто видит связи между статьёй и материалом базы знаний, которые вы не размечали руками. Это новые внутренние ссылки.
- Проверка кластеров — если ваши «рубрики» совпадают с кластерами Leiden-кластеризации, структура архива в порядке. Если нет — пора пересобирать навигацию.
- Контекст для агента — контент-агент получает не «весь архив сразу», а сжатый граф с понятными узлами и связями. Экономия токенов и лучшая релевантность.
Сравнение с соседними инструментами
| Инструмент | Фокус | Сильная сторона | Граница vs Graphify |
|---|---|---|---|
| Sourcegraph | Кросс-репо поиск кода | Enterprise-grade навигация по коду | Не строит knowledge graph, ограниченная семантика дизайна. |
| Code2Vec | Function-level embeddings | Векторный retrieval и классификация функций | Нет графовой структуры, не работает с мультимодальным входом. |
| Neo4j | General graph database | Мощные Cypher-запросы, прод-нагрузки | Не генерирует графы из кода сам — нужно сначала их построить. |
| RAG через embeddings | Семантический поиск | Прост в подключении, хорошо ищет «похожее» | Не показывает структуру связей и сообщества, дороже на больших корпусах. |
| Graphify | Multi-modal knowledge graph | Один инструмент от файлов до queryable графа + отчёта | Не векторный поиск. Не заменяет RAG, дополняет его структурным слоем. |
Ограничения
Ограничения
Что учитывать
Границы применимости и технические лимиты инструмента.
Overhead на построение — на маленьких корпусах (до 30–50 файлов) выигрыш не окупается.
Обычное чтение файлов будет проще и сопоставимо по цене.
Качество зависит от модели — чем дешевле модель на этапе экстракции, тем больше AMBIGUOUS-рёбер. Не экономьте на первом проходе:
дешёвая модель = шумный граф.
Граф не обновляется сам — вы добавили 20 новых статей, нужно гонять --update.
Можно автоматизировать через graphify hook install, но это надо сделать.
Чистота входа решает — если корпус хаотичный (разные форматы заголовков, нет дат, нет тегов), граф будет шумным.
Чем чище входная модель данных, тем полезнее результат.
LLM-проход на этапе извлечения — какие-то фрагменты текста уходят в модель.
Для sensitive-данных используйте on-prem (Ollama extras) или учитывайте это как границу применимости.
Не серебряная пуля — Graphify платит токенами и временем один раз вперёд, чтобы сэкономить их потом.
Прекрасно ложится на живые архивы, плохо — на одноразовые задачи.
Антипаттерны
Антипаттерны
Чего не делать
Типичные ошибки, которые ломают эффект или безопасность.
Гонять на маленьких проектах — если у вас 30 файлов, Graphify создаст overhead без выигрыша.
Просто прочитайте файлы.
Экономить на модели извлечения — дешёвая модель = много AMBIGUOUS-рёбер = шумный граф.
Лучше один раз прогнать на сильной модели, чем потом чистить руками.
Игнорировать разметку EXTRACTED / INFERRED / AMBIGUOUS — эта разметка не косметика.
Если вы доверяете INFERRED-связям как факту, получите ложные выводы в GRAPH_REPORT.md и в ответах агента.
Ставить skill из непроверенного источника — SKILL.md выполняется в вашей среде.
Prompt injection через skill.md теоретически возможен. Берите только из официального репозитория safishamsi/graphify и проверяйте обновления.
Не обновлять граф — забыли --update после добавления 20 статей, и агент работает по устаревшему корпусу.
Настройте graphify hook install для авто-пересборки на git commit.
Считать граф готовым после построения — самый важный шаг — открыть graph.html и GRAPH\_REPORT.md глазами.
Найти 3 сюрприза, висячие узлы, god nodes. Решить, что с этим делать.
Чеклист
Чеклист
Проверка перед запуском
Минимум, который стоит пройти, прежде чем пускать Graphify в живой корпус.
Корпус выбран
репо, Obsidian-волт, экспорт статей сайта, корпус PDF — что-то одно, не всё сразу.
Вход прибран — единые форматы заголовков, метаданные, даты.
Без этого граф будет шумным.
Модель извлечения выбрана осознанно — для sensitive-данных Ollama extras или on-prem.
Для публичных корпусов — Claude / GPT с сильной моделью.
Skill поставлен из официального репозитория
github.com/safishamsi/graphify, не форк и не зеркало.
Прогон на чистой копии — /graphify .
на чистой копии корпуса, не на рабочей.
graph.html и GRAPH_REPORT.md прочитаны
открыть в браузере, найти 3 сюрприза, отметить висячие узлы.
Регулярное обновление настроено
graphify hook install для авто-пересборки на git commit, или явный --update в CI.
Граф закоммичен в репозиторий — graphify-out/ коммитится в git, чтобы команда стартовала с готовой картой. Исключения:
graphify-out/cost.json — локальный.
Ссылки
Ссылки
- Сайт: graphify.net
- GitHub: safishamsi/graphify
- PyPI: graphifyy
- Y Combinator: Graphify company page
- Discord: Сообщество Graphify