4 Terminology
Every word in this book has a file behind it. That’s the pleasant thing about Crystalline’s vocabulary: a domain is a folder you can list, an engram is a file you can print, an address is a string you can paste and a status is a line in that file you can change with whatever editor you already own. So this chapter doesn’t open with a table. It opens one engram, the retry-queue gotcha the screenshots in this book keep returning to, and reads it from the top, stopping at each term as it comes up. By the end you’ll have met every word the rest of the book leans on, and seen each one on disk.
4.1 Domains
Start with where the file lives: ~/knowledge/engineering/retry-queue-gotcha.md. The folder is a domain. A domain is a registered folder of knowledge with a MANIFEST.md at its root, and the manifest is what makes it more than a folder. It says what the domain covers and when an agent should look there, and those bullets are what the routing prompt is built from at the start of every session. Registering is one command, crystalline domain add engineering ~/knowledge/engineering. The name you give it there goes into the manifest as the domain’s declared name, and that’s the name the agent and every link use from then on, on every machine that registers the domain (Chapter 18). Say your team has two domains: engineering for the payments service and everything around it, clients for the people it sells to. The line between them is who could vouch for a change (the engineers for one, the people who sell for the other), and chapter 17 makes that the rule for a team domain. A domain can also be virtual, living in the database with no folder at all; it carries the same manifest and answers to the same tools.
Every domain also has a source, the place it comes from: your machine itself or one server your Crystalline is connected to. A write always goes to that source, and a server’s domains appear beside your own under one name each (Section 16.10).
Inside a domain, subfolders are topic prefixes. A singleton engram stays at the root; once a cluster forms, it gets a folder, and the folder becomes part of the engram’s address. The manifest’s ## Notes for Agents section is where the agent finds what was decided about this domain’s layout.
4.2 Engrams
Below is the file itself, as it sits on disk, and everything in the rest of the chapter is a line of it:
---
type: engram
title: Retry queue gotcha
permalink: retry-queue-gotcha
tags:
- gotcha
- payments
status: stable
recorded_at: 2026-03-09
generated: { by: claude-code/2.1.233, at: 2026-03-09T16:42:10+00:00 }
---
The retry queue drops any job older than twenty-four hours instead of
retrying it. The team calls the queue the sin bin. The cutoff is not a
tuning choice: it mirrors the chargeback window at Encom, the bank
behind the card payments.
- [gotcha] The retry queue drops jobs older than 24h #payments
- [fact] The 24h cutoff mirrors Encom's chargeback window #payments
- depends_on [[Encom chargeback window]]An engram is one markdown file holding one unit of the agent’s own knowledge, the trace a session leaves behind in a form the next session can pick up. A YAML frontmatter block sits on top. The agent writes it, organizes it and reads it back, so its shape serves the agent. If the word sounds like something from a starship’s sickbay, that’s because Star Trek borrowed it from the same neuroscience textbook Crystalline did.
The frontmatter is identity and state. type says what kind of thing this is: engram by default, with guide, decision, architecture, runbook and reference as the recommended alternatives. title is the name the engram goes by and the thing other engrams link to. permalink is derived from the title and is the half of the address that links point at; when the engram moves to another folder, the permalink moves with it unless somebody chose it by hand. tags are what a search or a filter narrows on. status says whether the knowledge holds, and it gets its own section below. recorded_at is the day it was captured; generated records who wrote it and when, and for an agent also which model. When the knowledge is time-bounded, valid_from and valid_to sit here too; this engram has neither, which means it has always held and holds until further notice. Both type and status are required and free form; the recommended values are guidance, never an enumeration a write is rejected for.
Then comes the prose, the explanation a colleague would give across a desk: what the thing is, what it’s called and why it is the way it is. The prose is what search matches on and what the agent reads first.
Then come the observations. A top-level bullet of the form - [category] text #tag is an observation, and observations are the atomic unit of an engram’s body: the fact, the decision, the gotcha, each indexed on its own line so a search hit can point at it. The category in brackets is free text, and the precise ones earn their keep: decision, fact, pattern, gotcha, convention, lesson, risk, idea. A trailing #tag attaches the tag to that observation.
Then comes the relation. A top-level bullet of the form - rel_type [[Target]] is an edge in the knowledge graph, typed by whatever word comes first: depends_on here, supersedes and superseded_by in chapter 3, derived_from and split_into between the two halves of a split, relates_to when nothing sharper fits or a quoted phrase for a multi-word type. The target is a title (resolved within the domain) or [[domain:Title]] across domains. The target’s page shows the edge back as a backlink, and a target that doesn’t exist yet is an unresolved link the sweep will mention.
One topic per engram is the rule that keeps all of this easy for the agent to find and act on. When the topic grows, the engram is edited, not forked; when it splits, it splits by granularity or by validity. A large capture splits by granularity, a distilled summary beside a source engram holding the full text, linked both ways. An engram that bundles facts with different lifetimes splits by validity. Validity is set per engram, so when one fact expires while the rest holds, the still-valid observations move into an engram of their own first. The new engram carries the source’s tags and type, a stable status and no validity window, and points back with derived_from; the old one keeps what expired, points forward with split_into and retires.
4.3 The open format underneath
None of that is a private format. The engram extends Google’s Open Knowledge Format, OKF, version 0.2: plain markdown with YAML frontmatter, readable by any OKF tooling, with Crystalline’s routing, temporal and graph conventions layered on top. Unknown frontmatter keys survive every write and edit, so an OKF document from somewhere else drops into a domain intact and comes back out intact. The generated block is the provenance record, and the index.md Crystalline writes at a domain’s root declares the format version for anything that browses the folder without Crystalline running. Your knowledge stays files in a folder that any editor opens and any diff tool diffs, whatever tools come next.
4.4 Statuses
status is the field a reader that acts on knowledge needs most, because it answers the one question a page can’t answer about itself: does this still hold? stable is the default and the word for knowledge that holds now; the older spelling current means the same state, and a filter on either finds both. Before stability there are draft, proposed, idea and poc, for knowledge that’s on its way. implemented is on the recommended list too, and like any status outside the retirement set it ranks at full strength.
After stability there is the retirement set, four words that each mean one thing. deprecated says don’t do this again. superseded says a newer engram replaced this one, and the two are linked. archived says retired but kept for the record. legacy says still true of the old installation that’s somehow still running, like the terminals aboard the Nostromo, but not to be built on. A status in the retirement set fades the engram in search ranking, gently and never to zero, so current knowledge surfaces first and the past stays one scroll away, dated. Retiring is how a fact leaves the present without leaving the archive; deleting is for mistakes.
4.5 Salience
Most engrams are ordinary, and that’s fine. A few are the ones everything else hangs from: the rule that explains a dozen other rules, the insight that ended a week-long bug. Those can carry a salience, a number from zero to ten in the frontmatter, and hybrid search adds a small, bounded lift for it, so a salient engram ranks above equally relevant neighbours while relevance keeps the upper hand and nothing is ever filtered out by it. It’s set sparingly at capture time, and raised later when an engram turns out to have been what a task hinged on. The retry-queue engram carries none, and most never will.
4.6 Addresses
Every engram has an address, crystalline://engineering/retry-queue-gotcha: the scheme, the domain, the permalink. It’s the one absolute form. An agent hands it to another agent, build_context anchors on it, Fluid copies it to the clipboard in one click. It survives a commit message, a ticket or a chat. A folder prefix appears in the permalink (crystalline://engineering/queues/retry-queue-gotcha if the engram had been filed under queues/), and a trailing /* anchors the whole folder at once.
The rule that trips people up is the scheme-less one. An identifier without crystalline:// is domain-relative: retry-queue-gotcha, together with the domain named beside it, never engineering/retry-queue-gotcha, which would be read as a folder called engineering inside whatever domain you meant. The same holds for links: [[Retry queue gotcha]] resolves in the domain the linking engram lives in, and [[engineering:Retry queue gotcha]] reaches across. Either the address is absolute and carries its domain, or it’s relative and the domain comes from context. There’s no third form, and that strictness is what lets a permalink stay short.
4.7 The MANIFEST, up close
The next term is the first file in every domain. MANIFEST.md is an engram of type: manifest with the permalink manifest, which means it’s read, indexed and edited with the same tools as everything else. Its job is routing, and two sections do it. ## Scope says what the domain covers. ## When to Use says when an agent should route a task here, and those bullets, one line per domain, are what become the session-start briefing. ## Notes for Agents, the third section the scaffold creates, holds the conventions the agent should follow inside this domain, the folder layout above all. Two optional sections come later. ## Tag Aliases folds an old tag name into its canonical one so old searches keep working. ## Provisioning names the folders of skills, slash commands, subagent definitions and MCP server configs a domain ships beside its knowledge. The tools that knowledge depends on travel with it, and install into a harness once a person says yes. That section gets a chapter of its own (Chapter 21). You don’t have to keep all of this in your head: the domain’s page in Fluid lays the manifest out section by section, with an example for every section still missing, and an edit that breaks routing says so as soon as it lands. An engineering manifest, a few months in:
---
type: manifest
title: engineering
domain_name: engineering
permalink: manifest
tags:
- manifest
status: stable
recorded_at: 2026-03-02
---
# engineering
## Scope
- The payments service, its retry queue and the services around it
- Deploy runbooks, team conventions and the decisions behind them
## When to Use
- Route questions about the payments service, the retry queue or a deploy here
- Check here before touching anything the team has already been burned by
## Notes for Agents
- Runbooks live under runbooks/, gotchas at the root
- One engram per gotcha; edit the existing one before writing a secondWrite the When to Use bullets the way you’d brief a new hire on which drawer holds what. A machine reads them, but it reads them the way a person reads a label.
The manifest being an engram is why routing needs no separate configuration: crystalline prompt system parses each registered domain’s MANIFEST.md, takes the ## When to Use bullets, or ## Scope when there are none, and emits one routing line per domain plus the behaviour rules. Two filenames in a domain are reserved and never engrams. index.md is the table of contents Crystalline regenerates after every write so the folder navigates itself without Crystalline running. Each machine builds its own, and a team share leaves it out unless the MANIFEST asks for it; log.md is reserved but never generated. A title that would slug to either is refused.
Say your books domain is a year old and you start a second one, shops, because where to buy is a different kind of knowledge from what to read: which shop orders from small presses, which one delivers by Friday if you ask on Monday, which one never again. Your first engram there is about Capsule Corp Books, and it needs to say that the paperback rule in books (wait for the Tessier-Ashpool paperback, the hardbacks fall apart) is why you order there. You type - relates_to [[Wait for the paperback]], and the sweep tells you the link doesn’t resolve, because shops has no engram by that title. You change it to [[books:Wait for the paperback]] and the edge appears, with a backlink on the books side that nobody had to write.
A week later a friend asks what to read and where to get it, and instead of typing the answer out you hand your agent the address, crystalline://shops/capsule-corp-books, and ask what you’d tell her. It picks up the address, walks one hop into books and comes back with the paperback rule, the small press and the two authors you’d tell anyone about. That’s two domains and one edge, and the string is still readable in a year.
4.8 Reflections and the pact
Nothing in an engram is phrased for you, and that’s on purpose: the engrams are the agent’s own knowledge. When people need what a domain holds, the agent presents it to them, and that has a name. A domain’s Reflection, with a capital R, is the whole of the documents the agent presents for people, and a domain switches it on in its MANIFEST. One document in it is a reflection: a markdown file under the domain’s reflections/ folder, made of sections. A section is a ## heading and its text, and it records which engrams it was built from, so when one of them changes, the agent knows which sections to present again. A section may draw on another domain only when everyone who reads the page may read that domain’s engrams too, unless a person shares it on purpose (Chapter 20).
Who may do what with the reflections is a level of its own, the Reflection level, set beside the knowledge level that says what a person may do with the engrams. The knowledge level is the viewer or editor of Chapter 16 (plus manager on a private domain and admin on the instance), and it has one more value, none, for somebody who sees no engrams at all. There are two Reflection levels. A reader reads the reflections and comments on them. A contributor also edits their text and creates, moves and deletes reflections. Above both sits curating: writing sections from the engrams, settling what people changed and editing the pact. Nobody is given that by hand, because everyone from engram editor up curates, and their agents curate with their rights; Fluid shows them as curators. A viewer of the engrams is a reader without anyone setting it, and a Reflection level set on top only ever raises that, so a person with knowledge none and Reflection contributor works on every reflection and never sees an engram. A Reflection collaborator holds such a level for one domain only, which is how somebody works on that domain’s Reflection and nothing else.
Reflection is also the name of a mode in Fluid: in a domain with its Reflection switched on, a switch in the top bar flips between Reflection and Engrams. The Engrams half needs knowledge viewer or above, so somebody who sees no engrams gets the Reflection alone.
Two loops keep a domain in step when nobody opens a session. The reflect loop works what the Reflection needs, the evolve loop the sweep’s mechanical findings, and a runner starts each one on a schedule or when the instance calls it (Chapter 14). A run is an unattended run, a session nobody is behind: it reads only the domains everyone who reads its domain may read, writes only into that domain and never asks a question. On a team domain the scheduled evolve runs on one instance only, the domain’s evolve home.
The last term is a file again, the pact. Every domain with a Reflection has one, PACT.md at the root of reflections/, and it has five parts: who the reflections are for, how much detail they carry, how they’re presented (which diagrams, callouts and tables help those readers), how the tree is structured and which pages people asked for. It’s the MANIFEST’s counterpart: the MANIFEST tells the agent what the domain holds, the pact tells everyone how to talk about it. Switching the Reflection on writes a first pact with those five headings to fill in. Curators edit the pact; everybody else reads it and proposes a change in a thread. A pact for a book club’s club domain, for members and spoiler-free:
---
title: How we write about club
---
# How we write about club
## Audience
- Club members, including the ones who haven't started the
book yet
## Level of detail
- No spoilers past the first chapter
- What the club read, what's next and what members thought
## Presentation
- A table of the books per series; no diagrams
## Structure
One reflection per series, named after the series, in `series/`:
- series/*.md
## Pages
- next-meeting.md: "what we read next and where we meet",
asked by Lambert in OctoberOnly the bullets under ## Structure count, one glob each; the line above them is there for people. Under ## Pages the agent notes each page somebody asked for, in their words, so it knows where new knowledge belongs and can rebuild the page from the request.
You now speak the language. The rest of the book is conversation.
A domain is a registered folder with a MANIFEST.md whose When to Use bullets route an agent to it; an engram is one markdown file with YAML frontmatter, prose, observations of the form - [category] text #tag and relations of the form - rel_type [[Target]], all on Google’s Open Knowledge Format so nothing is locked in. status says whether knowledge holds: stable is the default, and deprecated, superseded, archived and legacy are the retirement set that fades in ranking without disappearing; salience is a rare, bounded lift. The absolute address is crystalline://domain/permalink, and anything without the scheme is domain-relative. The manifest is itself an engram, which is why routing needs no configuration of its own. A domain’s Reflection is the documents the agent presents for people, reflections made of sections, shaped by the pact in PACT.md (audience, level of detail, presentation and structure) and read and commented on by readers, edited by contributors and curated by everyone who may edit the engrams.