Markdown Frontmatter Knowledge Graphs
Markdown becomes a lightweight knowledge graph when notes carry typed metadata and relationships with enforceable meaning.
Evidence, retrieval, agents, and the paths that connect a question to a grounded answer.
Interactive model
Files become typed nodes and edges
The graph demo maps markdown entities connected by source, task, topic, and evidence relationships.
Live HTML simulation · adjust the controls and watch the computed output respond.
Interactive
Agent systems are graphs of state, routing, and tool access
This is a simplified teaching model. Its displayed values are computed from the controls; the article explains where the model stops.
Site connection
KRAIL reports markdown-frontmatter entities, edges, topic documents, search, think envelopes, and integrity artifacts in a repo-backed workspace.
Pilot-ready: The portfolio source calls KRAIL pilot-ready rather than polished production software. The modeling and validation practices below are recommendations unless explicitly identified as reported capabilities.
Frontmatter gives a readable note an addressable identity, type, lifecycle state, and explicit relationships. A graph emerges only when those fields have shared definitions and software can validate their targets; a folder full of tags is not automatically a knowledge graph.
id: claim-route-loop-time
type: claim
status: reviewed
topic: transit-analysis
supported_by:
- source-ntd-2025
about:
- route-loop-time-estimation
The prose can remain ordinary Markdown while tools query the typed metadata.
Reported KRAIL Capability and Modeling Recommendations
Project fact: the KRAIL portfolio source reports markdown-frontmatter entities, edges, and topic documents alongside deterministic file search, SQLite vector retrieval, task records, think envelopes, and integrity artifacts. It describes a local-first, headless runtime in a repository.
Project status: the same source calls the system pilot-ready. Stable IDs, controlled vocabularies, edge constraints, migration rules, and graph-quality metrics below are recommended modeling practices, not claims that the portfolio version enforces every rule.
| Statement | Classification |
|---|---|
| Markdown frontmatter represents entities and edges | Reported KRAIL capability |
| Files remain usable with Git and text search | Property of the repo-backed plain-text approach |
| Each node should have a stable ID independent of its filename | Recommended schema policy |
| Edge types should constrain valid source and target types | Recommended validation policy |
Nodes, Edges, and Semantic Contracts
A node is an entity with a durable identity, such as a source, claim, topic, task, or artifact. An edge is a typed assertion connecting two nodes. `supported_by` should mean evidentiary support; `depends_on` should mean workflow dependency; `about` should mean topical association. If every relationship is merely `related_to`, the graph cannot answer precise questions.
Recommended schema: require `id`, `type`, `status`, and a small set of typed relation fields. Keep filenames descriptive but do not use a path as the only identity because files move. Define cardinality and direction: a claim may have many supporting sources, while a supersession edge should point from the newer record to the older one.
Analogy limit: frontmatter is like an index card attached to a document. Unlike a database constraint, YAML text does not enforce uniqueness, referential integrity, authorization, or transactional updates unless separate tooling validates it.
| Node type | Useful fields | Example edge |
|---|---|---|
| Source | origin, captured_at, version, checksum | source supports claim |
| Claim | statement, status, confidence basis | claim supported_by source |
| Topic | label, aliases, scope | claim about topic |
| Task | owner, state, acceptance check | task depends_on task |
| Artifact | path, generator, verification | artifact derived_from source |
From Files to Queryable Indexes
A graph build reads frontmatter, normalizes IDs and relationship fields, validates targets, and materializes nodes and edges into an index. Full-text search remains valuable for exact phrases and identifiers; SQLite FTS5 officially provides full-text matching, prefix, phrase, proximity, Boolean queries, and relevance ordering. A graph traversal answers a different question: not 'which text contains this term?' but 'which reviewed claims depend on this source?'
Treat the index as derived data. The Markdown files remain the authored record, and a deterministic rebuild should reproduce the index. Record parser and schema versions, reject duplicate IDs, report dangling edges, and avoid silently guessing targets from similar filenames. Vector similarity may add candidates, but it does not create a semantically valid edge.
| Mechanism | Good at | Cannot establish alone |
|---|---|---|
| Text search / FTS5 | Exact terms, phrases, identifiers | Typed relationships |
| Frontmatter filters | Type, status, date, project | Relevance of prose |
| Graph traversal | Dependencies and provenance paths | Whether an asserted edge is true |
| Vector retrieval | Paraphrased topical similarity | Authorization or evidentiary support |
Worked Example
Suppose `claim-route-loop-time` is a reviewed claim supported by `source-ntd-2025`, and report `artifact-transit-brief` is derived from that claim. When the source note's checksum changes, a traversal finds the claim and then the report. An integrity job can mark both for review without scanning every file for matching words.
Now rename the source file from `ntd.md` to `sources/transport/ntd-2025.md`. Because the frontmatter ID remains `source-ntd-2025`, edges still resolve after rebuilding the index. If an author instead changes the ID without a migration alias, the validator reports a dangling `supported_by` edge rather than silently connecting to a similarly named source.
This is an illustrative schema and validation flow. The KRAIL source supports frontmatter graph capability, but it does not establish that these exact field names or migration behaviors are the portfolio implementation's contract.
| Change | Expected result | Reason |
|---|---|---|
| Move a file, keep ID | Edges remain valid | Identity is independent of path |
| Change source checksum | Dependent records become review candidates | Evidence freshness changed |
| Delete target node | Dangling edge error | Referential integrity is broken |
| Add similar prose | No automatic support edge | Similarity is not evidence |
Evolution, Governance, and Limitations
Recommended practice: version the frontmatter schema, validate in continuous integration, provide migrations for renamed types or IDs, and distinguish authored edges from generated suggestions. Review graph metrics such as duplicate IDs, dangling-edge count, orphan nodes, stale sources, and claims with no support. Generated backlinks should always be reproducible from forward edges.
Plain files trade database guarantees for portability and reviewability. Concurrent edits can conflict; large graphs may rebuild slowly; YAML types can surprise parsers; and access control cannot be inferred from a folder name. For high-volume transactional data or complex multi-user permissions, keep the repo as the durable contract while using a database or service as an execution index.
Common Pitfalls
- Using tags as decoration instead of defining queryable semantics.
- Using filenames as identities and breaking edges whenever files move.
- Treating vector similarity or co-occurrence as a verified relationship.
- Generating backlinks that cannot be rebuilt from canonical forward edges.
- Letting frontmatter drift from the prose without validation or review.
- Presenting recommended constraints as features already enforced by a pilot-ready project.
- Assuming YAML files provide database transactions, permissions, or referential integrity by themselves.