# Overview (/docs/agents/knowledge-base/overview)
> For the complete documentation index, see [llms.txt](https://docs.tandemcx.ai/llms.txt). Any page on this site can be fetched as Markdown by appending `.md` to its URL.
A knowledge base is a named set of documents your agent can search while it's on a
call. Attach one to an agent and it can answer from your own content — policies,
product details, hours, fees — instead of only what fits in its prompt.
Knowledge bases live under **Automations → Agents → Knowledge Base**, separate from any single
agent. You build one once and attach it to as many agents as you like, and editing
its content updates every agent using it. A knowledge base belongs to your
organization, and only your organization's agents can search it.
## How the agent uses it
When a knowledge base is attached, the agent gains a search tool and decides for
itself when to reach for it — typically when a caller asks something its prompt
doesn't cover. It searches, reads the passages that come back, and answers in its
own words rather than reciting the document.
Two things follow from that:
- **Matching is on meaning, not exact wording.** A caller asking "how late are you
open?" can match a document that only says "business hours." You don't have to
anticipate every phrasing.
- **New content isn't searchable instantly.** Indexing runs in the background, so
a document reads **Pending** for a short while before it becomes **Indexed**.
The agent also decides _not_ to search, and won't read a weak match aloud just
because one exists. If nothing relevant comes back, it falls back to its prompt or
tells the caller it doesn't have that information.
## Create a knowledge base
### Open the Knowledge Base page
Select **Automations → Agents → Knowledge Base** in the left navigation. This lists every
knowledge base in your organization.
### Create it
Click **Create Knowledge Base**, then give it a **Name** and, optionally, a
**Description**.
Name it after the subject rather than the agent. "Billing Policies" still makes sense
once a second agent needs the same content; "Agent 2 KB" does not.
### Open it
Select the new knowledge base from the list. This is where you add and manage its
content.
To rename it or change its description later, click the pencil icon beside its name at the
top of the page, edit **Name** or **Description** in the panel that opens, and click **Save**.
## Add content
A new knowledge base is empty. To fill it, click **Add Source** at the top of the knowledge
base's page and choose **Upload Files**, **Write an FAQ**, or **Crawl a Website**.
### Upload files
Choose **Upload Files**, then drag files onto the drop area or click to browse. Tandem
accepts **`.pdf`, `.docx`, `.txt`, and `.md`** files up to **20 MB** each. You can add
several at once; click **Upload** and they're sent one after another. A file with an
unsupported format or over the size limit is refused with a message naming it, and a file
that fails to upload stays in the dialog so you can try again.
The filename becomes the document's title, so a descriptive name is worth the few
seconds — `refund-policy-2026.pdf` reads better in the list than `scan001.pdf`.
A scanned PDF is an image of text, not text. If the file has no text layer there is nothing to
extract, and the agent will never find anything in it. Run it through OCR (optical character
recognition) to add a text layer, or retype the key facts as an FAQ.
### Write an FAQ
For facts that don't live in a file (a cutoff time, a fee, a one-line policy), choose
**Write an FAQ**. Enter a **Title** (the question, as a caller would ask it) and an
**Answer**, then click **Add FAQ**.
Typed FAQs are often the highest-value content in a knowledge base. They're short,
unambiguous, and already phrased the way callers speak, which is exactly what
retrieval matches best.
### Crawl a website
Choose **Crawl a Website**, enter a **Starting URL** beginning with `http://` or `https://`,
and click **Start Crawl**. Tandem crawls pages at or below that URL, following the site's
robots.txt, up to **100 pages** and **3 links deep** by default. To change either limit,
open **Advanced** and set **Max pages** (1–500) or **Max depth** (1–5). The dialog states
the limits that will apply before you start.
The site appears in the list as a **Website**, named by its path with the host underneath,
and a status of **Crawling**, then **Ready**, **Partial**, or **Failed**. Hover or focus a
**Failed** badge to see why and what to do next. Click its row, or **View Pages** on it, to open a panel with its
limits and the pages it indexed. Click **Re-crawl** on the row to pick up changes to the site.
## Find a source
Everything in the knowledge base (files, FAQs, and websites) is one list, newest change first,
with a **Type** column saying which each row is. Type in the search box to match by name, or
click **Filters** and pick one or more types. A long list is split into pages of 20.
### Edit a typed FAQ
A typed FAQ can be changed in place. Click the FAQ's row, or the pencil icon on it. A panel
opens beside the page with the current **Title** and **Answer**;
change either and click **Save**. The FAQ shows **Pending** while it re-indexes, then
**Indexed**, and the agent answers from the new text on its next call.
Only typed FAQs have the pencil. Replace a file by uploading the new version and deleting
the old one, and refresh a web source with **Re-crawl**.
### Let Tandem suggest the FAQs
Tandem also collects the questions people asked that this knowledge base couldn't answer, and
recommends them as FAQs to write. Those recommendations live on the
[Coaching](/docs/agents/coaching) page, not here, because they cover every knowledge base at
once.
## Attach it to an agent
A knowledge base does nothing until an agent points at it.
### Open the agent's Knowledge card
Go to **Automations → Agents**, open the agent, and step to **Conversation** in the editor's
stepper. The **Knowledge** card is there.
### Select the knowledge base
Choose it from the **Knowledge base** dropdown. Each agent uses one knowledge base
at a time; choose **None** to detach it. If your organization has no knowledge bases
yet, the card shows a message with a link to the Knowledge Base page instead of a
dropdown.
### Save the agent
Click **Save Configuration**. The agent searches the attached knowledge base on its next call. On
an agent that is on [versioning](/docs/agents/voice-agents/versioning), you'll be editing a draft —
the button reads **Save as New Draft** if you started from the published version — and it takes
effect when you publish that draft.
## Retrieval settings
Two fields on the **Knowledge** card control how much each search returns. Both are
optional — leave them empty to use the defaults, which suit most knowledge bases.
**Max results** — how many passages a search returns. Accepts **1–20**, default
**4**. Raise it when a correct answer depends on details spread across several
documents. Lower it when the agent drifts into loosely related material.
**Minimum score** — how closely a passage must match before it counts. Accepts
**0–1**, default **0.4**. Raise it when the agent answers with content that's
on-topic but not on-question. Lower it when you know the answer is in there but the
agent says it can't find one.
Changing the agent's knowledge base resets **Minimum score** to the default, unless the same
save sets a different value. The editor clears the field when you pick another knowledge base,
and shows `Minimum score reset to the new knowledge base's default.` when a save resets it. To
keep the same value on the new knowledge base, set it again after that save.
Change one field at a time and test with a real call. Raising **Max results** while lowering
**Minimum score** floods the agent with weak matches, which reads as vaguer answers rather than
better ones.
## Document status
Every document in the list carries a status:
| Status | Meaning |
| ----------- | ----------------------------------------------------------------- |
| **Pending** | Received but not searchable yet. Indexing runs in the background. |
| **Indexed** | Searchable. The agent can find it. |
| **Failed** | Couldn't be indexed. Hover or focus the badge for the reason. |
The list refreshes itself every few seconds while anything is **Pending** or a website is
**Crawling**, so a row usually flips to **Indexed** or **Ready** without you doing anything.
A **Failed** document has no retry — delete it and add it again. If it fails a
second time, the reason generally points at the file itself (an unreadable PDF, a
document with no extractable text) rather than at something you can configure.
## Limits and defaults
Tandem enforces these; the file limits are enforced on upload, so an oversized or
unsupported file is rejected rather than silently ignored.
| Setting | Value |
| -------------------------- | -------------------------------- |
| Supported file formats | `.pdf`, `.docx`, `.txt`, `.md` |
| Maximum file size | 20 MB per file |
| Knowledge base name | Up to 200 characters, required |
| Knowledge base description | Up to 2,000 characters, optional |
| FAQ title | Up to 300 characters |
| FAQ answer | Up to 100,000 characters |
| Pages per crawl | 1–500, default 100 |
| Crawl depth | 1–5 links, default 3 |
| **Max results** | 1–20, default 4 |
| **Minimum score** | 0–1, default 0.4 |
| Knowledge bases per agent | 1 |
| Agents per knowledge base | No limit |
## Writing content agents can use
Tandem enforces none of this.
- **Answer one question per FAQ.** A single FAQ covering shipping, returns, and
refunds matches all three questions weakly. Three FAQs each match strongly.
- **Use the words callers use.** Title an FAQ "How do I get a refund?" rather than
"Reimbursement Remediation Procedure." Retrieval matches meaning, but it matches
familiar phrasing best — and the agent reads your wording back to the caller.
- **Keep answers self-contained.** The agent may retrieve one passage without its
neighbors, so "as described above" or "see the table on page 4" gives it nothing
to work with. Repeat the fact instead of pointing at it.
- **Spell out abbreviations at least once.** Write "annual percentage rate (APR)"
so both forms can match.
- **Prefer prose to layout.** Dense tables, multi-column PDFs, and slide decks
often extract as jumbled text. If a fact matters, state it in a sentence
somewhere.
- **Say what's true, not what's marketed.** The agent will read a hedge or a
slogan aloud verbatim, which sounds evasive on a call.
- **Include the "we don't do that" answers.** Documenting what you _don't_ offer
stops the agent from improvising an optimistic guess.
## Structuring your knowledge base
- **Split by subject, not by department.** Callers ask about billing, not about
which team owns billing. Group content the way a question arrives.
- **Prefer several focused documents over one large one.** A 200-page handbook
splits its matches across many loosely related passages; ten short documents each
match cleanly.
- **Keep one authoritative answer per fact.** Two documents giving different hours
means the agent may retrieve either. Update in place rather than adding a second
version.
- **Use separate knowledge bases when audiences differ.** Content a sales agent
should read aloud is rarely the same content a support agent needs. Because an
agent attaches exactly one knowledge base, splitting them is how you scope what
each agent can say.
- **Re-upload to replace, don't accumulate.** Delete the superseded document when
a policy changes, so retired policies can't surface on a call.
- **Review after real calls.** Reviewing real calls is still the quickest way to find a
gap, but you no longer have to listen for one yourself. See [Answer a suggested
FAQ](#answer-a-suggested-faq) above.
## Delete a knowledge base or document
Delete a document from the list on the knowledge base's page. It stops being
searchable, and any agent using that knowledge base loses access to it on the next
call.
Deleting a whole knowledge base is **blocked while any agent still has it
attached** — the error names the agents that are holding it, so you can't silently
break a live agent. Detach it on each agent's **Knowledge** card (set the dropdown
to **None**), then delete it.
If some of its documents can't be deleted, the knowledge base is kept and the error says how
many failed, for example `Could not delete 2 of 40 documents; retry to finish removing this
knowledge base.` Delete it again to finish.
## Troubleshooting
**The agent says it doesn't know something that's in the knowledge base.** Check
the document's status is **Indexed** rather than **Pending** or **Failed**. If it's
indexed, the phrasing is the usual culprit: add an FAQ that asks the question the
way the caller did. Failing that, lower **Minimum score** slightly.
**The agent answers with the wrong part of a document.** A loosely related passage
cleared the threshold and outranked the right one. Raise **Minimum score**, or
split the document so each part covers a single subject.
**The agent gives stale information.** For a typed FAQ, edit it (see [Edit a typed
FAQ](#edit-a-typed-faq)) rather than adding a second one. For a file, the old document
is probably still there alongside the new one. Delete the superseded version — both
remain searchable until you do.
**The agent never uses the knowledge base at all.** Confirm a knowledge base is
selected on the agent's **Knowledge** card and that the change was saved. An agent
with **None** selected has no search tool.
**A document keeps failing.** Open the file and confirm it contains selectable
text. Image-only PDFs, empty files, and password-protected documents can't be
indexed.
## Next steps