6 Onboarding an agent
On a new colleague’s first morning somebody hands them the floor plan. Payments is on the second floor, the people who know about the bank sit by the window, the runbooks are in the cupboard that sticks. Which door leads where is the whole of day one, and it’s enough, because a person who knows where things are can find out everything else themselves.
That floor plan is what an agent receives at the start of every session with Crystalline. This chapter is about the day it arrives: what the briefing says, how the agent finds its way with it, what it means to hand a colleague a task instead of a question, and the reminder at the end of the day that turns a session into experience. Chapter 5 showed the wiring. This is what the wiring is for.
6.1 The briefing at session start
A session opens, and before the agent has read a word of your request, the session-start hook runs crystalline prompt system and puts its output in front of the model. Here is one a few months in, abridged:
CRYSTALLINE KNOWLEDGE ROUTING
You are being onboarded to the knowledge accumulated in this workspace.
It is served by the crystalline MCP server; these instructions govern
its tools. [...]
- engineering: 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
- clients: Route anything about a customer, a contract or a renewal
here; Check here before preparing for a customer meeting
[...]
Behavior:
- Search before you answer: a question about this project's past
decisions, its people, its systems or a name you do not recognise is
answered from search_engrams first, never from memory or a guess.
- Search before you start: a task begins with search_engrams on its
subject, so what an earlier session learned shapes the work instead
of being rediscovered after the fact.
- Narrow question: search_engrams with domains=[that domain]; broad or
unclear: no domains sweeps them all.
[...]
- Read a MANIFEST with read_engram only when the routing line is not
enough; list_domains with include_routing=true re-fetches the index
mid-session.Read it as the agent reads it. The opening says what this is and whose tools it governs, so an agent with four MCP servers connected knows which search_engrams is meant. Then there’s one line per domain, and every word of those lines was agreed with a person: they’re the ## When to Use bullets of each manifest, joined with semicolons, exactly as the team approved them (Section 4.1). On your own machine that’s every domain registered, since the CLI and a stdio session are the machine owner. On a shared instance the agent connects as an account, and the block lists every domain that account may see: a private domain it’s no member of is absent from the block, from list_domains and from every search, answered as if nobody had registered it (Chapter 19). Then come the behaviour rules, the same on every instance: the first two say when to search (before answering a question about the project’s past, its people or its systems, and before starting a task) and the rest name the exact tool each one reaches for. That’s the floor plan (Figure 6.1). It says where things are, nothing about what’s in them, and the agent goes and looks.
crystalline prompt system prints it.
How it reaches the desk depends on the harness, as chapter 5 said. Claude Code and Codex run the hook on a fresh start, after a /clear and after a compaction, and skip a resumed session; the Copilot CLI’s hook does the same on a fresh start and stays quiet on a resume. Cursor runs its session-start hook, Gemini CLI and Qwen Code run theirs on a fresh start only, and Kiro runs its hook too, with an always-on steering file that tells the agent to fetch the block if it’s missing. Claude Desktop gets the block inside the MCP server’s own instructions; a remote client fetches it with one list_domains call. Either way the agent starts out knowing which drawer holds what and nothing more, the state a good new hire is in at nine on Monday.
The block is built to survive being cut off. A harness in tool-search mode truncates a server’s instructions at roughly two kilobytes, so the MCP rendering keeps under a 1900-byte budget and degrades in fixed steps: every routing line drops to one bullet, then the list collapses to a count line pointing at the re-fetch call.
A remote client gets that count line on arrival whatever the block’s size. The MCP initialize handshake is answered before any request is in hand, so over HTTP there’s nobody to scope the block to and no way to leave a private domain’s name out of it. The handshake carries the behaviour rules, how many domains that aren’t private are registered and the pointer at list_domains, which does know who’s asking and filters.
6.2 How the agent finds its way
A routing line is a targeting aid. The routing skill says so in as many words, and adds what every colleague knows about floor plans: the label on the door isn’t the inventory of the room.
The first decision is whether to look, and the rules settle it: before the agent answers a question about the project’s past or starts a task, it searches. In Claude Code and Codex the prompt hook has usually brought the first few engrams along with your message already. The second decision is scope. A narrow question, one that clearly belongs to one service, team or customer, goes to the domain whose line describes it, in a single search_engrams call with domains set. A broad or unclear question omits domains and sweeps everything, each hit labelled with its domain. The agent doesn’t stop to ask you which it is: a search is cheap and usually settles the ambiguity, and a clarifying question is for after it came back empty.
The third decision is when to widen. A scoped search can return plausible near-misses when the subject belongs to one domain and the question to another: who gets paged about refunds is a people question, not a payments one. When the obvious domain keeps missing after a rephrasing or two, the agent runs one unscoped sweep. Then it reads. A snippet is a short window around a match, and a colleague who answers from a snippet is guessing, so anything that summarizes or quotes an engram goes through read_engram first. A strong hit becomes an anchor for build_context, which pulls in what the engram depends on before the work starts.
The agent is given the doors and, with each prompt, at most three engrams that may fit it; what’s behind every other door is fetched when a task calls for it. A colleague with a floor plan beats one carrying the building around in a wheelbarrow.
6.3 Assign, do not copy
You wouldn’t message a colleague a question, copy their answer into your editor and do the work yourself. You’d assign them the task, because doing it is how they get better at it. An agent with Crystalline’s tools is in the same position, and treating it as a lookup service wastes most of what you set up.
Give it the task. “Add a metric to the retry queue” lands better than “what do you know about the retry queue”, because the first sentence sends the agent through the whole loop on its own: it routes to engineering, recalls the gotcha and the bank rule, reads the engram in full, walks one hop to the deploy runbook, writes the change in Python and tells you what it found on the way. The floor plan only pays off when somebody walks the corridors, and the somebody should be the agent.
It follows the processes a person would, since it can be wrong in the same ways: review for its changes, a yes for its captures. A colleague you never delegate to never learns your work, and neither does an agent.
Here’s your first week with the agent, session by session. Monday is the afternoon from chapter 5: the briefing names books, and the agent knows your rules before you’ve typed one. On Tuesday you give it a real task (something for Saturday’s flight) and explain nothing. The agent routes to books, recalls the series rule and the translations, finds the note about the Tessier-Ashpool paperbacks you captured on Monday and comes back with three (a Doctorow you missed, the next Dungeon Crawler Carl and the Deep Space Nine novel that follows the one you finished last month), each with the shop that has it. On Wednesday it’s wrong for the first time: it recommends the new Vickers in hardback, and you tell it you don’t buy hardbacks, because you read outdoors and a hardback doesn’t survive the backpack. It asks whether to capture that in books as a [convention]. You say yes, and add the exception: a hardback is for collecting, bought after the ebook, when a book turns out to deserve a place on the shelf.
Thursday is a long session sorting the pile by the bed, and when it ends the reminder fires once: the agent proposes two captures (that you abandon anything with a map on page one, and a shelf engram per Star Trek series, classic, Next Generation, Deep Space Nine and the Destiny trilogy, saying which volumes you own and which is next) and raises the salience of the translations engram. On Friday you ask it to order the Vickers, and it answers, before you’ve said which edition, that the hardback is out by your own rule until you’ve read it, and the ebook is out today. On the first session it knew where the drawers were. On the fifth it told you something about yourself, unasked, that you’d taught it two days before. That’s the moment a stranger stops being one.
6.4 The reminder at the end of the day
A first week only counts if what was learned survives the weekend, and that’s the beat agents skip. Left alone, a model finishes the task and stops, and the gotcha it met at minute forty goes with it. So crystalline install wires a reminder, the closest thing the loop has to a habit.
It’s a Stop hook. On the first stop after a session has gained real substance it asks the agent to review the conversation for durable learnings: facts, decisions, patterns, gotchas, corrections from you. It also names what doesn’t count: what the session did, temporary paths and outputs, a one-off bug’s error text, steps that won’t recur and anything any model already knows. For each one not yet captured the agent proposes an engram in the fitting domain and waits for a yes; a correction that makes an existing engram wrong becomes a proposed edit or supersession rather than a second engram. If a recalled engram proved to be the key to the task, the agent raises its salience. If nothing qualifies or everything is captured, it finishes normally. The reminder fires at most once per session, and costs about a hundred and twenty tokens. When maintenance is due, a paragraph rides along asking for a sweep; when a team domain holds unshared work, another asks the agent to propose sharing, still a proposal, because sharing puts somebody’s work in front of reviewers.
An agent that reaches a shared instance only over MCP has no hooks. Crystalline’s one reliable channel to a model mid-session is a tool result, so the reminder rides there: a write, edit, move, split or delete comes back with a single clearly prefixed line appended when something is due, never a search or a read, so recalled knowledge is never mixed with guidance. Sharing and maintenance travel this way. Capture doesn’t, because it’s a reflection at the end of a conversation and the server can’t tell when a conversation ends; the routing block keeps teaching capture as standing practice instead. Each person is nudged on their own cadence, a few hours apart:
---
[crystalline] 3 changes in the team domain engineering are not yet
shared. If that work is done, propose sharing it with share_changes so
the team has it and the team's archive stays current - and wait for a
yes.The floor plan gets a new hire through the door. What they carry back at the end of the day is what makes them worth having on Tuesday.
Every session opens with a routing block: one line per domain the session may see (the manifests’ When to Use bullets) and the behaviour rules naming the exact tools. Each harness delivers it the way chapter 5 wired it. The agent searches before it answers or starts a task, scopes a narrow question to one domain, sweeps for a broad one, widens when scoped hits keep missing and reads before it answers. Hand it tasks rather than questions, and let the once-per-session reminder close the day: propose captures, wait for a yes.