novgraph

A live knowledge graph of your codebase, queried by coding agents.

Command-line client for Novgraph, a hosted knowledge graph of a git
repository. The graph holds your files and symbols as nodes and their real
relationships as typed edges, and coding agents query it over MCP or the shell
for four things a file read cannot give them: the recorded intent behind each
commit, files that change together without importing each other, ranked blast
radius, and computed architecture.

Token savings: 78% to 99.74% per answer, measured against the cost of
reading the files each answer cites — not modelled, not estimated from a
benchmark.

This repository is the client only — auth, agent detection, MCP registration
and request transport. Python 3.11+, standard library, no dependencies, no
engine. Indexing, storage and retrieval run on Novaya's servers.

uv tool install novaya      # the PyPI package is `novaya`
novgraph install <KEY>      # generate a key at https://app.trynovaya.com

install detects every supported agent on the machine, registers the MCP
server, writes a pointer into each agent's instruction file, adds a
/novgraph command, resolves which indexed codebase this checkout is, and
verifies each step. novgraph doctor re-runs those checks with an exit code.

What problem it solves

A coding agent starts each session with no memory of the repository. To answer
"what does this touch", it greps, opens files, and infers — spending tokens to
rebuild a picture it loses at the end of the session. Three classes of fact are
not recoverable that way at all:

Novgraph holds all three in a knowledge graph per repository and answers from
the graph. A query returns a few hundred tokens where the equivalent file reads
cost tens of thousands, and every answer reports the difference measured against the files
it cites:

◆ Novgraph · saved you an estimated ~191k tokens · ~622k this session
  traced what changes with core/novgraph_summary.py · vs reading the 12 files it cites

Measured range: 78% to 99.74% fewer tokens per answer. The floor is a short
answer about a small file — a ~223-token summary against a ~1k file is 78%. The
ceiling is a structural answer about a large dependency set — ~500 tokens
against the 191k of cited files above is 99.74%. The ratio is a property of how
much the answer's cited files would have cost to read, so it is reported per
answer rather than claimed as a headline.

What's in the knowledge graph

One graph per repository, built from the working tree and the full git history.

Language coverage is Python and JS/TS via tree-sitter, with a generic
tree-sitter path for Go, Rust, Java and C. Nothing about the graph is
hand-maintained: it is rebuilt from the repository on every push.

Features

• Recorded intent per commit. why <path> returns the reasoning behind the
  changes that touched a file, written back by agents via record-why.
• Co-change coupling. connections <path> includes files that historically
  change with it and have no static link to it, with the commit count.
• Blast radius, ordered by certainty. impact <path> separates facts
  (callers, importers) from history (co-change), and states when the history is
  too shallow to be evidence.
• Computed architecture. overview reports load-bearing files, de-facto
  subsystems, layering and dependency cycles.
• Exact identifier resolution, including module-level constants. A query
  for MAX_RETRIES returns its definition; if nothing is named that, the answer
  says so instead of returning fuzzy matches on a fragment of the name.
• History follows renames. After git mv, recorded reasoning and co-change
  edges move to the new path instead of staying attached to a path that no
  longer exists.
• Savings measured, not modelled. Every answer is compared against the
  token cost of reading the files it cites — 78%–99.74% in measured sessions.
  An answer whose baseline cannot be established reports no saving rather than
  a guess. /novgraph savings prints the per-query ledger.
• Per-session deduplication. A repeated query in one agent session returns a
  short reference instead of the same text again.
• Explicit staleness. While a new commit is indexing, changed files are
  flagged and ranked below fresh ones, and structural answers name the commit
  they describe. Anything newer than the index is reported as such, so the agent
  reads the working tree instead.

Knowledge graph vs. the alternatives

Commands

Setup

novgraph install <KEY>     set up this machine and repository, then verify
novgraph install -         read the key from stdin
novgraph doctor            re-run every check; non-zero exit on failure
novgraph doctor --json     same, machine-readable
novgraph doctor --quick    skip the MCP handshake and graph read
novgraph wire <agent>      set up one agent (claude-code, codex, cursor, ...)
novgraph adapters          list supported agents and what each one needs
novgraph key <KEY>         replace this machine's key
novgraph upgrade           update the client, then re-sync every bound repo
novgraph uninstall         remove every entry and file it wrote

Querying the graph

Each verb works in any terminal inside a bound repository, and is also exposed
as an MCP tool to agents.

novgraph summary                    what this project is
novgraph overview                   computed architecture
novgraph search <query>             locate code by concept or exact name
novgraph why <path>                 recorded reasoning behind a file
novgraph connections <path>         imports, callers, co-change
novgraph impact <path>              what breaks, most certain first
novgraph recent [limit]             recent commits and their intent
novgraph ask "<question>"           a briefing composed from several reads
novgraph record-why "<why>" --intent "..." --reasoning "..." --commit <sha>
novgraph codebases                  which repositories this key can read
novgraph call <tool> --json '{...}' any tool, including newer than this client

Agent workflows

install writes a /novgraph command into each agent that supports one:

/novgraph review          checks the current diff against co-change history
/novgraph brief <task>    files, constraints, blast radius, a plan
/novgraph impact <file>   what breaks, most certain first
/novgraph debug <error>   ranked causes, each with evidence and a check
/novgraph record          write a commit's reasoning back to the graph
/novgraph onboard [area]  guided tour of an unfamiliar codebase
/novgraph summary         the codebase at its latest indexed commit
/novgraph savings         measured token savings for this session

Codex has skills rather than slash commands, so there it is $novgraph.

What it writes

Plus .novgraph/rules.md, .novgraph/skills.md and .novgraph/blueprint.md
in the repository — generated, safe to commit.

Every edit is one named MCP entry and one marked block, added by
read-modify-write. A config file that cannot be parsed is left byte-for-byte
unchanged and reported. novgraph uninstall removes exactly what was written.

Key handling and data

• The key is stored in the OS credential store: Windows DPAPI, macOS Keychain,
  libsecret via secret-tool, or a 0600 file. It is never written to the
  repository, an agent config, or a log.
• NOVGRAPH_API_KEY overrides the store when set — for CI. NOVGRAPH_API_BASE
  overrides the endpoint.
• Requests carry the key, the query, and a per-session id. File contents are
  not sent. The hosted graph holds paths, symbol names, relationships,
  counts and recorded reasoning.
• Indexing reads the repository through your GitHub or GitLab grant on the
  server side; the client never uploads source.

Requirements

• Python 3.11 or newer. No third-party packages.
• A repository indexed by Novgraph — connect it at
  app.trynovaya.com.
• For the MCP path, an agent that speaks MCP over stdio. The shell verbs work
  anywhere.

Development

python -m pytest -q          # 80 tests, no network, no dependencies

Adding an agent is one module in novaya/adapters/ plus an entry in
ADAPTERS; there are eight to copy from. See
CONTRIBUTING.md. Report vulnerabilities privately per
SECURITY.md.

License

Apache-2.0 for this client. The hosted service it queries is proprietary.