Knowledge bundles: a graph you traverse, not a book you read

What a knowledge bundle is

A knowledge bundle is a directory of markdown files, one concept per file, designed to be walked as a graph rather than read as a document. Each concept carries a type — a person, a system, a procedure, a policy, a decision — and links to other concepts in the bundle. A person enters at whatever node is relevant and follows the links outwards. An agent does the same thing mechanically: it retrieves a concept and its neighbours instead of an entire document.

The defining property is that there is no reading order. A bundle has no first page and no ending, and no single file that contains the whole picture. Navigation happens through relationships, so the relationships are the content. That is why the quality of a bundle is decided by its edges and its citations rather than by the fluency of any single concept.

Why plain markdown and conventions are enough

Because the parts of a knowledge base that usually break are not the storage format. Markdown is readable by people and by every model and tool in common use, it diffs cleanly under version control, and it needs no runtime to open. Those are the properties that decide whether a corpus gets maintained.

What a bundle adds on top is a small set of conventions that turn a pile of notes into a graph. The Google Open Knowledge Format specification sets out this approach: a bundle of typed concept files with links between them, readable as prose and parseable as structure at the same time. The conventions are deliberately few, so that a person can hold them in their head and an agent engine can rely on them without a separate schema layer.

What has to be true for a bundle to work

A bundle works when a handful of small disciplines are followed consistently across every file.

• A type on every concept. Without a type, a concept is just a note, and a traversing agent cannot tell a procedure from a person or a policy from a product. The type is the cheapest structural fact in the bundle and the one that carries the most weight.
• Untyped links as edges, with the kind stated in prose. A markdown link carries no relationship kind. The convention is to state the kind in the surrounding sentence — "replaced by", "owned by", "supersedes" — so a person reads the relationship and a machine can recover it from the sentence.
• Per-claim sources. Every load-bearing claim in a concept points at something external and checkable. Without them, a bundle is a graph of assertions with no way to tell which still hold.
• Frozen conventions. Once the type vocabulary and the linking rules are set, they stop moving. A convention that changes every month produces a corpus where half the edges mean something slightly different from the other half.
• Aliases. Alternative spellings, former names, and abbreviations are recorded on the concept they belong to, so two spellings of one thing do not become two nodes and silently split the graph.
• Reserved index and log files. A bundle keeps a few predetermined files for entry points and for the record of what changed, which keeps the concept namespace clean and gives an agent a known place to start.

None of these is expensive on its own. Together they keep a corpus a graph as it grows, rather than letting it decay into a folder of documents that only a human can navigate.

How a bundle relates to RDF and JSON-LD

A bundle is a graph written in a form that is easy to author and review. RDF is the model it approximates: subjects, predicates, and objects, with an edge between two things as first-class as the things themselves. The difference is where the structure lives — in a bundle it lives in the prose and the conventions; in RDF it lives in the serialisation, where a machine reads it directly.

That difference is a trade, not a defect. A bundle is fast to write, easy to review in a pull request, and readable by a model without a parsing step. RDF is explicit, queryable, and composable across sources, but it raises the authoring cost and the tooling requirement from the first file.

JSON-LD is the bridge. It expresses the same subject–predicate–object structure in a form web tooling and search engines already consume, so a bundle can be published as linked data when the graph is worth querying, without giving up the markdown that made it writable.