3 The lifecycle: learn, evolve, remember
Nobody hires a senior engineer. You hire a person, and some years later, if things went well, a senior engineer is sitting where they sat. What happened in between was work: they did things, some of them wrong; someone told them; they didn’t make that mistake again, and they carried what they learned into the next thing. Strip that down and it’s a loop with three beats: learn, get corrected, remember. Every good colleague you’ve ever had was that loop, running for years.
Crystalline runs the same loop for an agent, and this chapter walks it once around. The beats have names in the software (learn, evolve, remember) and each is a thing the agent does, a thing you do and a place where the files change. The diagram is the whole loop; the sections are what each box means.
3.1 Learn
Learning starts before the first task, at the moment a session opens. An agent onboarded through Crystalline receives a routing prompt: one line per domain, drawn from the ## When to Use section of that domain’s MANIFEST, plus a handful of behaviour rules. The first two say when to search (before answering a question about the project’s past, its people or its systems, and before starting a task), and the rest say how. A narrow question goes to the domain that owns it. A broad question sweeps every domain. A write always names its domain, so nothing lands in the wrong place. The briefing is short, built to survive harnesses that truncate, and it turns a graduate into somebody who knows where the filing cabinets are. Chapter 6 shows a real one, and how each harness delivers it.
Then the work happens, and this is where a colleague actually learns: by doing it next to you. Pair with an agent on a change and it sees what you see: which config file holds the threshold, which dashboard lags, what you muttered when the test failed. That’s how craft has always moved from one head to another, and it’s why this book says work with your agent rather than ask it. The one difference from last chapter’s human new hire is that the agent needs somewhere to put what it noticed, which is what Crystalline calls capture.
Capture is a byproduct of the work. When something durable turns up (a decision, a fact about the world, a gotcha that cost an hour) the agent proposes writing it down and, once you say yes, writes an engram into the fitting domain. The engram’s body is observations, one bullet each, tagged with a category: - [gotcha] The retry queue drops jobs older than 24h #payments. Categories are free text, and the precise ones earn their keep: decision, fact, pattern, gotcha, convention, lesson, risk. When one piece of knowledge leans on another, the engram says so with a relation, - depends_on [[Encom chargeback window]], and the graph knows. When a piece of knowledge is exceptional (the thing that unlocked a week-long bug, the rule everything else hangs off) it can carry a salience, a number from zero to ten, so the next search lifts it above equally relevant neighbours. Salience is for the rare engram, the way an exceptional day is the one you can still describe years later.
The beat agents skip is the last one. Left alone, a model finishes the task and stops, and the gotcha it found at minute forty goes with it. So in Claude Code, Codex and Copilot the installer wires a reminder: a nudge at the first stop after a session has gained real substance, asking the agent to review the conversation for durable learnings and propose capturing each. It costs about a hundred and twenty tokens and fires at most once. Everything downstream depends on that beat landing, which is why the installer gives it a hook of its own.
3.2 Evolve
Knowledge decays, though not dramatically: a fact doesn’t go off like milk. But a validity window that ended last month is still marked current, a review date came and went without anyone checking, two engrams point at each other and only one of the links resolves, and somebody typed fluxcapacitor where everyone else types flux-capacitor. None of it was wrong on the day it was written. All of it is drift, and drift is what makes a new hire, six months in, confidently repeat something that stopped being true in spring.
The evolve beat is how the archive gets tended, and the important word is tended, because Crystalline never rewrites knowledge on its own. Ask for a sweep (crystalline evolve from a terminal, or the evolve_engrams tool from an agent) and what comes back is a ranked queue, read-only. Each finding names the engram, shows the evidence it fired on and states the one action that clears it. Findings come in four families. Temporal: a valid_to that elapsed while the status still says stable, a stale_after past due, knowledge long unverified, a retired engram whose observations survive in no live one. Structural: an unresolved [[link]], a relation declared on one side only (supersedes, summarizes and a split’s derived_from each owe a converse), an orphan, an engram too big to stay one. Redundancy: near-duplicate clusters, a tag spelled two ways. Meaning: two engrams saying one thing in different words and, when you switch the check on, two lines that may contradict each other. The maintenance page in Fluid shows a person the same queue (Figure 3.2), a look at the state of things; the agent is the one who works it.
The queue also says who acts. A finding marked mechanical completes intent the archive already records (a replacement already declares that it supersedes the old engram, so flipping the old status invents nothing) and the agent does those in a pass and reports back. A finding marked judgment changes what the archive claims (is this window ended or extended? is this fact still true?) and that wants a yes from a person first. The agent brings those to you one at a time, as proposals. It’s the difference between fixing a typo in a colleague’s document and changing their conclusion.
Two things happen to a fact over its life, handled differently. A correction is a sharper measurement of the same thing: the cutoff runs from first failure, not from enqueue. The old value was never quite true, so it is replaced where it stands, no ceremony. A supersession is the world changing: the drop rule was twenty-four hours and is now none. The old fact was true, and stopped being. For that the agent writes the replacement as a new engram, links it back with supersedes while the old one points forward with superseded_by, flips the old one’s status to superseded, closes its window with the real valid_to date and carries any lesson worth keeping forward into the live engram. Telling the two apart takes one question: does the new fact make the old one false going forward? If it was always false, correct it. If it just became false, supersede it.
When one fact in an engram stops holding and the rest doesn’t, the split comes first: the facts that still hold move out into an engram of their own (validity is set per engram, not per bullet) and only what’s left is superseded.
Take the rule from chapter 1 that says nothing from an unfinished series. It has a year of life ahead of it. In spring you notice it was never about series: the two you abandoned were both third volumes where the joke had run out, and a finished trilogy you’d have loved got skipped for nothing. That’s a correction: the agent finds the existing engram, changes the one observation where it stands and moves on. Nothing is retired, because nothing was true and then stopped. It was merely imprecise.
In autumn you have a fantasy phase. The Lord of the Rings first, then the Warhammer novels it led you to, and the agent writes the phase down as an engram of its own, “fantasy for now”. Halfway through the first Warhammer you put it down and go back to science fiction, and that’s a supersession. The agent writes the return as its own engram, links it with supersedes, flips “fantasy for now” to superseded with a valid_to of the month you stopped and carries one lesson forward into the live engram: half a book is enough to know. A year later you ask why your own list from that autumn is all Tolkien and Warhammer, and the agent recalls the retired engram, dates and all, and tells you what changed and when, without you having to remember it.
Statuses make that work. Every engram carries one, and stable is the default, the word for knowledge that holds now. Each value in the retirement set means one thing: deprecated says don’t do this again, superseded says a newer engram replaced this one, archived says retired but kept for the record and legacy says still true of old installations but not to be built on. Delete is for mistakes, never for history. A fact merely re-checked and found still true gets a single frontmatter field, verified: { by, at }, which is how the sweep knows to stop asking.
The sweep reads dates, links and graph shape: a status, a validity window, an edge that resolves or doesn’t, a tag with two spellings. It finds a half-finished retirement because a supersedes edge points at an engram still marked stable, not because it compares the two and judges which is right. Only the meaning family reads for meaning. The twin check, on an instance that computes embeddings, finds the engrams that say nearly the same thing (ten pairs per domain at most) and raises each pair for a person to judge: two texts that sit close together agree about their topic, not about what’s true. The contradiction check is off until you switch it on. Then a local model reads the observation lines of related engrams. A pair of lines it reads as contradicting each other comes up as a question, never a verdict, because the model can be wrong and can’t see dates (Chapter 11 is about what it finds and how you answer it). That limit is the design: a linter finds work, a person decides it. Re-running the sweep re-derives the queue from scratch, so “what is left” is only ever what is still true.
3.3 Remember
Remembering is the beat that pays for the other two, and most of it happens before you notice. You type a question, and a hook in the harness (Claude Code and Codex have it) has already searched on it: up to three engrams that may apply arrive with the question, each named by its address and each only once per session. So the agent doesn’t have to think of looking, and that’s the weak spot it covers: an agent that knows where knowledge lives still forgets to check. It reads what fits and moves on, and when nothing fits the hook says nothing and costs nothing.
When the task needs more, the agent searches the domain the routing prompt pointed it to. What comes back is ranked by a blend of two signals: text matching, which finds the exact phrase, and semantic similarity, which finds the engram about lost queue jobs when the question was about why payments go missing. Salience adds a small lift for the exceptional. Retirement fades the past: an engram with a retired status is softly pushed down the ranking, never filtered out, so current knowledge surfaces first and the old decision is one scroll away.
That’s what a person’s experience is like: someone three years out of a previous job still draws on what they learned there and doesn’t mistake it for the present. A superseded engram stays in every search, still readable, still addressable by date, and the lessons carried forward from it are live and unbounded. Retiring it loses nothing; it changes only what the agent will assume is true today.
Time is a first-class question. Ask what is true now, and the agent filters on status. Ask what cutoff applied last June, and it reasons over validity windows instead: valid_from and valid_to, plain dates on the engrams that carry them. The rule that makes those windows usable is the one most often got wrong: an absent valid_from means the engram has always been valid, and an absent valid_to means it’s valid forever. Set a bound only when a fact is genuinely time-limited, and never write a far-future date to mean forever, because absence already means it. Done that way, the archive answers a dated question from the windows rather than from a hunch, which is the closest thing to a save state a team ever gets.
Recall is more than search. Hand the agent an address (crystalline://engineering/retry-queue-gotcha) and ask it to walk out from there, and it follows the relations to what the gotcha depends on and what depends on it, across domains if the links cross, ranked by how strongly each neighbour connects. That’s how an agent assembles a neighbourhood before a task rather than a flat list of hits, and it’s the part a folder of files can never do on its own.
3.4 Reflect
Everything so far happens inside the agent’s own knowledge. The agent writes its engrams for itself, for the next session’s search, and nothing in them is phrased for you. People still need what’s in there, and Reflection runs a second loop for them beside learn, evolve and remember. It works like the colleague who presents a topic to the team in Section 1.2. The agent presents what it knows in documents for people, called reflections, and everyone puts them to the test (read one, change a line, comment on a passage), while the agent asks back where a change doesn’t fit what it knows. The feedback improves the presentation for everyone, and where it corrects the agent or tells it something new, it goes into the agent’s knowledge too.
The two loops share the agent’s knowledge and cross there in both directions (Figure 12.2). A fix from the sweep, a retired engram or a corrected date, leaves every section presented from the old fact out of date, so the agent presents those sections again. And when a discussion on a reflection settles something and the agent takes it in, it goes into the engrams, where the sweep tends it from then on like everything else. The loop in Figure 3.1 stays as it is, with Reflection running beside it, and Chapter 12 tells the whole story.
3.5 Around again
The first loop closes where it started. What was recalled shapes the work; the work produces something worth capturing; the sweep keeps what was captured honest; and the next session recalls a slightly better body of knowledge than the last. The small box in the middle of the diagram, session by session, is the whole story. None of the three beats is impressive alone. A briefing is just a briefing, a linter is just a linter, search is just search. Together, running for months, they are what turns the stranger of chapter 1 into somebody who was here yesterday and will be here tomorrow, and for whom the work in between isn’t lost.
A colleague grows through a loop (learn, get corrected, remember) and Crystalline runs the same loop for an agent. Learn: onboarded at session start with a routing prompt, the agent captures observations, relations and the occasional salient engram while pairing with you, nudged once per session (where the harness supports it) so the capture beat lands. Evolve: a read-only sweep returns a ranked queue of what the knowledge needs, with mechanical findings the agent completes alone and judgment findings it proposes; a fact is corrected in place or superseded with a status and a closed window, never silently overwritten. Remember: the engrams that may fit a question arrive with it (where the harness supports it), hybrid search ranks current knowledge first, temporal fields answer what applied last June and retired knowledge fades in ranking without disappearing. Reflection runs a second loop beside this one: the agent presents what it knows in documents for people, everyone tests them and what holds up improves its knowledge.