Skip to content
Back to search

evoontology

MarketplaceWorks with Claude CodeGitHub

EvoOntology: a self-evolving ontology layer for data agents. Install with `claude plugin install evoontology@evoontology`.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ruc-datalab--evoontology/badge.svg)](/listings/ruc-datalab--evoontology)

HTML

<a href="/listings/ruc-datalab--evoontology"><img src="/api/listings/ruc-datalab--evoontology/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the plugin from the GitHub marketplace—no repository clone, virtual environment, or separate `pip install` is required.

🤖 Claude Code

claude plugin marketplace add ruc-datalab/EvoOntology
claude plugin install evoontology@evoontology
claude plugin list

Start a new session, then run:

/evoontology:build-ontology
/evoontology:evolve-ontology
/evoontology:explore-ontology

🤖 Codex

codex plugin marketplace add ruc-datalab/EvoOntology
codex plugin add evoontology-codex@evoontology
codex plugin list

Start a new thread, then ask Codex to use:

$build-ontology
$evolve-ontology
$explore-ontology

Both plugins use the same Build / Evolve / Explore workflow names; only the platform-native invocation syntax differs.

Codex prepares questions from user needs, relevant project history and grounded exploration; question/trajectory files are optional. Build and Evolve automatically open the outcome explorer. SQLite has built-in read-only task replay; other data sources use host tools with explicit observation recording. See [Codex plugin](plugins/evoontology-codex/README.md).

Once built, the Data Agent can call `browse_semantics` and `resolve_semantics` without additional ontology configuration. See the [usage guide](USAGE.md) for the full workflow and data boundaries.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "evoontology",
  3. "description": "EvoOntology: a self-evolving ontology layer for data agents. Install with `claude plugin install evoontology@evoontology`.",
  4. "owner": {
  5. "name": "RUC DataLab",
  6. "url": "https://github.com/ruc-datalab"
  7. },
  8. "plugins": [
  9. {
  10. "name": "evoontology",
  11. "source": "./plugins/claude-code",
  12. "description": "Build, evolve, and explore a self-evolving ontology layer through three skills, a semantic MCP runtime, and a session-start evolution reminder.",
  13. "category": "data",
  14. "tags": ["ontology", "ontology-layer", "self-evolution", "data-agent", "text-to-sql", "mcp"]
  15. }
  16. ]
  17. }
README.md · README · 232 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="assets/logo.png" alt="EvoOntology" width="68%">
  3. </p>
  4. <h1 align="center">EvoOntology: A Self-Evolving Ontology Layer for Data Agents</h1>
  5. <p align="center">
  6. <a href="https://arxiv.org/abs/2609.15779"><img src="https://img.shields.io/badge/arXiv-2609.15779-b31b1b.svg?logo=arXiv" alt="arXiv"></a>
  7. <a href="https://github.com/ruc-datalab/EvoOntology"><img src="https://img.shields.io/badge/MCP-compatible-7c3aed.svg" alt="MCP compatible"></a>
  8. <a href="https://github.com/ruc-datalab/EvoOntology/tree/master/plugins/evoontology-codex"><img src="https://img.shields.io/badge/Plug--in-codex-white.svg" alt="Codex plugin"></a>
  9. <a href="https://github.com/ruc-datalab/EvoOntology/tree/master/plugins/claude-code"><img src="https://img.shields.io/badge/Plug--in-claude--code-orange.svg" alt="Claude Code plugin"></a>
  10. <a href="https://github.com/ruc-datalab/EvoOntology/stargazers"><img src="https://img.shields.io/github/stars/ruc-datalab/EvoOntology?style=flat&amp;logo=github&amp;color=3941EA" alt="GitHub stars"></a>
  11. <a href="https://github.com/ruc-datalab/EvoOntology/forks"><img src="https://img.shields.io/github/forks/ruc-datalab/EvoOntology?style=flat&amp;logo=github&amp;color=3941EA" alt="GitHub forks"></a>
  12. <a href="https://hitscounter.dev/history?url=https%3A%2F%2Fgithub.com%2Fruc-datalab%2FEvoOntology"><img src="https://hitscounter.dev/api/hit?url=https%3A%2F%2Fgithub.com%2Fruc-datalab%2FEvoOntology&amp;label=Views&amp;icon=graph-up&amp;color=%233941ea&amp;message=&amp;style=flat&amp;tz=Asia%2FShanghai" alt="Page views: today / total"></a>
  13. <a href="assets/wecom.jpg"><img src="https://img.shields.io/badge/WeCom-%E5%8A%A0%E5%85%A5Data%2BAI%E4%BA%A4%E6%B5%81%E7%BE%A4-black?logo=wechat&amp;logoColor=07C160" alt="Join the Data+AI Enterprise WeChat group"></a>
  14. </p>
  15. <p align="center">
  16. <a href="README.md"><strong>English</strong></a> | <a href="README.zh-CN.md">简体中文</a>
  17. </p>
  18. > **Authors:** [Meiduo Chong](https://github.com/MeiduoChong), [Shaolei Zhang](https://zhangshaolei1998.github.io/)<sup>*</sup>, [Ju Fan](https://iir.ruc.edu.cn/~fanj/), [Xiaoyong Du](https://info.ruc.edu.cn/jsky/szdw/ajxjgcx/jsjkxyjsx1/js2/7374b0a3f58045fc9543703ccea2eb9c.htm)<br>
  19. > Renmin University of China<br>
  20. EvoOntology is the first self-evolving ontology layer for data agents, aiming to bridge the **agent-data gap** over heterogeneous tables, files, and databases. It exposes a versioned **Ontology Layer through MCP tools**, grounds that layer in real workload evidence, and continuously adapts it from execution trajectories.
  21. - 🔌 Universal Agent Plugin as MCP: Seamlessly integrates with Claude Code, Codex, and other AI agents.
  22. - 🤖 Automatic Ontology Construction: Builds a tailored ontology layer directly from your data.
  23. - ♻️ Continuous Self-Evolution: Continuously evolves and refines the ontology layer based on interaction history.
  24. ## 🎬 Demo
  25. The Codex and Claude Code plugins build and evolve ontology layers over your data.
  26. https://github.com/user-attachments/assets/e15f4acd-7161-4ae1-ba41-f2f3ea05488b
  27. ## 🧭 EvoOntology Makes Your Data Valuable!
  28. - **Raw data leaves semantics implicit.** Table names, columns, file paths, and isolated observations rarely explain metric definitions, entity relationships, or business constraints. Agents must infer them repeatedly and are prone to semantic errors.
  29. - **Static semantic layers do not scale with use.** Hand-authored layers require sustained expert maintenance, become stale as data and workloads change, and consume increasing context when injected in full.
  30. - **Agents need semantics that can adapt.** EvoOntology provides a workload-grounded Ontology Layer that agents query on demand and that evolves from observed execution behavior under controlled evaluation.
  31. <p align="center">
  32. <img src="assets/evoontology-overview.png" alt="Data Agents with and without EvoOntology" width="92%">
  33. </p>
  34. <p align="center"><strong>An agent-first, self-evolving ontology layer for Data Agents.</strong></p>
  35. ## ✨ Why EvoOntology?
  36. ### 🎯 Problems We Address
  37. - **Semantic uncertainty.** Make domain concepts, data mappings, relationships, and constraints explicit instead of leaving agents to guess from raw sources.
  38. - **Repeated data exploration.** Reuse grounded knowledge across tasks so agents can focus on relevant data rather than rediscovering the environment for every request.
  39. - **Costly semantic maintenance.** Adapt the Ontology Layer to changing workloads and agent behavior while keeping updates inspectable, comparable, and reversible.
  40. ### 🧩 Design Highlights
  41. | Principle | Core idea |
  42. | --- | --- |
  43. | **Active access** | Retrieve only the semantics needed for the current step through MCP tools instead of injecting the full ontology. |
  44. | **Grounded construction** | Build around the workload and commit semantic objects only after verification against the underlying data. |
  45. | **Targeted evolution** | Diagnose interaction trajectories and apply localized updates to the interconnected Content, Schema, and Tool Layers. |
  46. | **Gated versioning** | Publish a Candidate only when paired evaluation shows a reproducible improvement over its Parent. |
  47. | **Agent integration** | Connect the ontology workspace and MCP runtime directly to supported agents through plugins. |
  48. ## ⚙️ How It Works?
  49. EvoOntology treats the Ontology Layer as trainable agent state—not model weights. A builder initializes grounded semantic objects from the workload and underlying data; an evolution agent then uses historical interactions to propose bounded updates and validates every Candidate against its Parent.
  50. <p align="center">
  51. <img src="assets/evoontology-framework.png" alt="EvoOntology builder and evolution framework" width="100%">
  52. </p>
  53. ### 🧠 The Ontology Layer
  54. Three interconnected layers define the ontology's knowledge, representation rules, and runtime access:
  55. | Layer | Role |
  56. | --- | --- |
  57. | **Content Layer** | A typed semantic graph with four node families: Terms, Mappings, Constraints, and Evidence. Semantic Relations connect Terms, while Structural References link Terms to Mappings and attach Constraints or Evidence to the objects they govern or support. |
  58. | **Schema Layer** | Defines the fields of the four node families, the allowed Semantic Relation types, and the permitted Structural Reference patterns, thereby setting the ontology's representational boundaries. |
  59. | **Tool Layer** | Exposes the ontology through `browse_semantics`, `resolve_semantics`, and a compact session manifest. The manifest initializes the session; detailed records and linked objects are retrieved on demand. |
  60. <p align="center">
  61. <a href="assets/ontology-layers/content-layer.png"><img src="assets/ontology-layers/content-layer.png" alt="Content Layer in the EvoOntology explorer" width="96%"></a><br>
  62. <sub><strong>Content Layer:</strong> inspect grounded concepts, mappings, constraints, evidence, and their relationships.</sub>
  63. </p>
  64. <table>
  65. <tr>
  66. <td width="50%" align="center">
  67. <a href="assets/ontology-layers/schema-layer.png"><img src="assets/ontology-layers/schema-layer.png" alt="Schema Layer in the EvoOntology explorer" width="100%"></a><br>
  68. <sub><strong>Schema Layer:</strong> inspect object types, fields, and controlled relationship rules.</sub>
  69. </td>
  70. <td width="50%" align="center">
  71. <a href="assets/ontology-layers/tool-layer.png"><img src="assets/ontology-layers/tool-layer.png" alt="Tool Layer in the EvoOntology explorer" width="100%"></a><br>
  72. <sub><strong>Tool Layer:</strong> inspect MCP tools and the compact runtime manifest.</sub>
  73. </td>
  74. </tr>
  75. </table>
  76. <p align="center"><sub>Click any screenshot to open the full-resolution view.</sub></p>
  77. ### 🔄 Lifecycle
  78. 1. **Build** —derive candidate concepts from the workload, verify them against raw sources, and publish `ontology_v0`.
  79. 2. **Use** —let the Data Agent query the Ontology Layer on demand while its tool interactions and outcomes are recorded.
  80. 3. **Evolve** —diagnose recurring behavior, attribute it to Content, Tool, or Schema, and produce a localized Candidate patch.
  81. 4. **Evaluate** —compare Parent and Candidate with the same data, agent, decoding settings, and interaction budget.
  82. 5. **Publish or reject** —publish the passing Candidate as `ontology_vN+1`; otherwise retain the Parent and use the result in the next round.
  83. ## 🚀 Quick Start
  84. Install the plugin from the GitHub marketplace—no repository clone, virtual environment, or separate `pip install` is required.
  85. ### 🤖 Claude Code
  86. ```bash
  87. claude plugin marketplace add ruc-datalab/EvoOntology
  88. claude plugin install evoontology@evoontology
  89. claude plugin list
  90. ```
  91. Start a new session, then run:
  92. ```text
  93. /evoontology:build-ontology
  94. /evoontology:evolve-ontology
  95. /evoontology:explore-ontology
  96. ```
  97. ### 🤖 Codex
  98. ```bash
  99. codex plugin marketplace add ruc-datalab/EvoOntology
  100. codex plugin add evoontology-codex@evoontology
  101. codex plugin list
  102. ```
  103. Start a new thread, then ask Codex to use:
  104. ```text
  105. $build-ontology
  106. $evolve-ontology
  107. $explore-ontology
  108. ```
  109. Both plugins use the same Build / Evolve / Explore workflow names; only the
  110. platform-native invocation syntax differs.
  111. Codex prepares questions from user needs, relevant project history and grounded exploration; question/trajectory files are optional. Build and Evolve automatically open the outcome explorer. SQLite has built-in read-only task replay; other data sources use host tools with explicit observation recording. See [Codex plugin](plugins/evoontology-codex/README.md).
  112. Once built, the Data Agent can call `browse_semantics` and `resolve_semantics` without additional ontology configuration. See the [usage guide](USAGE.md) for the full workflow and data boundaries.
  113. ## 📊 Performance
  114. Across the four-backbone analysis subset, the builder-constructed **Initial Ontology Layer** improves over **ReAct without an Ontology Layer**, and self-evolution produces a further gain with **EvoOntology** on all three benchmarks.
  115. | Benchmark | Primary metric | ReAct without Ontology Layer | Initial Ontology Layer | EvoOntology | Gain over ReAct |
  116. | --- | --- | ---: | ---: | ---: | ---: |
  117. | DDR-Bench (10-K) | Trajectory-Wise | 69.5 | 81.8 | **89.5** | **+20.0** |
  118. | InsightBench | Insight | 53.2 | 54.0 | **54.2** | **+1.0** |
  119. | BIRD | Execution Accuracy (EX) | 63.6 | 68.7 | **72.4** | **+8.8** |
  120. <p align="center"><sub>Results use the four-backbone analysis subset in the <a href="https://arxiv.org/abs/2609.15779">paper</a>: GPT-5.5, GPT-5.6-sol, Claude-Sonnet-5, and Claude-Opus-4.8. DDR-Bench values are reported directly in Tables 2 and 8; InsightBench and BIRD values are one-decimal means of the Figure 3 scores and match the stage gains stated in the accompanying analysis. See Tables 1, 3, and 4 for the full six-backbone results and evaluation protocols.</sub></p>
  121. ### 🧪 Evaluation Environments
  122. EvoOntology includes self-contained adapters for three complementary Data Agent settings:
  123. | Benchmark | Task | Directory |
  124. | --- | --- | --- |
  125. | BIRD | Text-to-SQL over real-world databases | [`benchmarks/bird/`](benchmarks/bird/) |
  126. | DDR-10K | Open-ended research over heterogeneous financial data | [`benchmarks/ddr_10k/`](benchmarks/ddr_10k/) |
  127. | InsightBench | Iterative business analysis and insight generation | [`benchmarks/insightbench/`](benchmarks/insightbench/) |
  128. Each environment implements an `EvolutionAdapter` and preserves its native rollout and evaluation protocol. List registered environments with `python -m benchmarks list`; see [Adding a benchmark](docs/guide/new-benchmark.md) for the integration contract.
  129. ## 🗂️ Repository Layout
  130. | Path | Purpose |
  131. | --- | --- |
  132. | [`assets/`](assets/) | README media, framework figures, and ontology-layer interface screenshots. |
  133. | [`evoontology/`](evoontology/) | Deterministic core: ontology store, runtime/MCP, trajectories, triggers, evaluation, evolution state, validation, and visualization. |
  134. | [`plugins/`](plugins/) | Self-contained Claude Code and Codex plugins with Build, Evolve, and Visualize skills. |
  135. | [`benchmarks/`](benchmarks/) | BIRD, DDR-10K, and InsightBench evaluation environments. |
  136. | [`docs/`](docs/) | Architecture and benchmark-integration documentation. |
  137. | [`scripts/`](scripts/) | Core-to-plugin synchronization utilities. |
  138. ## 📚 Documentation
  139. - [Usage guide](USAGE.md) —installation, workspace, lifecycle, configuration, and end-to-end operation.
  140. - [Architecture](docs/architecture.md) —module boundaries, evolution state machine, and evaluation modes.
  141. - [Add a benchmark](docs/guide/new-benchmark.md) —adapter, data loader, rollout, configuration, and seed-skill contract.
  142. - [Claude Code plugin](plugins/claude-code/README.md) and [Codex plugin](plugins/evoontology-codex/README.md) —client-specific installation and usage.
  143. ## 🖋 Citation
  144. If this repository is useful for you, please cite as:
  145. ```bibtex
  146. @misc{chong2026evoontologyselfevolvingontologylayer,
  147. title={EvoOntology: A Self-Evolving Ontology Layer for Data Agents},
  148. author={Meiduo Chong and Shaolei Zhang and Ju Fan and Xiaoyong Du},
  149. year={2026},
  150. eprint={2609.15779},
  151. archivePrefix={arXiv},
  152. primaryClass={cs.AI},
  153. url={https://arxiv.org/abs/2609.15779},
  154. }
  155. ```
  156. If you have any questions, please feel free to submit an issue or contact `zhangshaolei98@ruc.edu.cn`.
  157. ## Misc
  158. Welcome to join the [Data+AI Enterprise WeChat group](./assets/wecom.jpg), chat and share ideas with other users.
  159. <p align="center" width="100%">
  160. <img src="./assets/wecom.jpg" alt="Data+AI Enterprise WeChat group" style="width: 35%; min-width: 300px; display: block; margin: auto;">
  161. </p>
  162. If you like EvoOntology, give it a GitHub Star ⭐
  163. [![Star History Chart](https://api.star-history.com/svg?repos=ruc-datalab/EvoOntology&type=Date&legend=top-left)](https://star-history.com/#ruc-datalab/EvoOntology&type=date&legend=top-left)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.