Knowledge Architecture

An OKF Markdown bundle is the canonical knowledge corpus. People and agents edit this source. Indexes, graphs, exports, and runtime generations are rebuildable projections.

flowchart LR
  OKF["OKF Markdown and YAML"] --> AST["Validated AST and metadata"]
  AST --> Facts["Normalized semantic facts"]
  AST --> Search["BM25 and local vector indexes"]
  Facts --> RDF["RDF and bounded SPARQL"]
  Facts --> Rules["Mangle Datalog and proofs"]
  AST --> Graphs["Source and search graphs"]
  Search --> Hybrid["Explicit hybrid orchestration"]
  RDF --> Hybrid
  Rules --> Hybrid
  AST --> Publish["JSON, HTML, RDF, tar, MCP, runtime"]

Code and tests define the CLI behavior. The Wiki is the canonical CLI reference. The README is the product overview.

Shipped layers

Retrieval builds deterministic in-memory inverted and vector indexes. The default vector provider uses hashed word and character features without a model or network service. The Go API can supply another embedding provider. Hybrid CLI queries can use an OpenAI-compatible HTTP endpoint. Vectors use normalized float32 values. The optional on-disk cache uses the exact input digest and model fingerprint. Exact lookup uses postings. Prefix lookup uses a vocabulary range. Fuzzy lookup can scan the vocabulary.

The graph layer contains claim occurrences and explicit declaration, reference, supersession, contradiction, and derivation edges. The claim registry provides entity and predicate identity. The semantic fact layer projects these same assertions to RDF and Datalog without making the projections canonical. SPARQL handles graph-pattern queries. Mangle handles safe recursive rules and keeps asserted and derived facts distinct. The default profile does not apply closed-world negation; callers must select that profile explicitly.

Search supports type and tag metadata filters. It combines lexical and local vector candidates with a deterministic reranker. Hybrid query does not infer a query plan from prose. It runs only caller-supplied text, SPARQL, and Datalog routes, then fuses independent ranks and joins provenance back to source sections. It does not ship a cross-encoder reranker, remote embedding model, general OWL reasoner, or automatic GraphRAG reasoning agent.

The optional corpus schema validates allowed document types, paths, required metadata, typed local link predicates, and migration records. Stable claim entity IDs remain independent of filenames. Entity search and proposals are deterministic control-plane tooling; they are not an automatic entity resolver.

Maintenance and publication loop

flowchart LR
  Usage["Private usage events"] --> Insight["Stable gap insight"]
  Insight --> Job["Isolated job"]
  Job --> PR["Draft pull request"]
  PR --> Eval["Eval and GitHub checks"]
  Eval --> Approval["Approval and merge"]
  Approval --> Gate["Production required-check gate"]
  Gate --> Generation["Check-bound generation"]
  Generation --> Usage

insights from-usage converts recurring retrieval gaps into stable insights. An isolated job can research an insight and propose a draft pull request.

The worker reports bounded before and proposed eval pass counts. The publisher independently validates OKF, publication rules, and claim lifecycle history before GitHub review.

The pull request lists claim changes, evidence IDs, document impact, eval impact, and required human decisions.

An extracted, proposed, supported, or disputed claim disables low-risk auto-merge. Rejection, supersession, or archival of a verified claim also disables auto-merge.

GitHub approval and branch protection control the merge. After merge, the publisher verifies required checks on the production commit. It then creates the runtime generation and starts the next local usage cycle.