EvoOntology: a versioned ontology layer that data agents query through MCP

The agent-data gap this layer is built to close

EvoOntology is described as a self-evolving ontology layer for data agents, and the problem it targets is specific: the agent-data gap over heterogeneous tables, files and databases. The argument starts from what raw data leaves out. Table names, columns, file paths and isolated observations rarely explain metric definitions, entity relationships or business constraints, so an agent has to infer them again and again, and it makes semantic errors while doing it.

The second target is hand-authored semantic layers. The project states that they do not scale with use, because they need sustained expert maintenance, they go stale as data and workloads change, and they eat context when injected in full into a prompt. The third is the requirement it believes follows: agents need semantics that can adapt.

The response is a workload-grounded ontology layer that agents query on demand and that evolves from observed execution behaviour under controlled evaluation. The package is a Python project from Renmin University of China, with Meiduo Chong, Shaolei Zhang, Ju Fan and Xiaoyong Du credited as authors, and it is published with an arXiv identifier, 2609.15779.

What is being proposed is not a new model. The project treats the ontology layer as trainable agent state rather than model weights, which is a different way to think about where an agent's learned knowledge lives.

Content, Schema and Tool are the three layers of the store

The ontology itself is defined by three interconnected layers, and the division of labour between them is what makes the design legible.

The Content Layer is a typed semantic graph built from four node families: Terms, Mappings, Constraints and Evidence. Semantic Relations connect Terms to each other, while Structural References link Terms to Mappings and attach Constraints or Evidence to the objects they govern or support. In other words, a Term is not just a name, it is a node with typed edges and attached constraints and evidence.

The Schema Layer defines the fields of those four node families, the allowed Semantic Relation types and the permitted Structural Reference patterns. That is where the representational boundaries are set. Anything not expressible in the permitted patterns is not representable at all, which keeps the ontology from drifting into free form notes.

The Tool Layer is the runtime surface. It exposes the ontology through browse_semantics, resolve_semantics and a compact session manifest. The manifest initializes a session, and detailed records and linked objects are retrieved on demand rather than pushed in at once. The repository also carries a visualization package with a template.html and vendored assets, and the documentation shows the layers as they appear in an explorer, so the graph is meant to be inspected by a human as well as read by an agent.

MCP as the delivery mechanism, plugins as the entry point

The delivery mechanism is the Model Context Protocol, and the project advertises itself as MCP compatible. Plugins are shipped for Claude Code and Codex, living under the plugins directory, and the repository also has a .claude-plugin directory, which is where a Claude Code plugin is declared. That means the ontology is not a library your application links against; it is a workspace plus an MCP runtime that an agent connects to.

The distinction matters for how you evaluate the project. There is no adapter layer to write, and no API calls to instrument in your own code. The agent asks for semantics over MCP, and the layer answers. The cost moves to the other side: the semantics have to be queryable through two named tools plus a session manifest, so an agent working with your data has to be able to run those tools and read their output.

Two project documents matter here, and neither is the README. USAGE.md exists in English and in a Simplified Chinese version, as does the README itself, and the docs directory holds the rest of the reference material. The README is the pitch and the architecture overview; the usage documents are where the operational detail lives, and the README does not reproduce them.

A builder constructs it, an evolution agent then revises it

The runtime has two halves. A builder initializes grounded semantic objects from the workload and from the underlying data. Then an evolution agent uses historical interactions to propose bounded updates and validates every Candidate against its Parent.

The word bounded is doing real work in that sentence. An evolution agent that can rewrite the whole ontology would destroy the parts that still work, so the update is meant to be localized. The design summary names the mechanism targeted evolution: diagnose interaction trajectories and apply localized updates to the interconnected Content, Schema and Tool Layers.

Grounded construction is the other half. The builder works around the workload and commits semantic objects only after verification against the underlying data. So a term is not written into the ontology because an agent mentioned it, it is written because it was checked against the data it describes. Evidence is one of the four node families for exactly this reason, since it is what records that a semantic object survived verification.

The loop is therefore builder, then evaluation of a proposal, then publication or rejection. In a project that also has benchmarks and tests directories, plus a scripts directory, the machinery for measuring this loop is part of the package rather than something a user assembles.

Gated versioning is what keeps evolution honest

The rule that decides whether a change lands is gated versioning: publish a Candidate only when paired evaluation shows a reproducible improvement over its Parent. The word reproducible is the important qualifier, since a single run that looks better is not evidence of anything, and an ontology that changes after every agent session would be worse than a static one.

Two consequences follow. The first is that evolution is expensive relative to editing. Every proposed update has to be evaluated against its parent, so a team that wants quick semantic fixes will find the gate slow. The second is that changes stay inspectable, comparable and reversible, which the project lists as the answer to costly semantic maintenance. Reversibility in particular depends on keeping Parent versions, which is why the layer is described as versioned in the first place.

This is also where the alternative approach deserves a straight comparison. A hand-authored semantic layer is faster to change and cheaper to run, because nothing is built or evaluated automatically; it just needs a human expert to keep it true. EvoOntology trades that directness for maintenance cost that does not scale with the number of semantic objects. Which side of the trade you are on depends entirely on whether you have both the expert time and the execution history.

Packaging is minimal: no runtime dependencies, Python 3.10 and up

The package metadata is short and worth reading before you plan an integration. The distribution is named evoontology at version 1.1.0, requires Python 3.10 or newer, and declares an empty dependencies list. The build backend is setuptools with a minimum of 61, and the ruff configuration sets a line length of 100 with the E, F, I and W rule sets selected.

Two optional dependency groups exist. The dev group carries pytest and ruff, and the bird group carries httpx, the openai client, python-dotenv and pyyaml. The core package itself pulls in nothing at install time, which means the runtime is self contained and the plugin or MCP integration path carries whatever else is needed.

There is exactly one console script:

[project.scripts]
evoontology-validate = "evoontology.validate:main"

That entry point is the one command the packaging metadata exposes, and it points at a validate module inside the package. The repository description for the package lists its contents as a versioned ontology-layer store, the runtime and MCP layer, trajectory recording, an evolution trigger and an evaluation gate, which is a good map of what you are installing.

Note what is not in the metadata: no database driver, no model client, no HTTP framework in the core dependencies. The README does not document an installation command, so the practical path is to work from the repository itself, where USAGE.md and the docs directory describe how the plugins are wired to an agent.

A young project with no tagged releases and a Chinese-first centre of gravity

The repository has no GitHub releases, so there is no version history to read on the release page, and the package version 1.1.0 in pyproject.toml is the only version reference you get. It is not archived and the last push was on 2026-10-09, so the work is current, and the repository holds a working area rather than a finished release: an .agents directory, a benchmarks directory, a scripts directory and a tests directory all sit next to the package.

Two signals about direction are worth noting. The README is bilingual, with an English file and a README.zh-CN.md, and the USAGE documents come in both languages as well, while the community links point at a WeChat group, a Mattermost server and Chinese and international social accounts. That suggests a group whose day-to-day work happens in Chinese and whose public artefacts are being pushed outward in English.

Licensing is MIT, with the LICENSE file at the repository root, and the pyproject metadata points at it through a license file entry. MIT is permissive, so embedding the package or the ontology it produces in a commercial product raises no copyleft obligation for the package itself. The ontology layer your agents build, however, is derived from your own data and your own workload history, and what that layer contains is your problem to govern rather than the licence's.

Editorial conclusion

Adopt EvoOntology if your agents keep rediscovering the meaning of the same tables and files, and if you have a workload history you can evaluate a new semantic layer against. Do not adopt it for a one-off query over a small, well documented dataset, or if you cannot supply the execution trajectories the evolution step needs. Verify first that your Python is 3.10 or newer, that your agent can speak MCP, and that the version 1.1.0 package exposes the browse_semantics and resolve_semantics tools you plan to depend on.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. ruc-datalab/EvoOntology on GitHub