139 lines
9.4 KiB
Markdown
139 lines
9.4 KiB
Markdown
---
|
||
summary: A scannable do/don't checklist, command quick-reference card, multi-project setup guide, and common-mistakes list for using Graphify v0.8.30 correctly and efficiently.
|
||
tags:
|
||
- type/reference
|
||
- tool/graphify
|
||
- scope/global
|
||
- domain/knowledge-graphs
|
||
- domain/llm
|
||
source: cc-os
|
||
date: 2026-06-08
|
||
---
|
||
|
||
# 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
|
||
|
||
**Do**
|
||
|
||
- **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](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](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](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](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](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](07-token-economics-and-updates.md) and [external-tips.md](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](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**
|
||
|
||
```bash
|
||
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](05-local-models-and-backends.md))
|
||
|
||
```bash
|
||
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](08-workflows-and-use-cases.md) (Playbook 4) and the global-graph mechanics in [03-ingesting-code-ast.md](03-ingesting-code-ast.md).
|
||
|
||
1. **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](05-local-models-and-backends.md)):
|
||
```bash
|
||
/graphify . # in a code repo (free)
|
||
graphify extract ./notes --backend ollama # in a docs/KB folder (local model)
|
||
```
|
||
2. **Register each into the global graph** (lives at `~/.graphify/global.json`):
|
||
```bash
|
||
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
|
||
```
|
||
3. **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`.
|
||
4. **Pull in external knowledge** (papers, lectures — videos transcribed locally):
|
||
```bash
|
||
/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](00-README.md) · Concepts: [01-overview-concepts.md](01-overview-concepts.md) · Install: [02-installation-setup.md](02-installation-setup.md) · Community/skeptical notes: [external-tips.md](external-tips.md)
|