Structure that remembers why
Protocol + Runtime · v0.1.0Self-Describing Protocol for
Evolving Systems
Ontology + Reflection + Daemon + MCP— encode what a system IS (invariants, tensions, constraints) and where it IS GOING (state dimensions, transition conditions, membranes) in machine-queryable directed acyclic graphs. Software projects, personal operational systems, agent contexts — same three files, same protocol. First-class web UI (12 pages), MCP server (19 tools), live session sharing. One protocol for developers, agents, CI, and individuals.
Protocol + Runtime. Zero enforcement.
Architecture
The 7 Problems It Solves
Decisions Without Memory
- Architectural choices made in chat, forgotten after rotation
- No machine-queryable source of why something exists
- ADRs as typed Nickel: invariants, constraints, supersession chain
- Hard constraints enforced at every operation
Invisible Configuration Drift
- Configs change outside any review cycle
- No audit trail linking change to PR or ADR
- Rollback requires manual file archaeology
- Sealed profiles: sha256 hash, full history, verified rollback
Agents Without Context
- LLMs start each session with zero project knowledge
- Same mistakes, same questions, no accumulation across operations
- Actor registry tracks each session token, type, current mode, last seen — persisted to disk
- MCP tools give agents direct DAG read/write: nodes, ADRs, backlog, Q&A
- Composed tasks shared via daemon — multiple actors see the same operational context live
Scattered Project Knowledge
- Guidelines in wikis, patterns in docs, decisions in Slack
- No single source queryable by humans, agents, and CI equally
.ontology/separates three orthogonal concerns:core.ncl(what IS) ·state.ncl(where we ARE vs want to BE) ·gate.ncl(when READY to cross a boundary)reflection/reads all three and answers self-knowledge queries — an agent understands the project without reading code, only by consulting the declarative graph
Protocol Fragmentation
- Each project re-invents its own conventions
- No shared contract for how operations are defined and executed
- Reflection modes: typed DAG contracts for any workflow
- One protocol adopted per-project, without enforcing uniformity
Knowledge Lost Between Sessions
- Q&A answered in one session forgotten by the next
- Agent re-asks questions already answered in previous sessions
- Q&A Knowledge Store: typed NCL, git-versioned, persists across browser resets
- Notification barrier surfaces drift to agents proactively — pre_commit, drift, ontology_drift signals block until acknowledged
Decisions Without a Map
- Personal and professional decisions made against implicit, unverifiable assumptions
- No queryable model of what you never compromise
- No structured way to ask: does this opportunity violate who I am?
- ontoref as personal operational ontology — same core/state/gate files applied to life, career, and ecosystem dimensions
jpl validate "accept offer"→ invariants_at_risk, relevant edges, verdict
Ontology & Reflection — Yin and Yang
Yin — The Ontology Layer
What must be true
- Invariants — axioms that cannot change without a new ADR
- Tensions — structural conflicts the project navigates, never resolves
- Practices — confirmed patterns with artifact paths to real files and declared ADR validators
- Gates — membranes controlling readiness thresholds
- Dimensions — current vs desired state, with transition conditions
- Q&A Knowledge Store — accumulated Q&A persisted to NCL, git-versioned, queryable by any actor
Yang — The Reflection Layer
How things move and change
- Modes — typed DAG workflow contracts (preconditions, steps, postconditions)
- Forms — parameter collection driving modes
- ADR lifecycle — Proposed → Accepted → Superseded, with constraint history
- Actors — developer / agent / CI, same protocol, different capabilities
- Config seals — sha256-sealed profiles, drift detection, rollback
- Quick Actions — runnable shortcuts over modes; configured in
.ontoref/config.ncl - Passive Drift Observer — watches code changes, emits
ontology_driftnotifications with missing/stale/drift/broken counts
Ontology without Reflection = correct but static. Perfect invariants with no operations = dead documentation.
Reflection without Ontology = fluid but unanchored. Workflows that forget what they protect.
The protocol lives in coexistence.
Protocol Stack
Web UI — 12 Pages
The Web UI — 12 Pages
Project health, drift status, actor overview, and pending notifications at a glance.
Graph
Force-directed D3 visualization of the ontology DAG. Yang·Axiom diamonds, Yin·Tension circles, Spiral·Practice squares.
Search
Full-text search across nodes, ADRs, and reflection modes.
Sessions
Actor registry with token, type, registered_at, last_seen, and current mode per actor.
Notifications
Notification feed for pre_commit, drift, and ontology_drift signals. Acknowledge, dismiss, or emit custom notifications with action buttons.
Backlog
Work items filterable by status with add/update operations.
Q&A
Server-hydrated knowledge store from reflection/qa.ncl. Add, edit, and delete entries — persisted as typed NCL.
Actions
Quick actions catalog from .ontoref/config.ncl. Execute runnable shortcuts over modes via POST /actions/run.
Modes
Reflection mode list from reflection/modes/ — name, description, and full DAG contract per mode.
Compose
Interactive mode forms with live session sharing for multi-actor workflows.
The UI in Action · Graph View
Daemon & MCP — Runtime Intelligence Layer
ontoref-daemon is an optional persistent process. It caches NCL exports, serves 12 UI pages, exposes 19 MCP tools, maintains an actor registry, stores notifications, indexes everything for search, and optionally persists to SurrealDB. Auth is opt-in: all surfaces (CLI, UI, MCP) exchange a project key for a UUID v4 session token via POST /sessions; CLI injects ONTOREF_TOKEN as Bearer automatically. It never changes the protocol — it accelerates and shares access to it. Configured via ~/.config/ontoref/config.ncl (Nickel, type-checked); edit interactively with ontoref config-edit. Started via NCL pipe bootstrap: ontoref-daemon-boot.
The MCP Server — 19 Tools
- search, get_node, list_adrs, get_adr, list_modes, get_mode, constraints — full DAG traversal.
Notification Barrier
- pre_commit — pre-commit hook POLLs
GET /notifications/pending?token=X&project=Y; blocks git commit until all acked - drift — schema drift detected between codebase and ontology
- ontology_drift — emitted by passive observer with missing/stale/drift/broken counts after 15s debounce
- Fail-open: if daemon is unreachable, pre-commit hook passes — commits are never blocked by daemon downtime
- Ack via UI or
POST /notifications/ack; custom notifications viaPOST /{slug}/notifications/emit - Action buttons in notifications can link to any dashboard page
SurrealDB Persistence — Optional
- Enabled with
--dbfeature flag and--db-url ws://... - Connects via WebSocket at startup — 5s timeout, fail-open (daemon runs without it)
- Seeds ontology tables from local NCL files on startup and on file changes
- Persists: actor sessions, seeded ontology tables, search index, notification history
- Without
--db: DashMap-backed in-memory, process-lifetime only - Namespace configurable via
--db-namespace; credentials via--db-username/--db-password
Technology Stack
Crates & Tooling
ontoref-ontology
Load .ontology/ NCL files as typed Rust structs. Graph traversal (callers, callees, impact queries). Invariant extraction and constraint validation. Zero stratumiops dependencies — minimal adoption surface.
ontoref-reflection
Execute reflection modes as typed NCL DAG contracts. Step execution with dependency resolution. ADR lifecycle from Proposed through Accepted to Superseded. Config seal and rollback operations.
Nushell Modules
store.nu (SurrealDB-backed cache with NCL export) · sync.nu (ontology code synchronization) · describe.nu (actor-aware project self-knowledge) · coder.nu (structured session records). 16 modules total — one per operational domain.
Nickel Schemas
Core ontology types: Node, Edge, Pole, AbstractionLevel. State machine types: Dimension, Transition, Gate, Membrane. ADR schema: Constraint, Severity, Status, supersession. Reflection schema: Mode, Step, OnError, Dependency.
ontoref-daemon
Actor registry via DashMap. Notification barrier with pre-commit hook integration. Compose forms for shared mode dispatch. SurrealDB-backed persistence as opt-in feature. NATS feature gate for distributed setups.
Adopt in Any Project
ontoref setup wires up any new or existing project — idempotent scaffold with optional auth key bootstrap.
Protocol Metrics
Structure That Remembers Why
Start with ontoref setup. Your project gains machine-queryable invariants, living ADRs, actor-aware operational modes, and a daemon that shares context across every actor in real time.