# Grounding simulations and coaches in a knowledge base

> Attach knowledge bases and documents to a simulation or coach, choose whether sources are cited, and control how voice sessions use them.

- Plans: Core, Team, Enterprise
- Canonical: https://docs.devlin.ai/knowledge/ground-simulations-and-coaches-in-knowledge

Grounding gives a simulation's character or a coach your own documents to draw on. You attach knowledge bases or single documents in the editor, then choose whether the AI names its sources. This page covers attaching knowledge, the citation setting for simulations and for coaches (they work differently), how the material reaches the AI, and what changes in voice sessions.

## Before you start
- Knowledge is available on these plans: Core, Team, Enterprise. On other plans the **Knowledge** section of the editor shows an upgrade prompt instead of the controls described here.
- The documents you attach come from your workspace's library. To upload documents and organize them into knowledge bases, see [Knowledge bases](https://docs.devlin.ai/knowledge/knowledge-bases). You can also upload from inside the editor, as described in the steps.
- Any signed-in member of the workspace can attach knowledge and change the settings on this page. There is no owner or admin requirement.
- The simulation or coach must already exist. See [Create a simulation](https://docs.devlin.ai/simulations/create-a-simulation).

## Steps
To attach knowledge to a simulation or a coach:

1. Open the simulation or the coach in the editor. In the **Design** stage, select **Knowledge**.
2. Check a knowledge base to attach all of its documents. Documents that are added to that knowledge base later are attached too.
3. To attach only some documents, expand a knowledge base, or expand **Unfiled documents**, and check the documents you want. A document that is already attached through a checked knowledge base appears checked and cannot be unchecked on its own.
4. To add a new document, upload it in the same section. A document you upload here is attached to this simulation or coach automatically.
5. Set **Show source citations**. It is off by default for both simulations and coaches. What it does is different for each, and is described under "What the citation setting does" below.
6. If voice is turned on for the simulation or coach, set **Search knowledge during voice sessions**. See "Voice sessions" below.

There is no save button in this section. Each change to the attached knowledge and each switch saves as you make it. If a switch flips back by itself, the change was not saved. If the attached knowledge cannot be saved, the section shows "Couldn't save your knowledge selection. Please try again."

## Result
The character or coach uses the attached documents from the next learner message on, including on a simulation or coach that is already published. You do not need to publish again.

Learners never see the documents themselves. What they can see depends on the citation setting.

## What the citation setting does
The setting is stored as `kb_grounding_mode`, which has three values: `persona`, `ground` and `cite`.

For a simulation, **Show source citations** switches between `persona` (off, the default) and `cite` (on):

- Off (`persona`): the documents are private background for the character. The character is told to keep its world consistent with them, to stay in character, and never to cite, quote or mention the material or a knowledge base. It still follows its character instructions, including when they tell it to fall short of the standards in the documents (for example a character who is meant to get a procedure wrong).
- On (`cite`): the character is told to ground its replies in the material, to cite the document it drew from, and to say so plainly when the material does not answer the question instead of inventing an answer. In a text conversation, a line that starts with "Sourced from:" can appear under a reply, listing document titles, with a page number where one is known. That line appears only when the attached knowledge is being searched (see the next section) and only under a reply for which new passages were found. When the whole library is included instead, the character can still name a document in its own words, but no "Sourced from:" line appears.

For a coach, **Show source citations** switches between `ground` (off, the default) and `cite` (on):

- Off (`ground`): the coach grounds its answers in the material but is told not to cite it, quote it as a document or mention a knowledge base. If the material does not answer the question, the coach is told to say so and not to invent facts.
- On (`cite`): the coach is told to cite the document it drew from, and the page when the knowledge is being searched. The citation is part of the coach's own reply. A coach conversation does not show a separate "Sourced from:" line.

A coach that an AI tool has set to `persona` shows the switch as off. Turning the switch on and then off again while the **Knowledge** section stays open returns that coach to `persona`. After the editor has reloaded the coach with citations on, turning the switch off sets `ground`. A simulation cannot be saved with `ground`.

## When the whole library is included and when it is searched
How the attached documents reach the AI depends on their total size, measured in tokens (the units of text an AI model reads).

- If every attached document has finished processing successfully and together they are at or under 8,000 tokens, the full text of all of them is included in the prompt for every reply of a text conversation. Nothing is searched. One attached document that failed, is unsupported or is still processing switches the whole set to search, so remove or replace it.
- Otherwise, each learner message is used to search the attached documents, and up to 5 of the most relevant passages are added to that message. In a text conversation, passages added to a recent message are not added again while that message is still part of what the AI reads, and they keep informing later replies. In a long conversation, older messages drop out and a passage can be added again.
- When a search finds nothing relevant and no passages were added earlier, the AI is told that nothing matched, so it answers from its character or coach instructions without inventing reference content.
- If the search itself fails, the reply is still produced, without new passages.
- A coach's opening and debrief turns are not searched, because there is no learner message to search with. They still get the full text when the whole library is included.

A document counts once, even if it is attached directly and also through a knowledge base, or through more than one knowledge base.

## Voice sessions
Voice sessions use a higher size limit and do not search unless a switch allows it.

- If every attached document has finished processing successfully and together they are at or under 32,000 tokens, the full text is included in every voice session. The **Search knowledge during voice sessions** switch makes no difference in this case. One attached document that failed, is unsupported or is still processing counts as being over the limit.
- If the attached documents are over that size, the voice session searches them on each learner turn only when **Search knowledge during voice sessions** is on. When it is off, the voice session runs without the attached knowledge at all.
- The switch is off by default for a simulation and on by default for a coach.
- The switch appears in the **Knowledge** section only when voice is turned on for that simulation or coach.
- The citation setting applies to voice in the same way as to text, but nothing is shown on screen: there is no "Sourced from:" line in a voice session.

The attached knowledge and the citation setting are shared between text and voice. Only the size limit and the search switch differ.

## Credits
Attached knowledge adds text to what the AI reads, so grounded replies use more credits than ungrounded ones.

- When the knowledge is searched in a text conversation, the passages added to one reply cost up to about 12 extra credits, and usually less, because replies that add no new passages add nothing.
- In a voice session, the AI's usage is charged in addition to the per-minute voice rate. Searching during voice adds passages to that usage on each turn and adds a short delay before the reply, which is why it is off by default for simulations.

See [Credits, usage and low-credit alerts](https://docs.devlin.ai/plans-and-billing/credits-and-usage).

## If the workspace moves to a plan without knowledge
The attached knowledge bases and documents stay attached, but they are ignored: text and voice conversations run without them. After 30 days on a plan outside Core, Team, Enterprise, the documents and knowledge bases are permanently deleted, and the attachments with them. See [Knowledge bases](https://docs.devlin.ai/knowledge/knowledge-bases).

## AI tools over MCP
An AI tool connected through the [MCP server](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors) can change the citation setting with `update_simulation` (`persona` or `cite`) and `update_coach` (`persona`, `ground` or `cite`), and can turn voice search on or off for a simulation with `update_simulation`. It cannot change voice search for a coach, and it cannot change which knowledge bases or documents are attached to an existing simulation or coach. Do those in the editor.

## Reference documents for scoring are separate
A simulation's **Evaluation** section has its own document list under **Reference materials**, headed **Documents for the AI evaluator**. Those documents are never read by the character. They are used for scoring, when the switch in that section is on, and for drafting criteria. The documents in the **Knowledge** section are not read when scoring. See [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring). An evaluator has the same kind of list for its own scoring. See [Evaluators](https://docs.devlin.ai/evaluators/evaluators-scoring-submitted-work).

## Related
- [Knowledge bases](https://docs.devlin.ai/knowledge/knowledge-bases)
- [Source materials](https://docs.devlin.ai/knowledge/source-materials)
- [Audience profiles](https://docs.devlin.ai/knowledge/brain-audience-profiles)
- [Evaluation and scoring](https://docs.devlin.ai/simulations/evaluation-and-scoring)
- [Credits, usage and low-credit alerts](https://docs.devlin.ai/plans-and-billing/credits-and-usage)
- [MCP server and AI tool connectors](https://docs.devlin.ai/integrations/mcp-server-and-ai-tool-connectors)