How Knowledgebase Search Works

You don't need to understand search algorithms to use Knowledgebases - they just work. But once you've uploaded a few sources and noticed an agent answer in ways you didn't expect (good or bad), it helps to know what's happening behind the scenes.

This page is the mental model.

---

The big idea

Your Knowledgebases hold everything you've uploaded - docs, websites, synced files. But your agents don't read every source on every message. They search it, pull back the most relevant bits, and use those bits to compose an answer.

So Knowledgebase quality has two halves:

1. What's in it - the documents, structure, freshness.
2. How well your agent can find the right bits - which is what this page is about.

---

Step 1: Sources get chunked

When you add a knowledge source, FormWise splits it into smaller chunks - think paragraphs or short sections, not whole documents.

Why chunks?

• A 100-page PDF is too big to hand the model whole.
• Even if you could, only a few paragraphs are usually relevant to any one question.
• Chunks make retrieval precise: the agent gets the page on warranty policy, not the whole employee handbook.

---

Step 2: Chunks get indexed

Each chunk gets converted into a numerical fingerprint that captures its meaning. Two chunks that talk about similar things get similar fingerprints, even if they don't share the same words.

This is what lets a search for "how do I get my money back?" match a chunk that says "refund policy" - the wording is different, but the meaning is close.

Status states - A new source moves through pending -> processing -> ready (or failed). Only sources that hit ready are searchable. Big files take longer; check back in a few minutes.

---

Step 3: At runtime, the agent searches

When an end user sends a message, here's what happens:

1. FormWise uses the end user's latest message as the search query.
2. FormWise searches the attached Knowledgebases for the chunks most relevant to that query - using both meaning (fingerprint match) and keyword overlap. This hybrid approach catches the cases where one or the other would miss.
3. The top chunks come back - ranked by how well they match.
4. FormWise injects those chunks into the agent's context, so the model writes its answer with them in mind.
5. If that isn't enough, the agent can run its own, more targeted searches with a built-in search_knowledge tool - for example to look up a specific fact deep in a long document.

The end user sees an answer grounded in your real content, often with the source named.

---

What makes results better

If your agent is missing things in your Knowledgebase it should be finding, fix what you put in - it's almost always an input problem, not an algorithm problem.

• Give files clear names. "Refund Policy v2.pdf" beats "Doc1.pdf." Names show up alongside the chunks.
• Use real document structure. Headings, subheadings, bullet lists - structure helps chunking land on natural boundaries.
• Don't dump everything into one giant file. Five focused files outperform one mega-file every time.
• Deduplicate. If the same content lives in five places, retrieval gets noisy.
• Keep it fresh. Update sources when policies change. Old versions outranking new ones is a classic source of "but I updated that!"
• Trim the obvious filler. Cover pages, repeating headers, and "this page intentionally left blank" all become noise in the index.

---

When the agent uses Knowledgebases

An agent only searches the Knowledgebases you attach to it - never your whole library. This is how you build a focused HR Agent that doesn't accidentally answer with sales material. You choose them in a few places:

• Flow - Pick the Flow's Knowledgebase in the Knowledge section of the Flow editor's sidebar. Every AI step in the Flow uses it.
• Single step - Add extra Knowledgebases to one AI Prompt step in its settings. They apply to that step only, on top of the Flow's own.
• Agent - Link one or more Knowledgebases to an Agent in the Agent builder.

Once a Knowledgebase is attached, both kinds of search happen on their own: the automatic search on every message, and the search_knowledge tool whenever the agent decides it needs to dig deeper. See Configuring Agents.

Pages work differently - The folders and pages in a Knowledgebase are not split into chunks. Instead, the agent sees a list of the pages and opens the ones it needs, like reading a note.

---

Common pitfalls

---

What you don't need to manage

• Re-chunking - every new source, and every changed file in a synced source, is processed for you.
• Picking embeddings - FormWise handles the fingerprinting.
• Ranking tuning - the hybrid match is automatic.

Your job is the inputs and the agent instructions. FormWise handles the rest.

Next steps