Knowledge base

A knowledge base lets the agent answer from your own content: help articles, policies, product pages, PDFs. Add sources under Knowledge in the admin panel (they belong to the workspace), then pick the ones each bot uses in its Knowledge tab.

Sources

Kind	What it reads
Text	Text you paste in (up to 2 million characters)
File	A PDF, Markdown, text, HTML or CSV file, up to 25 MB
Page	One web page
Sitemap	The pages listed in a sitemap.xml (<loc> entries), up to the page limit
Site (crawl)	A site, starting from one address

Web pages are reduced to their readable content (the article, not the menus and footers), keeping headings, then split into passages of a few hundred words that remember which section they came from.

Crawling follows links from the start address breadth-first, up to three links deep, and stays on the same site and under the start address's folder (https://example.com/help/start covers https://example.com/help/...). It skips images, PDFs and other files, waits a moment between pages, identifies itself as WirefaceChat-Knowledge/1 (+https://wireface.dev), and obeys robots.txt the way RFC 9309 reads it: a group for wireface wins over the * group, Allow and Disallow rules both count, the longest matching rule decides (Allow wins a tie), and * and a final $ work as wildcards. The page limit is 50 by default, up to 500.

Refreshing. Page, sitemap and crawl sources can re-index themselves every so many hours (1 to 720). Re-index any source by hand from the admin panel. A source shows its status (pending, indexing, ready or error), and its pages or files.

Knowledge fetching is held to the public internet unless the server allows private addresses (ALLOW_PRIVATE_NETWORK); see Security.

How the agent uses it

knowledge.mode on the bot:

Mode	What happens
auto	Before each text reply, the passages that best match the visitor's latest message are added to the conversation for the agent.
tool	The agent searches when it decides to, with the search_knowledge tool.
both (default)	Both.

Voice engines always search with the tool. knowledge.topK sets how many passages each search returns (5).

Search is full-text (SQLite FTS5 with BM25 ranking) over the bot's sources: it matches the words of the question, not their meaning. Content that uses your visitors' own words works best.

Passages reach the agent marked as information, never instructions, so text on a page can't change the agent's rules.

Citations

With behavior.citations on (the default), a reply that used the knowledge base shows its sources underneath (up to five): the page title and section, linked to the page when there is one. Links to pages on the site the chat is on open in the same tab.

Gaps

Every search is recorded. Questions that found nothing are listed in the admin panel (and at GET /api/v1/knowledge/gaps), most frequent first: that's what to write next.

Trying it

The admin panel can run a search and show what the agent would get (POST /api/v1/knowledge/search with { "query": "..." }). Each hit has a relevance from 0 to 1, against the best hit of the same search.