1 What is Crystalline?
You need a function written, not a hard one: it takes jobs off the retry queue, drops anything older than the cutoff and hands the rest back to the payments service. So you leave the office, walk down to main street and stop the first person who looks like they might own a laptop.
They’re lovely about it. You explain the queue, the cutoff, the payments service; they nod, ask two sharp questions and set to work on a bench outside the bakery. Twenty minutes later they hand you a working implementation. It is clean. It has tests. It is in Haskell.
Your service is in Python. You didn’t mention that, because why would you? Everybody on your team knows that. The stranger, of course, isn’t on your team. They met you twenty minutes ago. They don’t know that the cutoff is twenty-four hours, that the payments team calls the queue the sin bin, that the last person who touched it left a comment saying DO NOT TOUCH and a wiki page explaining why. They did a good job with what they were given. What they were given was twenty minutes.
That stranger is every fresh session with a language model, and it’s the prologue’s waking seen from across the desk. The model is possibly the most capable engineer you’ve ever put a question to, and you keep meeting it for the first time.
1.1 The new-hire promise
Now imagine hiring the stranger, properly, with a desk. On day one they know nothing about you, the same as before. But on day one you show them where things are. You tell them the service is in Python, that the cutoff is a day, that the queue has a nickname and a history. You let them read the wiki. When they get something wrong in the first week, you don’t walk back down to main street and find somebody else; you tell them what was wrong and point them at the page that explains it. By the second month they’re correcting you. By the third they know more than the wiki page does.
That’s where the promise of this book starts. You get an agent you onboard, teach and correct like a colleague, and it carries what it learned into the next session and the one after that. Crystalline was built to keep that promise. The vocabulary throughout is the vocabulary of a new hire: onboard, teach, learn, capture, recall, evolve. Later in the book it gains one more word, reflect. The stranger becomes a peer, and a peer is somebody you learn from as well.
1.2 Where the two meet
Infinite diversity in infinite combinations.
- Vulcan philosophy, Star Trek
From here on the story has two sides: the agent on one, you and your team on the other. They’re built alike, but they learn in different ways and each knows things the other doesn’t.
The agent is a model plus the knowledge it keeps. The model does the reasoning. It arrives already educated, like a graduate on day one who knows nothing about your company. Chapter 2 takes that image further. The knowledge is what the agent has learned since it arrived, from the work and from you. It keeps that as engrams (small files, which the next section introduces), and they belong to the agent the way what you know belongs to you. It writes them for itself and organizes them so it can find them again, never for people to read. Your side has the same two parts: a mind that reasons, and what you know.
You picked up most of yours at school, from books and on the job, year after year. The agent learns through onboarding, when you hand it the docs, the code and the history of a system. It also learns from the experience of its own actions: the fix that held, the guess that didn’t. A lot of its learning happens while you work together. You pair on a task and it watches how things are done here. You correct it when it’s wrong, and every so often it spots the edge case you’d missed.
Above both sides there’s common ground (Figure 1.1), and that’s Reflection. Take the colleague who knows a topic best and ask them to present it to the team. Once it’s up on the screen everyone works with it, and the presenter often learns the most. In Reflection the agent is that colleague. Since the engrams are its own, it presents what it knows about a topic at your level. You and your team bring what you know, and then everybody puts it to the test. The agent asks when something doesn’t fit what it knows. People point out what it got wrong or left out, and either side can turn out to be the one who learns something. Nobody there plays the teacher, and whatever holds up goes back into the agent’s knowledge and into yours.
So the book works toward two things: an agent that learns and keeps its own knowledge, and a place where it and people meet as equals, which Crystalline calls Reflection (Chapter 12).
The first of the two needs no magic. It needs somewhere for what the agent learned to go and a way to find that knowledge again when the next task calls for it. It also needs enough discipline in the format that the knowledge stays true as the world moves. Crystalline gives the agent all three, and most of the book is about how.
1.3 What Crystalline is
Crystalline is a single Rust binary with three jobs: it’s a command-line tool for people, an MCP server for agents and a local search index over a folder of plain markdown files. That’s one download and one binary, with no server to deploy and no database to administer. MCP is the Model Context Protocol, the standard by which a harness like Claude Code, Codex or Claude Desktop hands tools to a model, and Crystalline’s tools are the ones through which an agent searches, reads, captures and refines knowledge. If the letters make you think of Tron’s Master Control Program, relax. This one hands tools out instead of taking them away, and nobody gets de-rezzed.
The files are the point. Knowledge in Crystalline lives in domains: a domain is a folder with a MANIFEST.md at its root that says what the folder covers and when an agent should look there. Inside a domain, each unit of knowledge is an engram: one markdown file with a YAML frontmatter block, holding a title, some prose, a list of observations (a fact, a decision, a gotcha, each as a bullet with a category) and relations to other engrams. Every engram has an address, crystalline://<domain>/<permalink>, that an agent can hand to another agent or to you. Chapter 4 takes each of those words apart properly. For now it’s enough to know that everything the agent learns ends up as a file you can open in any editor, diff in any repository and back up with anything.
On top of the files, Crystalline builds what a folder can’t give you on its own: routing, so an agent knows which domain owns a task without reading every file; full-text and semantic search, so a question phrased differently from the answer still finds it; a knowledge graph, so related engrams pull each other in; and a temporal model, so a fact that stopped being true in March is still there, still dated and no longer mistaken for the present. The index that powers all of that is a derived layer. Delete it and it’s rebuilt from the files. The files are the truth, and nothing else is.
An engram, by the way, is neuroscience’s word for the physical trace an experience leaves in a brain. Crystalline borrowed it because that’s what one is: the trace a session leaves behind, in a form the next session can pick up.
1.4 What Crystalline is not
It is not a notes app. The primary author in Crystalline is the agent, capturing what it learned as a byproduct of the work; you take part, correct and add, but you are not the one doing the filing. A notes app is a place a person writes for a person. Crystalline is a place an agent writes so that an agent can act.
It is not a wiki, either. A wiki is read by people, who bring their own judgment about what is current, what is relevant and which of two contradictory pages to trust. An agent reading a wiki has to be handed that judgment. Crystalline is built for a reader that acts on what it finds: every engram carries a status, a place for the dates that bound it and a record of who wrote it and when, because a reader that acts needs to know whether the fact in front of it still holds.
And it is not a retrieval pipeline dressed up as a product. A vector index will find text that resembles a question. It does not know which domain owns a task, that a fact was superseded in March, who verified a claim or that something worth writing down just happened in this session. Crystalline treats similarity as one ranking signal inside a larger system of routing, provenance and time, on files you own, with nothing to operate.
1.5 How teams end up here
Most teams that arrive here walked the same road, and it’s worth walking it once, because every step on it is reasonable.
It begins with one markdown file of instructions for the agent: conventions, the layout of the repository, the three things it keeps getting wrong. This works, and it works well, right up to the day the file grows past what fits comfortably in a session’s context. So the file becomes a folder of files, one per topic, and the agent is told to read the relevant one. This also works, until nobody, human or agent, can say which file is the relevant one for a given task, and the agent starts reading all of them or none.
So index files appear: a README that points at folders, folders with their own README pointing at files. Now a lookup is a walk down a tree of pointers, and keeping the pointers accurate becomes a job nobody was hired for. Every rung of this ladder scales further than the one before it, and every rung breaks somewhere in the hundreds of files. By this point you’ve hand-built a filesystem on top of a filesystem, and it’s exactly as much fun to maintain as that sounds.
When knowledge reaches the thousands of units, reading and pointer-walking stop being viable at all, and what’s needed is what every large body of knowledge has ever needed: real indexes. That’s the rung Crystalline is. It keeps the plain markdown (readable, and still yours) and adds domain routing, hybrid search, a graph and temporal filtering on top, so that the ten-thousandth engram is exactly as findable as the tenth.
1.6 Crystalline and Fluid
Crystalline has a second face, and it’s the one for people. The binary serves a web UI called Fluid, on by default at http://localhost:7411, on the same daemon your agents already talk to. There’s nothing to deploy, and the first visit creates your admin account in the browser.
The split is deliberate and it runs through the whole book. Crystalline stores what the agent learned. Fluid is where people and the agent meet in Reflection (Section 1.2), and that’s what most people open it for.
Opening the engrams in Fluid is the exception, a bit like debugging: you look into what the agent learned to check it and fix it. An engram shows as a page with its details in a rail down the side. There’s an editor with live preview, a search across everything, a graph of what connects to what and a maintenance page listing what the knowledge needs next. You can fix a fact the agent got slightly wrong or add something of your own, without going through the model and without spending a token on it. What you write there doesn’t sit unreviewed; the agent’s next maintenance pass verifies it, aligns the tags and wires it into the graph. The next chapter explains why the UI carries that name.
1.7 Where it runs
Crystalline isn’t a hosted service. Nobody’s servers are involved: the binary runs on a machine of yours, the knowledge is a folder on its disk and the index sits beside it. GitHub, when a team uses it, holds a copy of a domain’s files for review and sync, the way it holds code. It never serves the knowledge and never sees the index. So the question is where the one daemon runs, and there are two answers.
On your laptop is the default, and it’s where Crystalline does the most. The install wires your harness with the session-start briefing and the skills, plus the capture nudge and a prompt hook where the harness supports them, and a domain’s tools provision straight into it. The prompt hook hands the agent the engrams that may fit each question as it arrives. Everything the agent knows is on your disk, and Fluid shows it to you with no agent and no network. A shared instance, one daemon on a machine the team runs, is for the things a laptop can’t do. People who never open a terminal work with the agent in Reflection in the browser, several of them at once in a meeting, and only now and then open its engrams to correct something. Agents with no harness of their own (a hosted runner, a chat client) reach it over HTTP. Either way a domain can live in a GitHub repository and travel between instances as reviewed proposals. Start on the laptop; chapter 16 names the moment to move.
| Shape | Who connects | What it gives you |
|---|---|---|
| Your laptop | your harness and your browser | the full install: briefing, skills and tools wired into the harness, nudges where it takes them; knowledge on your disk, open in Fluid offline |
| A shared instance | the team’s agents over HTTP, everyone’s browser | one truth for the whole team, accounts, sign-in through the company’s identity provider, private domains, co-editing, agents and people with no harness |
| A team domain | any instance, laptop or shared | review before knowledge reaches anyone else; the domain travels between instances through GitHub |
On Monday you ask your agent for something to read on the flight. You explain yourself first: science fiction before anything else, the funny and the fast (the Hitchhiker’s Guide, Dungeon Crawler Carl, the Star Trek novels), Gibson and Doctorow when you want ideas and Dune when you’re feeling strong; English when the book was written in English, German translations for everything else, except manga, where the Catalan translation is the better one; nothing from an unfinished series, because the third volume never comes; the local shop before the online giant and never Sirius Cybernetics, whose parcels arrive bent. The agent finds you something good, and the session ends. On Tuesday you ask it about the sequel, and start by explaining the languages and the series rule. On Thursday you ask a third time, and catch yourself typing the sentence about the third volume, word for word, into a chat window, for the third time that week.
With Crystalline, Monday ends differently. Before the session closes, the agent proposes capturing what it learned: the languages, the series rule and the reason for it, where you buy and where you don’t, filed as engrams in your books domain. You say yes. On Tuesday you ask about the sequel, and the agent, told at session start where your reading knowledge lives, looks there first, recalls the rules and starts from them rather than from zero. On Thursday nobody explains anything. The stranger on main street was never the problem. The problem was that you kept going back to main street.
A fresh session with a language model is a brilliant stranger: capable of anything, told nothing, gone by tomorrow. Crystalline is a single Rust binary (a CLI for people, an MCP server for agents and a search index over plain markdown) that gives an agent somewhere for what it learns to go and a way to find it again, so it can be onboarded, taught and corrected like a colleague. That knowledge is its own, and it meets yours as an equal in Reflection. The files are the source of truth and the index is disposable; Fluid, the web UI on the same daemon, is where people meet the agent, and opening its engrams there is the exception. What it holds is knowledge for an agent to act on, which makes it neither a notes app nor a wiki. It runs on your laptop or on one machine your team operates, never as a hosted service, and GitHub is the review layer either shape can use.