cc-os/docs/graphify/00-README.md

Graphify — Setup & Best-Practices Guide

A practical handbook for setting up and using Graphify (safishamsi/graphify, PyPI package graphifyy) across many projects at once — code, documents, and a personal knowledge base. Graphify turns a folder of mixed content into a queryable knowledge graph that your AI coding assistant reads instead of re-reading the whole corpus every session.

The guide is distilled from a creator interview (a marketing/influencer piece — see provenance below), then verified and corrected against the official GitHub repository and supplemented with independent sources.

Read in this order

1. 01-overview-concepts.md — What Graphify is and the mental model: knowledge-graph-of-everything, god nodes, confidence tags, neuro-symbolic framing, why a graph beats plain file search and Obsidian. Start here.
2. 02-installation-setup.md — Install (uv tool install graphifyy), register with your assistant, first graphify . run, and how to avoid a first-run token blowout.
3. 03-ingesting-code-ast.md — Indexing code with tree-sitter AST: free, no LLM, 33 languages, multi-repo. The core rule: AST for code, save the model for documents.
4. 04-ingesting-docs-knowledge.md — Indexing documents & a personal KB: PDF/docx/xlsx/images, audio/video transcription, YouTube, Google Workspace; when documents need a model.
5. 05-local-models-and-backends.md — Backends: local Ollama/SLM vs. cloud (Bedrock, Claude, Gemini, OpenAI, …), env vars, privacy, and choosing on cost/quality/privacy.
6. 06-querying-and-god-nodes.md — The highest-leverage skill: ask for god nodes first, then scalpel down; prompt the graph, don't make the LLM read the corpus.
7. 07-token-economics-and-updates.md — Where savings really come from (honestly), cost levers, and keeping the graph fresh with --update (SHA-256 + dedup) and hooks.
8. 08-workflows-and-use-cases.md — End-to-end playbooks: onboarding, bug tracing, AI-slop audits, the cross-project "second brain," PR impact analysis.
9. 09-best-practices-checklist.md — The do/don't reference card + command quick-reference + setting-up-across-many-projects mini-guide. Keep this one open while working.
10. external-tips.md — Independent/community tips, gotchas with issue links, and an even-handed look at the token-savings debate.
11. 10-extraction-model-options.md — Why Graphify uses a general structured-output LLM (not a purpose-built KG extractor), the architecture constraints that make drop-in specialist models (Triplex, GLiNER, REBEL) non-starters, and an honest assessment of whether the Triplex adapter route is worth experimenting with.

One-paragraph summary

Install with uv tool install graphifyy (the package is graphifyy — double-y, a temporary name — but the command is graphify), then graphify install to register it with Claude Code (or Codex/Cursor/Gemini/OpenCode). Run graphify . on a folder; it writes graphify-out/ containing an interactive graph.html, a GRAPH_REPORT.md (whose top lists the god nodes — the most-connected concepts), and a graph.json. Code is parsed locally with tree-sitter AST — free, no tokens, 33 languages. Documents, images, and media need a model backend for semantic extraction; point that at local Ollama to keep it free and private, or at a cloud model. The retrieval discipline that delivers the savings: ask for god nodes first, then query the graph (graphify query/path/explain) rather than dumping the whole corpus into context. Always graphify ... --update when adding data so it merges (SHA-256 hashing + dedup) instead of rebuilding. Fold many repos into one graph with graphify global add.

How this guide was built — provenance & honesty

This matters because you're going to run these commands. Each substantive claim in the docs is tagged inline:

Tag	Meaning
[github]	Verified against the official repository README (see version note below) — most trustworthy
[interview]	Stated only in the creator interview — unconfirmed framing or claim
[community](url)	From an independent third-party source, with link
[site] / [pypi]	From graphifylabs.ai or the PyPI listing
[unverified claim]	Asserted (often marketing) but not confirmed against a primary source

Sources, and how much to trust them:

• The interview (graphify-interview in the repo root) is a hype/marketing influencer piece with the creator (Safi Shamsi) and noisy auto-transcription. It's a good source of intent and workflow advice but a poor source of facts — names, commands, and numbers are garbled. We treated it as a starting hypothesis, not ground truth.
• The GitHub repo is the authority. We anchored on the v0.8.30 release README (published 2026-06-02, the latest published release as of 2026-06-03; a v1.0.0 tag also exists but isn't a published release). Disputed flags were settled by grepping the raw README bytes, not summaries.
• The official site (https://graphifylabs.ai/) returned HTTP 403 to automated fetches, so nothing was verified directly from it; site-only claims are flagged.

Corrections we made to the interview's claims (and why they're in the docs):

• "AST for code, LLM for documents" holds — but the interview's claim that shell scripts aren't AST-supported is outdated; v0.8.30 lists .sh/.bash/.ps1 among its 33 tree-sitter languages.
• Package name is graphifyy (double-y), not graphify, on PyPI.
• Flag set is version-dependent. --token-budget, --max-concurrency, --api-timeout, --budget, and --force are all real in v0.8.30 (grep-verified) but absent from the shorter main-branch README. If your build differs, confirm with graphify --help. Note: --budget caps query answer size; --token-budget sets extraction chunk size — different flags, different stages.
• "Meetings / Slack / OneNote connectors" are roadmap or belong to a separate product, not shipped in Graphify today.

On the headline token-savings numbers (70x / 90x / 71.5x): treat them as corpus-dependent marketing, not a guarantee. Independent testing (roborhythms) reproduced large-monorepo wins but measured a realistic ~1–49x, with net-negative results on small repos (the mandatory "read the graph first" preamble can cost more than it saves on <100-file projects — see GitHub issue #580). The creator himself says there's "no floor, no ceiling." Measure your own with graphify benchmark. (Separately, the repo's popularity claims under-sold reality: third-party trackers showed ~58K stars and ~1.28M downloads as of 2026-06-03 — bigger than the interview's figures.)

Caveat — Graphify moves fast. Multiple releases shipped per day during early June 2026. Commands and flags here reflect v0.8.30; if something doesn't match, run graphify --help and prefer the latest release README.

Last updated: 2026-06-03 · anchored to Graphify v0.8.30