How to Do Graph Engineering in a Markdown Vault
Your linked vault is already 80% of a graph index. The missing 20% is typed edges, supersedes chains, a lint, and a recall budget. Here is how to build each one.
TL;DR
Graph engineering is making the relationships between your notes explicit enough that an AI agent can traverse them, not just read them.
Plain wikilinks say two notes are related. They never say how. Typed edges, supersedes chains, a graph lint, and a bounded recall budget close that gap.
Every step below is a general method first. My open-source vault system is the worked example, running in public.
In the graph engineering field guide I defined the term: structuring knowledge as nodes and explicit relationships so agents can answer chain questions. Who decided this. What replaced it. What broke because of it.
That post ended with a claim: a vault of linked markdown is already 80% of a graph index. This post is the missing 20%, as a build sequence you can copy.
One boundary first. “Graph engineering” also gets used for wiring multi-agent workflows, nodes as agents, edges as routing. That is a different discipline with its own tooling, and this post is not about it. This is about your knowledge.
Step 1: choose a small edge taxonomy
The principle: name the relationship types you will actually need to traverse, and keep the list small. Every type needs an inverse, or your graph only reads one direction.
Ask one question per candidate type: will an agent ever need to follow this to answer a real question? If not, it does not earn a place.
In my vault system, obsidian-second-brain, the answer settled at six types: supersedes, depends_on, caused, decided_by, contradicts, and a generic relates_to. Each carries an inverse (superseded_by, required_by, caused_by, decides). Six survived because agents kept needing them. A dozen others did not.
To pick your own set, work backwards from questions, not from ontology. Write down the five questions you actually ask your notes (”what is the current decision on X”, “what breaks if we change Y”), then keep only the edge types those questions traverse. A type you cannot attach a real question to is decoration.
And resist the generic type. Everything can be relates_to, which is exactly why it carries almost no signal. Use it only when nothing sharper is true.
Step 2: put edges where machines read them
The principle: a relationship buried in prose is invisible to traversal. Edges live in structured metadata, stated once, in a place a parser reaches without reading the whole note.
In markdown that place is frontmatter. This is the entire syntax in my system:
relations:
supersedes: ["[[ADR-006 - Use Redis]]"]
depends_on: ["[[Tide Gateway]]"]
caused_by: ["[[Redis outage 2026-03]]"]
Nothing here needs a graph database. The nodes are files. The edges are three lines of YAML. Any tool that parses frontmatter can now walk decision chains in either direction.
Two traps to skip. First, relationships stated only in prose (”this replaces our earlier Redis decision”) feel recorded but are unreachable: an agent would have to read and correctly interpret every sentence in the vault to find them. Second, tags are not edges. A tag groups notes; it has no direction, no target, and no meaning an agent can follow.
You also do not need to retrofit the whole vault on day one. Start writing edges on new notes and on any old note you touch. The graph grows along the paths you actually use, which is also the order in which it pays off.
Step 3: make truth supersede, not accumulate
The principle: in a knowledge graph that lives for months, the dangerous notes are not the wrong ones. They are the formerly right ones. Without an explicit “this replaces that” edge, an agent retrieves the old truth with the same confidence as the new.
So every decision that reverses an earlier one carries a supersedes edge, and retrieval must respect it: the superseded note steps back in search results instead of competing with its replacement.
This is the single highest-value edge type. In my vault, search honors supersedes chains and fades notes marked declined or archived, so an agent asking “what is our current approach” gets the current approach.
Step 4: lint the graph like code
The principle: a graph nobody validates rots quietly. Edges point at renamed notes. Cycles appear. Inverses go missing. None of it is visible while you write, all of it corrupts traversal later.
So the graph gets a linter, run the way you run tests. Mine flags five failure classes: unknown edge types, dangling targets, self-edges, supersedes cycles (A replaces B replaces A), and missing inverse edges. It runs inside the vault health check, and a typed edge pointing at a note that does not exist is an error, not a suggestion.
If you build only one piece of tooling from this post, build the lint. It is the difference between a graph and a pile of arrows.
Step 5: give agents a traversal budget
The principle: an agent with unlimited graph access does not get smarter, it drowns. Traversal needs a budget: how many nodes per question, what confidence justifies including one, and what happens on a miss.
My numbers: at most 4 notes injected per prompt, abstain when relevance is unsure, fail closed when retrieval errors. I wrote up the reasoning in how I gave Claude Code memory without a vector DB: memory as a recall budget, not a database. The graph makes the budget spend better, because a typed edge is a reason to include a note, not just a similarity score.
When a loop beats a graph
The strongest advice in the practitioner literature is also the least exciting: keep it a loop first. A vault with thirty notes does not need an edge taxonomy. A workflow that reads three files does not need traversal.
Graph engineering earns its cost when chain questions start failing. Three concrete signals, in the order they usually appear:
“What is the current approach” returns a superseded answer with full confidence.
“Why does this exist” needs more than one hop, and the agent stops at hop one.
Two notes contradict each other and nothing in the system knows they are even related.
I hit that wall around month four of running an AI-maintained vault, documented in Karpathy’s LLM Wiki v2: what to keep. Until you hit it, plain links are fine.
What is still missing
Honesty section. Two pieces of my own 20% are not finished. Multi-hop traversal queries (follow depends_on two levels out) work only as manual link-following, not as one retrieval call. And I have not yet published measured recall numbers for graph-aware retrieval against flat search on the same vault. The eval harness exists in the repo; the benchmark post is future work, and I would rather ship the method now and the numbers when they are real.
That is the practice: four buildable pieces, one boundary, one budget. The graph is not the product. The answers are.
Frequently asked questions
What is graph engineering?
Structuring knowledge as nodes and explicit typed relationships so AI agents can traverse chains (what replaced X, what depends on Y) instead of only matching similar text. The full definition is in the field guide linked above.
Do I need a graph database like Neo4j to do graph engineering?
No. Markdown files as nodes and frontmatter YAML as edges give you a working graph index. A dedicated graph database matters at a scale most personal and team vaults never reach.
What are typed edges in a knowledge graph?
Relationships with a named meaning and direction, like supersedes or depends_on, instead of a bare link. The type is what lets an agent follow the right edge for the question it was asked.
How is this different from GraphRAG?
GraphRAG extracts entity graphs from documents automatically at retrieval time. Graph engineering as practiced here writes the edges at authoring time, where the author still knows the relationship. The trade is a little discipline for much higher edge precision.
How do AI agents actually use a markdown knowledge graph?
Through retrieval that respects the edges: superseded notes step back, dependency chains resolve in order, and a bounded number of the most relevant notes gets injected into the agent’s context.
When should I not build a knowledge graph?
When chain questions are not failing yet. Small vaults and short-lived projects do better with plain links and a search tool. Add edges when the wrong-old-answer problem shows up.
Key takeaways
A linked markdown vault is 80% of a graph index. The missing 20% is typed edges, supersedes chains, a graph lint, and a recall budget.
A plain wikilink says two notes are related. A typed edge says how, and direction plus inverse is what makes traversal possible.
The supersedes edge is the highest-value relationship type: it is the difference between retrieving current truth and retrieving confident stale truth.
Lint the graph like code. Dangling targets, cycles, and missing inverses corrupt traversal silently until a validator makes them errors.
Agents need a traversal budget, not unlimited graph access. Four notes per prompt with abstention beats a context window full of maybes.
Do not graph-engineer three notes. Add the machinery when chain questions start returning stale answers.
Further reading
What is graph engineering? A field guide for builders - part 1: the definition, the evidence, and the viral fake study that started the discourse.
We are entering the graph engineering phase - the post that put the term in circulation.
GraphRAG and multi-hop question answering - research grounding for where graphs beat vector retrieval.
obsidian-second-brain on GitHub - the open-source implementation every step above ships in, MIT-licensed.
About the author
Eugeniu Ghelbur writes The AI Operator, a publication about practical AI systems. He maintains Obsidian Second Brain, an open-source system starred by over 3,700 developers on GitHub. The writing here comes from building and maintaining that public system.