Manage knowledge bases in ModuleX

Knowledge is how you give ModuleX your own content to work from. You group documents into a knowledge base, ModuleX prepares them for search, and your chats, the Assistant, and your workflows can then answer from that material instead of guessing. This page is the hands-on tour: where Knowledge lives in the app, how to create a knowledge base, how to add documents and watch them process, and how to put a knowledge base to use. For the ideas behind it — what a chunk is, how retrieval works, and managed versus your-own storage — read Knowledge & RAG.

Where Knowledge lives

Open your organization’s settings and select Knowledge. From there you can:

See every knowledge base

A table of your organization’s knowledge bases, with totals for documents, chunks, and tokens across all of them.

Create a knowledge base

Start a new, empty library and set how its documents are split for search.

Add and manage documents

Upload files, watch them process, and retry or remove them.

Test a search

Run a question against a knowledge base to preview what it returns.

Knowledge bases belong to the organization, not to a single person. Creating and managing them requires the owner or admin role — see Roles & permissions. The header sent with every request is X-Organization-ID, which scopes the work to the right organization (see Org context).

Create a knowledge base

Select Create knowledge base and give it a name. That is the only required field — the rest have sensible defaults you can change later.

Name it

Choose a clear name, such as Product docs or Support playbook. You can add an optional description.

Set how documents are split (optional)

A knowledge base splits each document into smaller passages so answers stay focused. You can adjust the chunk size and chunk overlap, or leave the defaults.

Choose where vectors live (optional)

By default, ModuleX hosts the storage for you with the built-in modulexdb provider — nothing to set up. You can instead point the knowledge base at your own vector store. See Managed versus your own storage.

Create

ModuleX creates the empty knowledge base and adds it to your list, ready for documents.

Chunking settings

Chunking controls how each document is divided before it is made searchable. Smaller chunks make answers more precise; larger chunks keep more context together. The defaults work well for most content.

Setting	What it does	Default	Allowed range
Chunk size	How large each passage is, in characters	`1000`	`100`–`4000`
Chunk overlap	How much neighboring passages share, so context is not cut off mid-thought	`200`	`0`–`1000`, and less than the chunk size

You do not have to get chunking perfect up front. Different libraries suit different settings — longer chunks for reference PDFs, shorter ones for short snippets — and you can create more than one knowledge base to tune each separately. For the reasoning behind these numbers, see Knowledge & RAG.

Add documents

Open a knowledge base, then drag files onto the upload area or click to choose them. You can add several files at once; ModuleX uploads them one after another.

Supported formats

PDF, Word (.docx / .doc), plain text, Markdown, HTML, CSV, JSON, Excel (.xlsx), and PowerPoint (.pptx).

File size

The largest file you can upload is set by your plan, not a single fixed cap — see Plan limits.

Once a file is uploaded, ModuleX prepares it in the background — extracting its text, splitting it into chunks, and turning each chunk into a searchable vector. You can keep working while large files process. For the full document workflow — monitoring, retrying, and deleting — see Managing documents.

Watch documents process

Every document reports its progress, so you always know whether it is ready to search. The app refreshes the status automatically while files are still being prepared.

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 turned into searchable vectors.
Completed — fully prepared and ready to answer questions.
Failed — something went wrong while preparing the file. Fix the source file and retry the document. Retrying an unchanged document does not spend extra credits.

For step-by-step details on retrying and removing documents, see Managing documents.

Use a knowledge base

Once at least one document is completed, the knowledge base can answer questions. You rarely run a search by hand — it happens 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 can retrieve from your knowledge as one of the tools it uses to complete a task.

Knowledge node

Add a step to a workflow that retrieves from a knowledge base.

An external AI client

Let an MCP client such as Claude Code or Cursor search your knowledge through ModuleX MCP.

To preview what a knowledge base returns before wiring it into anything, use the search test inside the knowledge base — type a question and see the matching passages ranked by relevance.

Manage a knowledge base over time

From a knowledge base you can also:

Delete

Permanently remove a knowledge base and all of its documents and chunks.

Managed versus your own storage

When you create a knowledge base, you choose where its searchable vectors live. This decides 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. Preparing documents and running searches are metered in credits.

Bring your own (BYOK)

Point a knowledge base at a vector store you already run — Qdrant, Pinecone, MongoDB Atlas, or Weaviate. ModuleX does not charge credits for usage on your own store; your provider bills you directly.

Billing in one line. Managed (modulexdb) knowledge is billed in credits. Bring-your-own knowledge is uncosted by ModuleX — it is tracked for analytics only. On a managed knowledge base, an action that would exceed your plan allowance can return a billing denial — a 402, 403, or 429 response — instead of a result. See Credits & metering and Usage gating & limits.

Manage knowledge bases over the API

Everything above is also available programmatically. Authenticate every request with your API key and organization, exactly as on every other endpoint — an Authorization: Bearer mx_live_… header plus X-Organization-ID (see Authentication). The example below lists your knowledge bases and creates a new one.

# List knowledge bases
curl https://api.modulex.dev/knowledge-bases \
  -H "Authorization: Bearer mx_live_8Kd2pQ7rExample" \
  -H "X-Organization-ID: org_3xampleOrg42"

# Create a knowledge base
curl -X POST https://api.modulex.dev/knowledge-bases \
  -H "Authorization: Bearer mx_live_8Kd2pQ7rExample" \
  -H "X-Organization-ID: org_3xampleOrg42" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Product docs",
    "description": "Technical documentation"
  }'

import asyncio
from modulex import Modulex


async def main():
    async with Modulex(
        api_key="mx_live_8Kd2pQ7rExample",
        organization_id="org_3xampleOrg42",
    ) as mx:
        # List knowledge bases
        knowledge_bases = await mx.knowledge.list()
        for kb in knowledge_bases:
            print(kb.id, kb.name)

        # Create a knowledge base
        kb = await mx.knowledge.create(
            name="Product docs",
            description="Technical documentation",
        )
        print(kb.id)


asyncio.run(main())

import { Modulex } from "modulex";

const client = new Modulex({
  apiKey: "mx_live_8Kd2pQ7rExample",
  organizationId: "org_3xampleOrg42",
});

// List knowledge bases
const knowledgeBases = await client.knowledge.list();
for (const kb of knowledgeBases) {
  console.log(kb.id, kb.name);
}

// Create a knowledge base
const kb = await client.knowledge.create({
  name: "Product docs",
  description: "Technical documentation",
});
console.log(kb.id);

Creating a knowledge base returns the new record with its id, which you then use to add documents and run searches. For the search and retrieval calls, see Knowledge & RAG; for an end-to-end walkthrough in three languages, see Build a RAG knowledge base.

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.

Limit	Free	Pro	Max	Enterprise
Knowledge bases	10	3	50	Unlimited
Max file size per upload	10 MB	50 MB	100 MB	Unlimited
Documents per knowledge base	100	1,000	1,000	Unlimited

In the current plan configuration the Pro knowledge-base count (3) is lower than Free (10). This is a known inconsistency in the source data, shown here as-is — confirm the limit that applies to your organization on the Plans & pricing page before relying on it. The per-upload file size is set by your plan, not a single fixed cap.

Where to go next

Knowledge & RAG

The concepts behind Knowledge: chunks, embeddings, ingest, and retrieval.

Managing documents

Upload, monitor processing, retry, and remove documents.

Managed knowledge (modulexdb)

How ModuleX-hosted vector storage and retrieval work, and what they cost.

External knowledge providers

Connect Qdrant, Pinecone, MongoDB Atlas, or Weaviate.

Chat with your knowledge

Ask questions in chat answered from your documents.

Build a RAG knowledge base

A start-to-finish guide: create, ingest, and query.

​Where Knowledge lives

See every knowledge base

Create a knowledge base

Add and manage documents

Test a search

​Create a knowledge base

​Chunking settings

​Add documents

Supported formats

File size

​Watch documents process

​Use a knowledge base

Chat with your knowledge

The Assistant

Knowledge node

An external AI client

​Manage a knowledge base over time

Archive

Delete

​Managed versus your own storage

Managed (modulexdb)

Bring your own (BYOK)

​Manage knowledge bases over the API

​Plan limits

​Where to go next

Knowledge & RAG

Managing documents

Managed knowledge (modulexdb)

External knowledge providers

Chat with your knowledge

Build a RAG knowledge base

Where Knowledge lives

Create a knowledge base

Chunking settings

Add documents

Watch documents process

Use a knowledge base

Manage a knowledge base over time

Managed versus your own storage

Manage knowledge bases over the API

Plan limits

Where to go next