# 07 — Token Economics & Keeping the Graph Fresh

Where Graphify's token savings actually come from, how honest the headline numbers are, the practical levers you control, and how to keep the graph current with incremental updates instead of rebuilding from scratch.

> **Provenance:** Claims are tagged `[github]` (verified on 2026-06-03 by reading the raw `skill.md`, `__main__.py`, and `README.md` at the release line this guide anchors on — the `v0.8.x` line, which the brief refers to as "v8"; the disputed flags below were also checked against the `v1.0.0` tag and are absent there too), `[interview]` (creator interview — treat as intent/sales claims), `[community](url)`, or `[unverified claim]`. Several flags people repeat online do **not** exist in the shipped CLI; those are flagged explicitly below. Never assume a flag exists because it sounds plausible — check `--help` or `skill.md`.

Related docs: [overview](01-overview-concepts.md) · [code/AST ingest](03-ingesting-code-ast.md) · [docs ingest](04-ingesting-docs-knowledge.md) · [local models & backends](05-local-models-and-backends.md) · [querying & god nodes](06-querying-and-god-nodes.md) · [workflows](08-workflows-and-use-cases.md) · [best practices](09-best-practices-checklist.md).

---

## 1. Where the savings actually come from

Graphify does not "compress" your tokens. The savings come from three mechanics. Understanding them tells you exactly when savings will be large and when they'll be near zero.

### a) Code extraction is free (local AST)
Code is parsed locally with tree-sitter into an abstract syntax tree. No API calls, no tokens, no cost — just CPU. `[github]` In the creator's words: *"If you are calling an LLM to parse your codebase, that doesn't make sense at all… the AST call is free of cost. There's no API call included."* `[interview]`

So for a pure-code corpus, **building** the graph is effectively free. Only **documents, papers, and images** go through a model backend (cloud LLM or a local SLM). `[github]` That single split — free code vs. paid docs — is the biggest cost lever you have. (See [04-ingesting-docs-knowledge.md](04-ingesting-docs-knowledge.md).)

### b) Querying the graph instead of dumping the corpus
The real recurring savings are at **query time**. Instead of letting your assistant read dozens of raw files to orient itself, you query the pre-built graph and pull back only the relevant subgraph. `[github]` The skeptical-but-fair review puts it well: the savings come *"from precision — not from compression — allowing you to pay for relevant tokens, not orientation tokens."* [community](https://www.roborhythms.com/graphify-review/)

The creator's rule: *"Don't ask the LLM to go through the graph; ask the LLM to extract from the graph. The graph is the memory, the graph is the context."* `[interview]`

### c) God-nodes-first retrieval
Query the **god nodes** (the highest-connectivity hub nodes / `GRAPH_REPORT.md`) first to get the architecture in one shot, then "scalpel" down into the specific subgraph you need. `[interview]` This avoids the expensive pattern of repeatedly reading files to reconstruct structure the graph already encodes. See [06-querying-and-god-nodes.md](06-querying-and-god-nodes.md).

---

## 2. How honest are the savings numbers?

**Treat every multiplier as corpus-dependent, not a guarantee.**

- The README/benchmark headline is **71.5x fewer tokens per query** — but that is from **one specific run**: a mixed corpus of Karpathy repos + 5 papers + 4 images. `[github]` The benchmark is printed automatically after a run via `graphify benchmark`. `[github]`
- The creator is explicit that this is not a floor or a ceiling: *"There is no ceiling or floor in token savings here… 71.5 in my readme is for the repository I tried on. I've seen people getting 90x… and people getting 20x. It's totally corpus dependent."* `[interview]`
- He also acknowledges the backlash directly: *"I have a lot of hate in my comments… 'Oh, 70 times, are you out of your mind?'"* `[interview]`

**Independent / skeptical takes (read these before quoting a number):**
- An independent review reproduced the mechanism but found the realistic range is roughly **6.8x to 49x**, with the 71x figure being *"the upper bound on a curve… the tail of the distribution, not the middle."* It reports near-**1x–3x savings under ~100 files** and large multipliers only on very large repos. [community](https://www.roborhythms.com/graphify-review/)
- Community criticism also targets non-technical claims — GitHub star-count growth tactics and missing credit for early PR contributors — separate from whether the tool works. [community](https://www.mindstudio.ai/blog/graphify-claude-code-knowledge-graph-large-codebase-70x)

**Bottom line:** savings scale with corpus size and how disciplined your querying is. Small corpora may save little or nothing (graph-building overhead isn't amortized). Don't promise a multiplier to anyone — measure your own with `graphify benchmark`. `[github]`

> **The download/star numbers** ("500K+ PyPI downloads", "43K stars") are creator sales claims from the interview. `[interview]` Third-party write-ups cite different figures (e.g. ~55K stars / ~450K downloads). [community](https://www.mindstudio.ai/blog/graphify-claude-code-knowledge-graph-large-codebase-70x) Treat all of these as **unverified and time-sensitive.** `[unverified claim]`

---

## 3. Practical cost levers

### Lever 1 — Use a local backend (Ollama) for documents
Code is free regardless. The cost is documents. Route document extraction through a **local small language model via Ollama** instead of a paid cloud model. `[interview]` The creator's own workflow: *"local LLM for the extraction… free of cost as well rather than going for a cloud-based LLM."* `[interview]` Backends are installed as optional extras (e.g. `uv tool install "graphifyy[anthropic]"` for the cloud path). `[github]`

> Note: the package on PyPI is **`graphifyy`** (double *y*); the CLI command is **`graphify`**. `[github]` Exact Ollama/SLM setup steps live in [05-local-models-and-backends.md](05-local-models-and-backends.md). The *intent* (Ollama for docs to cut cost) is well-supported; treat specific Ollama flag syntax as `[unverified claim]` until confirmed against your installed `--help`.

### Lever 2 — Split large corpora and re-ingest in pieces
Don't dump one giant corpus in a single shot. *"You can split your repository or your documents and then reingest them… rather than putting the whole chunk in one shot."* `[interview]` More context per pass also raises hallucination/dilution risk, so smaller, merged passes are both cheaper and more reliable. `[interview]` Each re-ingest should use `--update` (Section 4) so pieces merge instead of rebuilding.

### Lever 3 — Cap query answer size with `--budget`
You can cap how many tokens a **query answer** returns:

```bash
/graphify query "how does auth talk to the database?" --budget 1500   # cap answer at ~1500 tokens
```

Default budget is ~2000 tokens; results are ranked by relevance and truncated at the budget. `[github]`

> **`--budget` vs `--token-budget` — two different flags for two different stages** (both verified in the v0.8.30 README): `--budget N` caps **query answer** size (retrieval), while **`--token-budget N`** controls the **semantic chunk size sent to the model during extraction** (smaller = better for local/small models). `[github]` Don't confuse them — `--budget` is for `query`, `--token-budget` is for `extract`. See [05-local-models-and-backends.md](05-local-models-and-backends.md) for `--token-budget` tuning.

### Lever 4 — Tune extraction cost with `--token-budget` and `--max-concurrency`
For the **extraction** stage (where document tokens are actually spent), v0.8.30 exposes two real flags: `[github]`

```bash
graphify extract ./docs --token-budget 30000   # smaller semantic chunks for local/small models
graphify extract ./docs --max-concurrency 2    # fewer parallel LLM calls (useful for local inference)
graphify extract ./docs --api-timeout 900      # longer HTTP timeout for slow local models (default 600s)
```

- **`--token-budget N`** — size of each semantic chunk sent to the model. Smaller chunks fit small/local model context windows and reduce tokens per call. `[github]`
- **`--max-concurrency N`** — number of parallel LLM calls; lower it for local inference so you don't overwhelm a single GPU/CPU. `[github]`
- **`--api-timeout` / `GRAPHIFY_API_TIMEOUT`** — HTTP timeout in seconds (default 600). `[github]`

Under the hood the skill also parallelizes automatically (semantic-extraction subagents over chunks, AST in parallel), so these flags tune — rather than introduce — concurrency. `[github]` Exact Ollama setup and a worked example live in [05-local-models-and-backends.md](05-local-models-and-backends.md).

---

## 4. Incremental updates — always `--update` when adding data

**The single most important habit.** When you add new files, run `--update` so Graphify re-extracts only what changed and merges into the existing graph, instead of rebuilding from scratch:

```bash
/graphify ./raw --update      # re-extract only new/changed files, merge into existing graph
```

The creator hammered this twice: *"When you are ingesting more data, make sure you use the word update — `graphify update` — so it doesn't start fresh from the beginning."* and *"Always make sure you put `graphify update` when you are ingesting new files or codebases or documents, so it doesn't have to go through the whole code once more."* `[interview]`

**How `--update` knows what changed:**
- **SHA-256 content hashing** of each file. Unchanged files (same hash) are skipped; only changed/new files are re-processed. The cache lives in `graphify-out/cache/`. `[github]` *"I've used hashing strategy SHA-256 in here so it will start from where it left."* `[interview]`
- **Deduplication** of entities so the same node isn't created twice across documents/passes. `[github]` *"I've also got some deduplication techniques so there will be very few collisions of the entities."* `[interview]`

This is what makes Lever 2 (split + re-ingest) safe: each piece merges cleanly via hash + dedup rather than producing a duplicated or reset graph.

### "Overwrite" / `--force` semantics — read this carefully
A re-run of the full pipeline (without `--update`) rebuilds the graph rather than merging incrementally. `[github]`

> **`--force`:** The `--force` flag **does exist** in v0.8.30 (equivalently set `GRAPHIFY_FORCE=1`). It overwrites `graph.json` **even when the rebuild produces fewer nodes**, which is exactly what you want after a refactor that deleted files — otherwise the old "ghost" nodes linger. `[github]`
>
> ```bash
> graphify extract . --force         # rebuild, overwrite even if fewer nodes (clears ghost nodes after deletions)
> graphify update ./src --force      # same, while still merging changed files
> ```
>
> Mental model: **`--update` = merge changed files; plain re-run = rebuild; `--force` = rebuild and overwrite even if the graph shrinks.** `[github]`

---

## 5. Auto-rebuild: git hooks and `--watch`

To avoid forgetting to update, automate it.

### Git commit hook (recommended for code)
```bash
graphify hook install      # post-commit hook: re-runs AST on changed files, rebuilds graph after every commit
graphify hook status       # check if installed
graphify hook uninstall    # remove it
```
After each commit the hook detects changed **code** files (via `git diff HEAD~1`), re-runs AST extraction on just those, and rebuilds `graph.json` + `GRAPH_REPORT.md`. `[github]`

> **Important limitation:** the hook handles **code only**. Doc/image changes are *ignored* by the hook — you must run `/graphify ./raw --update` manually after editing docs, because those need the (paid) LLM semantic re-pass. `[github]`

### Watch mode (for active/agentic sessions)
```bash
/graphify <path> --watch   # watch folder, auto-rebuild on code changes (no LLM)
```
Code saves trigger an instant AST-only rebuild (free, debounced ~3s). Doc/image changes write a `graphify-out/needs_update` flag and notify you to run `--update`. `[github]` Useful when parallel agents are writing code in waves. `[github]`

---

## 6. The staleness problem (and how the above mitigates it)

The interview's most candid admission is the operator's real pain point: assets go stale and re-grooming them is a chore. The interviewer: *"My assets become stale over time, so the process of having to remember to groom your data… becomes a bit of a constraint."* `[interview]` The creator's framing is a *"digital twin / enterprise brain that gets smarter with time"* via incremental updates `[interview]` — but that only holds if the graph is actually kept current.

**How to keep it from going stale (all verified):**
- **Code:** install the commit hook (`graphify hook install`) or run `--watch` during active work — code rebuilds are free and automatic. `[github]`
- **Docs/knowledge:** the hook and watch mode will **not** auto-update these (they cost tokens). Build a habit (or a scheduled job) of running `/graphify ./raw --update` after adding/editing documents. `[github]`
- **Merge, don't reset:** always `--update` so SHA-256 + dedup re-process only what changed and merge it in. `[github]`

A realistic personal cadence: hook on for every code repo; a periodic `--update` on your docs/notes folder (manually or via cron) so the knowledge base never drifts far from reality.

---

## Quick reference (verified against v0.8.30)

| Goal | Command | Cost |
|------|---------|------|
| First build of a corpus | `/graphify <path>` | code free; docs/images cost backend tokens |
| Add/changed data later | `/graphify <path> --update` | only changed files re-processed |
| Richer inference | `/graphify <path> --mode deep` | higher (more LLM passes) |
| Auto-rebuild on commit (code) | `graphify hook install` | free (AST only) |
| Live auto-rebuild (code) | `/graphify <path> --watch` | free (AST only) |
| Query, capped answer | `/graphify query "..." --budget 1500` | small (subgraph only) |
| Smaller chunks for local models | `graphify extract <path> --token-budget 30000` | lowers tokens/call |
| Fewer parallel model calls | `graphify extract <path> --max-concurrency 2` | eases local GPU/CPU load |
| Rebuild, overwrite even if smaller | `graphify extract <path> --force` | clears ghost nodes after deletions |
| Measure your own savings | `graphify benchmark` | free |

---

## Open questions / unverified

- **Flag set is version-dependent.** All of `--budget`, `--token-budget`, `--max-concurrency`, `--api-timeout`, and `--force` are documented in the **v0.8.30** release README (verified by grepping the raw file). `[github]` The shorter `main`-branch README omits them, so if you're on a different build, confirm with `graphify --help`.
- **Ollama backend specifics** — the *intent* (local SLM for docs to save cost) is well-supported `[interview]`, and backends install as extras `[github]`, but exact Ollama setup/flags were not confirmed from the raw repo here. See [05-local-models-and-backends.md](05-local-models-and-backends.md) and confirm with `--help`. `[unverified claim]`
- **Savings multipliers** — 71.5x is one Karpathy-corpus benchmark; independent testing suggests ~6.8x–49x realistically, ~1x–3x under ~100 files. Always measure your own. [community](https://www.roborhythms.com/graphify-review/)
- **Download/star counts** — creator figures (500K downloads, 43K stars) differ from third-party figures; all are time-sensitive. `[unverified claim]`
