The Crystalline Handbook
Evolve any frontier model from stranger to peer
Preface
A beginning is the time for taking the most delicate care that the balances are correct.
- Frank Herbert, Dune
This is a handbook about onboarding a colleague who happens to be a language model. The colleague is already on your machine, inside whichever harness you use: Claude Code, the Codex CLI, the Copilot CLI, Claude Desktop. It’s brilliant and tireless, and at the start of every session it’s completely new here. Crystalline is the software that changes the last part, and gives the two of you somewhere to meet. This book is the story of how, and the manual for doing it.
Who this book is for
You run an agent every day, and you’ve noticed that you explain the same things to it every day: which service owns the retry queue, why the payments team never deploys on a Friday, that the thing the wiki calls “the gateway” is the thing the code calls “edge”. You’d like to stop, and this book shows you how to teach those things once and have them recalled in every session that follows, in files on your own machine.
Or your team is adopting Crystalline together: one shared instance, domains that live in a GitHub repository, knowledge that goes out for review the way code does. Parts V and VI are written for exactly that, and the chapters on sharing and access carry the team story.
Or you’re the person who onboards agents for other people - platform engineer, enablement lead, the one everybody asks. Every chapter here works as a standalone training module, with a summary at the end you can hand round.
Whichever of those you are, the payoff is the same. Teach an agent where things are, which tools the team uses, what was tried and what to leave alone, and it does the job in one pass instead of looping until something sticks. It stops reinventing the wheel.
The bigger payoff is trust. A model told nothing about your company fills the blanks with the general case, the intelligent guess chapter 2 describes, and a guess about your company looks exactly like a fact about it. An agent you’ve taught has no blanks to fill. It answers from what you told it, and it can say where that came from.
Where this comes from
I started where everyone starts: a CLAUDE.md and a README.md for the agent, the folder the harness keeps for its own notes, markdown files in subfolders of the project, one per topic. All of it works, and for the usual cases it works well. Then I wanted to hand the agent more than one project’s conventions: over a decade of engineering knowledge and experience, sitting in code reviews, slide decks, documentation, tickets and a wiki. I wanted it extracted and taught, so that the agent could act like an engineer with those ten years behind them, one who knows how things are and remembers why: the reasons, the discussions and the decisions behind them. At that size none of those approaches held. Index files pointing at folders bought some time, until every lookup was a walk down a tree of pointers and keeping the pointers true had become a job of its own.
The ingest was also a look ahead, because a decade of material arriving at once is every problem a knowledge base will ever have, compressed into a few weeks: decisions reversed twice over, the same rule written three ways in three years, a wiki page nobody had believed since 2019, facts that held until a date nobody wrote down. The material had kept moving underneath itself as well: processes, best practices and coding conventions had changed, and so had the tech stack and the architecture, and each of those had to come through as true for its time rather than as a contradiction. The precogs in Minority Report saw a crime before it was committed. This was that view of a knowledge base: everything it would have to survive, shown before it had grown into any of it. The statuses, the validity windows, the provenance on every engram and the maintenance sweep are all answers to something in that view.
I tried what was already out there, and some of it was good, but none of it was built for this: a colleague who is new every session, a body of knowledge that has to be recalled rather than read, and files that stay plain files. At some point the picture of how it should work was simply clear, down to the details, and Crystalline is that picture built. That’s also why it has opinions, about domains and manifests and statuses and what an engram is, where a more general tool would have left the choice to you. Chapter 1 walks the same ladder for teams in general, because it turned out I hadn’t been alone on it.
Along the way I’ve given this material as a workshop more than thirty times, to teams of every size and temperament, and the chapters are those sessions. The questions the rooms kept asking are folded back into the text, and the book is what the workshop became once it had been given often enough to know what it was.
A word about Raymond Cattell, whose line between fluid and crystallized intelligence gave Crystalline and Fluid their names (chapter 2). Cattell also spent decades promoting eugenics and racial separation, a doctrine he called Beyondism. I reject those views without reservation. This book takes exactly one idea from his work, the distinction between the mind that reasons and the knowledge it gathers, which he developed with John Horn and which psychology has long since carried on without him. Nothing else of his has a place here.
“The glory of creation is in its infinite diversity.”
“And the ways our differences combine to create meaning and beauty.”- Miranda Jones and Spock, Star Trek, “Is There in Truth No Beauty?”
How to read it
Part I is an evening’s read (tea, Earl Grey, hot - or coffee, black, if you side with Janeway), and nothing in it needs a terminal. It’s what makes the rest make sense. Parts II and III are meant to be read with a keyboard under your hands and an agent running, and they assume you’ll stop and try things. Part IV is the whole system surface by surface, and it reads either way: in a sitting, or a section at a time when a chapter sends you there. Parts V and VI are for the day the team arrives, and they want the keyboard again. Part VII is for looking things up rather than reading through: open it when a chapter names a setting in passing or a code turns up in front of you.
Every chapter stands on its own and closes with a summary you can read aloud to a room. If you’re training a team, hand out chapters, not the book.
The browser isn’t the only place to read it: the same text is there to download as a PDF or an EPUB, each rebuilt from the same sources whenever this site is.
Conventions
The same three asides recur throughout the book, and this is what each looks like.
Each vignette is two paragraphs: a named team, a real situation. Read these when you want to know what a feature feels like on a Tuesday.
These say what the software actually does underneath a behaviour. Skip them on a first read and come back when something surprises you.
The TL;DR is the whole chapter in a few sentences, for the reader who scrolled straight to the end and for the colleague who swears they read it. It’s always last, so you always know where to find it.
The screenshots are of Fluid, the web UI, taken on a small demo instance seeded for this book, so the engrams in them are the ones the chapters keep talking about. The diagrams are drawn by hand and kept deliberately plain, and each one has a caption telling you where to look, because a diagram without one is a puzzle.
Anything you can type is in a code block, ready to paste. Conversations with an agent appear as short You: and Agent: transcripts, trimmed of the small talk. Your agent won’t say it quite this way, and that’s fine: watch what it does, not how it phrases it. And whenever something lands on disk, you get to see the file, because knowing what was written is half of trusting it.
What you need
You need a machine with an AI harness that speaks the Model Context Protocol. Claude Code, the Codex CLI, the Copilot CLI, Cursor, Kiro, Gemini CLI and Qwen Code are wired up with one command each, and Claude Desktop gets an extension that starts Crystalline once it’s installed. On Windows neither step needs a terminal, and on a Mac where Desktop is all you use, the Desktop-only bundle carries Crystalline inside and needs none either. A terminal helps for the local install and the occasional maintenance command, and semantic search wants the local embedding model fetched once; plain text search works before that.
You don’t need a server, an account with anyone or a database. Everything except the shared-instance and team chapters runs on a laptop, and what it produces is a folder of markdown that opens in anything.
The version covered
This handbook describes Crystalline 0.30.0. The colophon at the front carries this text’s license, the address of the latest release and a QR code that takes you there.