> ## Documentation Index
> Fetch the complete documentation index at: https://docs.modulex.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Manage knowledge bases

> Create knowledge bases in the ModuleX app, upload documents, and use them to answer questions across chats, the Assistant, and workflows.

export const MediaEmbed = ({id, type = 'screenshot', caption = '', ext, ratio = '16 / 9'}) => {
  const isVideo = type === 'video' || type === 'app_video';
  const resolvedExt = ext || (isVideo ? 'mp4' : type === 'screenshot' ? 'webp' : 'svg');
  const src = 'https://media.modulex.dev/' + id + '.' + resolvedExt;
  const [status, setStatus] = useState('loading');
  const [isDev, setIsDev] = useState(false);
  const [inView, setInView] = useState(false);
  const boxRef = useRef(null);
  useEffect(() => {
    if (typeof window === 'undefined') return;
    const h = window.location.hostname;
    setIsDev(h === 'localhost' || h === '127.0.0.1' || h.endsWith('.mintlify.app'));
  }, []);
  useEffect(() => {
    if (inView) return;
    if (typeof IntersectionObserver === 'undefined') {
      setInView(true);
      return;
    }
    const el = boxRef.current;
    if (!el) return;
    const io = new IntersectionObserver(entries => {
      if (entries.some(e => e.isIntersecting)) {
        setInView(true);
        io.disconnect();
      }
    }, {
      rootMargin: '300px'
    });
    io.observe(el);
    return () => io.disconnect();
  }, [inView]);
  if (status === 'missing') {
    if (!isDev) return null;
    return <div style={{
      display: 'flex',
      flexDirection: 'column',
      justifyContent: 'center',
      gap: '0.4rem',
      padding: '1rem 1.25rem',
      margin: '1.25rem 0',
      width: '100%',
      aspectRatio: ratio,
      boxSizing: 'border-box',
      border: '1px dashed rgba(128,128,128,0.45)',
      borderRadius: '0.75rem',
      background: 'rgba(128,128,128,0.06)',
      color: 'currentColor',
      fontSize: '0.85rem',
      lineHeight: 1.45
    }}>
        <div style={{
      display: 'flex',
      alignItems: 'center',
      gap: '0.5rem',
      opacity: 0.75
    }}>
          <span aria-hidden="true">🎬</span>
          <code style={{
      fontSize: '0.75rem'
    }}>{id}</code>
          <span style={{
      fontSize: '0.65rem',
      textTransform: 'uppercase',
      letterSpacing: '0.04em',
      padding: '0.1rem 0.4rem',
      borderRadius: '0.4rem',
      background: 'rgba(128,128,128,0.18)'
    }}>
            {type}
          </span>
        </div>
        <div style={{
      opacity: 0.9
    }}>{caption || 'Media not uploaded yet.'}</div>
        <div style={{
      fontSize: '0.7rem',
      opacity: 0.5
    }}>
          Upload to R2 as <code>{id}.{resolvedExt}</code> — preview only, hidden in production.
        </div>
      </div>;
  }
  const mediaStyle = {
    display: status === 'loaded' ? 'block' : 'none',
    width: '100%',
    height: 'auto',
    borderRadius: '0.75rem'
  };
  const media = isVideo ? <video src={inView ? src : undefined} autoPlay loop muted playsInline preload="metadata" onLoadedData={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} /> : <img src={inView ? src : undefined} alt={caption} onLoad={() => setStatus('loaded')} onError={() => setStatus('missing')} style={mediaStyle} />;
  return <figure style={{
    margin: '1.25rem 0'
  }}>
      <div ref={boxRef} style={status === 'loaded' ? {
    width: '100%'
  } : {
    width: '100%',
    aspectRatio: ratio,
    borderRadius: '0.75rem',
    background: 'rgba(128,128,128,0.06)'
  }}>
        {media}
      </div>
      {status === 'loaded' && caption ? <figcaption style={{
    marginTop: '0.5rem',
    textAlign: 'center',
    fontSize: '0.85rem',
    opacity: 0.7
  }}>
          {caption}
        </figcaption> : null}
    </figure>;
};

**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](/concepts/assistant), and your
[workflows](/concepts/workflows-and-runs) 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](/concepts/knowledge-rag).

<MediaEmbed id="MX-MEDIA-3380" type="screenshot" caption={"The Knowledge settings page showing the list of knowledge bases with the summary stats row."} />

## Where Knowledge lives

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

<CardGroup cols={2}>
  <Card title="See every knowledge base" icon="library">
    A table of your organization's knowledge bases, with totals for documents,
    chunks, and tokens across all of them.
  </Card>

  <Card title="Create a knowledge base" icon="plus">
    Start a new, empty library and set how its documents are split for search.
  </Card>

  <Card title="Add and manage documents" icon="file-text">
    Upload files, watch them process, and retry or remove them.
  </Card>

  <Card title="Test a search" icon="search">
    Run a question against a knowledge base to preview what it returns.
  </Card>
</CardGroup>

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

## 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.

<Steps>
  <Step title="Name it">
    Choose a clear name, such as `Product docs` or `Support playbook`. You can add
    an optional description.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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](#managed-versus-your-own-storage).
  </Step>

  <Step title="Create">
    ModuleX creates the empty knowledge base and adds it to your list, ready for
    documents.
  </Step>
</Steps>

<MediaEmbed id="MX-MEDIA-3381" type="screenshot" caption={"The \"Create knowledge base\" dialog with the name, description, chunk size, and chunk overlap fields."} />

### 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 |

<Tip>
  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](/concepts/knowledge-rag).
</Tip>

## 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.

<CardGroup cols={2}>
  <Card title="Supported formats" icon="file-check">
    PDF, Word (`.docx` / `.doc`), plain text, Markdown, HTML, CSV, JSON,
    Excel (`.xlsx`), and PowerPoint (`.pptx`).
  </Card>

  <Card title="File size" icon="weight-hanging">
    The largest file you can upload is set by your **plan**, not a single fixed
    cap — see [Plan limits](#plan-limits).
  </Card>
</CardGroup>

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](/platform/knowledge/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.

<Accordion title="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](/platform/knowledge/documents).
</Accordion>

<MediaEmbed id="MX-MEDIA-3382" type="app_video" caption={"Uploading documents to a knowledge base and watching them move from processing to completed."} />

## 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.

<CardGroup cols={3}>
  <Card title="Chat with your knowledge" icon="messages-square" href="/platform/chat/knowledge-chat">
    Ask a question in chat and get an answer drawn from your documents.
  </Card>

  <Card title="The Assistant" icon="bot" href="/concepts/assistant">
    The Assistant can retrieve from your knowledge as one of the tools it uses to
    complete a task.
  </Card>

  <Card title="Knowledge node" icon="workflow" href="/workflow-builder/nodes/knowledge">
    Add a step to a [workflow](/concepts/workflows-and-runs) that retrieves from a
    knowledge base.
  </Card>

  <Card title="An external AI client" icon="plug" href="/api-reference/mcp/overview">
    Let an MCP client such as Claude Code or Cursor search your knowledge through
    ModuleX MCP.
  </Card>
</CardGroup>

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:

<CardGroup cols={2}>
  <Card title="Archive" icon="archive">
    Set a knowledge base aside without deleting it. Archiving frees a slot against
    your [plan's knowledge-base limit](#plan-limits).
  </Card>

  <Card title="Delete" icon="trash-2">
    Permanently remove a knowledge base and all of its documents and chunks.
  </Card>
</CardGroup>

## 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.

<CardGroup cols={2}>
  <Card title="Managed (modulexdb)" icon="database" href="/platform/knowledge/managed">
    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](/billing/credits).
  </Card>

  <Card title="Bring your own (BYOK)" icon="key" href="/platform/knowledge/external-providers">
    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.
  </Card>
</CardGroup>

<Info>
  **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](/billing/credits) and
  [Usage gating & limits](/billing/usage-gating).
</Info>

## 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](/api-reference/authentication)). The example below lists your
knowledge bases and creates a new one.

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```

  ```javascript JavaScript theme={null}
  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);
  ```
</CodeGroup>

Creating a knowledge base returns the new record with its `id`, which you then use
to [add documents](/platform/knowledge/documents) and run searches. For the search
and retrieval calls, see [Knowledge & RAG](/concepts/knowledge-rag); for an
end-to-end walkthrough in three languages, see
[Build a RAG knowledge base](/guides/build-a-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  |

<Warning>
  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](/billing/plans) page before relying on it. The per-upload file
  size is set by your **plan**, not a single fixed cap.
</Warning>

## Where to go next

<CardGroup cols={2}>
  <Card title="Knowledge & RAG" icon="book-open" href="/concepts/knowledge-rag">
    The concepts behind Knowledge: chunks, embeddings, ingest, and retrieval.
  </Card>

  <Card title="Managing documents" icon="files" href="/platform/knowledge/documents">
    Upload, monitor processing, retry, and remove documents.
  </Card>

  <Card title="Managed knowledge (modulexdb)" icon="database" href="/platform/knowledge/managed">
    How ModuleX-hosted vector storage and retrieval work, and what they cost.
  </Card>

  <Card title="External knowledge providers" icon="plug" href="/platform/knowledge/external-providers">
    Connect Qdrant, Pinecone, MongoDB Atlas, or Weaviate.
  </Card>

  <Card title="Chat with your knowledge" icon="messages-square" href="/platform/chat/knowledge-chat">
    Ask questions in chat answered from your documents.
  </Card>

  <Card title="Build a RAG knowledge base" icon="hammer" href="/guides/build-a-knowledge-base">
    A start-to-finish guide: create, ingest, and query.
  </Card>
</CardGroup>