AI assistants reason better when they are given reliable facts instead of guesses. vg facts produces deterministic open facts for a code node — statements about its contract, invariants, and characterization — each typed by how it was derived. This article explains what facts are and how to use them.
Overview
For a given node, vg facts emits facts such as its contract (what it promises), invariants (what must always hold), and characterization (observed behavior). Crucially, each fact is epistemic-typed: it ranges from declared/static (read directly from the code) through to observed/derived (inferred from behavior). This lets a reader — human or AI — know how much to trust each statement.
Prerequisites
Build a code map so node analysis is available:
vg build
Generate facts
vg facts
The output is deterministic: the same code yields the same facts. That stability is what makes facts safe to feed into prompts and tooling — they will not drift between runs.
Why epistemic typing matters
Not all facts are equally certain. A declared type signature is more authoritative than an inferred invariant. By tagging each fact with how it was derived, vg facts lets you and your AI assistant weight them appropriately — trusting declared facts strongly and treating derived ones as hints.
Facts for AI assistants
Facts pair naturally with Vibgrate AI Context. Serve them, your code map, and version-correct docs to any assistant with the local offline MCP server:
vg serve
To wire the context server into your assistant:
vg install
See facts for AI assistants for a deeper walkthrough.
Related
- Inspect a node with
vg show. - See which tests cover a node with
vg tests. - Start the context server with
vg serve.
Facts are generated locally and remain on your machine.