9.1 KiB

Raw Blame History

09 — Best-Practices Checklist & Quick Reference

The page to keep open while using Graphify (v0.8.30): a scannable do/don't list, a command quick-reference, a "many projects" setup mini-guide, and the common mistakes to avoid. Detail lives in the sibling docs — this card cross-links to them.

Provenance tags: [interview] (creator's intent/sales claims), [github] (verified repo facts), [community] (third-party), [unverified claim].

Do / Don't

Index code freely — it's local AST, no tokens. Code (33 languages, tree-sitter) parses on your machine with no model calls. Run graphify . on any repo without fear. [github] [interview] — see 03-ingesting-code-ast.md
Reserve the model (tokens) for documents/images/audio/video only. This split is the #1 cost rule. [interview] — see 04-ingesting-docs-knowledge.md
Use a local backend (--backend ollama) for documents to keep extraction free and private. [interview] — see 05-local-models-and-backends.md
Ask for god nodes FIRST, then scalpel down. Read the top of GRAPH_REPORT.md for the architecture spine, then explain / path / bounded query into specifics. [interview] — see 06-querying-and-god-nodes.md
Prompt the graph, don't make the LLM read the corpus. The graph IS the memory; have the assistant extract from it, not traverse it. [interview]
Always --update when adding data. SHA-256 hashing + dedup re-process only changed files and merge in, instead of rebuilding. [interview] [github] — see 07-token-economics-and-updates.md
Split large corpora and re-ingest in pieces rather than dumping one giant chunk — cheaper and less hallucination/dilution. [interview]
Tune for local/small models: smaller --token-budget (chunk size), lower --max-concurrency, raise --api-timeout if it stalls. [github]
Automate freshness for code: graphify hook install (commit hook) or --watch — both AST-only, free. [github]
Measure your own savings with graphify benchmark instead of trusting any headline multiplier. [github]

Don't

Don't quote a token multiplier as a promise. "70x / 90x / 71.5x" are corpus-dependent marketing figures; independent testing shows ~1–49x, and net-negative on small repos (<100 files ≈ 1–3x; some users measure more tokens). Say "measure with graphify benchmark." [unverified claim] [community] — see 07 and external-tips.md
Don't run your first build on a big doc pile with a cloud backend — that's the way to burn your daily limit (one user burned theirs + $25–30 extra). Start on code, then add docs locally. [interview]
Don't expect graphify query "god nodes" to return the ranking — query is semantic search; the structural god-node list lives at the top of GRAPH_REPORT.md. [github]
Don't confuse --budget with --token-budget. --budget N caps a query answer; --token-budget N sets the extraction chunk size. Different stages. [github]
Don't expect the commit hook (or --watch) to refresh docs — they handle code only. Re-run --update on docs manually (they cost tokens). [github]
Don't rebuild from scratch to add data — use --update. Use --force only to overwrite/clear ghost nodes after deletions. [github]
Don't treat Obsidian as a substitute. It's a nice visual pairing, but it can't cluster or surface cross-community links the way Graphify does. [interview] — see 01-overview-concepts.md
Don't get the package name wrong — it's graphifyy (double-y), the binary is graphify. The single most common install mistake. [community]

Command quick-reference (v0.8.30)

Invocation forms. In-IDE uses the slash form (/graphify ./path --update) and borrows your session's model for docs. Headless uses graphify extract ./path and needs an explicit --backend. The query / path / explain verbs work both ways (drop the slash in a terminal; always use the no-slash form on Windows PowerShell). [github]

Install & register

uv tool install graphifyy        # recommended (or: pip install graphifyy)
graphify install                 # register the skill with your assistant
graphify claude install          # optional: make Claude consult the graph automatically

Build / update

Goal	Command	Cost
First build	`/graphify ./path` — or headless `graphify extract ./path --backend ollama`	code free; docs/images cost tokens
Add / changed data	`/graphify ./path --update`	only changed files re-processed
Rebuild, clear ghost nodes after deletions	`graphify extract . --force` (or `GRAPHIFY_FORCE=1`)	as a full rebuild
Richer inference	`/graphify ./path --mode deep`	higher (more LLM passes)
Auto-rebuild on commit (code only)	`graphify hook install`	free (AST)
Live auto-rebuild (code only)	`/graphify ./path --watch`	free (AST)
Measure savings	`graphify benchmark`	free

Query (start at god nodes in GRAPH_REPORT.md, then drill down)

Goal	Command
Semantic search, bounded answer	`graphify query "..." --dfs --budget 1500`
Connect two named nodes	`graphify path "A" "B"`
Deep-dive one node	`graphify explain "Node"`
Visual call-flow	`graphify export callflow-html`
Re-cluster (free, no re-extract)	`graphify cluster-only . --resolution 1.5`
De-noise god-node ranking	`... --exclude-hubs 99`
PR impact / review queue	`graphify prs` (`prs 42`, `--triage`, `--conflicts`)

Local-model tuning flags (extraction stage; see 05)

graphify extract ./docs --backend ollama \
  --token-budget 4000 --max-concurrency 2 --api-timeout 900
# Ollama env: OLLAMA_BASE_URL, OLLAMA_MODEL,
#             GRAPHIFY_OLLAMA_NUM_CTX, GRAPHIFY_OLLAMA_KEEP_ALIVE

Outputs land in graphify-out/: graph.html, GRAPH_REPORT.md, graph.json, cache/. Backends: ollama (local), bedrock, claude, gemini, openai, deepseek, kimi.

Setting up across many projects (code + docs + KB)

The pattern: one graph per project, folded into one global view. Keeps each --update cheap and isolated while giving you a single place to query across everything. Full playbook in 08-workflows-and-use-cases.md (Playbook 4) and the global-graph mechanics in 03-ingesting-code-ast.md.

Build a graph in each repo / doc folder / KB vault. Code is free (AST); route documents through a local backend to keep them free and private (see 05-local-models-and-backends.md):

/graphify .                                    # in a code repo (free)
graphify extract ./notes --backend ollama      # in a docs/KB folder (local model)

Register each into the global graph (lives at ~/.graphify/global.json):

graphify global add graphify-out/graph.json my-api
graphify global add graphify-out/graph.json my-notes
graphify global list                           # node/edge counts per repo
graphify global remove my-api                  # unregister

Set a freshness cadence by content type:
- Code → automate: graphify hook install per repo (rebuilds on commit, free). [github]
- Docs/KB → on demand: --update deliberately after adding/editing material (costs tokens; the hook won't touch docs). [github]
- Re-register after a doc refresh so the global view picks up new nodes: graphify global add graphify-out/graph.json my-notes.

Pull in external knowledge (papers, lectures — videos transcribed locally):

/graphify add https://arxiv.org/abs/1706.03762
/graphify add <youtube-url>

Common mistakes

Wrong package name. Install graphifyy (double-y); the binary is graphify. [community]
First run = big docs + cloud backend → token burn. Start on code (free), add docs with a local Ollama backend. [interview]
Expecting query to return god nodes. It's semantic search — read the ranking at the top of GRAPH_REPORT.md. [github]
Mixing up --budget (query answer) and --token-budget (extraction chunk). [github]
Expecting the commit hook / --watch to refresh docs. Code only; re-run --update on docs yourself. [github]
Stale-node drift. --update is known to leak stale nodes (removed symbols aren't always pruned); use --force to rebuild clean when the graph drifts. [community] [github]
Quoting a savings multiplier. Corpus-dependent — measure your own with graphify benchmark. [unverified claim]

Index: 00-README.md · Concepts: 01-overview-concepts.md · Install: 02-installation-setup.md · Community/skeptical notes: external-tips.md

9.1 KiB Raw Blame History Unescape Escape