--- # Post metadata id: "your-ontology-should-live-with-your-code" title: "Your Ontology Should Live With Your Code" slug: "your-ontology-should-live-with-your-code" subtitle: "Sovereignty, federation, and why knowledge infrastructure without a home isn't infrastructure at all" excerpt: "Enterprise knowledge graphs live in a triplestore maintained by a dedicated team on a vendor's platform. When the team changes, the budget gets cut, or the vendor pivots, the knowledge disappears. Ontoref takes the opposite approach: sovereign, local-first knowledge that lives alongside its subject, versioned, queryable across four surfaces, and federated without a central broker." # Publication info author: "Jesús Pérez" date: "2026-05-10" published: false featured: false # Categorization category: "ontoref" tags: ["ontoref", "sovereignty", "federation", "radicle", "jujutsu", "knowledge-infrastructure"] # Display read_time: "6 min read" sort_order: 4 css_class: "category-ontoref" category_description: "Ontoref — protocol and tooling for structured self-knowledge in software projects" category_published: true --- # Your Ontology Should Live With Your Code Jessica Talisman, in her KGC 2026 talk, says something worth highlighting: *"Your ontology is your moat — your IP."* She's right. And she's describing the enterprise knowledge graph model, where the moat is held in a vendor's triplestore, maintained by a dedicated team, on a platform with a subscription. When the team changes, the budget gets cut, or the vendor pivots, the moat drains. Ontoref takes the opposite approach. ## What Sovereign Knowledge Means In ontoref, the knowledge of what a project is — its principles, practices, tensions, architectural decisions, operational state — lives as NCL files alongside the code. In the repository. Versioned with the same discipline as the source. This is not a documentation approach. It's a storage decision with architectural consequences: - **No vendor can take it from you.** The ontology is in your repo, not their database. - **No platform migration.** GitHub, Gitea, Radicle — the knowledge moves with the code. - **No dedicated infrastructure.** The daemon runs locally; the files are the source of truth. - **Offline by default.** Knowledge that requires a network connection to exist is not infrastructure — it's a service. The closest analogy is SQLite vs. PostgreSQL: local-first, embedded, always available, no connection required. When you need distribution, you add it. But the baseline is sovereignty. ## Four Surfaces, One Source Sovereign storage doesn't mean isolated. Ontoref exposes the same ontological knowledge across four surfaces simultaneously: **CLI (Nushell):** The developer's native interface. `ontoref describe project`, `ontoref graph ontology`, `ontoref sync diff --docs`. Fast, scriptable, CI-composable. The surface for humans who live in the terminal and for automated checks that run in pipelines. **UI (axum):** A web interface for visual inspection, onboarding, and management. Not a dashboard over a remote API — a local server that renders the same NCL-backed knowledge. The surface for project managers, new contributors, or anyone who prefers navigating a graph visually. **MCP:** The agent surface. Ontoref's MCP endpoint is the semantic layer that sits above the transport protocol. As Talisman's framework correctly identifies, MCP moves bytes — it doesn't establish shared meaning. Ontoref provides that meaning through its ontological layer, exposed via MCP to agents that need structured knowledge about the project to work accurately rather than hallucinate context. **GraphQL:** The integration surface. SPARQL is the semantic web standard, but GraphQL is what most developers know and every tooling ecosystem supports. A GraphQL API over the ontological DAG removes the barrier of expertise without sacrificing structure. Four surfaces, one canonical source: the NCL files in the repository. ## jj and Radicle The storage model pairs naturally with a specific class of VCS tooling. **Jujutsu (jj):** A Git-compatible VCS where the working copy is always a commit — there is no dirty state. This aligns directly with ontoref's approach to continuous state capture: every project state is capturable, every transition is a first-class event. jj's operation log is the VCS equivalent of ontoref's reflection session history. **Radicle:** P2P, local-first, sovereign code collaboration. If the code is sovereign, the knowledge about that code should be too. Radicle as transport means the federation of ontoref-enabled projects doesn't depend on any centralized platform — no GitHub, no GitLab, no hosted Gitea. Nodes discover each other and exchange knowledge directly. Together: sovereign code and sovereign knowledge, distributed without a central broker. ## Federation Without a Central Broker The enterprise model for knowledge federation is a central knowledge graph that all projects point to. One team maintains it. One platform hosts it. Every query routes through it. Ontoref's federation model is different: ``` project-A queries: which projects implement "zero-trust-auth"? project-B, project-C respond from their own ontologies no central server that knows everything ``` This is possible because each project is self-describing. The ontological DAG in `.ontology/core.ncl` is queryable without any external dependency. Federation via NATS connects the daemons — each project's daemon registers itself, publishes its capabilities, and responds to queries from other daemons in the federation. The result: ecosystem-level visibility without ecosystem-level centralization. You can discover which projects share your architectural constraints, which implement compatible practices, which are in conflicting states — without any of them requiring a shared platform. ## Why This Architecture Now Two shifts made this viable: **Agentic AI as the consumer.** Before agents, knowledge infrastructure was built for human consumption — ontologists maintaining graphs for analysts to query. Agents are different: they need machine-readable, structured, typed knowledge to operate accurately. Ontoref's multi-surface model is designed for a world where the primary consumer of project knowledge is not a human reading a wiki but an agent making decisions in a context window. **Local-first as the default.** The decade-long trend toward cloud-hosted everything is reversing for knowledge infrastructure. The risks are clear: vendor lock-in, platform discontinuity, sovereignty loss, and the compounding cost of external dependencies for what should be internal knowledge. Local-first with optional federation is the architecture that survives platform changes. ## The Moat Argument Talisman's framing — "your ontology is your moat" — is more accurate than she might intend it to be. A moat works because it's attached to the thing it protects. A moat stored in someone else's database is not a moat. It's a service agreement. When the knowledge of what your project is, why it exists as it does, and what decisions have lasting consequences lives alongside the code that implements those decisions — versioned, queryable, sovereign, federated — it is genuinely yours. It accumulates. It survives team changes. It informs agents. It can be queried by projects that depend on you. That's the kind of moat worth building. --- *Ontoref is open source. The protocol specification, Nushell automation, and Rust crates are at [github.com/jesusperezlorenzo/ontoref](https://github.com/jesusperezlorenzo/ontoref).*