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:
  - knomit://github.com/org/repo/src/preferences.ts
---
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).

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.

The knomit: URI scheme

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

Form	Meaning	Example
Relative (no authority)	Fact in the current knowledge base	knomit:/kb/technology/debugging/pool-fix.md
Absolute (with host)	Fact in an external repo	knomit://github.com/org/repo/src/main.ts
Plain URL	Any web resource — article, paper, commit	https://example.com/doc

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. Seven tools cover the full fact lifecycle — their descriptions carry all the behavioral guidance a model needs, no prompt scaffolding required. Each agent connects to a branch-scoped endpoint, so reads and writes land on its own branch automatically; isolation is structural, not convention. Three profiles (code, chat, generic) tailor the tool descriptions to the client. See MCP tools.