Knowledge Bases (RAG)

Required Access Level

Manager or above

The Knowledge Base module allows administrators to upload company documents (PDF, TXT and Markdown) to give context to the AI Agents using Retrieval-Augmented Generation (RAG) technology.

The screen sits under Content, next to the CMS, and shows for Manager or above — a knowledge base is content that feeds the agent, not platform configuration.

The role is enforced on the server

The barrier is not only the menu: the tenant knowledge-base endpoints require Manager or above on the server itself, and anyone calling the API directly without that role gets a 403 — on reading the listing as much as on the upload, the deletion and the link to a process. The global base keeps its own requirement: only a Super Admin creates or changes a global base.

The same holds for the per-process base, the one the catalogue's RAG tab feeds at /a/definitions/{key}/knowledge: uploading and deleting a document, wiping the whole base and asking for a reindex all require Manager or above, and so does reading the listing. It is the same capability reached by another route, so it takes the same role.

When attaching a document to a Knowledge Base, Flowi Agentic performs:

1. Text Extraction: Secure reading of the original content.
2. Chunking: Splitting the text into fixed-size passages, measured in tokens rather than paragraphs — a passage can start mid-sentence, which is why the guidance below is to write blocks that stand on their own.
3. Embeddings: Converting the text into mathematical vectors, saved in the database (pgvector).

Creating a Base

1. Access the Content → Knowledge Bases menu.
2. Click on New Base.
3. Define a name and a clear description for the scope of this base.

A base created here belongs to your tenant and only your tenant sees it.

Global bases

Besides your own bases, the listing also shows the global bases — provided by the platform and read by every tenant, usually travelling with a global process template. They are flagged as Global and are read-only for a tenant administrator: they cannot be edited or deleted, and the delete button is disabled with the reason.

Global bases are created and maintained by the platform administrator, under Global (Super Admin) > Global Knowledge Bases. The split is deliberate: each role configures only the scope it answers for, and the tenant screen offers no switch to mark a base as global.

Anything global is visible to everyone

Every tenant reads a global base. Content one customer must not see does not belong in the global scope — load it into the tenant's own base.

Writing for vector search

Vector search does not read the whole document: it splits the text into chunks and sends the agent only the 3 chunks closest to that step's instruction. Everything else stays out. Writing for that cut is what separates a base that helps from one that gets in the way.

Write chunks that stand on their own. A rule spread across five sections of a manual does not arrive whole — at most three pieces of it do, possibly without the opening premise. Prefer a short block that states the complete rule, carrying its context inside it, over a long exposition that only makes sense read from the beginning.

A small, focused base beats a complete one. There is no relevance cut-off: the 3 nearest chunks are always sent, even when none of them is good. A base that mixes subjects is not neutral — it fills the space with irrelevant material and pushes out what mattered. Prefer several lean bases, each linked to the process where it belongs, over a single base holding everything.

Speak the language of the agent's instruction. The search is driven by the instruction configured on the step, not by a user question. If the instruction says "delivery deadline" and the document says "lead time", proximity drops and the right chunk may not make the cut. Review both sides together and use the same terms.

Prefer text over scans. An image-only PDF with no text layer produces no chunks at all: the document uploads, appears in the list, and is simply never retrieved.

In practice

The same content, written both ways:

<!-- ❌ the chunk cannot stand alone: it depends on what came before -->
As described in the previous section, the limit mentioned applies in
full. In all other cases, the preceding paragraph governs, save for the
exceptions already noted.

If that piece is one of the 3 selected, the agent receives "the limit mentioned" without knowing which limit, which section, or which exceptions.

<!-- ✅ the chunk answers on its own -->
## Approval limit — travel reimbursement

Travel expenses up to R$ 2,000 are approved by the direct manager.
Above R$ 2,000 they require approval from the area director.

Applies to every cost centre, from 01/2026 onwards.
Exception: international travel always requires director approval,
regardless of amount.

A heading that names the subject, the complete rule, explicit value bands, the effective date and the exception — all inside one block. Even if this is the only chunk retrieved, the agent still decides correctly.

What must NOT go into a Knowledge Base

Code and identifier tables — product catalogues, cost centres, municipality codes, job title tables, price lists. They look like documents but do not work by similarity: neighbouring codes have nearly identical descriptions, and thousands of rows repeat generic terms like "Other". Asking for a specific code returns, with full confidence, an unrelated row.

That kind of data belongs in the CMS, where lookups are exact. The rule of thumb is: exact identifier → CMS; text that must be interpreted → Knowledge Base.

Linking to Processes

After populating the knowledge base with corporate documents, you link it to a process definition, not to an agent. The agent reaches the base because it runs inside that process — if the same base serves more than one process, each one needs its own link. When the agent runs, the AI automatically searches the linked bases before responding, so the answers stay grounded in your company's guidelines and the risk of hallucinations drops.

The process link defines the set within reach; inside it, each step of the flow can narrow which bases it consults, or declare that it consults none — see Knowledge bases for this step.

Deleting a base

Deleting a base removes the record immediately, but the vectors built from its documents do not disappear at the same moment: they are marked as orphaned and removed by a daily cleanup after a retention window — 30 days by default, configurable through RAG_ORPHAN_VECTOR_RETENTION_DAYS.

This is deliberate. Rebuilding a large index costs hours of processing plus the price of the embeddings, so the window exists to give you time to recover a base deleted by mistake. During that window the vectors show up in no search — retrieval only considers bases linked to a process, and a deleted base is linked to nothing.

A base still linked to a process is not deleted: the platform refuses and answers listing the processes that still use it. Unlink each one and repeat the deletion.

Reloading a whole base

To replace all the content of a base, create a new base, load into it, link it to the process, and only then unlink the old one. Loading on top of the existing base adds to what is already there: the old and new versions of the same documents end up side by side, and retrieval returns both.