ontoref/assets/presentation/docs/posts/en/your-ontology-should-live-with-your-code.md

---
# 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).*