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.
Why does the Assistant sometimes not search my documents?
Why does the Assistant sometimes not search my documents?
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.
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.
What if nothing relevant is found?
What if nothing relevant is found?
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.
Can the Assistant search more than one knowledge base for one question?
Can the Assistant search more than one knowledge base for one question?
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.
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 aDenialEnvelope as a 402, 403, or 429 response.
What a billing denial looks like
What a billing denial looks like
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 withAuthorization: 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.