ontology Skill in Practice: Installing a Knowledge Graph for Your AI Agent (126k Downloads Explained)

What ontology Does: A Concept Dictionary for AI

Most AI agents handle questions using vector similarity — find the nearest match and go. The ontology skill takes a different approach: it gives your AI agent a structured network of concept relationships, letting it understand hierarchies, types, attributes, and connections between entities explicitly.

With 126k+ downloads on ClawHub (top 3 overall), we've run it in production for three weeks. Here's what it actually solves.

Installation and Basic Configuration

Install with one command:

clawhub install ontology

After install, an ontology/ directory appears in your workspace. The core file is ontology.json — your knowledge graph definition. Basic structure:

{"version":"1.0","namespace":"sfd-lab","entities":{"Agent":{"type":"class","properties":["name","role","capabilities"],"relations":{"reports_to":"Agent","owns":"Project"}},"Project":{"type":"class","properties":["name","status","stack","repo"]}}}

Use Case 1: Role Inference in Multi-Agent Collaboration

Without ontology, dispatching a task means manually stuffing background context: which server, what repo URL, who has SSH access. With ontology, define your instances once:

{"instances":{"小蜜蜂":{"type":"Agent","role":"DevOps","capabilities":["SSH","PM2","Nginx"],"servers":["149.104.44.34"]}}}

ontology resolves these relationships automatically and injects the right context into the task. The agent receives a complete task without back-and-forth clarification.

Use Case 2: Graph Queries

ontology includes a lightweight graph query interface. Ask in natural language, get precise results via graph traversal (not vector similarity):

ontology query "who owns database"
# Output: 小章鱼 (Backend Dev) — owns PostgreSQL, Redis

Use Case 3: Document Auto-Association

Tag documents with entity labels and agents get related documents automatically surfaced when working on relevant tasks. No manual context hunting.

Lessons Learned

Pitfall 1: Validation is strict. Any typo in ontology.json causes silent load failure. Always run: ontology validate ontology/ontology.json

Pitfall 2: Don't over-define instances. We defined every port and process — file ballooned to 500 lines, queries slowed. Trim to "information needed across agent boundaries" and 120 lines is more effective.

Pitfall 3: Relationship with MemOS. ontology handles structured relationships (who is who, who owns what). MemOS handles semantic memory (how was this done before). They're complementary — we use both.

SFD Lab Notes

We installed ontology to solve information silos. The bigger value turned out to be eliminating ambiguity in collaboration. When 15 agents all say "database," they might mean different things. ontology forces you to make those fuzzy concepts explicit. That process alone makes team collaboration clearer.

126k downloads didn't happen by accident.