Your Documents, Indexed and Kept Fresh: 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) or sync them from external sources, 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, a DataStream destination for bulk ingestion, and a built-in search interface for testing. Synced sources stay fresh through incremental sync — and for the part everyone forgets, upstream deletes, each source carries a configurable tombstone strategy you pair with a full re-sync cadence.

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, and it's exactly the gap ByteChef's Knowledge Base is built to close.

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 — uploaded files or records synced from external systems, 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, track storage usage against your plan's limit, 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. Write from a workflow. The Knowledge Base is also a DataStream destination — "Write as Knowledge Base Document." Out of the box, Airtable, CSV File, and JSON File ship DataStream readers, and because the reader contract lives in ByteChef's component SDK, any connector can join the pool — pouring records straight into a KB through the chunked, transactional pipeline we covered in the DataStream post.
3. Connect a source. The managed option: register an external system as a Knowledge Base Source, and ByteChef generates the sync workflows for you — no pipeline authoring at all.

That third door deserves its own section, because it hides the hardest problem in the feature.

Staying Fresh — Including the Deletes

Keeping a knowledge base synced is really three problems wearing one name. New and changed records are the easy two: the generated sync runs on a schedule and uses DataStream's incremental sync to pull only what changed since the last successful run.

The third problem is the one that quietly poisons RAG systems: deletions. Incremental sync cannot see them — asking the upstream for "records changed since Tuesday" returns the records that still exist, not the ones that vanished. Left alone, every deleted upstream document lives on in your knowledge base forever, still being retrieved, still being quoted by your agent.

ByteChef treats this as a first-class, configurable policy: each source carries a tombstone strategy, defaulting to PERIODIC_FULL_REPLACE. You turn it on by pairing the frequent incremental cadence with a full re-sync cadence — weekly, say, against an hourly incremental. ByteChef then generates two triggers instead of one, and the full run, which sees the complete current upstream set, lets a tombstone sweep mark anything missing as deleted. Deletions surface within one full cycle, while the frequent runs stay cheap. Leave the full re-sync empty and you keep single-trigger behavior: cheaper, and blind to deletes. (A second strategy, reading a component's own deletion feed, is reserved for sources that can report deletes directly; a third, NONE, is the explicit opt-out for append-only sources where deletions shouldn't propagate.)

It's the kind of unglamorous correctness machinery you only appreciate after your agent has cited a policy that was retracted a month ago — and it's worth the one extra field at setup time.

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, 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.
• In the AI Hub. ByteChef's own AI surfaces stand on the same store, and they don't just read it: the Hub's agents can list, query, create, and clone knowledge bases, and add or remove documents. "Take these five PDFs and build me a knowledge base from them" is a sentence, not a setup task — and the Hub ships a knowledge base viewer for looking at the result.

One store, four 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, with storage tracked and capped.
• Chunking is a splitter you instantiate with magic numbers → chunk size, minimum, and overlap are fields on the create-knowledge-base form.
• Keeping the index synced is entirely your problem → ByteChef generates the sync workflows, runs them incrementally, and derives deletions via tombstone strategies.
• 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 all of it: documents in through upload, DataStream, or managed sources; chunks and vectors in pgvector; freshness handled down to the tombstones; retrieval exposed as agent tools, workflow actions, and a human search box. Your agents get something to know — and you get to skip building 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.