> For the full page index, fetch https://echonova.ai/llms.txt

# How knowledge works

Knowledge sources belong to the workspace, each agent picks the ones it may use, and retrieval pulls matching passages into the turn.

Knowledge is the material your agent can quote from: files you upload, text you
paste, and web pages you point it at. Sources belong to the workspace, not to a
single agent. Each agent picks which of them it is allowed to use, and
retrieval decides, turn by turn, which passages are worth putting in front of
the model.

## One library, many agents

Every source you add lands in the workspace library. You open it from
**Knowledge base** in the left navigation. A source is always one of two kinds:

| Kind   | What it is                                                                    |
| ------ | ----------------------------------------------------------------------------- |
| `file` | An uploaded document. Pasted text is stored this way too, as a Markdown file. |
| `web`  | A single page or a crawled site.                                              |

Sources can sit loose at the root of the library, or inside a folder. A folder
is a named group inside the workspace; it has a name and nothing else.

Because the library is workspace-wide, the same handbook or price list is
uploaded once and used by every agent that needs it. Deleting a source from the
library removes it from every agent that used it.

## What each agent uses

An agent keeps two lists: the folders it selected and the loose sources it
selected. You edit both on the agent's **Knowledge** tab.

- Selecting a **folder** is a live reference. The agent gets whatever is in that
  folder at the time of the call, so a file added to the folder next week is
  picked up with no change to the agent. The portal says this in the folder row:
  **Live folder: always reflects its current contents.**
- Selecting a **source** works for a loose source. A source that lives inside a
  folder is covered by selecting its folder, and moving a source into a folder
  drops it from every agent's individual picks.

If someone deletes a folder, the agents that selected it are updated rather than
left pointing at nothing.

## What happens at a turn

Retrieval is per agent, and it is off until you turn it on. It has three
settings:

| Setting         | Portal label            | Default | Accepted range                            |
| --------------- | ----------------------- | ------- | ----------------------------------------- |
| `enabled`       | **Enable retrieval**    | `false` | on or off                                 |
| `topK`          | **Top documents**       | `5`     | 1 to 50 in the API, 1 to 20 on the slider |
| `minSimilarity` | **Relevance threshold** | `0.7`   | 0 to 1                                    |

When retrieval is off, the agent ignores every source you selected. The portal
says so on the tab: **Retrieval is off** and **This agent ignores all selected
knowledge, so nothing below is used.**

When retrieval is on, the agent searches the sources it can use on every turn
and keeps the passages that clear **Relevance threshold**, up to
**Top documents** of them. Those passages are what the model answers from.

## Only ready sources count

A source is used only once it shows **Ready**. A document still indexing, or one
that failed, is simply not part of the turn: nothing is queued and nothing
waits.

That is why a selected folder on the agent's **Knowledge** tab reads
**All ready** only when every source inside it is ready, and otherwise shows how
many are still indexing. It is telling you how much of what you selected can be
used right now.

A ready source also carries a chunk count, shown in the **Chunks** column: how
many passages the source was split into. A source that is ready with very few
chunks usually had very little extractable text.

## Get it right

Retrieval competes: only **Top documents** passages reach a turn, so a few
focused sources beat one folder holding everything the workspace has ever
uploaded.

**Recommended**

- A **Returns and refunds** folder on the returns agent, holding the policy and
  the FAQ.
- One folder per job, selected by the agent that does that job.

**Less effective**

- One **Company documents** folder holding contracts, slide decks and the
  handbook, selected by every agent.
- Individually picking forty loose sources so that the right one is "in there
  somewhere".

## When a change takes effect

Adding, removing or replacing an agent's knowledge applies to the next
conversation at once. Changing **Enable retrieval**, **Top documents** or
**Relevance threshold**, and a source turning **Ready**, can take up to a minute
to reach a new conversation. A conversation already running keeps the settings
it started with.

After any change, start a new conversation to test it.

## FAQ

### Why does my agent ignore a document I attached?

Retrieval starts off on a new agent. Turn on **Enable retrieval** on the
**Knowledge** tab, then work through
[the checklist](/docs/agents/knowledge-troubleshooting).

### Does knowledge go into the prompt?

No. The prompt is your **Personality** text. Knowledge is searched during the
conversation and only matching passages reach the model, which is why reference
material costs less here than in the prompt.

### Can one agent's knowledge be private to it?

No. Every source is in the workspace library and visible to the workspace.
Selection is per agent; storage is shared.

### How many sources can one agent select?

There is no limit on the selection. The practical limit is **Top documents**,
since only that many passages reach any one turn.

### Does the agent tell me which source it used?

Not on the knowledge screens. Compare the answer against the sources you
selected, and use the **Chunks** count to check a source has usable text in it.

## Related

- [Add documents to the library](/docs/agents/knowledge-documents): upload a file and watch it index
- [Add text directly](/docs/agents/knowledge-text): paste a policy with no file to prepare
- [Add a web page or crawl a site](/docs/agents/knowledge-website): point the library at a URL
- [Organize knowledge in folders](/docs/agents/knowledge-folders): live folders and what delete does
- [The agent did not use my document](/docs/agents/knowledge-troubleshooting): the five checks, in order