7 Teaching
The best onboarding you ever had was a walk. Somebody took you across the floor, stopped at a machine and said “that one lies”, and you never trusted it again. Nobody wrote that down. It was not on the slide. It was the kind of knowledge that only moves from one head to another when a person decides it matters enough to point at, and the pointing is what this chapter is about.
Day one, last chapter, was the floor plan. Now comes the proper onboarding: what you tell a colleague in the first month, how you tell an agent the same things, what a well-taught fact looks like on disk, and the two rooms where the teaching happens, a session and a browser tab. It ends with two people editing the same page at once, which is where teaching stops being a lecture.
7.1 What to teach
Ask any good manager what a new hire needs and the list comes out in the same shape every time: what we value, and what we won’t do even when it would be faster. How things are done here (the review, the deploy, the meeting that actually decides) and what’s expected of the role. Which tools we use, and which we abandoned and why. And where information lives: which repository, which dashboard, which person. An agent needs the same list, in the same order of importance, and the last item is the one that makes the other four cheap.
A person’s knowledge doesn’t look like a source tree. No engineer on your team holds the payments service in their head by the letter. They know it’s in the payments repository, that the retry logic is under queue/, that the config nobody documented is in the deploy chart, who owns it and that Encom’s rule explains its strangest number. They know how to get access and which door to knock on. What they carry is a map of the territory plus the concepts to navigate it fast, and that’s exactly what to teach an agent. The source tree it can read with the tools its harness gives it whenever a task calls for it. What it needs from you is which repository holds the code for which purpose, how access is granted, the architecture and the vocabulary. Pointer knowledge, access knowledge and the mental model. Teach the map and the territory stays where it is, reachable.
So the engrams that earn their place in the first month are the ones a person would say across a desk: the chargeback rule behind the cutoff, the name the team uses for the queue, the fact that the wiki says gateway where the code says edge, and the rule about Fridays. Not one of them is on any page, and every one of them is what an experienced colleague knows.
7.2 Teaching through the agent
In a session, the simplest way to teach is to say something worth keeping and watch what happens.
Tell the agent “the settlement job runs at six because Encom’s file lands at five, and it fails silently if the file is late”, and it doesn’t write. It searches first, in engineering, because the capture skill makes search-before-write a hard gate, and it checks whether an engram already owns the topic, in which case the new fact becomes an edit of that engram rather than a second one beside it. Finding nothing, it proposes: “Should I capture this in engineering as a [gotcha]?” A terse “store this” is already a complete instruction and skips the question; an aside you obviously didn’t mean to keep gets no question at all. It names the domain every time, since a write has no default, and when the owner isn’t obvious it asks rather than guesses. A rotation detail learned during a payments incident is people knowledge, and the agent sweeps every domain before filing it where the incident happened to be.
Then it writes a well-formed file: a title, tags drawn from the vocabulary already in use rather than a near-synonym, a folder matching the domain’s layout and a body of at least three lines, because verification rejects a lone bullet as too thin. Hand it one sentence and it pads honestly, one bullet for the fact in your words, one for how and when it was learned, one for the scope and never an invented specific. You glance at the result the way you glance at a new hire’s first commit, and say yes. The write answers with its nearest neighbours too: the receipt names the existing engrams closest in meaning to what just landed. The instruction beside them is to read the one that fits, then merge into it, supersede it or link it, never to pass over the list in silence. So the duplicate check runs twice, before the write on your sentence and after it on the engram as written. A write that starts a new folder beside one with a close name, planview next to planview-work, says so too, and the agent can move the engram where its topic already lives instead of splitting it over two folders.
Correction is the same conversation. “The file lands at half past five, not five” finds the engram and changes the value where it stands. “We moved settlement to the new broker in August” is a different thing, the world changing, and the agent supersedes rather than edits, as chapter 3 walked through. Teaching and correcting are one motion, which is why the framing in chapter 2 said teach, rather than file.
7.3 Teaching through Fluid
The other room is the browser. Sometimes the fastest way to teach is to write it yourself, without a model in the loop and without spending a token: open the engram in Fluid, switch to edit and type (Figure 7.1). The editor previews live, the frontmatter is a form, and typing [[ completes titles across every domain, so a relation is two keystrokes and a pick. Callouts, status labels, diagrams and the rest of what a page can hold sit in the Insert menu, tables and task lists have buttons of their own and a / typed at the start of an empty line offers all of them; Chapter 13 shows each one. The file on disk is what changes; the page you were reading (Figure 15.4) is that file. Save a page you’re editing alone and you get the second look a session’s write gets, as a panel above the text with the same instruction.
What you write there doesn’t sit unreviewed. The engram records that a person wrote it, human: and your account name in its generated.by, and the next maintenance sweep raises it as a finding of its own: captured by a person and never reviewed. The finding is judgment class: what you capture yourself is teaching, so a change to what it claims goes back to you. The agent reads the engram, verifies the claim, aligns the tags with the vocabulary, wires relations both ways into the neighbourhood the engram belongs to and records a verified entry; any change to the wording it proposes and waits. In chapter 2 you typed a note into Fluid yourself, and that week’s sweep is where the agent tidied it into the graph. That’s the division of labour: you teach in whichever room is nearest, and the agent keeps the archive coherent.
7.4 The anatomy of a good engram
Chapter 4 read an engram line by line. What makes one good deserves a page of its own, because the difference between a good engram and a page is the difference between a colleague who explains and one who forwards you a link.
An engram is one unit of knowledge, about one thing, and when the thing grows the engram is edited, not forked. One thing is one lifetime too: validity is set per engram rather than per bullet, so a fact that expires on its own schedule (a price, a deadline, an owner) gets an engram of its own. Where a bundle mixed them, split_engram moves the facts that still hold into a new engram before the rest retires. Prose comes first: the explanation you’d give across a desk, what the thing is and why it’s the way it is, because prose is what search matches and what the agent reads first. Then the observations carry the facts, one bullet each with the most precise category you have, [fact] for verified state, [decision] for a choice, [gotcha] for the trap, [lesson] for what cost an hour, [risk] for the concern, never [fact] for a guess. Relations come next, for structure: depends_on, supersedes or a plain relates_to, so the graph can carry the agent to what the fact leans on. Inside its own domain the agent writes a bare [[Title]], and a link into another domain carries that domain’s name first, [[shops:Capsule Corp Books]], because a bare link never leaves the domain it’s written in. Tags stay within the vocabulary in use. A salience goes on only when the engram is genuinely exceptional (the rule a dozen other rules hang from), since most never need one. And an engram is what’s true now: a corrected value is replaced where it stands, never stapled on as a dated update, and the validity dates stay absent unless a fact is genuinely bounded. This one your agent wrote into books, after the exchange below:
---
type: engram
title: "What I finish: short, funny, one big idea"
permalink: what-i-finish-short-funny-one-big-idea
tags:
- taste
- reading-log
status: stable
recorded_at: 2026-06-11
generated: { by: claude-code/2.1.233, at: 2026-06-11T17:05:41+00:00 }
---
Three years of the reading log say the same thing three ways. The
books finished inside a week are all under three hundred and fifty
pages; the ones abandoned are all epics in volumes; the five-star
reads open with a joke or a big idea, usually both. Dune is the one
exception to the page count, and the log calls it heavy but good.
- [pattern] Under 350 pages, a joke or a big idea on page one #taste
- [gotcha] An epic in volumes, or a map on page one, is where the log says "abandoned" #taste
- [fact] Derived from the reading log, 2023 to 2026, 412 entries #reading-log
- relates_to [[Wait for the paperback]]
- summarizes [[Reading log, 2023 to 2026]]Notice what’s in it and what isn’t. The pattern, the trap and the provenance are there, and the log is kept beside it, attached in the agent’s word and on disk as a type: source engram under sources/ linked both ways, so the agent can check the derivation whenever it needs to. The log itself isn’t in the engram; a summary is what most recalls read, and the full text is pulled in only when the summary falls short.
You’ve had three duds in a row, and on Sunday you sit down with your agent:
After a bad run
You: Three duds in a row. Here's my reading log from the last three
years - work out what I actually like.
Agent: Read it. The pattern: under 350 pages, a joke or a big idea on
page one, and a ship's computer somewhere. Dune is the exception,
and you called it heavy but good. An epic in volumes is where you
stop. Captured "What I finish: short, funny, one big idea" into
books (#taste #reading-log), log attached.
Six months later, a fresh session
You: Something for the long weekend.
Agent: Three candidates, all under 350 pages, one of them a Doctorow
you haven't logged - recalled that a map on page one is where
you give up. The Gibson is the heavy-but-good kind.Look at what you didn’t do. You didn’t tell the agent a fact. You handed it the source material and a question, the way you’d hand a friend the log and say “work out what I like”, and the agent derived the pattern, wrote it down with the log kept beside it as provenance, and six months later recalled it in a session that had never seen the log. That’s teaching at its most economical: you supply the material and the judgment about what matters, and the colleague does the learning.
7.5 Attachments
Some teaching material is a file: the chargeback agreement, the deck a vendor sent, the diagram you drew at the whiteboard and photographed. In Fluid you paste, drag or upload it onto the engram it belongs to, and it lands under the domain’s assets/ folder with a reference in the engram’s body, an image  or a link [...](assets/deck.pdf). Images, PDFs, slide decks, office documents and data files are all accepted, up to ten megabytes each. Files enter through Fluid or a domain archive, never through an agent write, and an attachment always belongs to some engram’s teaching: a file nothing references comes up in the sweep as something to delete or to turn into knowledge.
They aren’t opaque to the agent. read_engram returns each attachment as a resource link, and the agent fetches the file itself over MCP before summarizing what it shows; a picture it needs to see comes back as an image. The sweep closes the loop from the other side: an attachment nobody has analyzed is a finding, and working it means reading the file, capturing what it teaches and marking on the engram which file was analyzed at which version, so a changed deck comes back around. One small courtesy for images: a formatting fragment on the target, , floats and sizes the picture in Fluid, and every other markdown renderer ignores it.
7.6 Editing together
Chapter 3 said the way a colleague really learns is by pairing, and Fluid makes pairing literal. Open an engram that somebody else has open and you see their cursor; type, and both sets of edits merge conflict-free and land as one save: two people, one page, one whiteboard. Review mode changes the room: everyone writes in a draft of their own, and a colleague joins yours through a draft share-link (chapter 17).
The third name in the strip can be the agent’s. When your agent reads or edits an engram somebody has open in the editor, it joins that page as a named peer: your account with an agent designation, a bot glyph beside the name and a colour from the same palette as everyone else’s. It has no cursor, so its sentences aren’t painted in that colour; the glyph in the strip is how you know an agent is writing. An edit it makes is computed against the page as it stands at that moment, so it composes with what you typed seconds ago instead of stomping it. Anyone with the page open just to read sees the change appear in place as it lands, with a line saying who made it, no reload needed. When it reads, it sees your unsaved typing rather than a stale copy. Its write receipt says the change landed in a live page and names who is present, so it can tell you “I updated the section you’re looking at” and mean it. Only a wholesale overwrite of a page somebody has open is refused: the agent edits the parts instead or replaces the page once you close it. That’s the fluid and crystalline halves working on one page at once, human with human and human with agent.
Now and then a save can’t land: two edits conflict, the server refuses the save or somebody switches a domain’s Reflection off under the page you’re writing. Your text isn’t lost. When the last person leaves that page, the server keeps the text, and the editor offers it back the next time you open the page, to put back or to drop. The domain’s settings list every kept text you may see.
A kept text is a file in the server’s state folder. On the server, crystalline kept list shows every one with a short id, crystalline kept show <id> prints one so you can copy it back and crystalline kept drop <id> deletes it after you confirm. Nothing deletes a kept text on its own, because it may be the last copy of somebody’s work, and crystalline doctor warns about one older than thirty days. Agents have no tool for kept texts: it’s a person’s unsaved typing, and the person decides what happens to it.
What that is like is a napkin on the table between you. You write the line you’re sure of, the retention rule you want, and ask the agent in your session to fill in what you’re not. While you keep typing it goes and reads: the engram that holds Encom’s chargeback window, the vendor’s documentation for the retry limit. The window lands under your line, address and all, and the retry limit beside it with a link to the vendor’s page. The month you misremembered is corrected in the sentence you just typed. You ask it to sketch the retry flow so you can check what it understood, and a diagram appears under the text, drawn from what the two of you wrote. None of it waits for a save, and none of it happens unless you asked. It’s JARVIS in Tony Stark’s workshop: he builds, and the voice in the room has the schematic in the air before he asks for it and tells him, politely, when he’s wrong. On a shared instance anyone can pull up a chair. Chapter 17 puts a whole meeting in that room.
Teaching a colleague is pointing at the machine that lies. Teaching an agent is the same gesture, and this one writes it down.
Teach an agent what you’d teach a new hire: values, processes, expectations, tools and above all where information lives, taught as a map (which repository holds what, how access works, the architecture). In a session, say something worth keeping and the agent searches first, proposes a capture in the fitting domain, writes a well-formed engram once you say yes and reads the neighbours its receipt names, with corrections edited in place and changed facts superseded. In Fluid, write it yourself, and the next sweep verifies, tags and wires what a person captured, with any change to what it claims going back to that person. A good engram is one unit of knowledge and one lifetime, with prose, categorized observations, typed relations and, rarely, a salience; attachments hand over files that agents read back. Co-editing merges live, your agent can sit in that session as a named peer and a text that can’t be saved is kept for you.