Treating the ontology as trainable agent state beats static semantic layers by 20 points

The core problem EvoOntology addresses is one that anyone who has watched an LLM agent thrash around a database will recognize immediately: the agent keeps rediscovering the same semantic facts from scratch. Column names don't explain metric definitions. Table relationships don't encode business constraints. Every new task starts from zero, burning context and accumulating errors. Static semantic layers—hand-authored data dictionaries, schema annotations—help initially but rot as data and workloads shift, and injecting them wholesale bloats the context window.

EvoOntology's answer is to treat the ontology as trainable agent state rather than a static document. It structures knowledge into three interconnected layers: a Content Layer (a typed semantic graph of Terms, Mappings, Constraints, and Evidence), a Schema Layer (the rules governing what can be represented), and a Tool Layer (two MCP tools, browse_semantics and resolve_semantics, plus a compact session manifest). The agent retrieves only the semantics relevant to the current step rather than loading everything upfront—keeping context lean while still grounding the agent in verified domain knowledge.

The evolution mechanism is what distinguishes this from a fancier data dictionary. After the initial ontology is built from workload evidence, an evolution agent diagnoses recurring failure patterns in interaction trajectories, proposes localized patches targeting whichever layer is responsible, and validates the Candidate against its Parent using the same backbone, data, decoding settings, and interaction budget. A Candidate only gets published as the next version if it demonstrably improves on its predecessor. That gated versioning keeps updates inspectable, comparable, and reversible—the README's explicit design goal.

The benchmark numbers are worth examining carefully. On DDR-Bench, a financial research task over heterogeneous data, the trajectory-wise score moves from 69.5 for a plain ReAct agent to 81.8 after the initial ontology build, then to 89.5 with self-evolution—a 20-point gain over baseline. On BIRD, the text-to-SQL benchmark, execution accuracy goes from 63.6 to 72.4. InsightBench shows a more modest improvement, from 53.2 to 54.2. These results are reported on a four-backbone analysis subset, and the README is explicit that full six-backbone results live in separate tables in the paper.

Installation is plugin-based for both Claude Code and Codex—no repository clone required, just three shell commands and then slash-commands or dollar-prefixed prompts to build, evolve, and visualize. The repo also ships self-contained benchmark adapters for BIRD, DDR-10K, and InsightBench, each implementing an EvolutionAdapter interface, which means the evaluation loop is reproducible rather than ad hoc.

One design constraint worth noting: the evolution lifecycle explicitly requires recorded interaction trajectories to diagnose and propose updates. The README describes this as a deliberate workload-grounded approach—semantic objects are committed only after verification against underlying data, and evolution is triggered by observed execution behavior rather than manual curation.