How to build a chatbot knowledge base that answers well

A chatbot knowledge base works when it is written for retrieval rather than for reading. Split it into eight short focused pages instead of one long PDF, put repeating facts like shipping rates into tables, and move anything that changes weekly out of documents and into curated answers.

Most assistants that give bad answers are not badly built. They are badly fed. The material is usually all there, written the way a person reads: one long document, long paragraphs, an out of date section nobody deleted. Retrieval does not read like a person, and once you know how it does read, rewriting your material takes an afternoon. If you are still deciding whether you want an assistant at all, start with the ecommerce chatbot guide and come back to this.

What is a chatbot knowledge base?

A chatbot knowledge base is the material an assistant is allowed to answer from: uploaded documents, text pasted in directly, product entries, and question-and-answer pairs written by the owner. It is not a help centre for customers to browse. Nobody reads it. Its only job is to be found in fragments and quoted back.

That distinction drives every decision below. A help centre is written to be navigated, so it can afford a contents page and a friendly tone. A knowledge base is written to be matched, so both are a cost.

How does a chatbot read your documents?

Nothing reads your document end to end when a customer asks a question. The document was taken apart on upload, and only a few pieces come back. Here is the sequence chatfor.site runs, with the real numbers.

1. Text is pulled out of the file. PDFs go through a text extractor; plain text and Markdown are taken as they are. A scanned PDF has no selectable text, so it is rejected with a message telling you to run OCR on it first. Files are capped at 20 MB and ten per upload.
2. The text is split into chunks. Each chunk targets 450 tokens, roughly 1,800 characters, with about 240 characters of the previous chunk carried into the next so a fact straddling a boundary stays retrievable. Splits are taken at the largest natural boundary that fits: paragraph, then line, then sentence, then word.
3. Every chunk gets a vector. The embedding model is bge-small-en-v1.5, run locally through transformers.js rather than a paid API, so indexing costs nothing per document.
4. The customer's question gets a vector the same way and is compared against your chunks.
5. The top four chunks are taken, each above 0.45 similarity, and packed into the prompt in similarity order until a 1,400 token context budget is spent.

Step five is the one that changes how you write. About 1,400 tokens of your material, roughly 900 words, is all that reaches the model for any single question. Everything else you uploaded is invisible for that question. You are not writing a library to be consulted. You are writing so the right 900 words surface.

Worth knowing: more context is not better context. Anthropic's documentation warns that "as token count grows, accuracy and recall degrade, a phenomenon known as context rot", and that "curating what's in context [is] just as important as how much space is available" (Source: Anthropic documentation, 2026). A tight knowledge base is not a compromise. It is the better answer.

Why one 40-page PDF answers worse than eight short pages

Take a 40-page trading manual. It becomes something like 150 chunks. A customer asks about next day delivery to the Highlands, and the retriever has to pick four of those 150. Compare that with eight one-page documents, maybe 15 chunks in total. Same information, and the second version answers better for five reasons.

• Fewer candidates means fewer near misses. Picking the best four out of 15 is easier than out of 150, and the retriever has no understanding of your business to help it.
• Mixed-topic chunks match nothing strongly. A chunk becomes one vector. If 1,800 characters cover delivery, returns and gift wrapping together, that vector sits between all three and scores middling on each. Measured on a sample corpus, a direct hit scores about 0.72, a paraphrase 0.54, a question the documents genuinely cannot answer 0.51, and something unrelated 0.43. That band is narrow, so diluting a chunk is enough to push a real answer down among the noise.
• Boilerplate competes for the budget. Contents pages, page numbers, running headers and legal preamble all get chunked and indexed alongside the useful text. They sometimes win a slot in the four, and every character eats the budget.
• You cannot fix one fact. Changing a delivery time in a 40-page PDF means re-exporting and re-uploading 40 pages. With one page per topic you replace one page.
• The document limits make this free. Free allows 25 documents, Starter 200, and Growth and Business are unlimited. Eight short pages costs eight of 25, so there is no reason to economise by bundling.

A sensible starting set for a shop is eight documents, one per topic:

1. Delivery: options, prices, timings, countries.
2. Returns and exchanges: window, condition, who pays postage.
3. Sizing and fit: the size chart, how to measure, which lines run small.
4. Payment: methods accepted, instalments, VAT and duties.
5. Orders: tracking, changes, cancellations, missing parcels.
6. Product care: washing, materials, warranty, spare parts.
7. The shop itself: address, opening hours, parking, click and collect.
8. Accounts and privacy: signing up, deleting an account, marketing.

Write the facts as a table, not a paragraph

This is the most common mistake and the easiest to fix. Here is delivery information written the way most shops write it.

We aim to dispatch all orders within one working day. Standard delivery is usually with you in three to five working days and costs £3.95, although orders over £50 qualify for free standard delivery. If you need something sooner we offer an express service which is normally next working day for £6.95, and please note that deliveries to the Scottish Highlands and Islands, Northern Ireland and the Channel Islands may take an extra day or two and are charged at our express rate regardless of order value.

Every fact a customer needs is in there, and it still answers badly. "Is next day delivery free if I spend £60?" requires the assistant to connect a threshold in the middle of the paragraph to an exception at the end, and to work out that the exception wins. That is inference, and inference is where wrong answers come from.

Now the same facts as a table.

Four things improved at once. Each row is a complete, self-contained fact, so a chunk containing it can be quoted without the rest of the document. The chunker splits on newlines before sentences, so rows tend to survive as units rather than being cut in half. The head terms a customer will type, delivery, express, next working day, free, repeat in every row, which lifts the similarity score for the questions people really ask. And the awkward exception is no longer buried in prose. It is a cell that says "Never free".

Worth knowing: if a table is long enough to split across two chunks, the second chunk arrives without the header row and its numbers lose their meaning. Keep a table under about 1,500 characters, and write cells that still make sense with the column heading missing: "£6.95" and "5 to 7 working days" rather than a bare "6.95" and "5 to 7".

The same treatment works for anything with repeating structure: size charts, opening hours by day, warranty periods by product line, return windows by category.

Build it in this order

1. List the twenty questions you already answer. Go through last month's emails, phone notes and chat log and record the real wording customers used. This list is your specification and your test suite. Do not write documents from imagination instead.
2. Group them into topics, one page each. A topic collecting one question folds into a neighbour. A topic collecting nine splits.
3. Write each page as facts. No welcome paragraph, no brand voice, no contents page. Anything with rows becomes a table. Aim for one screen per page.
4. Add a product entry for each thing you sell, with a name, a price and a short description. These are shown as cards next to the answer, up to four at a time, and only when the question is genuinely about a product.
5. Write question-and-answer pairs where you want exact wording. Use the customer's phrasing as the question. These take precedence over your documents.
6. Upload, then ask it your twenty questions, and fix what it gets wrong before it goes on the site.

What to do about information that changes weekly

Retrieval has no sense of time. It cannot tell which of two contradictory passages is newer, and it has no way to break the tie. If last season's returns policy is still uploaded alongside this season's, both are retrievable, and on any question the model may see one, the other, or both. That is the failure mode to design around.

Three rules cover almost everything.

Keep volatile facts out of documents entirely. Stock levels, "currently available", this week's offer, today's dispatch cut-off: none of these belong in an uploaded file. A document is for policy, which changes a few times a year.

Put weekly facts in question-and-answer pairs instead. A curated pair is a text field you edit in the dashboard, not a file you re-export. It is retrieved above 0.62 similarity and presented to the model as an approved answer that takes precedence over your documents, and at 0.92 similarity or above the pair is returned as written without calling the model at all. Measured against a real pair, the exact question scored 1.000, a trivial rewording 0.993 and a genuine paraphrase 0.853. Slight rewordings get your words verbatim; real paraphrases still get an answer built on them.

Put prices in product entries. They are indexed on the chat path, up to 25 pending entries per question, so a price changed a minute ago is matchable on the very next question a visitor asks.

Two habits make the rest manageable. Date the headings inside your documents, "Delivery times, updated 1 September 2026", so a stale passage announces itself in the answer. And replace documents rather than adding to them: one per topic, always overwritten, never supplemented with an addendum. An addendum is how you end up with two answers and no tie-breaker.

Retrieval quality is only half of it. How the assistant behaves when your material runs out is the other half, and that is covered in the explainer on handling a question the documents do not cover.

How do you know it is working?

Ask it your twenty questions and sort the replies into three piles.

• Right. Move on.
• "I do not have that to hand." The good failure. The assistant is built to say so rather than guess when your material does not cover a question, so this is a gap with an obvious fix: write the missing page.
• Confidently wrong. The one to chase. It nearly always means two passages contradict each other, or a curated answer matched a question it was not written for.

For the third pile, open the conversation in the dashboard and look at which passages the answer drew on. That tells you whether the retriever picked the wrong chunk or the right chunk said the wrong thing, and those need opposite fixes. Conversation history and search is included on Growth and above, and you can overrule an answer while you are in there. Then re-upload: embeddings run locally, so re-indexing costs nothing.

None of this replaces a well-written delivery page, but be honest about how much of it gets read. Nielsen Norman Group found that "users have time to read at most 28% of the words during an average visit; 20% is more likely" (Source: Nielsen Norman Group, 2008). Being asked is the format that works.

Once the material is right, the rest is one script tag and five minutes, covered in the guide to installing the widget. If you are comparing tools on how they treat source material rather than on feature lists, the head-to-head on document grounding is the closer read.

Frequently asked questions

How many documents does a chatbot knowledge base need?

Eight to fifteen short documents covers most shops. One page per topic beats one long manual, because only four chunks and about 900 words of your material reach the model per question. The Free plan allows 25 documents, Starter 200, and Growth and Business are unlimited, so there is no reason to bundle topics together.

What file formats can I upload?

PDF, plain text and Markdown, up to 20 MB per file and ten files per upload. You can also paste text straight in as a source, which is often quicker than making a file. Scanned PDFs are rejected because they contain no selectable text; run OCR on them first, or paste the text instead.

Should I upload my whole website?

No. Marketing pages are mostly persuasion, navigation and repetition, and all of it gets indexed and competes with your real answers for four retrieval slots. Take the facts out of your pages and write them as short topic documents. A trimmed knowledge base answers better than a complete one.

How do I stop the assistant giving out of date information?

Delete the old document rather than uploading a new version alongside it. Retrieval cannot tell which passage is newer, so two contradictory passages leave the answer to chance. Keep anything that changes weekly in curated question-and-answer pairs and product entries, which you edit in the dashboard and which take effect immediately.

Do question-and-answer pairs override my documents?

Yes. Curated pairs are given to the model as approved answers to use in preference to document text, and a question matching a pair at 0.92 similarity or above is answered with the pair as written, without calling the model. That makes them the right home for anything where you want exact wording, such as a refund policy or a legal statement.

Sources

• Anthropic documentation, "Context windows", 2026. https://platform.claude.com/docs/en/build-with-claude/context-windows
• Nielsen Norman Group, Jakob Nielsen, "How Little Do Users Read?", 5 May 2008. https://www.nngroup.com/articles/how-little-do-users-read/