Graph structure

What’s in a node

A node is a single markdown file. Most code maps stop at an address: this thing lives in that file, on that line. That tells an agent where to look, not what it will find, so it still has to open the source and read. A Graft node holds the meaning inline, so the agent learns what it needs up front and opens the file only when it wants more.

Each node holds:

Part	What it holds
Summary	A plain-English explanation of what the code does, written by the model and cached. It is there whether or not the code was ever documented, and it is regenerated when the source changes.
Crux	The handful of lines that actually carry the logic: the guard, the skip condition, the state change. Lifted straight from the source and stored inline, so the agent sees how it works, not just what.
Sources	The exact files the node is built from, each tracked by a content hash, so Graft can tell precisely when a node has gone stale.
Links	Typed connections to other nodes (depends_on, part_of, uses, implements, produces), written as [[wikilinks]] your agent can follow.
Notes	Anything you write below the generated block. It is preserved across regenerations, so your own context is never overwritten.

That is three depths in one file: the summary says what the code does, the crux shows how, and the sources point to the rest if the agent needs it. A plain index makes it read a whole file to learn one thing. A Graft node hands it the answer inline, and the follow-up read often never happens.

The crux is stored as the code itself, not as a line range, on purpose. Line numbers drift whenever unrelated code above them shifts, but the lines that matter do not. Keeping the text, not the numbers, means the crux stays correct even as the file around it moves.

Summary, sources, links, and notes ship today in markdown nodes. The crux ships per-symbol in the code graph (graft build --deep); inlining it into markdown nodes is next.

What runs where

• On your machine, no key, no network: the structural code graph. graft build (wiring graph + per-file cards), graft check, and graft ask are deterministic tree-sitter — they never call a model.
• Through your provider key: the LLM-written parts — graft build --deep adds the concept nodes (file summaries + node synthesis) and the per-symbol summaries and cruxes. graft is vendor-neutral: set GRAFT_PROVIDER (openai for any OpenAI-compatible endpoint, or anthropic for the native API), your GRAFT_API_KEY, GRAFT_MODEL, and — for the openai wire format — GRAFT_BASE_URL to point at OpenRouter, Fireworks, Groq, a LiteLLM proxy, a local server, or OpenAI itself. Or pass --provider/--model/--api-key/--base-url on the command line. (OPENROUTER_API_KEY still works as a deprecated fallback.)
• No telemetry and no analytics — the only network calls are the LLM requests you configured.