zerograph

A project knowledge graph that costs zero API tokens to build, keep fresh, and query.

Get started · See it in action · Features · Benchmarks · How it works · Docs

zerograph reads a repository's markdown and code in 24 languages, extracts the structure the authors already wrote by hand (requirement ids, cross-references, exports, imports, calls, decorators, ids quoted in comments) and answers questions about it in a few lines of text.

Why zerograph

• Zero tokens by default. Build, refresh and query run locally. ask --rerank can spend model tokens and is opt-in.
• A better door, not a better graph. Exact id, BM25 and local dense retrieval find the entry point from a question in ordinary words, in about 200 tokens an answer.
• Built for agents. --json on every reader, an MCP server, and hooks that keep the graph fresh.

Sources: the three-tool run and the 0.6.0 rows of bench/history/runs.jsonl.

Get started

npm install -g zerograph                   # or: pnpm add -D zerograph
echo .zerograph/ >> .gitignore             # the graph is built per checkout
zerograph build                            # first run downloads the embedding model (~1.2 GB)
zerograph ask cancellation policy          # stays fresh with your edits, no update to run
zerograph install-agent --claude           # optional: MCP server + git hooks for your agent

Prebuilt for macOS arm64, Linux x64 and Windows x64. Defaults read markdown and code in 24 languages; a zerograph.toml changes that (Configuration). install-agent takes --claude, --codex, --cursor, --copilot, --gemini or --opencode, several at once (MCP).

• On Windows: Windows notes.
• Upgrading from repograph: the old store, config and variables are read where they are, see coming from repograph.

See it in action

$ zerograph ask cancellation
packages/db/src/schema/salon/scheduling.ts:110  CANCELLATION_CONSEQUENCES
docs/.../BE-M10-payments-provider-stripe-connect-….md:80  BE-M10/T05  Cancellation policy engine (`packages/domain/policy.ts`): inputs policy + appoin…
  └ docs/.../BE-M10-payments-provider-stripe-connect-….md:1  BE-M10  BE-M10 Payments provider: Stripe Connect implementation…

Each line is path:line [ID] headline. A document id is printed; a code id is not, because the location and the name already say it. Top-level lines are the seeds the question matched; a └ line is a neighbour one hop away, printed under the seed it came from.

zerograph ask FR-PAY-22                    # an exact id or symbol goes straight to the node
zerograph impact StaffService              # callers by depth, importing files, a risk line
zerograph trace StaffController StaffService   # shortest call chain between two symbols
zerograph changes --base main              # what the diff touches, and who reaches it
zerograph explain FR-PAY-22                # one node and everything attached to it

Features

Build and refresh	build, update, watch, and a self-healing ask that re-reads what changed (keeping fresh)
Ask	ask, explain, impact, trace, changes, verify, families, all with --json (commands)
Resident process	serve answers a fused question in 66 ms instead of 326 ms (serve)
Agents	zerograph mcp, install-agent, prime (MCP)
Languages	TypeScript and JavaScript, Kotlin, Java, C#, Rust, Python, Dart, Swift, GraphQL, SQL, Bicep, HCL, Shell, Vue, Lua, Go, C, C++, PHP, Ruby, Scala, Elixir, OCaml (languages)
Optional spend	ask --rerank, a model picking seeds from a 200-deep pool per question (rerank)
Bench	zerograph bench fails the process when a recall floor is missed (benchmarks)

Configuration

zerograph.toml at the repository root, plus an optional machine file at ~/.config/zerograph/config.toml. Every key is optional. The globs, include, text_globs, model and resources keys, and the ZEROGRAPH_* environment variables are in configuration; embedder choice is in embeddings.

How it works

Exact id or symbol first, then BM25 over passages, then a dense list, interleaved rank by rank; the surviving seeds expand one hop over the id graph. The graph records only what a file proves, so a call through a chained expression or a callback has no edge: pair a "nothing uses this" with rg -l. See how it works and the graph model.

Documentation

All reference material lives in docs/:

• Use it: install, commands, keeping fresh, serve, MCP, configuration, Windows notes
• Understand it: how it works, the graph model, languages, embeddings, rerank
• Measure it: benchmarks, the measurements, bench campaigns, decisions

Contributing

Issues and pull requests are welcome at devmaxxx/zerograph. Before a pull request, run cargo test and cargo clippy --all-targets -- -D warnings; a change to retrieval is judged by the three-way rule.

License

MIT.