10 Evolving
When a colleague gets something wrong, you don’t fire them. You say what was wrong, point at the page that explains it, and the next time is better. Every team keeps its people’s knowledge honest that way, and it works because nobody expects what a person learned in March to hold forever. Information lives: the cutoff changes, the vendor rewrites its terms, the customer’s CTO who decided in the room is replaced by one who reads. What you taught the agent in chapter 7 and handed it in chapter 8 was never set in stone, only in files, and a file can be corrected.
Evolving is the beat that does the correcting. Chapter 3 walked it around once, and this chapter works it at the pace of a real archive.
10.1 Why knowledge needs tending
Nothing in an archive goes wrong dramatically. A validity window ends on a Tuesday and the engram still says stable on Wednesday. A runbook that names a person has a review date, and it comes and goes. A replacement lands in one session and the session ends before the old engram was flipped. An engram retires because one of its facts expired, and the two beside it that still held retire with it, carried forward nowhere. Somebody types a correction into Fluid on a Friday and nobody looks at it again.
Then the structural kind: a link that points at a title nobody captured, a live engram citing one that has retired, a supersedes written on one side only, an engram nothing links to, one that grew past the point where it should have split, one that never grew past its frontmatter, a reference to an attachment whose file is gone, a file in assets/ that no engram claims. A permalink left behind by a file moved by hand belongs here too; a move made through Crystalline carries the permalink along and rewrites every link, relation and address that pointed at the old one. Then the redundant kind: two engrams saying nearly the same thing, two titles a link can’t tell apart, one tag spelled two ways. Then the meaning kind: two that say one thing in different words (the sweep calls those twins) and, if you switch the check on, two lines that look like they contradict each other, which Chapter 11 takes up on its own. None of it is a mistake anyone made, it’s what happens to knowledge when time passes, and it’s what a colleague six months in will confidently repeat if nobody tends it.
10.2 The sweep
The agent asks for a sweep. You can ask for one from a terminal too (you’ll see what the agent sees). What comes back is a ranked queue and nothing else: the sweep is read-only, and the standing reminder at the bottom of every run says so. The queue is written for the agent to work: each finding names the engram, the evidence it fired on and the one action that clears it, with the tool that performs it. The four families are the four kinds above in that order: temporal, structure, redundancy and meaning. A run narrows to one family, one rule, one domain or a minimum priority, and pins the date rules to a chosen day when you want it to reproduce. Here’s an engineering domain on a Monday in October:
Sweep of engineering as of 2026-10-05
41 engrams scanned, 3 findings (showing 3, page 1)
temporal 1, structure 1, redundancy 1
1. [85] V001 JUDGMENT
Broker migration freeze crystalline://engineering/broker-migration-freeze
validity window ended 2026-09-30 but the status is still stable
evidence: valid_to=2026-09-30; today=2026-10-05; status=stable; inbound refs 1
fix: set_frontmatter valid_to=<later date> or status=superseded
2. [50] V102 MECHANICAL
Retry queue drain procedure crystalline://engineering/runbooks/retry-queue-drain-procedure
unresolved reference [[Edge health check]]
evidence: rel_type=depends_on; nothing titled `Edge health check` in engineering; nearest is `Edge health checks`
fix: [[Edge health check]] -> [[Edge health checks]]
3. [30] V203 JUDGMENT
crystalline://engineering
2 tag spellings look like one tag (plural variants)
evidence: #runbook used 2 time(s); #runbooks used 9 time(s)
fix: crystalline tags merge runbook runbooksThe number in brackets is the priority: how much the archive gains from clearing this one first. A finding on an engram that many others link to, or that carries a salience, gets lifted, because a wrong hub does more damage than a wrong leaf. The word beside the rule id decides who acts.
The agent’s call is evolve_engrams, and crystalline evolve prints the same queue from a terminal. families picks temporal, structure, redundancy or meaning, rules a rule id like V001, min_priority a floor under the bracketed score and class keeps only mechanical or only judgment findings, which is what a run without a person asks for (include_acknowledged comes up with the acknowledgments below). --today evaluates the date rules as of a fixed day so a run reproduces.
10.3 Mechanical and judgment
A mechanical finding completes intent the archive already records. The link in item 2 points at a title one letter off a real one, and fixing it invents nothing, so the agent does the mechanical findings in one pass and reports once at the end (you’d fix a colleague’s typo without calling a meeting about it).
A judgment finding would change what the archive claims, and that wants a yes first. Item 1 asks whether the migration freeze ended or was extended. Only a person who was there can say. The agent brings it to you as a proposal, evidence and its own reading included, and writes only when you say yes:
Agent: The broker migration freeze ran to 30 September and the
migration landed on the 12th. I read this as ended rather than
extended: retire it, close the window on the 30th and carry
the "no payments deploys during a broker cutover" lesson into
the deploy runbook? (y / n)Some judgment findings carry a rule of their own. An engram a person captured directly in Fluid is judgment class whatever else is true of it: the agent verifies the claim, aligns the tags and wires the relations both ways, but it proposes any change to the wording and waits: a person’s capture is teaching, so a change to what it claims goes back to that person (Chapter 7). Tag drift, item 3, comes back as a command rather than an edit, since folding a tag is a bulk rewrite the agent never does on its own: it hands you crystalline tags merge runbook runbooks and leaves it there. The merge rewrites the tag everywhere and records the fold under ## Tag Aliases in the manifest, so the old spelling keeps finding what it always found and the sweep never raises the pair again.
Then ask again. The second run re-derives the queue from scratch (nothing about the first was stored), so what’s left is only what’s still true. In the run above the three become one (the tag merge that waits for a terminal, which is waiting on a person rather than on the archive), and that shrinking number is the feedback loop.
In a domain that reviews changes before they land (chapter 17’s review mode) a sweep covers the reviewed folder plus the sweeper’s own drafts: the problems in a draft are its author’s to see and nobody else’s, and a finding on the shared truth shows for everyone.
10.4 The page for people
Fluid’s maintenance page shows the same queue to a person: the stale dates, the half-finished retirements, the unreviewed human captures, ranked the same way. Every finding about an engram links to it. It’s there for your curiosity and for a sense of how the knowledge is doing, and it’s a report rather than a workbench, on purpose. The queue’s consumer is the agent, so no button on the page edits an engram. The work a finding names is the agent’s, done in the engram itself. What you do on the page is watch the list shrink. Two filters, a domain and a family, scope the sweep rather than the view: pick one and the server sweeps again with what the filter names, the header says so and the rows dim until the new queue arrives. Figure 3.2 shows the queue with the Meaning family picked. Its three buttons are about the queue rather than the knowledge: acknowledge a finding as intentional, take that back and delete an orphaned attachment. What an acknowledgment silences is never hidden: a toggle draws the silenced rows muted.
10.5 Retiring done right
The sweep finds retirements that were never finished, so it’s worth being precise about finishing one. Start with the question chapter 3 asked: does the new fact make the old one false going forward? If the old fact was never quite true (a cutoff measured from the wrong event), correct it where it stands: a correction is a sharper measurement. If it was true and stopped being (the rule went away with the broker), supersede it: a supersession is the world changing.
A correction the agent can’t make itself still reaches you. That happens when the domain is read-only for it, when the engram holds your own words or decisions or when the right value is your call. Then it tells you: it links the engram, says what’s true instead with the source that shows it and proposes the edit. Where it may write, it captures the correct fact as well and links it to the wrong one with corrects.
One move comes before either. Validity is set per engram, not per observation, so an engram that bundled three facts retires all three when one of them stops holding. When the rest still holds, split first: those facts move into an engram of their own, linked with derived_from and split_into so the pair resolves from both ends, and only the remainder is superseded. Re-typing the survivors into the successor loses their history and copies them forward again at the next expiry. A retirement that skipped the split shows up in the temporal family as a carry-forward gap, a retired engram whose observations appear in no live one, matched as text and never as meaning; the fix is the split or, when the facts expired along with the rest, an acknowledgment.
A supersession has four parts, and the sweep notices when any one is missing. The replacement is an engram of its own that points back at what it replaces. The old engram is marked superseded, with the real date the fact stopped holding (never a guess, never a placeholder). The old engram points forward at its successor, so the graph reads the same from both ends. And any lesson that’s still true moves into the live engram, because the lesson outlives the fact. A retirement without a successor gets the status that fits instead: deprecated for do-not-do-this-again, archived for kept-for-the-record, legacy for still-true-of-the-old-installation, with the window closed when the date is known and the lesson carried into a live engram either way. The retired engram stays in every search, dated and ranked softly below the current one, so the next time somebody asks why an old dashboard still says twenty-four hours, the answer includes the date the answer changed.
A whole domain can be finished too, and you can freeze it with read_only in its MANIFEST, so nothing changes it by accident and the sweep leaves it alone until you switch it back (Section 25.7).
You’ll rarely ask for the four parts by name. What arrives is a proposal with the date already in it and a question at the end:
You: The new Vickers is nine hundred pages and has six narrators.
I gave up on page forty. Here are my notes.
Agent: That's the third in a row since the trilogy ended. The engram
"Vickers: buy on sight" was true until the trilogy closed and
false since, so I propose a supersession rather than an edit:
a new engram "Vickers: wait for the reviews" that supersedes
the old one, the old one marked superseded as of the trilogy's
last volume and one lesson carried forward: a favourite is a
run, not a rule, so re-check after every book. Yes?
You: Yes.That exchange is yours. You hand your agent the notes on the new Vickers the way you’d hand it any book’s notes, and the agent does something you didn’t ask for. The engram “Vickers: buy on sight” described an author whose every book you’d finished in a weekend. The agent recognizes that the engram was true and has stopped being, and proposes the supersession rather than an edit: a new engram for the author’s books from here on with supersedes pointing back, the old one flipped to superseded with a valid_to of the month the trilogy’s last volume came out and the lesson carried forward, unbounded. You say yes. Your notes on the trilogy stay attached to the retired engram, still its provenance.
A month later the sweep raises the paperback-rule engram, which carries a relates_to of its own back to the buy-on-sight engram: a live reference to retired knowledge. The agent proposes repointing it at the new one. You say no: the rule was written with Vickers as its one exception, the author whose every book had earned the shelf before you’d finished the ebook, and the citation is history rather than guidance. The agent acknowledges the finding on the engram with a note, “lineage citation, keep”. The sweep stops raising it while the citation and the retirement both stand, and the old engram stays in the picture, dated, the way Marty’s siblings did not.
The split is one call. split_engram takes the source, a title and what moves, observations (the line numbers read_engram reports) or sections (heading paths, deeper subsections with them); the new engram keeps the source’s tags and type and gets status: stable with no window. Both relations come written for you. It refuses a selection that would leave the source under verify’s three content lines, the case for retiring the whole engram. The four parts come out as four calls. write_engram creates the successor with - supersedes [[Old title]] among its relations. Two edit_engram calls with set_frontmatter set the old engram’s status to superseded and its valid_to to the date, one lifecycle field each, and a third appends - superseded_by [[New title]] to the old engram. The lesson rides in the successor’s body as an observation, with no validity window. The replacement carries status: stable like any live engram. A retirement with no successor sets status to deprecated, archived or legacy instead. Skip the status and the sweep raises a half-finished retirement, skip the back-link and it raises a one-sided pair, do all four and the sweep has nothing to say.
10.6 Verification and acknowledgments
Some findings are answered with a record rather than an edit, and telling the two records apart keeps the archive honest. A re-check that finds a fact still true is written down as a verification: who checked and when. A review date pushed to a later day says the same thing with a deadline attached, and the sweep prefers one, since an old engram with no review date and no verification is one it starts asking about on age alone.
An acknowledgment says something different: this finding is intentional. It names the rule it answers, carries an optional note (the vignette’s “lineage citation, keep”) and records that the person ruled on it. The server records what evidence the finding fired on, so the acknowledgment holds exactly as long as that evidence does and comes back marked stale when the evidence changes. A twin finding’s evidence is the pair, so an engram that twins two others carries two findings and each takes an acknowledgment of its own. Every run reports how many findings its acknowledgments suppressed, a suppressed finding can be brought back into view with its note, and an acknowledgment can be taken back. Acknowledge only what the person actually ruled on, because the sweep is only as trustworthy as the decisions it was told to respect.
Both records are edit_engram with set_frontmatter, one lifecycle field at a time. verified stamps who checked and when, and it never removes (one entry per verifier, refreshed each time that person re-checks). stale_after takes the later review date. evolve_ack takes the rule and the optional note as its value, V101 lineage citation, keep, and the value remove V101 takes that acknowledgment back. include_acknowledged on a run shows the suppressed findings with the note on each.
10.7 When to sweep
The sweep is event-driven maintenance, never a session-start ritual. A large ingest that lands a dozen engrams at once calls for it, and so do two search hits that disagree when a half-finished retirement is the likely reason. The third event is the calendar: the manual suggests the first session of a month. The reminder at the end of a session helps with that one: when maintenance is due, chapter 6’s stop hook (in Claude Code, Codex and Copilot) adds a paragraph asking the agent to run the sweep and work the queue, mechanical findings directly, judgment findings one at a time with a yes. The calendar can also run the sweep without you: the evolve loop fixes the mechanical findings on a schedule and leaves the judgment ones for your next session (Chapter 14).
The sweep reads dates, links and graph shape, plus meaning for the twin check when the instance computes embeddings. With evolve.contradictions set to full it also reads the contradiction scores the daemon stored: the daemon scores pairs between sweeps (its model downloads on first use), so a sweep itself scores nothing. The rule for old, never-verified knowledge is capped per run, oldest first, so an archive that’s never been swept gets asked about in instalments. The twin check is capped too: ten pairs per domain, closest first, and a very large domain is skipped with a line saying so. An acknowledgment lives in the engram’s own frontmatter, beside the scope the server recorded for it, so it travels with the file and survives a rebuild of the index, which stores nothing about a sweep between runs.
A colleague who is corrected gets better, one who never is gets confident, and the sweep is how you keep telling the difference.
Knowledge drifts rather than breaks: windows lapse, review dates pass, replacements land without the retirement being finished, captures go unreviewed, links dangle, tags fork. The sweep, crystalline evolve or evolve_engrams, returns a read-only ranked queue in four families, each finding naming the engram, the evidence and the one action. The agent completes mechanical findings in a pass and proposes judgment findings one at a time, and Fluid’s maintenance page shows a person the same queue, to look at rather than to work. Split out what still holds first, then retire by superseding: a new engram with supersedes, the old one set to superseded with a real valid_to and a superseded_by, the lesson carried forward. Correct in place only when the old fact was never true. A re-check is a verified stamp or a later stale_after; an intentional finding is an evolve_ack naming the rule, which holds while its evidence holds. Sweep after an ingest, when hits disagree and on a cadence, and stop when the number stops falling.