Concepts
knomit is a distributed, decentralized knowledge base built from facts 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, not documents.
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.
Confidence, domains, entities, and provenance refs travel in the
frontmatter. A 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.
--- type: synthesis confidence: 0.72 domain: [ai, agents, governance] entities: [OpenAI, KPMG, Anthropic] refs: - kb/technology/ai/trends/73f515b5.md ---
By mid-2026 a consistent pattern emerges across independent sources: agentic AI is displacing chatbots as the primary mode of enterprise AI use, simultaneously driving workforce and safety governance responses.
Every fact is one of two kinds: epistemic facts describe what is — observations, concepts, syntheses, hypotheses — knowledge to weigh as evidence, with a confidence that can move; pragmatic facts prescribe what to do — policies and heuristics — rules to follow or lean on.
The leaf type refines this further
(observation, principle, pattern,
synthesis, hypothesis, methodology,
and more), but the epistemic/pragmatic split is the load-bearing one: it
is the difference between knowing and acting.
The ontology is a directory tree under kb/ that is not just
organization — it carries meaning: a fact placed at a higher level applies
to everything beneath it, so a fact at kb/invariants/ is
inherited by kb/invariants/concurrency/branch-lock/.
The ontology is configurable. knomit ships with two:
General Knowledge — a broad taxonomy derived from
Wikipedia's main topic classifications, covering
technology, science, geography,
history, and more — and Source Code Knowledge
— a codebase taxonomy for AI agents, with topics like
invariants, conventions,
decisions, and gotchas.
An ontology also carries validation rules — expressions evaluated against every fact on write — so it does not just say where a claim is filed, it decides whether the claim may enter the corpus at all. Writing an ontology.
Clustering is emergent structure the author never declared: facts group by meaning — embedding similarity puts facts about the same thing together, wherever they were filed — and by classification — shared ontology paths, domains, and entities group facts by how they were declared.
The distill pass synthesizes each cluster into a
synthesis fact, then re-clusters and distills again, up
to depth 3. The result is a hierarchy of increasingly abstract
knowledge: raw observations at the leaves, higher-order insight at
the top.
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.
There is a special case worth knowing: a hypothesis is
subsumed by a newer observation when the world catches up
to the prediction. The fact survives, its type transitions, and the
git history records the exact moment evidence closed the loop.
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 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,
approved, and merged into main — by a Librarian agent, a CI
policy, or a human merge. No peer merges another's branch
directly; main is the single point of agreement.
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.
Every write — learn, update, retract, subsume, sync — is a commit
authored under an identity-carrying address. Agent commits use
<agent-id>+<operation>@agents.knomit.io as the
author; humans use their own email with +operation
subaddressing. Commits are signed with the agent's Ed25519 key.
That makes the (who, what, when, why) tuple cryptographic rather than hand-waved. The same key that signs commits also names the branch and authenticates remote sync — one identity, end to end. What that key protects →
knomit treats git history as a first-class temporal axis, not an
implementation detail. Each commit is a moment of belief: the state of
the fact graph as some agent understood it at that instant. The
git log of a fact is its epistemic history — how
the claim evolved, when confidence shifted, when sources were added.
So you can time-travel. Ask what was known as-of any commit, and the entire graph rewinds: every ref resolves to whatever its target was at that point in time, even if it has since been updated or retracted. The graph is a record of what was believed and when — never silently overwritten with "now".
Refs anchor a fact to its source material — the evidence behind the claim. A ref points to another fact, to a source file at a given commit, or to any web resource: an article, a paper, a press release. Refs are stored verbatim — never rewritten or resolved.
| Form | Meaning |
|---|---|
kb/technology/debugging/pool-fix.md | Local fact in this knowledge base |
kb://<id12>/kb/… | Fact in another repo mounted in this lens |
src://<repo>/<path>@<commit>:<blob> | Source file, pinned to a commit and a blob — so it resolves even after a rename |
https://… | Any web resource — article, paper, press release |
Review (knomit_review) is a
session-based maintenance loop with three passes: prune —
remove redundant or stale facts; distill — cluster related
facts and derive a synthesis fact (a higher-order claim
that no individual source fact makes on its own); reflect —
record methodology facts from resolved hypothesis
transitions. Synthesis produces new knowledge from what the corpus
already holds. How synthesis works.
Hypothesize (knomit_hypothesize) is a
separate, explicit pass over synthesis facts. For each one it decides
whether a hypothesis is warranted — a falsifiable,
forward-looking prediction with a concrete settlement criterion.
Skipping is the expected default; a hypothesis is
only written when it fills a genuinely load-bearing gap that new
evidence could close.
Every fact records how it came to exist — its
origin: authored (written or asserted),
distilled (synthesized from sources), or
discovered (emergent). It is orthogonal to type and kind:
a discovered fact is still a normal synthesis or
hypothesis — origin only records that knomit
inferred it.
Most systems retrieve what is similar to a query. knomit also discovers: an effort dial seeds from bridges — facts sharing a domain or entity yet sitting in different similarity clusters — and proposes the keystone those bridges imply. Load-bearing facts hide in exactly the cross-cluster links that similarity-only retrieval is structurally blind to. How discovery works →
MCP is not an optional add-on — it 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 none of them need scaffolding to be called correctly.
Each agent connects to a branch-scoped endpoint, so reads and writes land on its own branch automatically — isolation is structural, not enforced by convention. One server instance serves every repo and lens: each handler resolves its binding from the request, and the instructions the model receives are computed per session from that binding.