Today we're open sourcing Yurtle — the file format at the heart of everything we build at Congruent.AI.
The idea is almost embarrassingly simple: what if every .md file in your project was automatically part of a queryable knowledge graph? Not through a plugin. Not through a database. Just through the way you write the file.
The Problem
Knowledge management tools make you choose. You can have human-readable documents (Markdown, Notion, wikis). Or you can have machine-queryable structured data (databases, RDF stores, graph databases). Pick one.
If you pick documents, humans can read them but machines can't reason over them. If you pick databases, machines can query them but humans need special tools to see what's in there. And if you try both, you get sync problems — the document says one thing, the database says another, and nobody knows which is true.
The Solution: Three Layers, One File
A Yurtle file is a Markdown file with semantic frontmatter. That's it.
Layer 1 — Frontmatter. At the top of every file, structured metadata declares what this document is and how it relates to other things. You can write this in YAML (familiar) or Turtle RDF (powerful).
Layer 2 — Content. Standard Markdown. Write whatever you want. Link to other documents with [[wiki-links]]. Humans read this.
Layer 3 — Yurtle Blocks. Anywhere in your document, drop in a fenced code block with structured data. Define relationships, add measurements, record facts. Machines read this.
---
id: santiago-toddler-v11
type: Being
domain: children's literature
status: active
parent: santiago-fleet
---
# Santiago Toddler v11
A neurosymbolic being trained on early childhood literature...
\`\`\`yurtle
training_triples: 32609
extraction_precision: 0.976
last_trained: 2026-02-14
hypotheses_validated: 6
\`\`\`
That file is simultaneously:
- A readable document any human can understand
- A node in a knowledge graph that machines can query
- Version-controlled in Git with full history
No transformation step. No export. No sync. The file is the data.
Version 2.0: The Y-Layer Specification
When we started building AI beings that learn and reason, we needed to organize knowledge the way minds do — not just as a flat bag of facts, but with structure that reflects how knowledge is used.
Yurtle 2.0 introduces the Y-Layer Specification: seven layers of knowledge, organized by what the knowledge is for — Y0 Prose (raw source text with provenance), Y1 Semantic (entities, facts, relationships), Y2 Reasoning (rules, ontology, constraints), Y3 Experience (what the being did and said), Y4 Journal (what it thinks — opinions, reflections), Y5 Procedural (workflows and skills), and Y6 Metacognitive (calibration and error tracking).
The distinction between Y2 and Y3 is the one that does the work: rules you reason with are a different kind of thing from what happened to you, and collapsing them is how systems end up unable to say which of their beliefs are derived and which are remembered.
Every layer is just Yurtle files. Every layer is queryable. Every layer is versioned in Git.
This isn't theoretical — our beings are organized this way, and every fact traces back to its source document.
One honest note about where the format ends and our runtime begins. The Y-layer model is the durable part. Our own storage moved to Arrow tables in V14, and the seven layers carried forward unchanged — which is the useful evidence about the model, not a retraction of it. Yurtle remains the authoring and interchange format, and the spec is versioned independently of anything we run (it is at v2.1 now; v2.0 is the release that introduced the Y-layers described here).
Why This Matters
Yurtle is the foundation everything else in our stack builds on:
- yurtle-rdflib turns Yurtle files into SPARQL-queryable graphs
- yurtle-kanban tracks work as Yurtle files in Git — the whole board is the repo
- Our beings' definitional knowledge is organized by the Y-layer model this spec defines
But you don't need any of that to use it. A Yurtle file is a valid Markdown file. It works in Obsidian, VS Code, GitHub, anywhere Markdown works. The semantic layer is additive — it gives machines a way to read what you've already written for humans.
Get Started
pip install yurtle-rdflib # The Python implementation
Or just start writing .md files with structured frontmatter. That's all Yurtle is.
Repository: github.com/hankh95/yurtle License: MIT
The simplest possible bridge between human-readable and machine-queryable. No magic. Just files.