The Botpress knowledge base: how it works, and how to load your knowledge base into it

Botpress bots search their knowledge bases through a card in the conversation flow. A new bot's Autonomous Node already has a Search Knowledge card that searches every knowledge base, and Botpress passes the model a set number of the closest chunks. Botpress is mainly used for chat agents; its knowledge base docs describe chat channels.

This page is written from Botpress's own documentation, checked on 25 September 2026. KB Builder is not affiliated with Botpress. Our own live calls so far ran on a different platform, so the advice below applies what we learned there; it has not been tested on Botpress yet.

How the Botpress knowledge base works

	What the docs say
Where it lives	The Knowledge Base menu in Studio; a bot can have several
How the bot uses it	The Autonomous Node's Search Knowledge card (searches all knowledge bases by default), or a Query Knowledge Bases card in standard nodes
What you can add	Documents (.pdf, .html, .txt, .doc, .docx, .md, up to 50 MB each), websites, specific pages, tables, rich text, web search, Notion, Google Drive
Retrieval	RAG; the Chunks Count setting decides how many chunks reach the model
Chunk size	Not stated in the docs
Storage	Counts against the workspace's vector storage quota, set by your plan
Updating	Upload the new file and delete the old one; websites can be re-crawled on a schedule

Botpress's logs show the exact query sent to the knowledge base and what came back, which is the first place to look when an answer is wrong.

Where it goes wrong in conversations

Chunks without owners. Botpress converts every document to Markdown and cuts it into chunks. A chunk can hold a price whose product name was in the chunk before, and the bot attaches it to whatever the customer asked about.

Two cards, one random choice. With more than one Search Knowledge card and no instructions on each, Botpress's docs say the Autonomous Node "won't be able to tell the two Cards apart, and will pick one randomly".

Old and new versions together. Because updating means a new file, forgetting to delete the old one leaves two prices for one product in the same knowledge base.

How to load a KB Builder file into Botpress

A KB Builder knowledge base is a Markdown file written in short sections that each name one product or service, so every chunk carries its own product's name.

1. In Studio, open the Knowledge Base menu and select the default knowledge base, or create one named after the business.
2. Choose Documents and upload the .md file.
3. A new bot's Autonomous Node already searches all knowledge bases. If you have more than one, give each Search Knowledge card instructions saying which business it covers.
4. For businesses with many similar products, raise the Knowledge Agent's Chunks Count a little.
5. Test in the emulator and read the logs to check which chunks were retrieved.

When the business's website changes, rebuild the file in KB Builder, upload the new file and delete the old one.

Lines to add to the bot's instructions

These come from our own live calls. They were written for voice, and they work the same way in chat:

Answer questions about the business only from the knowledge base. If it doesn't have the answer, say you will check, and give the business's phone number.
Give a price, time or rule only from a sentence that names the product or service the customer asked about.
Whenever you give a price, say the name of the product or service with it.
If the customer hasn't said which product or service they mean, ask before answering.
When the knowledge base says something has not been confirmed, say exactly that. Never guess.
Don't promise messages, callbacks or bookings unless the knowledge base says the business offers them.