Questions and answers

These are the questions people ask in the first week, and a few that come up in the second, once somebody is onboarding agents for other people. Each answer points at the chapter that goes deeper.

Why not just a folder of markdown files?

It’s one. Every engram is a markdown file in a folder you chose, readable in any editor, diffable in any repository and backed up with whatever you already use. What a folder can’t do on its own is what Crystalline adds on top: routing, so an agent knows which domain owns a task without reading every file; search that blends the exact phrase with the meaning; a graph of relations and backlinks; and a temporal model, so a fact that stopped being true in March still carries its dates and is no longer mistaken for the present. Chapter 1 walks the ladder from one file of instructions to real indexes.

Why not a vector database or a retrieval pipeline?

Retrieval is the easy half. A vector index finds text that resembles a question. It doesn’t know which domain owns the task, that a fact was superseded, 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 no pipeline to operate. A pipeline also swallows whatever it’s fed. Here knowledge is taught, and in a team it’s reviewed by default before it reaches anyone else’s agent, so what comes back is meant to make sense rather than merely to resemble the question. Chapters 9 and 15 cover the ranking, and chapter 17 the review.

Where does the name come from?

It comes from psychology. Crystallized intelligence is what learning deposits in a person; fluid intelligence is the reasoning applied to a problem never seen before. A model arrives with fluid intelligence in abundance and none of your crystallized kind, so every session starts as a brilliant stranger. Crystalline is the crystallized half, the store of what an agent has learned. Fluid, the web UI, is named for the fluid minds, yours and the model’s, that meet there on reflections, with a side door into the engrams. An engram is neuroscience’s word for the trace an experience leaves. Chapter 2 is the whole story.

Is Crystalline a hosted service?

No. It’s a binary that runs on a machine of yours, your laptop by default or a server your team operates, and the knowledge is a folder on that machine’s disk. Nothing runs on anyone else’s servers. GitHub, where a team uses it, holds a reviewed copy of a domain’s files, the way it holds code; it serves nothing and sees no index. Chapter 1 has the two shapes and chapter 16 the shared one.

Does Crystalline phone home?

No. There’s no telemetry and no update check, and Crystalline never sends your knowledge to a language model itself: your harness gets what Crystalline answers and passes it to the model provider you chose there, the engrams the prompt hook brings along included. One connection happens by default, the download of the embedding model from Hugging Face on the first start, and it sends no engram data. Point Crystalline at a mirror or at a model directory fetched ahead of time and it never talks to Hugging Face at all. Every other connection exists only once you turn it on: the contradiction check’s model (from Hugging Face again), GitHub for a team domain, your single sign-on provider, a remote embedding service (which does get the text of your engrams) and a PostgreSQL server holding a shared index (which holds that text too). So is a Crystalline server you connect to with crystalline connect or CRYSTALLINE_REMOTE_URL: by design your laptop’s Crystalline then works as a tunnel to it. A call for one of its domains goes there (a write carries the engram’s text), and a search over all domains sends its text, your prompt too when the prompt hook searches. You chose that server, so its knowledge is handled and stored there, apart from a few small cached answers, and your own domains’ engrams never go to it. docs/security.md lists each connection with what it sends; chapter 5 has the model download and chapter 16 the connected server.

Do I have to run a server?

No. The first agent that connects starts a background daemon on your machine, and every later agent, terminal and browser tab attaches to it. It stops only when told to, with crystalline ctl shutdown, Ctrl-C in a foreground run or the signal a container sends. It keeps running after the last agent disconnects, so the index stays warm for the next session. The one exception is the daemon of the Desktop-only bundle on a Mac, which exits five seconds after its last client. If a crash ever leaves a stale lock or socket behind, crystalline doctor --fix clears it and a daemon that’s alive but no longer answering is replaced by the next client that connects.

How do I start the daemon myself?

crystalline serve runs it in the foreground, where you can watch it work, and crystalline serve --daemon puts it in the background. It’s the one process the machine shares: it serves Fluid at http://localhost:7411, answers MCP over HTTP on that same port and takes the agents and crystalline commands on the machine itself over a local socket. Starting it yourself is worth it when you want the browser open before any agent has connected. crystalline ctl status tells you whether one is already running, with its pid, its uptime and the sessions attached. On a server nobody types serve at all, because the systemd unit or the container starts the daemon at boot. Chapter 5 has the laptop and chapter 16 the server.

Do I need a terminal at all?

You need one only for the local install and the occasional maintenance command. Claude Desktop users can do without one: on Windows they install the MSI and then an extension from the releases page, and on a Mac where Desktop is all they use, the Desktop-only bundle is the most elegant way in, one extension with Crystalline inside. The agent creates its first domain itself, and Fluid, in the browser, is where a person works with the agent and opens its engrams when something needs correcting. Chapter 5 has both paths.

Is the MCP endpoint over HTTP protected?

On a laptop it listens on loopback, 127.0.0.1:7411, and any process on that machine can reach it, which is the right trade for one person. crystalline config set service.http false turns the endpoint off. The daemon also checks the request’s Host header against a loopback allow-list to block DNS rebinding, so a hostname or a proxy name has to be added first. Fluid and its API on the same port have accounts of their own, and nothing there is readable without a session.

On a shared instance turn on auth.mcp, and from then on every agent that connects over HTTP identifies itself with a token that belongs to one person, with no anonymous tier beside it. Chapter 16 sets it up and chapter 19 says what the token means.

How does a hosted client connect, with nowhere to paste a token?

It signs you in instead. On a shared instance whose agents identify themselves (auth.mcp on), a chat website or the app on your phone connects by sending you to sign in through the instance, with the login the instance already has. From then on it holds a credential the same gate checks on every request, the way it checks a token. A harness that can send a header keeps working with a pasted token. Chapter 16 has the setup and chapter 19 the two credentials at one gate.

Where does my knowledge actually live?

In your domain folders, as plain markdown. By default those folders sit under ~/Documents/Crystalline, one per domain, which is where an agent creates a domain when nobody names a path. A folder you registered yourself lives where you put it, like chapter 5’s ~/knowledge/engineering, and the domains_root setting moves the default. Everything Crystalline derives from it is disposable: the search index lives in the state directory and crystalline reindex --full rebuilds it from the files at any time. The config file, the index and the embedding model live in the platform’s config, state and cache directories, ~/.config/crystalline, ~/.local/state/crystalline and ~/.cache/crystalline on Linux and macOS.

Is my knowledge locked in?

No. An engram extends Google’s Open Knowledge Format, OKF 0.2: markdown with YAML frontmatter, readable by any OKF tooling and by any text editor. Frontmatter keys Crystalline doesn’t know are preserved through every write, and an index.md at each domain’s root lets a folder navigate itself with nothing running. crystalline import brings an existing tree of frontmatter markdown in as a pure file transformation. If you stopped using Crystalline tomorrow, the folder would still be a readable knowledge base. Chapter 4 has the format.

What happens to wrong knowledge?

It depends on how it was wrong. A fact that was never quite true, a cutoff measured from the wrong event, is corrected where it stands. A fact that was true and stopped being is superseded: the replacement is written as its own engram with supersedes pointing back, the old one gets status: superseded and a real valid_to, and any lesson worth keeping moves forward. The past stays in every search, dated and gently below the present. The sweep finds the retirements nobody finished, the links that dangle and the tags spelled two ways, and hands each to the agent as a mechanical fix or to you as a judgment. Deleting is for mistakes, never for history. Chapter 3 has the lifecycle and chapter 10 the sweep.

What is GitHub, and what does Crystalline use it for?

GitHub is a website where teams keep files and every change ever made to them, above all source code. Its habit worth borrowing is the review: a change to something shared is proposed first, a colleague who knows the subject reads it, and only then does it land for everyone. Crystalline uses GitHub for exactly that, with knowledge in place of code. A team domain’s markdown lives in a GitHub repository. By default a change goes out as a proposal (a pull request, in GitHub’s own words) and reaches everyone’s agent once somebody has merged it. A small team can switch a domain to sharing straight onto the branch instead. You don’t need to learn GitHub’s tools to take part: a one-time sign-in through a code in the browser connects your machine. After that the agent, Fluid or the command line does the talking. Chapter 17 walks through it. A team that doesn’t use GitHub loses nothing else in this book; only sharing a domain between machines needs it.

Do I need git to share knowledge with a team?

No. A team domain talks to GitHub directly over its API: each person connects once with a browser code, and proposals open as pull requests that a person reviews and merges there, unless the domain shares straight onto the branch. There’s no local clone and no SSH key, and nobody types git. Chapter 17 has the detail.

Can the agent see my private domain?

Only if its user can. On a shared instance an agent authenticates with a token that belongs to one person and acts as that person for the length of the session: it sees what they see, writes where they may write and captures under their name. A private domain shows to its owner, to the instance’s admins and to the members the owner invited, and to everyone else it reads as absent, on every surface. On a team server with its own GitHub App, a team domain follows its repository instead, and the person’s role on GitHub decides who reads and writes it. There’s no tool for changing a membership, so an agent cannot talk itself in. An agent can do two things to a domain itself. It can unregister it with remove_domain, which is open to an instance admin or a private domain’s owner and refused outright on the open tier. And it can change the domain’s policies with configure, under the same owner-or-admin rule, though the open tier may do that wherever it may write. On a server with a GitHub App the open tier acts on the team domains as the account github.agent_identity names, private ones included, so turn auth.mcp on there. With auth.mcp on, add_domain, a configure that changes the instance and a provision that decides need the admin role behind the agent as well. Before you rely on it, know the limits: admins see every domain, and a private domain protects from the instance’s other users, never from whoever operates the machine. Chapters 16 and 19 have the rest.

What does the onboarding cost in tokens?

It costs little, and the same on the tenth session as on the thousandth. The routing block is one line per domain and a handful of rules. The reminder at the end of a session costs about a hundred and twenty tokens and fires once. Recall loads only the engrams that matter, routed by domain and narrowed by the indexes, instead of a folder read whole every session. Chapter 6 has the briefing and chapter 9 the recall.

AGENTS.md or CLAUDE.md?

Use the name your harnesses read. An instruction file is a project’s standing orders: people write it, and the harness reads all of it at the start of every session. Crystalline holds what the agent learned and brings back the piece a task needs, so the two sit side by side and Crystalline never writes into either. As for the name, AGENTS.md is the one most harnesses share: Codex, the Copilot CLI, Cursor, Kiro and Qwen Code read it, and Gemini CLI does once its settings name it. Claude Code reads it when the project has no CLAUDE.md of its own (a CLAUDE.local.md counts too), and its /config can make it read both. So keep one AGENTS.md, and if some lines are for Claude alone, put them in a CLAUDE.md that pulls in the rest with @AGENTS.md. Chapter 5 lists the files the install does write.

What should I teach first?

Whatever you’d tell a new hire in the first week, and the test is that sentence. Think of the rule behind the strange number, the nickname, the word the wiki gets wrong, the day nobody deploys. Teach where information lives rather than the information itself: which repository holds what, how access is granted, the architecture, so the agent can reach the territory with the tools its harness already gives it. Chapter 7 has the list, and chapter 8 says what to do when the first week meets the wiki.

One big domain or many small ones?

For search it makes no difference. An agent searches every domain its instance has registered unless it narrows the search to a few, so splitting doesn’t make the results better and merging doesn’t make them worse. Long material doesn’t crowd anyone out either: a meeting transcript is kept as a source engram beside a short summary, and the summary is what recall reads. What decides the split is who looks after the knowledge. Chapter 8 has the summary and its source, and chapter 9 the search.

When does a new domain earn its place?

When the knowledge needs a different owner. Ask who should approve a change to it. When that’s somebody other than the people who own the domain it would go into, start a new one. It stays where it is when:

• The knowledge is about a product or a system that already has a domain. Its architecture, the decisions that affect other teams and how it works belong there, even when your team wrote them.
• Your team is the only one working on the product. Then the product domain’s owners and your team are the same people, so everything goes into the product domain: the team’s own notes, open questions, transcripts and reflections. A second domain only gives everyone one more place to look.

Several teams work on one product. How many domains is that?

Usually one for the product and one per team. The product domain is shared by every team, reviewed and slow to change: it holds the architecture, the decisions across teams and how the product behaves. A team domain belongs to its team and holds the fast-moving rest (grooming notes, open questions, drafts, transcripts, how the team is organised), and it links into the product domain instead of copying from it. A team that writes a lot sets the review rules that fit its pace in its own domain and leaves the shared domain’s review as it is. If you started as the only team and a second one joins, keep the product domain for what both teams share. Move your own topics into a new team domain once the other team shouldn’t be the one approving changes to them. Chapter 17 has the review and chapter 25 the domain settings.

How do domains point at each other?

With a crystalline://<domain>/<permalink> link. It resolves across domains, so a team engram can point at the decision it relies on in the product domain. When something a team wrote turns out to matter to everyone, move it into the product domain. The links to it follow, and in a team domain the move goes out as a proposal like any other change. Chapter 18 says why the domain’s name in that link has to stay stable, and chapter 25 has the move.

Is there anything hidden in Crystalline?

There is. The crystal in Fluid’s top corner takes you home, like every logo does. Click it the way Dorothy clicks her heels, and it takes you somewhere else.