Semantic & behavioral¶
TOVIO understands your repository as more than a pile of text. When the semantic layer is on, it keeps a live map of your code's symbols — functions, types, who calls what — and it can version the behavior of an AI system on its own, apart from the code that runs it.
These guides cover three jobs:
- Read a semantic diff — see a change as "this export was removed, that signature changed," not just added and removed lines.
- Query the symbol graph — ask where a symbol is defined, who calls it, and what depends on it.
- Version AI behavior — snapshot, diff, and roll back an agent's model, prompts, tools, and memory without touching a line of code.
Built and default-on — optional and additive
The semantic layer is built and on by default: tovio semantic diff, the tovio semantic
symbol-graph queries, the semantic-check land gate, and the tovio behavioral registry are
implemented in the current source tree. No generally available package has been published. It
stays optional and additive — TOVIO is fully usable without it, and it never sits on the
critical path of a commit, land, or sync, so turning it on can't slow or block a core operation.
A CLI built with --no-default-features never builds the index, and the tovio semantic
command group is not compiled into that binary at all. The symbol_context, symbol_relations, and change_impact MCP tools are implemented.
The remaining AI-facing item is a production tovio resolve --ai provider integration; the
consent/redaction/audit seam and hermetic mocks exist.
What "semantic" buys you¶
A text diff sees lines. The semantic layer sees structure. That difference shows up in three places:
| Without the semantic layer | With it on |
|---|---|
"12 lines changed in auth.ts" |
"verifyToken(). signature changed — a breaking interface change" |
| "grep for the function name" | "tovio semantic callers 'verifyToken().' — from the recorded call graph, not a text match" |
| Agent behavior scattered across prompt files and config | One behavioral snapshot you can diff and roll back |
Under the hood it is one idea applied twice. TOVIO maintains an incrementally-updated symbol graph
(definitions, references, call and test relations, type hierarchies) stored as ordinary
content-addressed objects — a per-file symbol-shard and a per-commit symbol-xref — and it stores
behavioral snapshots as objects of their own. Both are just data in the same store your commits live
in — versioned, syncable, and re-hashed on read like everything else.
Before you start¶
- The layer indexes Rust, TypeScript/JavaScript, Python, and Go with pure-Rust parsers. A file in any other language is simply not indexed — the semantic diff and the queries skip it rather than failing, and the plain text diff still covers it. You never lose a diff; you just don't get the symbol-level view for that file.
- The queries are read-only intelligence over your existing history. Indexing itself is part of
commit: each commit records a pointer to its symbol graph, and a behavioral snapshot or rollback re-seals the current commit with a pointer to the snapshot — the tree, parents, message, and change ID stay exactly as they were, though the re-sealed commit is a new address and the lane advances to it. - Symbols under a policy-protected path live in sealed shards. A reader who holds the file's key sees them stitched into the graph; anyone else sees the clear-path projection only.
- For the bigger picture of how TOVIO models a repository, see the concepts. For how agents consume this surface, see the agents guide.
Last reviewed September 9, 2026
Suggest an improvement to this page Not for security reports — see disclosure