Concepts

knomit is a distributed, decentralized knowledge base built from facts, not documents on git. A handful of ideas explain the whole system — each one falls out of a single decision: make git the only source of truth, and represent knowledge as facts. This page is the reference companion to the visual Concepts overview.

A fact is a markdown file

Knowledge in knomit is a fact: one concise, atomic claim — not a chunk of an ingested document. Each is a plain markdown file: YAML frontmatter for structured metadata, a markdown body for the claim. The file is the fact — no database rows, no binary blobs, no opaque embeddings.

---
type: observation
origin: authored
confidence: 0.8
domain: [music]
entities: [alice]
sources: 1
refs:
  - src://knomit/src/preferences.ts@a1b2c3d
---
Alice prefers rock music over jazz.

Confidence, domains, entities, and provenance refs travel in the frontmatter. confidence is a degree of belief that can rise and fall; refs relate the fact to others, forming a graph. Because it’s just a file, humans edit it with any text editor and agents write it over MCP — both paths land at the same file, through the same operations.

Epistemic vs pragmatic

Every fact carries a kind that tells the consumer how to apply it. Epistemic facts describe what is — knowledge to weigh as evidence, with a confidence that can move. Pragmatic facts prescribe what to do — rules to follow or lean on. The leaf type refines this further:

Kind	Types
Epistemic — what is	observation (default), concept, process, principle, pattern, reference, synthesis, insight, hypothesis, methodology
Pragmatic — what to do	policy, heuristic

The epistemic/pragmatic split is the load-bearing one: it is the difference between knowing and acting. Only epistemic facts seed synthesis.

Origin

Independent of what a fact is (type) and how to apply it (kind), every fact records how it came to exist — its origin:

Origin	Meaning
authored	Written by a human or asserted by an agent via knomit_learn.
distilled	Emitted by the synthesis pipeline — a synthesis fact clustered up from sources.
discovered	Emergent — surfaced by the discovery engine from structural bridges nobody declared (see Emergent discovery).

origin is orthogonal to type and kind: a discovered fact is still a normal synthesis (a forward consequence) or hypothesis (a backward keystone) — origin only records that knomit inferred it rather than being told. Query the emergent set with origin: discovered on knomit_query.

Ontology & inheritance

Facts live in a directory tree under the ontology root (kb/ by default). That tree is not just organization — it carries meaning. A fact placed at a higher level applies to everything beneath it: a fact at kb/invariants/ is inherited by kb/invariants/concurrency/branch-lock/.

Each fact also declares its subject along three independent axes — its ontology path, cross-cutting domain tags, and named entities — which together make the corpus introspectable. The ontology is configurable; knomit ships with two: General Knowledge (a broad taxonomy derived from Wikipedia’s main topics) and Source Code Knowledge (a codebase taxonomy with topics like invariants, conventions, decisions, and gotchas).

The tree is not only a taxonomy: an ontology also declares validation rules that run against every fact on write, so it decides what counts as a well-formed fact in this knowledge base. See Ontologies for the file format, the rules, and how to write your own.

What a knowledge base repo contains

A knowledge base is an ordinary git repository, so it holds more than facts. Three root-level conventions matter.

README.md — the repo’s description

The description you see in the UI is README.md, read verbatim at HEAD. It is not metadata stored beside the repo: editing the description commits the file to the agent branch, so it has a history, diffs, and syncs with everything else. Capped at 64 KiB.

LICENSE — the terms

The terms the KB’s content is published under, at the tree root beside the README. knomit reports it, and since v0.5.3 can also write it: a missing LICENSE can be created from Manage and an existing one edited, the same way the README is.

One asymmetry with the README: a LICENSE over 64 KiB is refused rather than replaced. The server cannot read a file that size back to diff it safely, so it leaves the existing terms untouched instead of overwriting terms it never saw.

Looked up by that exact spelling only. LICENSE.md, LICENSE.txt, COPYING, and even License are not found, because the lookup is an exact tree-entry match rather than a case-insensitive search. A missing licence is not an error; “this KB states no terms” is an ordinary state.

Dot-prefixed paths are private

Any path segment beginning with . makes a path private — .github/, .knomit/, kb/.drafts/. Private paths are excluded from fact discovery everywhere: the search indexer, knomit verify, and the OKF exporter all skip them, and no fact is ever allocated one.

Discovery exclusion is absolute. Writing is not: a caller may name a path under .knomit/<area>/ explicitly and the fact tools will write it, which is how a periodic job keeps private state without polluting the corpus. Such a path is still private in every sense that matters here — invisible to every walker — it is simply reachable by name.

Private means “not knowledge”, not “invisible”

The rule governs walking, never opening. knomit still reads specific known paths by name — which is exactly what lets it load its own ontology definition from .knomit/ontology.yaml, a private path it depends on at boot.

So a dot-path is not hidden, blocked, or refused by storage. These files commit, diff, push and pull like any others. They simply never enter the corpus as facts.

Not to be confused with an OKF export repo

An OKF export repository has README.md and LICENSE at its root too, and the rules there are the opposite: both belong to the publisher, and knomit-okf never reads, writes, or stages either of them. The distinction is which repository you are looking at — your knowledge base, or the bundle it publishes.

How knowledge clusters

Beyond what each fact says about itself, the corpus has emergent structure the author never declared. Facts cluster by meaning — embedding similarity groups facts that talk about the same thing, wherever they were filed — and by classification — shared ontology paths, domains, and entities. The distill pass synthesizes each cluster into a synthesis fact, then re-clusters and distills again, producing a hierarchy from raw observations at the leaves to higher-order insight at the top.

Subsumption — never learned twice

When a fact is written via knomit_learn, knomit runs a near-duplicate check in the same category using embedding similarity before committing. If a match is found, the incoming fact subsumes the existing one — or is absorbed by it — producing a single fact that carries refs to both sources. Two chunks that say the same thing never pile up.

A special case: a hypothesis is subsumed by a newer observation when the world catches up to the prediction. The fact survives, its type transitions, and git history records the exact moment evidence closed the loop.

Peers, branches & consensus

knomit is distributed and decentralized by construction. Every peer — human or agent — operates on a long-lived personal branch (agent/<id>, derived from machine hostname plus a short hash of its Ed25519 key). All learn, update, and retract operations land on that branch. No peer writes main directly.

Consensus is reached deliberately: a peer’s facts are reviewed and merged into main — by a Librarian agent, a CI policy, or a human merge. Each peer then pulls main and merges it locally, inheriting the agreed truth instead of re-deriving it. Learning effort is shared, not re-paid. (Merge, never squash — see Remote sync.)

Provenance & signing

Every write — learn, update, retract, subsume, sync — is an atomic commit authored under an identity-carrying address. Agents use <agent-id>+<operation>@agents.knomit.io; humans use their own email with +operation subaddressing. Commits are signed with the agent’s Ed25519 key, which makes the (who, what, when, why) tuple cryptographic rather than hand-waved. The same key signs commits, names the branch, and authenticates remote sync — one identity, end to end.

The temporal graph

knomit treats git history as a first-class temporal axis, not an implementation detail. Each commit is a moment of belief. Refs resolve at commit-time, not at HEAD: reading a fact as-of commit C follows its refs to whatever those targets were at C, even if they have since been updated or retracted. The graph is a record of what was believed and when — never silently overwritten with “now”.

Git is the only source of truth

The SQLite search index, embeddings, and commit/graph caches are all rebuildable from git at any time. Git provides the proof system (signed commits), the temporal model (history), and the distribution model (push/pull/merge); everything else is ephemeral cache.

Ref forms

Refs anchor a fact to its source material — the evidence behind the claim. A ref points to another fact, to a source file, or to any web resource:

kb/technology/debugging/pool-fix.md

Local fact path — a fact in this knowledge base.

kb://a1b2c3d4e5f6/kb/technology/debugging/pool-fix.md

Repo-qualified — a fact in another repo mounted in this lens, addressed by that repo’s 12-hex id.

src://7b4887ce51d9/internal/store/service.go@<commit>:<blob>

Source anchor — a source file, pinned to a 40-hex commit and a 40-hex blob, optionally with #L10-L24. Why the blob.

https://example.com/doc

Plain URL — any web resource: article, paper, commit.

Refs are stored verbatim — never rewritten, resolved, or normalized. A ref is classified local when it does not start with kb:// and does end in .md; everything else is external.

Why a source ref carries a blob

The current src:// form names three things: the source repo’s id (its root commit, a different namespace from a knomit repo id), a full 40-hex commit, and the 40-hex blob of the file at that commit — optionally with #L10-L24.

The blob is what makes the citation durable. With it, git cat-file blob <blob> retrieves exactly the bytes that were cited, even if the file was later renamed or deleted. The older src://<source>/<path>@<commit> form is still accepted, but it is weaker on purpose: git show <commit>:<path> fails outright if the path did not exist at that commit, which is the failure the blob removes.

knomit stores no source objects and cannot verify a src:// ref for you — the command that resolves it is the check. Get the three parts from the checkout you are citing: git rev-list --max-parents=0 HEAD for the repo id, git rev-parse HEAD for the commit, and git rev-parse <commit>:<path> for the blob.

A kb:// path is a stable identifier: pass it back as knomit_explain’s file, or store it in a fact’s refs to cite across repos — the server never rewrites it. It is classified as an external ref rather than a local fact edge, so it contributes no evidence weight and creates no local provenance edge.

Synthesis & hypotheses

Review (knomit_review) is a session-based maintenance loop with three passes: prune (remove redundant or stale facts), distill (cluster related facts into a synthesis fact no individual source makes on its own), and reflect (record methodology facts from resolved hypothesis transitions). Hypothesize (knomit_hypothesize) is a separate, explicit pass that writes falsifiable hypothesis facts — and skipping is the expected default. Synthesis is the only LLM-backed feature. See Synthesis & hypotheses for the full pipeline and RAPTOR, and Emergent discovery for the effort dial and the bridge engine.

The MCP operational loop

MCP is the primary interface for humans (via Claude Code and editors) and agents alike. Eight tools cover the full fact lifecycle — their descriptions are written as prompt engineering for the calling model, so no scaffolding is needed to call them correctly (knowing when to call them is what Claude Code’s skills add). Each agent connects to a branch-scoped endpoint, so reads and writes land on its own branch automatically; isolation is structural, not convention. A single MCP server instance serves every repo and lens; each handler resolves its binding from the request, and the instructions sent to the model are computed per session from that binding. See MCP tools.