Ontology

The Larder lesson built a meal-planning harness, the files, tool and gates around the language model that give each piece of a task to whatever suits it and leave the judgment with you. Its files were an identity file (CLAUDE.md, the instructions the agent reads before anything else), a skill file, a preferences file, a folder of recipes, and a pantry.md, which was a markdown list of what was on the shelves.

That harness works. I still run it. But the pantry file was always the weak joint, and this lesson is about why. A list can tell an agent what you have. It cannot tell it what any of those things are, where they live, what they can stand in for, or which of them is about to turn.

If you skipped Larder, nothing here requires it. You need a folder, a coding agent, and a text editor. I use Claude Code because that is what the series uses, but nothing in the files is vendor-specific.

One idea runs through all of it: an ontology is a small model of your world an agent can read, and it is only worth having once a script checks it.

Here is the pantry, the same pantry.md Larder built, and it is the same pantry for the whole lesson. Flour, sugar, salt, milk, eggs, butter that has been opened, one lemon, and a tub of sour cream that has been open for six days. No buttermilk. No baking powder. Write it down the way anybody would write it down.

Now the question, and it is the one this whole lesson keeps asking:

Can I make pancakes tonight, and what should I use up first?

The recipe is in the folder. The pantry is in the folder. Let me ask three times, in three fresh sessions. A session is one run of the agent against the folder, carrying nothing over but the files, so pancakes.md and pantry.md are the only context.

Those three are composites: exchanges assembled from real sessions to show one failure at a time. The kitchen is a problem I made up to learn this method, and every quoted run in Chapter 4 is a real run against that made-up file. Chapter 4 puts this same eight-line list in front of three sizes of model, and one of the three failures I describe next does not survive it. Guess which before you get there.

Three sessions, three answers, each reasonable on its own. The first invented baking powder: the recipe calls for two teaspoons and the pantry has none. A kitchen with flour and sugar in it probably does have baking powder, which is a good guess about kitchens in general and a wrong claim about mine. The second noticed the missing buttermilk and then walked past the lemon sitting four lines above it. None of the three ranked the sour cream first, and it is the only item in that kitchen with a real deadline on it.

Look at what pantry.md cannot say. It cannot say anything about what is absent. Ask it about buttermilk and it has no way to distinguish "you definitely do not have this" from "this never came up."

That gap, no way to say "not here", is the one every later chapter comes back to.

The fix is to give each word a kind, a place, and a relation to the others. That is the next three chapters.

Start over with a new file. ontology.md, same folder.

Every line is a triple: three words, a subject, a relation, an object. The subjects and objects here are entities, and each one is a thing or a kind. A thing is one item you could pick up: butter. A kind is a label several things share: dairy. The test is whether it could go in a shopping basket: butter can, so butter is a thing; dairy cannot, only some particular dairy thing can, so dairy is a kind. Milk, butter, sour cream and buttermilk are four things under that one kind, and dairy sits under a larger kind, perishable, which it shares with produce. Every thing gets one is-a line naming its kind; a kind gets one only when it sits under a larger kind. The file keeps them under separate headings, so you never have to guess which is which. Read each one out loud and it is an English sentence: butter is-a dairy. If you can write a shopping list you can write this.

The first relation is is-a. It says what a thing is, and what a kind is a kind of.

The declarations at the top, the kind: and relation: lines, are the file's meta model: the small set of types and relationships, kinds and relations in this file's own words, that the lines below are allowed to use. The AI in Systems Engineering talks use the same term, where SysML v2 is the meta model under an engineering model of Apollo 11. The three-word lines underneath are the kitchen itself, written in those terms. The two layers fail differently, which is the quickest way to tell them apart. Write butter is-a cheese and the checker, which Chapter 5 walks through, objects: cheese is not a declared kind. Add kind: cheese at the top and the same line passes, true or not. The top says what may be said; the lines say what is so. The whole file, meta model and kitchen together, is what this lesson calls an ontology. If you came here looking for the phrase knowledge graph, those lines are its edges, and the meta model is its schema, what makes them more than text.

One line per thing, one blank line between them. The gaps stop looking silly in two chapters, when most of these grow to three or four lines each.

baking-powder is-a staple and buttermilk is-a dairy: neither is in my kitchen. They are declared anyway, because declaring a thing and having a thing are now two different statements. The model can finally be definite about an absence instead of silent about it.

is-a is marked transitive: a transitive relation chains, so two lines that share a middle word yield a third line nobody wrote. Watch:

Ask the question again. It is better and it is still wrong.

The invention is gone. It knows what is missing and it says so, and it has narrowed use-first from eight items to the two that can actually spoil. What it cannot do yet is rank them, find a substitute, or tell you where anything is. It has the nouns and the kinds. What it needs next are verbs: where things live, and what stands in for what.

Nouns and kinds get you a taxonomy. The questions people actually ask are about relationships: where is it, what does it go in, what can I use instead. Those are verbs, and each one is a new relation. A relation line can carry a mark that says how the relation behaves. Transitive you have met: it chains. Symmetric means the line reads in both directions: if the file had a next-to relation, milk next-to butter would already say the butter is next to the milk, with no second line to keep in step. Conditional means the line holds only under a purpose named on a when line beneath it. The marks guide whoever reads the file. My script stores them and walks only is-a; it is the model that reads symmetric and conditional and concludes no more from a line than they allow.

stored-in is transitive, like is-a, and it pays off immediately. The substitutions further down show why substitutes-for needs both of its marks.

Notice which lines are missing from that update. baking-powder and buttermilk have kinds and no locations. An entity with no stored-in is not here, and that is a positive, checkable fact.

ingredient-of points from a thing to a recipe, which makes the recipe queryable from either end. It carries no transitive mark, on purpose: flour is an ingredient of pancakes, and if a brunch recipe listed pancakes, flour would still not be an ingredient of the brunch in any sense a shopping list needs. My script walks only is-a; the mark is what tells a model not to chain this one.

The recipe is still a recipe file that a person reads, with quantities and a method. The triples are the part of its ingredient list a script can read, and keeping the two in step is a job for the checker in Chapter 5.

The first word on each ingredient line is the entity name, before the comma. That one convention is what lets a dumb script check a file written for humans.

Then substitutes-for, which is the relation that does the most work and gave me the most trouble.

Subjects can be combinations joined with a plus, because most real substitutions are two things standing in for one thing. Every substitution carries a when, drawn from the purpose vocabulary declared at the top.

The when is there because symmetry only holds inside a purpose. Declare substitutes-for symmetric and stop, and the file licenses buttermilk in place of the sour cream in something that wanted sour cream as a topping. It is an honest swap for baking and a bad one on a baked potato, and the when clause is what fences it in. Read backwards, the pair's line says buttermilk can stand in for sour cream thinned with milk; that holds in a batter, and the when keeps it there.

Ask again.

The substitution chain landed, and it landed without me writing a word about pancakes and lemons in the same sentence. The structure is what let it chain those four lines.

The ranking still needs dates, and the file will happily accept nonsense: I could type butter stored-in garage or invent a relation and nothing would object.

A file that only describes will drift. Someone finishes the milk and nobody edits the line, and the file still reads as though they had.

Rules fix that, and they come in two shapes. The controlled vocabulary is already in place: the kind:, location: and purpose: lines at the top are a closed list of legal values. butter stored-in garage is now a typo with a name, because garage was never declared a location.

The other shape is invariants: rules the whole file must keep, every time it is read. Always-and-never sentences in plain English, written into the file itself. The script carries code for each one; the English is for people, and the code is what runs. Five now; Chapter 4 adds a sixth.

The first two invariants demand data the file does not have yet. Write the rule, watch it fail, then satisfy it.

milk sealed yes is not beautiful English. It is three words, which is what the parser wants. The dates are the ones I had the day I wrote this. keeps-for 30 is days after opening.

Write the perishable rule without the "with a location" clause, so it says only that every perishable carries an opened date or a sealed mark, and run the checker.

All three findings are the rule's fault, not the data's, and I could not see that until the checker ran against the file. Each was found by the script walking is-a upward, buttermilk to dairy to perishable, with no model in the loop: the walk from Chapter 1, doing work. Buttermilk is not here and has no state to declare, dairy and produce are kinds rather than things, and scoping the rule to perishables with a location fixed both errors at once.

The keeps-for lines came from the same kind of correction, and this one matters more because it changes the answer. The obvious rule is to rank use-first by how long something has been open. Butter has been open fifteen days, sour cream six, so days-open puts the butter first. But butter keeps a month once opened and sour cream keeps about ten days, so the sour cream has four days left and the butter has fifteen. Ranking by days remaining reverses the order.

One line is still missing. Days remaining needs a day to remain from, and taking that from the clock would mean this chapter's numbers change every time somebody reads it. So the file names the day.

The checker counts from that line rather than from the machine's date, so four days left is four days left on any machine on any day. --live counts from the machine's date instead, and --today 2026-09-01 counts from a day you name.

Now the closed questions, the ones whose possible answers are fixed before you ask, yes or no, here or not here, are genuinely closed.

"No, unless" is a much more useful sentence than either "yes" or "probably", and the file can now prove every part of it.

The question is whether the file is doing the work or the model is. The floor is no files at all, just the question.

A competent answer that makes no claims about my kitchen. Now hold the file still and change the model.

The grid is three model tiers across, Opus, Sonnet and Haiku, the same product at three sizes and prices, largest first, as the table below reads; and four context conditions down, four versions of what the files put in front of the model: twelve cells, one answer each. I walk the conditions in order and call each pass a round. Same question in every cell, a fresh session each time, no tools and no web, nothing in the context but the files and the question. I capped the answers at 120 words, a little longer than the answer at the top of this page, so manner could not hide a miss. Each answer is scored on three things the file settles. The first is absence: does the answer say no to pancakes, because baking powder is declared and nowhere. Then a substitution for the buttermilk that comes from the file, and a use-first item with a date.

All twelve answers are verbatim, from a real run on 2026-08-26, and the complete record of them is a page of its own. Four are quoted here and the rest are linked. The transcripts earlier in this lesson are composites, assembled to show one thing at a time.

Round one is the eight-line pantry.md from Chapter 0, plus the recipe. All three tiers caught the missing baking powder, and all three went vague on use-first, because the list carries no dates to rank with. The composites in Chapter 0 show a flat list inventing baking powder. It did not happen once in these three runs. Eight items is few enough to scan, so checking for an absence is just reading the list.

Round two swaps the list for ontology.md as it stood at the end of Chapter 3. Everything the list could not reach arrived at once: the sour cream's opened date, its keeps-for, the real expiry, and the conditional substitution with the method note attached, because the note is a line in the file. And two of the three answered yes anyway, with only the buttermilk to work around: Haiku by listing baking powder among the things I had, Opus by never mentioning it.

The flat list went three for three on absence. The ontology, which is the entire point of this lesson, went one for three.

Nothing there says what a missing stored-in means. I wrote that convention in Chapter 2, in prose, to you. the model got the file, where the line reads as an assertion that baking powder is a staple in a kitchen, and the model fills in what a kitchen usually has.

Round three writes it there, in the place where the rules already live.

The score did not move: Sonnet quoted the rule back and stayed correct, and the other two had the line in front of them and still listed baking powder among the things I had. Haiku wrote "you don't have buttermilk in the house", which is the invariant applied correctly, in the invariant's own words, and three paragraphs later it listed baking powder as available. Same rule, same file, two entities that differ in nothing the rule cares about. A rule in an Invariants section is a job the model has to do against every entity, every time, and that job is the model working it out.

If the problem is that the model has to apply the rule, apply it in the script and hand over the result. The checker has been sitting in the folder since Chapter 1, and Chapter 5 has the checks. This is the six lines I added to the end of it.

located was already computed for one of the invariant checks, so the report reuses work the checker does anyway.

That output is the file's implications, computed. The last line is the ranking from Chapter 3, done in arithmetic rather than asked for in English. Put it in the context alongside the ontology, and ask all three tiers again.

Three for three on all three things I was scoring.

What is left between those three answers is manner. Haiku is terse. Sonnet notices that the substitution and the expiry solve each other. Opus, unprompted, tells me to look in the cupboard because the checker only knows what it has been told. The claims underneath are the same three claims.

None of that is the model working anything out. Is sour cream perishable becomes two hops up is-a. Is baking powder here becomes whether a stored-in line exists. What replaces buttermilk becomes a read of the substitutes-for block. Three lookups, and the earlier rounds asked the model to produce what those lookups return, which is why the earlier rounds moved between tiers. Round two is the reminder that having the lookups available is not the same as having them done: a lookup the model has to decide to perform is still a decision, and decisions vary.

Three criteria, each checkable against the file. Absence: the answer says no to pancakes because baking powder is not in the house. Substitution: it offers a buttermilk swap the file lists. Use-first: it names the sour cream with a date or a day count. All three is a correct answer; anything less is a miss on a question the file settles. Below the table, the same scorecard as pips, three per cell, one per criterion, filled when met.

With the derived report every tier is correct, and without it the tier doing the reading decides the answer.

The file mattered more than the tier reading it, once the file's implications had been derived for it. That clause is what Chapter 5 is about.

The report also changes what happens when I ask about something the file has never heard of.

The flat list answered the same question with a guess: no, I don't see saffron in your pantry. That converts "absent from my list" into "absent from your kitchen", which is a claim the list cannot support. A jar of saffron at the back of a cupboard that never made it onto any list is the case that answer gets wrong. A list has two states, on it or not on it. A controlled vocabulary has three: declared and located, so definitely here; declared and unlocated, so definitely not here; not declared, so no record either way. The middle one only holds when something enforces it, which is what round four settled.

The answer that closed Chapter 3 can also cite itself, line by line.

Citations show the answer follows from the file, not that the file is right: type sour-cream keeps-for 100 and every one above still resolves.

Twelve runs, one answer per cell on one question, is a demonstration and not a benchmark. It cannot say how often a tier would miss on a second run; I scored the answers myself; and the conditions differ in more than one way, so it cannot say which difference did the work. A version worth citing would repeat each cell many times, have someone else score them, and change one thing per condition; the article's methods set that out. One result does not transfer unexamined: run your own question with your own key before you trust it on your kitchen. The Representation lesson is that measurement on one Apollo 11 question, tokens and cost beside correctness, as the representation changes, over recorded runs or live with your own key.

A file is a claim about the world, and claims rot. The pantry changes on Saturday, someone finishes the milk, you buy baking powder and forget to write it down. Within a month the structure is confidently describing a kitchen that no longer exists, and it will keep citing line numbers while it does it.

Declare. One file. ontology.md, and nothing else claiming to be the source of truth. The flat pantry.md comes out of the folder now, because two files describing the same shelves means one of them is lying and you will not know which.

Validate. A script that reads the file and complains. Mine is 141 lines of Python, standard library only, a few screens: it parses the three-word lines into triples, then checks the invariants written at the top of the ontology and prints what they imply. The English is for people; the code is what runs. The loop below carries the declaration rule, every relation and every name used below declared above, and the recipe-file check.

Only the first line of that is a check. The other three are the questions I ask most often, answered by a script for free, because once the structure exists the mechanical questions stop needing a model at all. One question the report does not answer yet, can I make pancakes, is still a join the model does for itself: not-in-the-house against ingredient-of. The day that answer wobbles, it becomes a report line too; anything the file implies and a session needs is a candidate.

Gate. A gate is a check that has to pass before work goes on. Here the script runs before an edit lands, not after. A git pre-commit hook, a script git runs before it accepts a commit, is one way. A line in the identity file, CLAUDE.md, telling the agent to run the check after editing the ontology is the lazier way, and it is what I actually do. The agent can forget a line in CLAUDE.md; the hook runs on every commit.

Read. Writing "read ontology.md at the start of every session" into the identity file feels like closing the loop, and it does not close it. Round two says why: handing over a file hands over the job of working the rules out again, and that job is the flaky part. So the session reads the report, and the file behind it.

The checker reports both directions, things declared that nothing uses and things used that nothing declares. The second is where the real bugs live. Rename baking-powder to baking_powder in the ontology, forget the recipe file, and it catches both sides of the split:

This is a handful of files that check each other every time you touch them.

Larder's loop is the weekly tending: a retrospective that adds a line to a memory file, preferences.md. This lesson's loop runs on every edit: a script that reads a file and tells you when you have contradicted yourself.

The kitchen was the worked example; the method transfers to anything you keep re-explaining to an agent.

Start from the questions you actually ask, not from the things you have. The file in this lesson grew from the pancakes question and the ten in questions.md; nothing in it was written for its own sake. Write down the three or four questions you put to an agent most often, work out what a file would have to contain to answer them, and stop there. I would not start with an inventory of everything you own: most of those lines would never be read, because nothing asks for them.

Your nouns become entities, each one a thing or a kind.One name you type the same way every time, and one is-a line each.

Your verbs become relations.Declare each one, and mark it transitive if it chains.

Your always and never sentences become invariants.The rules you already say out loud, written where something can check them.

The words you keep repeating become a controlled vocabulary.Close the list, and a typo becomes an error instead of a new entity.

Start embarrassingly small. Add a field the day a second file needs it, not before.

The next time you catch yourself explaining the same background to an agent for the fourth time, try writing down the nouns.