What a knowledge base is
A knowledge base is a named collection of your documents that ModuleX has prepared for search. Think of it as one searchable library: a set of product manuals, a policy handbook, or a folder of support articles. Each knowledge base carries its own settings for how documents are split and how they are turned into searchable vectors, so you can tune one library for long reference PDFs and another for short snippets — without affecting the rest.Documents
The files you upload. Each one moves through the ingest
pipeline and ends up searchable.
Chunks
Each document is split into smaller passages. Retrieval returns chunks, not
whole files, so answers stay focused.
Embeddings
Every chunk is converted to a numeric vector that captures its meaning, which
is what makes search by meaning possible.
Managed versus bring-your-own storage
When you create a knowledge base, you choose where the vectors live. This choice decides both who hosts the storage and how usage is billed.Managed (modulexdb)
ModuleX hosts the vector storage for you with the built-in modulexdb
provider. Nothing to set up. Ingest and retrieval are metered in
credits.
Bring your own (BYOK)
Point a knowledge base at a vector store you already run. ModuleX reads and
writes to it, and usage on your own store is not charged in credits —
your provider bills you directly.
Managed knowledge: modulexdb
Managed knowledge bases use ModuleX’s hosted vector store, modulexdb. They are the fastest way to start because there is no external account to connect. Because ModuleX runs the storage and the embedding calls on your behalf, each retrieval and each document ingest spends credits (see How credits apply).Bring your own key (BYOK)
If you already operate a vector database, you can connect it and keep your data in your own infrastructure. ModuleX supports these external knowledge providers:Qdrant
Use a Qdrant cluster as your vector store.
Pinecone
Use a Pinecone index as your vector store.
MongoDB Atlas
Use MongoDB Atlas Vector Search.
Weaviate
Use a Weaviate instance as your vector store.
Billing in one line. Managed (modulexdb) knowledge is billed in credits.
BYOK knowledge is uncosted by ModuleX — it is tracked for analytics only, and any
charges come from your own provider. See Credits & metering.
Getting content in: ingest
Ingest is the one-time preparation each document goes through after you upload it. ModuleX runs it in the background so you can keep working while large files process.1
Upload
You add a file to a knowledge base. Supported formats include PDF, Word
(
.docx / .doc), plain text, Markdown, HTML, CSV, JSON, Excel (.xlsx),
and PowerPoint (.pptx).2
Parse
ModuleX extracts the readable text from the file, whatever its format.
3
Chunk
The text is split into smaller passages using the knowledge base’s chunking
settings, so each piece is a focused, retrievable unit.
4
Embed
Each chunk is converted into an embedding — a vector that represents its
meaning — and stored alongside the text in the knowledge base.
Watching a document process
Every document reports its progress, so you always know whether it is ready to search.Document status: pending → processing → completed (or failed)
Document status: pending → processing → completed (or failed)
A document moves through these states:
- Pending — uploaded and waiting in the queue.
- Processing — being parsed, chunked, and embedded.
- Completed — fully ingested and ready to retrieve.
- Failed — something went wrong during ingest. You can fix the source file and retry the document; retrying a document does not re-charge an unchanged ingest.
Getting answers out: retrieval
Retrieval happens every time something asks a question. ModuleX turns the question into an embedding, compares it against the stored chunks, and returns the closest matches. Those passages are then handed to the model so its answer is grounded in your content. ModuleX offers a few retrieval styles for different needs:Semantic (vector) search
Finds chunks by meaning, even when the wording differs from the question.
This is the default style.
Hybrid search
Blends meaning-based search with exact keyword matching, which helps with
names, codes, and acronyms.
Multi-knowledge search
Searches several knowledge bases at once and merges the best results.
Context retrieval
Returns a ready-to-use block of text, assembled from the top chunks within a
token budget, for dropping straight into a prompt.
Where retrieval shows up
You rarely call retrieval by hand. It runs wherever an answer should come from your own material:Chat with your knowledge
Ask a question in chat and get an answer drawn from your documents.
The Assistant
The Assistant retrieves from your knowledge as one of the tools it can use.
Knowledge node
Add a step to a workflow that retrieves from a knowledge base.
Retrieving over the API
If you build on ModuleX directly, you can run a search against a knowledge base yourself. Authenticate every request with your API key and organization, exactly as on every other endpoint (see Authentication).Response
On a managed (modulexdb) knowledge base, a search that would exceed your plan
allowance can return a billing denial instead of results — a
402, 403, or
429 response. See Usage gating & limits and
Errors & status codes for the response shape and how to
handle it.How credits apply
Credits are only spent on managed (modulexdb) knowledge. BYOK knowledge bases are not charged by ModuleX. One credit is a small, fixed unit of managed usage (100 credits = $1.00).
On a BYOK knowledge base, neither ingest nor retrieval spends credits.
For the full pricing model — how credits are metered, the wallet, and overage —
see Credits & metering and
Billing & credits overview.
Plan limits
Your plan sets how many knowledge bases you can keep, how large each uploaded file can be, and how many documents each knowledge base holds. The values below come from the current subscription plan configuration.Where to go next
Knowledge overview
Create and manage knowledge bases in the ModuleX app.
Build a RAG knowledge base
A start-to-finish guide: create a knowledge base, ingest documents, and query
it.
Managed knowledge (modulexdb)
How ModuleX-hosted vector storage and retrieval work.
External knowledge providers
Connect Qdrant, Pinecone, MongoDB Atlas, or Weaviate.