Knowledge Graphs

A platform engineer gets paged about a deprecated internal API. Before shutting it down, the runbook says to check what depends on it. There is no dependency graph — there is a wiki, four Slack threads, three services’ READMEs, and several people’s memories, none of which agree completely. The engineer greps the codebase for the API’s URL pattern, finds three callers, and ships the deprecation. A fourth caller, wired through a shared client library the grep missed, breaks a billing job two weeks later, quietly enough that nobody connects it back to the deprecation until a much longer investigation than the original question deserved.

Ask an AI agent the same question — what depends on this service — and it hits the identical wall, just faster. The agent can read every document in the repository in the time it takes a human to open the first one. What it cannot do is see a relationship nobody wrote down, because reading comprehensively is not the same operation as knowing where to look. Prose documentation, however complete, is optimized for one access pattern: read from the top, extract meaning as it goes. A dependency question is not a reading question. It is a traversal question, and a paragraph does not know how to be traversed.

What a graph is that a document is not

A knowledge graph is not a fancier document. It is a different data structure: a set of entities — services, components, people, decisions, concepts, whatever the domain calls for — connected by typed, meaningful relationships, instead of the same facts embedded in prose that has to be read start to finish before any single fact can be pulled back out. One of the more cited surveys of the field puts the formal version of this plainly: a knowledge graph represents structural relations between entities as a directed, edge-labeled graph — nodes for the things, labeled edges for how they relate to each other. The term is newer than the idea. Tim Berners-Lee, James Hendler, and Ora Lassila were describing essentially the same ambition in 2001 under the banner of the semantic web, aiming at “a new form of Web content that is meaningful to computers.” Google gave the current name its popular currency a decade later, framing its own search-index shift in a phrase that stuck: “things, not strings.”

Retrieval: a structural question, not a hopeful keyword

The first thing a graph buys over flat documentation is retrieval — asking a precise, structural question and getting a precise, structural answer, instead of running a keyword search and hoping the right document happens to contain the right words near each other. “What depends on this service,” “who has touched this code,” “which decisions relate to this component” are not prose-search questions. They are graph queries: follow the depends-on edges out of this node, follow the touched-by edges into this file, follow the relates-to edges from this component. A flat document store can approximate an answer to each with enough keyword luck. A graph does not approximate it; it returns exactly the set of things connected by exactly that relationship, because the relationship was made explicit when the graph was built, rather than left for a search index to infer after the fact.

Reasoning: what a document never made anyone write down

The second thing a graph buys is reasoning, and it is the less obvious one. If service A depends on service B, and B has a documented limitation, that limitation’s relevance to A is not a fact anyone necessarily wrote down about A — it is a two-hop traversal an agent or an engineer can perform only if the depends-on edge and the limitation both exist as structured facts to traverse between. A flat document about service A can only surface what someone thought, at the time they wrote it, to mention about service A. It has no mechanism for inheriting a fact from a document it never links to. A graph does, structurally, by construction: the traversal becomes available the moment both nodes and the edge between them exist, whether or not anyone ever sat down and composed the sentence “A is affected by B’s limitation.”

That A inherits B’s limitation was never written down about A. It was always there in the graph, the moment someone thought to draw the edge.

A framework: what belongs in the graph, and what stays prose

None of this argues for graphing everything. A schema that tries to capture every nuance ends up either too rigid to hold the nuance or too loose to query, and the discipline of knowing what to leave as prose is as much a part of building a useful graph as knowing what to model. A rough, practical split:

A decision graph is one instance of this, not a separate idea

This volume’s Decision Archives chapter treats one specific, narrower case of exactly this structure: a decision graph, where the entities are decisions and the edges are relationships like supersedes and relates-to, built to answer “why does this exist” rather than the more general “what does this connect to.” A decision graph is a knowledge graph scoped to one entity type and a handful of relationship types. Nothing about this chapter’s argument changes when the entity is a decision instead of a service — the same retrieval-versus-reasoning case applies, narrowed to a domain where the payoff happens to be easiest to see.

A graph that already exists, not a hypothetical one

It is worth being concrete that this is buildable, not aspirational. A scoped knowledge graph does not require inventing new database technology; it requires deciding which relationships are worth making explicit, and then keeping the discipline of writing the edge, not just the sentence.

The maintenance problem: a graph that lies is worse than no graph

None of this is free, and it does not stay free once built. A knowledge graph has to be populated, and — the harder part — it has to be kept current as the system it describes keeps changing, or its edges silently stop being true. Engineers from five technology companies who compared notes on running knowledge graphs at real scale converged on the same lesson: the ongoing effort of maintaining a graph, not the initial modeling exercise, is where most of the real cost lives. That cost does not disappear because a graph is small, scoped, or well-intentioned. It comes back, on a schedule, for as long as the graph is meant to stay useful.

The staleness problem for a graph is worse in kind, not just degree, than the staleness problem this volume’s Engineering Documentation chapter raises for prose. A stale document is at least legible as suspect — a reader skimming a page dated three years ago has some chance of noticing the date and discounting accordingly. A stale edge in a graph carries no such signal; it looks exactly like a current one. A reasoning process, human or agent, that trusts the graph’s structure has no local cue that a depends-on edge it just traversed stopped being true eight months ago. This is the same failure mode Volume VII’s Trust Calibration chapter documents as automation bias: attention correctly allocated to the cases where a system is usually right is exactly what makes the exceptions invisible. A graph earns trust by being structurally authoritative, which is precisely why an untrustworthy graph is more dangerous than an untrustworthy document — the format itself signals more confidence than an out-of-date fact deserves.

Who builds it: agents as both the opportunity and the risk

The reason this is worth writing about now, rather than a decade ago, is that the cost side of the ledger just changed. Extracting entities and relationships from code, commits, and conversations by hand does not scale past a small, disciplined team willing to do the bookkeeping. A growing body of 2024 and 2025 work is aimed at having a model do the extraction instead. Graph-structured retrieval systems such as Microsoft’s GraphRAG build a knowledge graph out of a document corpus before any query arrives, and code-specific systems such as CodexGraph build a queryable graph database directly from a repository’s structure, so an agent can traverse dependencies and call sites instead of guessing from similarity search. A graph too expensive to build and maintain by hand becomes tractable the moment an agent can do the extraction pass.

The same shift is the risk, not just the opportunity, and it compounds the maintenance problem rather than solving it. An agent-extracted relationship that is subtly wrong — a dependency inferred from a coincidental import, a supersession claimed between two decisions that were actually independent — does not just sit there as one bad fact. It propagates through every future reasoning step that touches it, with the same silent authority as a correct edge, because nothing in the graph’s structure distinguishes a well-founded edge from a hallucinated one. A 2025 survey of LLM-driven knowledge graph construction frames reconciling neural extraction against symbolic accuracy as exactly this kind of open problem, not a solved one. Whether and how a team can trust an agent to maintain its own knowledge graph, not just build the first version of it, is this volume’s next chapter’s question, and it is not a small one.