Your Documents, Chunked and Searchable: The Knowledge Base in ByteChef

TL;DR: A Knowledge Base in ByteChef is a managed RAG store: drop in documents (PDF, Markdown, Word, JSON, plain text - and scanned PDFs or images, through an OCR path) and ByteChef parses, chunks (with size and overlap you pick per knowledge base), embeds, and indexes them in a pgvector-backed Spring AI VectorStore. Retrieval is everywhere you'd want it: a Knowledge Base Search tool for AI Agents (with tag filtering), Load/Search/Update/Delete actions for workflows, and a built-in search interface for testing. Keeping the index current is yours to drive - re-run an ingestion workflow on whatever schedule you like - and the part to plan for deliberately is upstream deletes, which no refresh can spot on your behalf.

Every team building with agents arrives at the same sentence: "It should know our stuff." The product docs. The runbooks. The policy PDFs. And the standard answer - RAG, retrieval-augmented generation - is conceptually simple: chunk the documents, embed the chunks, search by similarity, hand the best matches to the model.

The concept is a weekend. The operation is a project. Someone has to parse five file formats, pick chunk sizes, run an embedding model, host a vector database, keep the index in sync when the source-of-truth changes - and notice when a document is deleted upstream, because a knowledge base that confidently serves stale policy is worse than none at all. That's the gap between a RAG demo and a RAG system. ByteChef's Knowledge Base closes most of it for you - and this post is honest about the part it leaves to you.

What a Knowledge Base Is

In ByteChef, a Knowledge Base is a first-class object with its own home in the workspace: a named store of documents, each broken into chunks, each chunk embedded and indexed for semantic search. The layering is straightforward:

• Documents are what you put in - files you upload, or records a workflow or an agent writes in, organizable with tags.
• Chunks are what retrieval actually works with. You pick the chunking when you create a knowledge base - maximum chunk size (default 1024 tokens), the minimum chunk size in characters used to find a clean break point (default 100), and how many tokens neighboring chunks overlap (default 200) - so a KB full of dense legal prose can chunk differently than one full of short FAQ entries. The splitter counts tokens with CL100K_BASE, the same encoding GPT-4 uses, and prefers to break on sentence punctuation rather than mid-thought.
• Embeddings live in pgvector - a Spring AI PgVectorStore over a pgvector-enabled PostgreSQL database, built with the platform's configured EmbeddingModel and indexed with HNSW over cosine distance. There's no proprietary vector service to sign up for and no new operational vocabulary to learn: it's Postgres, backed up and monitored like the rest of your Postgres, and ByteChef creates and maintains the schema, the index, and the per-knowledge-base partitioning for you.

And in the Knowledge Base workspace, none of this is a black box. You can open any document and inspect its individual chunks - and edit them, because sometimes the fix for a bad retrieval is one badly split paragraph - watch a document's indexing status, and, before any agent ever touches it, try queries against the KB in a built-in search interface to see exactly what retrieval returns.

Getting Documents In

There are three doors in, matched to three situations:

1. Upload. Drag files into the workspace. The ingestion pipeline picks the right parser per format - a dedicated PDF reader (page- or paragraph-oriented), a Markdown reader, JSON and plain-text readers, and an Apache Tika-based reader as the catch-all for Word documents and other office formats. All of these are Spring AI's document readers; ByteChef orchestrates them into one pipeline that ends in chunks and vectors. With OCR enabled, PDFs and images take a different route entirely - straight through an OCR service - so the scanned contract and the photographed whiteboard land in the index like everything else.
2. From a workflow. The Load Data action writes into a knowledge base from anywhere a workflow can reach. Attach a document reader (plus any transformers you want), point the action at the target KB, and every run pushes documents through the same chunk-and-embed pipeline the uploader uses. Put that workflow behind a schedule, a webhook, or a file-landed trigger and ingestion runs without you.
3. From an agent. The Knowledge Base Update tool is a cluster element you attach to an AI Agent, so an agent can contribute what it learns rather than only consume it - useful when the thing worth keeping is something the agent worked out mid-conversation.

Whichever door you use, everything downstream is identical - parse, chunk, embed, index. What differs is who pushes the button, and how often.

Keeping It Current - and the Deletes Nobody Plans For

An index is a snapshot, and snapshots rot. Re-running ingestion is the easy half: put the Load Data workflow on a schedule and new and changed documents flow in on whatever cadence suits the material - nightly for a handbook, hourly for a status page.

The hard half is the one that quietly poisons RAG systems: deletions. A refresh that asks the upstream for "everything that changed since Tuesday" gets back the records that still exist - never the ones that vanished. Left alone, a document deleted at the source lives on in your knowledge base indefinitely, still retrieved, still quoted by your agent, long after somebody retracted it.

That half is yours to own today - ByteChef has no "connect a source and forget it" option that derives deletions for you. It's worth owning deliberately rather than discovering later, and the shape of the fix is simple enough: tag each ingested document with its upstream id, and on the runs where you can enumerate the full current upstream set, use the Delete Documents action - it removes documents by metadata filter - to drop whatever is no longer in it. Unglamorous, and far cheaper than the alternative, which is an agent confidently citing a policy that was withdrawn a month ago.

Getting Knowledge Out

A knowledge base earns its keep at retrieval time, and ByteChef exposes it on every surface:

• As an AI Agent tool. The Knowledge Base Search tool is a cluster element - attach it to any AI Agent (the same way as every tool in our agentic patterns series), pick which KB it searches, and optionally scope it by tags (documents matching any selected tag are eligible). From then on, the agent decides when to reach into the knowledge base, mid-conversation, on its own. There's a Knowledge Base Update tool too - for agents that should be able to contribute knowledge, not just consume it.
• As workflow actions. The Knowledge Base component ships Load Data, Search Data, Update Documents, and Delete Documents actions, so ordinary workflows can query or maintain a KB with no agent involved - "on new support ticket, search the KB and attach the top three matches" is three nodes.

One store, several ways in and out - and because retrieval is tag-filterable, a single knowledge base can serve multiple audiences ("customer-facing" vs. "internal-only") without maintaining parallel copies.

If you want to tune retrieval itself - query rewriting, expansion, custom joins over several stores - that's a different layer: ByteChef's RAG cluster elements, which work over any vector store you like. The Knowledge Base is the batteries-included end of the same spectrum: you don't configure retrieval, you just ask it questions.

What You Inherit from Spring AI - and What ByteChef Adds

By now you know the shape of this section. The primitives are Spring AI's; the product around them is ByteChef's:

• Document readers exist as library classes (PDF, Markdown, JSON, text, Tika) → ByteChef auto-selects the parser per file in one managed ingestion pipeline.
• Spring AI has no OCR reader at all → ByteChef adds one, and routes scanned PDFs and images through it before any other parser gets a look.
• PgVectorStore + EmbeddingModel are yours to configure and operate → ByteChef owns the schema, the HNSW index, and the per-knowledge-base partitioning.
• Chunking is a splitter you instantiate with magic numbers → chunk size, minimum, and overlap are fields on the create-knowledge-base form.
• Ingestion is a pipeline you assemble, wire, and run yourself → it's one action with a reader attached, on any trigger - or no workflow at all, if you just upload.
• Retrieval is code you write → it's a tool on any agent, actions in any workflow, and a search UI for humans.

Same foundation as everything in this series - Spring AI under the hood - with the operational half of RAG, the half that actually hurts, absorbed into the platform.

Running It Yourself

If you're self-hosting, the Knowledge Base ships disabled - two switches turn it on:

bytechef:
  ai:
    knowledge-base:
      enabled: true
    vectorstore:
      provider: pgvector
      pgvector:
        url: jdbc:postgresql://localhost:5433/bytechef_vectorstore
        username: postgres
        password: postgres

That second block is the part worth planning for. The vector index lives in its own pgvector-enabled PostgreSQL database, separate from ByteChef's application database - the development compose file runs one for you alongside the main Postgres, and in production it's a second database to provision, monitor, and back up. Still Postgres, still nothing exotic, but not the same Postgres. ByteChef creates the schema and the index inside it on first use.

One more prerequisite, easy to miss: an embedding model has to be active for the environment. Without one there's nothing to turn chunks into vectors with, and the Knowledge Base page says so outright rather than quietly indexing nothing.

Wrapping Up

The distance between "agents are impressive" and "agents are useful here" is almost always knowledge - your documents, your data, your vocabulary. RAG closes that distance in principle; in practice it comes bundled with a parsing zoo, a vector database, an embedding budget, sync jobs, and the deletion problem nobody budgets for.

ByteChef's Knowledge Base packages most of it: documents in through upload, a workflow action, or an agent; chunks and vectors in pgvector; retrieval exposed as agent tools, workflow actions, and a human search box. What stays with you is the refresh policy - how often to re-run ingestion, and what to do about the deletes. Your agents get something to know, and you skip almost all of the machinery of knowing.

Have a folder of PDFs your agent should be quoting? Open ByteChef, create a **Knowledge Base, drop them in, and attach the **Knowledge Base Search* tool to your agent.*