> ## Documentation Index
> Fetch the complete documentation index at: https://help.ciarem.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Knowledge bases: what your agent knows
> Create a knowledge base, fill it with files, free text, or websites, and learn what belongs in it, what does not, and the mistakes that make an agent answer badly.
The **Knowledge base** holds what your agents know: your business information, organized so the AI can consult it when responding. Open it from the Control center's knowledge card, create a knowledge base with **Create knowledge base**, and fill it with your content: files, free text, or websites. For a website, Ciarem finds the pages of the site, lets you pick which ones to index, and checks them for changes every week. See [Website sources](/ai-agent/website-sources).
The agent answers from what you have given it. If a customer asks something outside its knowledge, transfer rules catch it rather than letting the agent invent an answer. The most common cause of wrong answers is a price or policy that changed in real life but not in the knowledge base, so keep it current.
## How the agent reads it
Most knowledge-base problems come from expecting the agent to read a document the way a person would. It does not:
Every file, free text, and web page is split into fragments of a few paragraphs each, cut at paragraph breaks. The source card shows how many it produced (**Fragments: 12**). A source that failed with *No readable text was found* produced none.
When a customer writes, the agent searches the fragments by meaning and by keywords, and reads only the handful that best match that message, never the whole document. A sentence that does not resemble anything a customer would ask is, in practice, never read.
The agent uses the fragments as facts about your business and writes its own reply in your voice. It never quotes or names the document, and it is not looking for orders in it. What it finds shapes the answer, not how the agent behaves.
**This is why instructions in the knowledge base do nothing.** "Always ask for the customer's phone number before quoting" is only found when someone writes about phone numbers, and even then it is read as a fact, not followed as a rule. Behavior lives in [Basic configuration](/ai-agent/basic-configuration), each agent's own settings, and [transfer rules](/ai-agent/human-handoff-and-escalation). The knowledge base is for what the agent needs to *know*, not what it should *do*. The reverse is also true: a transfer rule or a tone setting cannot teach the agent a price or a policy. Every assistant that answers from documents keeps *knowledge* (reference material) apart from *instructions* (rules, tone, workflow).
## What goes where
| You want the agent to… | Put it in |
| ----------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| Explain policies, hours, how a service works, what to expect, the answers to frequent questions | **The knowledge base** |
| Speak in a certain tone or language, introduce the business a certain way | [Basic configuration](/ai-agent/basic-configuration): voice and tone, primary language, business context |
| Open every conversation with a welcome | [The first message](/ai-agent/first-message) |
| Ask for the customer's name, phone, city, budget… | The qualifier agent's **Questions** in [Agent team](/ai-agent/agent-team) |
| Handle a topic with a specific agent, or stay out of a topic | **When should this agent step in**, on each agent |
| Quote prices, check stock, list products or plans | A [catalog](/using-ciarem/catalogs): the agent looks up the exact record and reads its fields as they are |
| Offer and book appointments | A [connected calendar](/ai-agent/booking-and-calendars) |
| Hand the conversation to a person when something happens | [Transfer rules](/ai-agent/human-handoff-and-escalation) |
| Nudge a customer who went quiet | [Follow-ups](/ai-agent/follow-ups) |
| Stop giving one specific wrong answer | A correction in [the playground](/ai-agent/playground) or the [Evaluation center](/ai-agent/evaluation-center) |
## Common mistakes
Every one of these comes from real knowledge bases. Open each for the fix.
The most common one by far. The document reads like a briefing for the agent ("always", "never", "you must") and none of it happens, because the agent only sees a fragment when a customer's message resembles it, and reads it as a fact when it does.
| ❌ In the knowledge base | ✅ Instead |
| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Agent: never give discounts. If the customer asks for a discount, always transfer to sales." | A transfer rule: *the customer asks for a discount, a coupon, or negotiates the price*. In the knowledge base, the fact: "Prices are fixed and the same for everyone. The only discount is 10% on annual plans paid upfront." |
| "Ask for the customer's name and city before answering anything." | The qualifier agent's **Questions**: *What is your name?* (saved to name) and *Which city are you in?* (saved to city, asked only if there is no information). |
| "Always answer in a friendly, short way and use emojis." | Basic configuration: **Voice and tone: Casual**, **Response length: Brief**, plus an example sentence written the way you talk. |
A quick test: if a sentence starts with "the agent", "you should", "always", or "never", it is a setting, not knowledge.
"Our basic plan costs \$49" works until the price changes and the old sentence survives in three documents. Prices, plans, stock, and anything the agent should look up *exactly* belong in a [catalog](/using-ciarem/catalogs), where each record has its own fields and the agent reads them as they are. Keep the knowledge base for what surrounds the price: what is included, how billing works, whether taxes apply.
| ❌ In the knowledge base | ✅ Instead |
| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Cleaning: \$50. Whitening: \$200 (promo \$150 this month). Braces from \$1,200." | A *Services* catalog with one record per service and a price field. In the knowledge base: "Every price includes the initial consultation. Braces are paid in monthly installments; the exact plan is agreed at the first visit." |
An old PDF says 24 hours' notice to cancel; the website says 48. The agent may read either fragment, so customers get different answers on different days. When something changes, update or delete the old source. Do not add a new one on top of it.
| ❌ In the knowledge base | ✅ Instead |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `policies-2023.pdf` (24 hours) **and** `policies-2025.pdf` (48 hours), both in the base. | One current *Cancellation policy* source; the 2023 file deleted. If the policy lives on your website, edit the website. The weekly recrawl picks it up. |
"The leading clinic in the city, with world-class service and a passion for smiles" gives the agent nothing to answer with. Neither does an FAQ entry that just says "Yes." The agent cannot fill in what you left out. Customers ask concrete things: how long, how much, what do I bring, what happens if. Write the answer you would give on the phone.
| ❌ In the knowledge base | ✅ Instead |
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Our whitening treatment uses cutting-edge technology for spectacular results." | "Whitening takes one 60-minute session. Results last 1 to 2 years. It is not recommended during pregnancy or with untreated cavities; we check this at the consultation." |
| "Do you deliver? Yes." | "Yes, we deliver in Bogotá and Chía. Orders placed before 2 p.m. arrive the same day; later orders arrive the next business day." |
"20% off this week", "closed tomorrow for the holiday", "see the table above": the agent reads that fragment months later, on its own, with no idea what "this week" or "above" referred to. Use dates, and make every paragraph stand on its own.
| ❌ In the knowledge base | ✅ Instead |
| -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| "This week only: 20% off all packages. We will be closed tomorrow." | "Promotion: 20% off all packages from 1 to 7 March 2026. Closed on 8 March 2026 (public holiday)." Remove it afterwards. |
| "As mentioned above, the same conditions apply to the premium plan." | "The premium plan has the same 48-hour cancellation window as the basic plan." |
Websites are full of "get in touch for pricing" and "ask our team about availability". Indexed as they are, they teach the agent to send the customer somewhere else, often to you, in the same chat. Replace each one with the actual answer, or with a step the agent can take (a transfer, a link, a booking). The same goes for text that only points to another page ("see our FAQ page"): the agent reads the sentence, not the page it points to.
| ❌ In the knowledge base | ✅ Instead |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| "For pricing and availability, contact our team." | "Cleaning costs \$50 and takes 45 minutes. To book, tell us the day and time you prefer and we confirm it here." |
Staff procedures, supplier costs, margins, notes about specific customers, passwords, the "what to say when a customer is angry" script: anything in the base can be found and repeated. The knowledge base is a customer-facing document. Keep internal material out of it entirely.
| ❌ In the knowledge base | ✅ Instead |
| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| "The whitening kit costs us \$40 and we charge \$200. If they complain, offer the \$150 promo to close." | "Whitening costs \$200. Occasional promotions are announced on our Instagram." |
Uploads are **PDF** and **TXT**, up to 20 MB each, and the PDF must contain real text. Word and Excel files are not accepted; paste their text as a **Free text** source. A scanned document, a photo of a price list, a menu exported as an image, or slides full of screenshots fail with *No readable text was found*. Tables and multi-column layouts often come through as a jumble, too. When in doubt, paste the text as a **Free text** source and check the fragment count.
| ❌ In the knowledge base | ✅ Instead |
| ---------------------------------------- | --------------------------------------------------------------------------------------- |
| `menu.pdf`, a photo of the printed menu. | A free-text source with one line per dish and its description; the prices in a catalog. |
| `price-list.pdf`, a 12-column table. | One paragraph per product, or one catalog record per product. |
A 60-page "everything about us" PDF is not read cover to cover. It becomes hundreds of fragments, and a fragment that mixes hours, refunds, and parking is a weaker match for any single question than a fragment about one thing. Split content by topic, give each section a clear heading, and start each paragraph with the subject it answers. The same applies to websites: index the pages that answer customer questions, not the blog archive or the careers page. See [Website sources](/ai-agent/website-sources).
| ❌ In the knowledge base | ✅ Instead |
| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `everything.pdf`: hours, policies, services, history, and staff bios in one flow. | Sources named *Opening hours*, *Cancellations and refunds*, *How a first visit works*, *Parking and how to get here*, each a few paragraphs long. |
Internal codes, abbreviations, and assumed context: "PX-200 avail. per SOP, see SKU list" means nothing to the agent or to the customer. Write it the way a customer would ask about it, and the way you would answer them.
| ❌ In the knowledge base | ✅ Instead |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "Ortho eval req'd before tx. Ref. protocol 4B." | "Before starting braces you need an orthodontic evaluation. It takes 30 minutes and costs \$40, which is discounted from the treatment if you go ahead." |
## What good content looks like
A source named for what it answers (*Cancellations and refunds*), a few paragraphs long, with a heading per sub-topic. Easy to find, easy to replace when it changes.
Write it the way you would say it on the phone: "Yes, we deliver in Bogotá and Chía." Then the conditions.
Who it applies to, when, and what happens otherwise: "Free up to 48 hours before; after that, the full price is charged."
"Fast delivery" and "this week" mean nothing months later. "Same day for orders before 2 p.m."; "valid until 15 August 2026."
## Before and after
One free-text source for a dental clinic, as it is often written and as it should be:
> Agent instructions: always be polite and ask for the patient's name first. Never give medical advice. We are the best clinic in the city with top-notch technology. Cleaning \$50, whitening \$200 (this month \$150!). For other prices, contact us. Cancel with 24h notice (new policy: 48h). If the patient is upset, transfer to Dr. López.
> **Cancellations.** Appointments can be cancelled or moved free of charge up to 48 hours in advance. Later than that, the visit is charged in full.
>
> **Whitening.** One 60-minute session; results last 1 to 2 years. Not recommended during pregnancy or with untreated cavities; this is checked at the consultation.
>
> **Cleaning.** A 45-minute visit that includes a check-up. Recommended every 6 months.
Everything else moved to where it works: the tone and the name question to Basic configuration and the qualifier agent, the prices to a *Services* catalog, and "if upset, transfer to Dr. López" to a transfer rule with Dr. López as its destination.
## Check that it works
Every source shows a fragment count above zero and no error. A failed source means nothing usable was extracted: fix the file, or paste its text as free text.
Then use the chat on the knowledge base's own page. Ask five questions the way your customers actually write them ("how much is a cleaning?", "do you take walk-ins?") and look at the **cited sources** under each answer. If the wrong source answers, or none does, the fix is in the text (a clearer heading, a sentence that matches how people ask), not in the agent.
When a real customer gets a wrong answer, the [Evaluation center](/ai-agent/evaluation-center) groups the replies that need fixing by theme. A missing or outdated fact is a knowledge-base fix; a wrong behavior is a configuration fix.
## Which agents can read it
Each agent picks the knowledge bases it may consult: the **Knowledge** switches in its configuration, one per knowledge base. See [Your AI agent team](/ai-agent/agent-team).