Skip to main content
Chat with your knowledge means asking a question in plain language and getting an answer drawn from the documents you have loaded into ModuleX. Instead of replying from general training, the Assistant finds the most relevant passages in your knowledge bases, writes an answer grounded in them, and shows you the sources it used. This is retrieval-augmented generation (RAG), explained end to end in knowledge and RAG. This page covers the everyday version: how to attach a knowledge base, what a cited answer looks like, and the difference between managed and bring-your-own retrieval.

What it is

Every chat in ModuleX runs on the agentic Assistant. When you ask something, the Assistant decides — on its own, per message — whether your question is answerable from your stored documents. If it is, the Assistant searches the right knowledge base, reads the passages it finds, and answers from them. If your question is general chit-chat or has nothing to do with your documents, it skips the search and just answers. This is different from older “always search every message” behavior. Retrieval here is on demand: the Assistant only reaches for your documents when they are likely to help.

You ask a question

Type a question in plain language, the same as any other chat message.

It finds the passages

The Assistant searches the relevant knowledge base and pulls the most similar passages.

You get a cited answer

The reply is written from those passages, with the source documents shown alongside it.
Who can do this: chat requires an owner or admin role in the organization. The member role has been retired, so a plain member cannot open chat or query knowledge. See roles and permissions.

Attach a knowledge base

You do not attach a knowledge base to a single chat by hand. Every active knowledge base in your organization is already available to the Assistant — it picks the right one for each question by matching your wording to each base’s name and description. So “attaching” is really two steps you do once, in the knowledge area of the app, before you chat.
1

Create a knowledge base

In the knowledge area, create a base and give it a clear name and description — for example, “Product Docs — installation, configuration, and troubleshooting guides.” The Assistant uses that name and description to decide which base to search, so descriptive wording helps it choose correctly. See knowledge overview.
2

Upload your documents

Add the files you want answerable — PDFs, Word documents, text, Markdown, HTML, CSV, JSON, and spreadsheets are supported. ModuleX processes each file in the background: it splits the document into passages and prepares them for search. See managing documents.
3

Wait for processing to finish

A document is only searchable once its status reaches completed. While it is pending or processing, its content will not appear in answers yet. You can watch each file’s status in the knowledge area.
4

Ask a question in chat

Open a chat and ask. The Assistant matches your question to the right base, searches it, and answers from what it finds. No mode to switch and nothing to attach per message.
If your organization has no knowledge bases, the Assistant answers from its own general knowledge instead of searching. Knowledge chat starts working the moment you have a base with at least one processed document.
The Assistant only searches when your question looks answerable from your stored documents. A general question (“write me a haiku”) will not trigger a search. If you expect an answer from a specific document but the Assistant answered generally, ask more specifically — name the topic or the document — so it can match your wording to the right base. If a relevant base still is not found, check that the document finished processing and that the base’s name and description describe its contents.

Ask and get a cited answer

When the Assistant searches your knowledge, the reply is grounded in real passages and shows you where each came from. A cited answer has three parts you can see in the thread.

The search step

A short step appears in the thread while the Assistant searches, so you can see it is drawing on your documents rather than guessing.

The grounded answer

The reply is written from the retrieved passages and streams in live, the same as any chat answer.

The sources

The documents the answer drew from are listed as source chips. Each source is the filename of a document in the searched base.
Behind the scenes, each retrieved passage carries a similarity score and the filename of the document it came from. The Assistant uses the passages to write the answer and surfaces the document names so you can verify the reply against the originals. Passages below a relevance floor are dropped, so a question with no good match returns no sources — and the Assistant will tell you it could not find anything relevant rather than inventing an answer.
A cited answer points you to the document a passage came from, by filename. To read the full context, open that document in the knowledge area. Treat citations as a pointer to verify against, not a page-exact reference.
If the search returns no passages above the relevance floor, the Assistant has nothing from your documents to ground an answer in. Rather than guess, it tells you it could not find anything relevant. Try rewording the question, confirm the document finished processing, or check that you uploaded it to a base whose name and description match the topic.
The Assistant searches one knowledge base per search, choosing the base that best matches your question. If your knowledge is spread across several bases and a question spans them, ask follow-up questions that point at each topic, or keep closely related documents in the same base so a single search covers them. For searching across multiple bases programmatically, see knowledge and RAG.

Managed vs bring-your-own retrieval

Where your knowledge is stored and embedded determines whether searching it costs ModuleX credits. There are two paths, and the difference is purely about billing — the chat experience is the same either way.

Managed retrieval (modulexdb)

Your knowledge base is hosted by ModuleX on the managed vector store, modulexdb. Searching it is billed in credits — each search reserves a small base charge, plus the cost of turning your question into a search vector.

Bring your own (BYOK)

Your knowledge base lives in your own vector store, such as Qdrant, Pinecone, MongoDB Atlas, or Weaviate. Searching it is not billed in credits by ModuleX — that usage is yours.
A knowledge base is managed when its embedding runs through ModuleX-managed models; otherwise it is BYOK. You set this when you create the base, and you can mix both in one organization. For what a credit is and what consumes them, see credits and metering; for the storage options, see knowledge providers.
Only managed retrieval (a base hosted on modulexdb) is metered. Searching a BYOK base is uncosted by ModuleX. The reply, the sources, and the in-chat search step look identical regardless of which one you used.

When credits run out

Because managed retrieval is metered, it goes through the ModuleX billing gate like every other managed action. If your organization is out of credits or over a limit, a managed knowledge search is denied before it runs and the chat surfaces a DenialEnvelope as a 402, 403, or 429 response.
A denial is a small, flat JSON object — for example {code, layer, key, current, limit, reason} — rather than a normal answer. The layer field tells you why: credit and wallet map to 402, quota maps to 403, and rate maps to 429. See usage gating and limits for each case, and errors and status codes for the full envelope. BYOK retrieval does not hit this gate, because it is not credit-metered.

Try it from your own code

The app does this for you, but you can drive the same knowledge search from your own code. Two pieces are involved: starting a chat turn (the Assistant decides when to search), and — if you want to search a knowledge base directly — calling the search endpoint yourself. The direct search below runs one semantic search over a single knowledge base and returns the matching passages with their scores and source filenames. Every request authenticates with Authorization: Bearer mx_live_… plus your X-Organization-ID header — see authentication.
A direct search against a managed base goes through the billing gate and is metered in credits; a search against a BYOK base is not. To let the Assistant decide when and what to search inside a conversation, start an Assistant turn (POST /assistant/chat) instead — covered in chat overview.

Where to go next

How knowledge and RAG work

The full picture: ingesting documents, retrieval, and how grounded answers are produced.

Knowledge overview

Create and manage the knowledge bases that power retrieval across chats and workflows.

Managing documents

Upload files, watch processing, and keep your knowledge current.

Meet the Assistant

The agentic chat that decides when to search your knowledge and how to answer.