15 What Crystalline provides
Picture a workshop with two doors and a hatch. Through one door come the agents; that door is a protocol, and whoever arrives through it is handed tools. Through the other come people; that door is a browser tab. The hatch at the side is for anyone with a terminal open, which is where the command line lives. Behind all three is one room with one set of shelves, and on the shelves are plain files. The room has a single keeper, a daemon, that watches the shelves, keeps the index warm and answers whoever comes in, whichever way they came. That’s the whole architecture, and the rest of this chapter walks the room surface by surface: the command line, the tools an agent sees, search, the graph, time, Fluid, the skills and the sweep. Chapter 1 named them and the last eight chapters used them one at a time. This chapter lays them side by side and says what each one lets a colleague do.
The room is also, for most of its life, invisible. Once it’s set up, the agent comes in through its own door at the start of every session and you come in through the browser when you feel like it. The keeper starts itself when the first visitor arrives, and the hatch stays shut. The command line below is for the install you’ve already done, for standing up a shared instance and for the occasional maintenance run. If the list of commands looks long, read it as a tour of what’s there rather than a list of what you’ll type.
15.1 The command line
Crystalline ships as one binary, and the binary is the product: no server package beside it, no database to install first, no UI to deploy separately. crystalline install claude-code wires a harness in one step (Codex, Copilot, Cursor, Kiro, Gemini CLI and Qwen Code take the same command with their own names). It registers the MCP server, writes the hooks the harness supports and copies the skills into place. Every harness gets the session-start hook that delivers the routing prompt. Claude Code, Codex and Copilot also get the stop hook that nudges capture, and in Claude Code and Codex the prompt hook hands each question the engrams that look like a fit. Run it twice and the second run writes nothing and says so. crystalline uninstall reverses it and leaves anything that isn’t Crystalline’s own untouched.
Domains are managed the same way. crystalline domain init scaffolds a folder with a starter MANIFEST.md, crystalline domain add registers it, and domain add --virtual registers a domain that lives in the database with no folder at all, for a container without a writable volume or a knowledge base you’d rather not mirror to disk. crystalline domain remove takes one off the instance and leaves its files where they are. A virtual domain has no files and its engrams go with the registration, so there the command refuses until you add --purge. crystalline domain rename repairs a name that turned out wrong and keeps the old one working as an alias (Chapter 18). crystalline users manages the accounts that can sign in to the web UI, although the first admin is normally created in the browser. crystalline prompt system renders the routing briefing to stdout, ready for any harness with a session-start hook, and prompt connector prints the standing instruction for a chat client that has no hooks. crystalline serve runs the daemon in the foreground and serve --daemon in the background, though most people never type either, because the first agent that connects starts the daemon on its own.
The rest of the CLI mirrors what an agent can do, for scripting and for the quick fix that doesn’t deserve a session: write, read, edit, split, search, context, vocabulary, evolve. Three commands ask three different questions about health. verify asks whether the format holds, statically, with no daemon involved, and it is what the bundled GitHub Action runs on every proposal a team reviews. doctor asks whether the machinery around the format is healthy and repairs what it safely can with --fix. evolve asks whether the knowledge itself is still true and still well organized, which neither of the others can. A fourth, import, brings an existing markdown-plus-frontmatter knowledge base under Crystalline as a pure file transformation, dry run first.
Exactly one process ever holds the index open. The first crystalline mcp or crystalline serve takes an advisory lock and becomes the daemon; every later agent, terminal or CLI command attaches to it over a local socket. The daemon watches the domain folders, embeds new engrams in the background and keeps running after the last agent disconnects, so the index is warm for the next session; it stops only when told to, with crystalline ctl shutdown. The daemon of the Desktop-only bundle on a Mac is different: it exits five seconds after its last client. What it keeps is derived from the files: crystalline reindex --full re-reads every file and keeps the embeddings, and crystalline reindex --wipe rebuilds an index that won’t open, so a corrupted index or a schema change is never a data-loss event for a folder domain. A virtual domain has no files behind it (its engrams live only in the index), so the wipe refuses while one is registered. The accounts for the web UI live in their own small database beside the index, never inside it, so a rebuild can’t take them along.
15.2 The tools an agent sees
An agent meets Crystalline as a set of tools over MCP, and they’re best described by what they let a colleague do, because that’s how the agent chooses among them. Twenty-four are listed on a default writable instance and thirty with team collaboration turned on. Four of them belong to Reflection and are the same for every client: reflect, read_reflection, write_reflection and discuss (Chapter 12). A read-only instance hides reflect, write_reflection and discuss.
The core is small. search_engrams is recall: search before writing, search to remember, across every domain or a chosen few. read_engram fetches the whole engram, because a search hit is a snippet and a colleague who answers from a snippet is guessing. write_engram captures something new, and it always names its domain; there’s no default, so nothing lands in the wrong place. edit_engram refines what exists instead of forking a second engram about the same topic: append a section, replace one, find and replace a phrase or assign one lifecycle field by name, which is how an engram is retired or re-verified with no text matching involved. Both answer with a hint: the receipt of a write, or of an edit that adds text, may name up to three existing engrams closest in meaning to what just landed, with guidance to merge into the one that fits, supersede it or link it and never to ignore the list silently (capture.similar switches it off). split_engram is for the engram that mixes lifecycles. Validity is set per engram, not per bullet, so when one fact in it expires while the rest still holds, the survivors move out into a new engram first and only the remainder retires. The pair stays linked, derived_from on the new engram and split_into on the source. A split that would leave the source under three content lines is refused, because that’s the case for retiring the whole thing. build_context walks out from an address and assembles the neighbourhood. vocabulary lists the tags, categories, relation types and statuses already in use, so an agent reuses a term rather than coining a near-duplicate. evolve_engrams runs the maintenance sweep. configure is the settings page, for the instance or, given a domain, for how that domain shares and which checks it runs. add_domain gives an agent somewhere to write on an instance that has nowhere yet. remove_domain is its counterpart: the registration and the index rows go, and the knowledge stays. In a domain in review mode the removal would also end everyone’s unshared drafts, so there it refuses until each person who is still drafting is named. A folder’s markdown sits on disk until an add_domain re-adopts it, and a team domain is reconnected by its repository. A virtual domain’s engrams live in the database and go with it.
Around them sit the tools for orientation: list_domains, which re-fetches the session briefing mid-session; browse_domain, one level of the folder tree at a time; move_engram and delete_engram, with delete reserved for mistakes; recent_activity to catch up on a week; and skills to read a playbook. A move works like a refactoring in code: every link to the engram in the domains you may write follows it to its new address. A domain that wants its engrams to share a shape gets validate_engrams and infer_schema, and one that ships tools of its own gets provision. The six collaboration tools share, update, check standing, settle a conflict, withdraw a proposal and put unshared files back the way the team has them. Chapter 17 is theirs.
The difference between this and a lookup service is the difference between a colleague with a badge and a visitor with a lanyard. The tools let an agent act: find what applies, read it in full, do the work and leave behind what it learned, with nobody relaying anything.
15.3 Search
The most used surface is the one nobody notices, and it blends two signals. Full-text matching finds the exact phrase, the way you find your own notes when you remember the wording. Semantic similarity finds the engram about dropped queue jobs when the question was about payments going missing, because the two are about the same thing in different words. Crystalline runs both and ranks by the blend. The local embedding model is fetched once, on first use or ahead of time with crystalline model download; until then, search falls back to plain text.
Search also decides the size of a session. An agent that keeps its knowledge as a folder of markdown files reads the folder, and reads it again next session, every file whether or not the task touches it, because a folder has no way of saying which page matters today. An agent working from a knowledge base receives only the knowledge that applies. The search is routed to a domain first, then narrowed by the indexes: full text and semantic similarity for the phrase and the meaning, the graph of relations and backlinks for what the answer leans on, tags, the folder prefixes build_context globs and the temporal filters for what holds now. Reading a folder costs the whole folder, every session. Recall costs the engrams that matter, and nothing else is loaded. Chapter 9 made a section of it.
Two priors tilt the ranking, both small and both bounded. A salience on an engram lifts it above equally relevant neighbours without ever excluding anything, for the rare piece of knowledge that outranks its surroundings. A retired status fades an engram softly, so current knowledge surfaces first and the superseded decision from March sits one scroll further down, still there. Searches also filter: by domain, type, tag, status, any frontmatter key or a recorded-after date, and a search with no query text at all is a legitimate way to ask for everything of one kind. Fluid puts the same ranking behind a faceted page (Figure 15.2).
15.4 The graph
Every relation in an engram’s body, - depends_on [[Encom chargeback window]], is an edge, and the target’s page shows it back as a backlink, so knowledge points both ways without anyone writing the return trip. A [[Title]] in prose counts too. Links resolve within the domain by title, and across domains with a prefix, [[engineering:Retry queue gotcha]]; move an engram to another folder or domain and every link, relation and address pointing at it is rewritten in the domains you may write. The moved engram’s own links keep finding what they found, and the receipt names any link the move couldn’t fix.
build_context is what makes the edges useful before a task. Hand it an address and it follows the relations and links outward, one to three hops, across domains if the edges cross, and returns the neighbours ranked by how strongly each connects to the anchor, with salience counted and retired statuses ranked lower. A folder prefix with a /* suffix anchors a whole topic at once. The agent starts the task holding a neighbourhood rather than a flat list of hits, which is what an experienced colleague does when they pull up the runbook, the decision behind it and the incident that prompted the decision before touching anything. Fluid draws the same neighbourhood as an interactive graph (Figure 15.3).
15.5 Time
Every engram records when it was captured and who wrote it, and can carry the dates that bound it. valid_from and valid_to are plain dates, and the rule that makes them usable is the one worth memorizing: an absent valid_from means always valid, an absent valid_to means valid forever. A far-future date written to mean forever is dropped at write time because absence already says it. stale_after asks for a re-check by a date; verified records that the check happened and who did it; source_date says when the underlying source was written. A retired engram closes its window with the real transition date, which is what lets a search filtered on those fields answer what applied last June with the engram that was true then. Chapter 9 put the dated questions to work and chapter 10 the retirements.
15.6 Fluid
The door for people opens at http://localhost:7411, on by default on the same daemon the agents use, and the first visit to a fresh instance creates the admin account in the browser. The menu behind your avatar links to the latest edition of this handbook. An engram is a page (Figure 15.4): the frontmatter as a rail of details, each observation led by its category and each relation by its type, backlinks, the crystalline:// address one click from the clipboard and an agent’s-eye view showing exactly what the tools serve an agent for that page. You switch domains from the top bar, and Cmd+K jumps anywhere by name.
Behind the same door is Reflection (Chapter 12): in a domain that switches it on, the agent presents what it knows in documents written for people, and the top bar flips between Engrams and Reflection.
Editing happens in place, in a live-preview editor with a frontmatter form in the details rail and wikilink completion across every domain, and the file on disk stays the source of truth. A solo save answers like a write over MCP, with a panel of the nearest existing engrams, each linked to its page, replaced on the next save and gone when you dismiss it. Attachments go onto an engram by paste, drag or upload: a screenshot, a slide deck, a PDF, a data file. They’re how a person hands over teaching material, and they aren’t opaque: an agent reads them back over MCP and the sweep notices when a fresh file still needs capturing. Two people in the same engram see each other’s cursors, and their edits merge conflict-free into one save. Who can sign in, and how, is chapter 16’s.
15.7 Skills
A tool tells an agent what it can call. A skill tells it when, and how to do it well. Crystalline ships six harness-agnostic skills as plain folders with a SKILL.md each: routing, which domain to search and when to sweep them all; capture, what is worth writing down and the search-before-write, edit-over-create discipline; schema, for a domain that wants structure; collaboration, for a domain with a team behind it; provisioning, for a domain that ships its own tools; and presentation, for pages people read. A seventh, consolidated skill folds the essentials into one file for Claude Desktop and any harness that installs one skill at a time.
crystalline install copies the skills into the harness’s own skills folder and keeps them current across upgrades. All seven are served over MCP as well, through the skills tool and as resources, so a remote client that never ran the CLI can read the playbook before its kind of task. Loading one is the nearest thing an agent gets to “I know kung fu”. The gap between an agent that has the tools and an agent that runs the capture loop is that folder.
15.8 Evolve
The last surface is the sweep, and it’s a linter for what the agent knows. crystalline evolve from a terminal, evolve_engrams from an agent and the maintenance page in Fluid all show the same ranked queue of temporal debt, structural gaps, redundancy and meaning. Each finding names the engram, the evidence and the one action that clears it, marked mechanical or judgment so the agent knows whether to act or to ask. It reads dates, links and graph shape (and meaning only to spot two engrams that say the same thing or, once you switch it on, two lines that may contradict each other). It changes nothing itself; crystalline evolve run hands the mechanical findings to a headless agent on a schedule (Chapter 14). It also surfaces what a person captured directly in Fluid and nobody has reviewed, and an attachment nothing references. Chapter 3 walked the loop it serves and chapter 10 worked a queue end to end.
Say a small press sends you its spring catalogue, forty pages of it. You don’t read it aloud to anyone. On Sunday you open the Tessier-Ashpool engram in Fluid, drag the PDF onto it and add one observation of your own: the paperbacks come out in March, six months after the hardbacks, which is how long the rule makes you wait. You close the tab. A week later you ask the agent for a sweep, and it lists two findings against that engram. One is an unreviewed human capture, which the agent verifies, tags to match the vocabulary and wires into the graph. The other is a fresh attachment whose knowledge hasn’t been extracted yet. The agent reads the PDF over MCP, proposes three titles for to-read/ with the page each came from, and you say yes.
The following Tuesday you’re in a hurry and type crystalline search "the one with the ship's computer that sulks" into a terminal. The to-read engram comes back first, from a question the engram never poses. You open the graph view and see the press one hop away, the paperback rule and the shop that orders from them beside it, and the press’s page still carries the catalogue where you left it. Two doors and a hatch, one room: the browser on Sunday, the tools all week, the terminal on Tuesday, and none of the three had to be told what the others had done.
Eight surfaces, one room, two doors and a hatch: everything on either side of this chapter is one of them, used on purpose.
Crystalline is one binary with two doors and a hatch: agents come in over MCP, people through Fluid and the terminal through the CLI, and behind all three is one daemon over one set of plain markdown files. The CLI installs harnesses, manages domains, users and the routing prompt, and mirrors every tool for scripting; the MCP surface is, on a default instance, twenty-four tools that let an agent search, read, write, edit, walk the graph, check the vocabulary and run the sweep. Search blends full text with semantic similarity and tilts for salience and against retired status; the graph turns relations into backlinks and neighbourhoods; the temporal fields make absence mean unbounded. Skills teach a harness when to use all of that, and evolve is the read-only linter that keeps it true.