@vortex-os/ontos

A lightweight ontology of your operational world — objects, typed relations, and multi-hop traversal — built from your VortEX records, layered on @vortex-os/base. It is a distinct add-on from @vortex-os/memory-extended: memory-extended recalls what was said; ontos models what is and how it connects, and acts on recurring situations.

Sibling add-ons, one line: remember (memory-extended) · perceive (computer-use) · model (ontos).

Status — Phase 2 stable

Phase 1 is text-first: the ontology is built only from existing markdown records (the failure ledger, decision-log, memories, runbooks, [[wikilinks]]), with no screen perception and no background daemon (deferred — Phase 1 had to prove its value first; Phase 2 became conversation extraction, see below). Storage is sqlite (better-sqlite3) with recursive-CTE traversal — no graph DB (TypeDB/Neo4j) and no formal OWL/RDF reasoner.

Phase 1 (text-first graph) is the foundation below; Phase 2 (conversation extraction + cross-model verification) is the section after it. Implemented and verified (typecheck/build/verify 119/119; confirmed on a real instance — e.g. literal-control-bytes → 6 occurrences, guard fires):

• sqlite/OntosStore — schema; idempotent object/relation upsert (relId = sha256(source⏎relation⏎target)); alias-based identity resolution; hop-capped (≤ 3) cycle-guarded recursive-CTE traversal; recurrence count; clear() + a transaction wrapper for a true rebuild. Plus the relation_proposals table (kept SEPARATE from the trusted graph), additive migration, and confirmProposal / rejectProposal / proposalsFor.
• extract/ — the deterministic extractor (§4): failure ledger → recurring-failure subgraph (recurs-as occurrence→class, covered-by →rule); decision-log → decision: objects (+ wikilink candidates); memory → rule: objects; runbooks → action: objects (resolved-by targets). A record's relations: frontmatter field is read into TYPED, durable relations (applies →rule, builds-on lineage, relates-to generic) — validated for domain/range at extraction, with rejected entries and orphaned targets surfaced by the rebuild — so the decision graph carries the cross-references records actually make, not just wikilink candidates.
• enrich/ — agent-mediated LLM enrichment: build an extraction request, validate the agent's proposals (vocab + domain/range), tier them (deterministic HIGH / cross-model MEDIUM / self LOW / disagreed rejected), and store them as PROPOSALS only. A proposal never reaches the trusted graph until human-confirmed.
• writeback (§5-bis) — on confirm, persist the relation to the source record's ontos: frontmatter block via a format-preserving parseDocument round-trip (idempotent; malformed/colliding/ambiguous frontmatter untouched), so confirmed knowledge syncs across machines via git. The entry is self-contained (source+target node ids), so a deterministic rebuild-ontos re-derives it — confirmed record-sourced relations survive a rebuild.
• actions/ — recurringFailureGuard (the §5A fast-proof), why (§5B decision archaeology, evidence-first ≤ 3 hops), and proposalHints (surface unconfirmed links, hedged — actions read the trusted graph only).
• scripts/ — rebuild-ontos (read-only deterministic rebuild from _failures/decision-log/_memory/runbooks); enrich-ontos --emit|--ingest (the agent I/O wrapper) and --gc (reconcile orphans after rename/delete).
• CLI — vortex ontos check | why <target> via @vortex-os/base (optional; base works without ontos installed).

Deferred (later): identity embedding-candidates (optional reuse of @vortex-os/memory-extended's embedder when present), broader object coverage (Component extraction beyond runbooks), session-start ambient surfacing, and Phase 2 (vision / daemon).

Design: the concept and Phase 1 build spec live in the maintainer's VortEX instance (Codex-reviewed, 2 rounds).

Phase 2 — conversation extraction + cross-model verification

Phase 2 mines closed session transcripts (not just curated records) for ontology candidates, and proposes new objects so a conversation's substance is captured — not only relations between pre-existing objects. Everything stays a human-confirmed proposal, kept separate from the trusted graph.

• Safe by construction. Conversation candidates go to relation_proposals / object_proposals, never the trusted graph, until you confirm. Conversation trust is capped at MEDIUM (a matching record may be derived from the same conversation — circular corroboration), so HIGH stays human-only.

• Anchored. Each candidate cites a verbatim quote from a named message, validated against the transcript (forged/paraphrased quotes are dropped). Corroboration = COUNT(DISTINCT transcript) over append-only evidence.

• Durable. Confirmed conversation knowledge is written to an ontos-owned record under data/ontos/ that the rebuild reads back, so it survives a rebuild + syncs via git.

• CLI (enrich-conversation): --scan (auto pass: emit only transcripts not yet extracted; --limit caps transcripts/run) · --emit (→ agent) · --ingest (agent →) · --review · --confirm <id> · --reject <id> · --write-record. Extraction is agent-mediated (ontos has no LLM of its own); the transcript is treated as inert data.

• No re-extraction. A transcript-level extraction watermark (machine-local, keyed by the transcript's content hash) records which closed sessions are already mined, so --scan skips them. It survives re-chunking (hash, not the positional chunk id); an edited transcript re-extracts, and its stale unconfirmed conversation candidates are purged (confirmed knowledge and record-sourced proposals are never touched).

• Cross-model verification. A self-checked candidate is LOW; an independent second model (e.g. Codex) agreeing raises it to cross-model / MEDIUM. It is OPT-IN and privacy-gated: only with .agent/vortex.json → ontos.verify.crossVendorEgress (or --cross-vendor-egress) does ingest honor a cross-model verdict, and every candidate must clear a fail-closed gate — config on · deterministic secret/PII filter · the extractor's affirmative sensitive:false · only the triple + a ≤ 240-char quote ever leaves the host · ingest re-checks the whole gate and downgrades anything that fails.

• Used by default, hedged. Extracted knowledge is used immediately, scaled by conversationUse (high/medium/low — never asserted as fact); the user corrects rather than approves. It earns confidence from salient un-objected use and loses it from a correction. A re-ingest can demote a stale verdict (same conversation source only; a different transcript's corroboration, and confirmed/rejected rows, are protected).

• Surfacing. Session start shows a 🧠 ontos: line; a fresh install shows a one-time rebuild-ontos bootstrap cue instead of sitting dormant.

Still a follow-up: sensitive-transcript handling (local model / redaction) is not done — pilot on non-sensitive transcripts only. Verified by 119 tests + a real-conversation dogfood (cross-model verification + the privacy gate, end-to-end on real data).

Develop

npm run typecheck --workspace=@vortex-os/ontos
npm run build     --workspace=@vortex-os/ontos
npm run verify    --workspace=@vortex-os/ontos