Knowledge graph

Khiip is designed to model relationships between captures as a typed knowledge graph: a small, purpose-designed vocabulary of canonical edges plus an escape hatch for everything else.

Status: planned

The edge vocabulary and storage schema are defined and locked (ADR-0005 / ADR-0007 / ADR-0008), and the Edge types live in the substrate. A read/write API to create and query edges is not yet surfaced — it’s planned, on no committed version. This page documents the design that’s in place, not a feature you can call today.

The edge vocabulary

SUPPORTS · CONTRADICTS · SUPERSEDES · ELABORATES · REFERENCES   +   RELATES

The five typed edges give deterministic, queryable semantics; RELATES is the escape for novel relationships the vocabulary didn’t anticipate. This hybrid model (per ADR-0008) is deliberate — a small, typed canonical set keeps edges deterministic and queryable while RELATES preserves coverage for the long tail.

Each edge also carries a plain-English template (e.g. “Khiip detected: {source} backs up {target}”) so relationships read naturally in any surface.

Interpretability fields

Every edge records, per ADR-0005 (Option Δ):

• evidence_span — the span that justifies the edge
• confidence — 0.0–1.0; ≥0.7 reads as a primary edge, below that as tentative
• vocab_match — whether it landed on a canonical type or fell back to RELATES

This lets you filter to high-confidence canonical edges, or include tentative emergent ones.

Storage

The graph lives in the SQLite index as an append-only structure with a correction chain (per ADR-0007) — edges are superseded, not deleted, so the history of how the graph evolved is preserved.