> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/en/quickstart/knowledge-base-vs-file-library.md).

# Knowledge Base vs. File Library: How They Work and When to Use Each

For SIs, presales engineers, and implementation engineers: how knowledge bases and the file library work in MaiAgent, supported conversation channels, permissions and visibility, capacity and file for

Both knowledge bases and the file library can store documents, but they deliver data to the model in very different ways: **a knowledge base splits documents into chunks and indexes them, then passes only retrieved chunks to the model when answering; the file library stores complete original files, which the Agent reads in full using tools and can rewrite directly when needed.**

This page explains how the two work and why to choose each, for SIs, presales engineers, and implementation engineers. Customer-facing guidance, common mistakes, and a “What do I want to do → Where should I put it?” decision table are in [Knowledge Base vs. File Library: Differences in Purpose and When to Use Each](https://docs.maiagent.ai/work/file-library/vs-knowledge-base) in the user manual and are not repeated here.

***

## How They Work <a href="#how-they-work" id="how-they-work"></a>

|                                   | Knowledge Base (RAG)                                                                                                                                       | File Library                                                                                                                                                                                   |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **How data is ingested**          | Parse → Chunk → Vectorize with an Embedding model → Store in a vector database                                                                             | Store original files in object storage; documents are parsed for reading but **are not vectorized**                                                                                            |
| **What the model receives**       | The chunks most relevant to the question                                                                                                                   | The entire contents of files the Agent actively reads (long documents can be read in sections)                                                                                                 |
| **How data is found**             | Hybrid semantic and keyword retrieval (followed by reranking when Reranker is enabled for the knowledge base), with query metadata and tag filters applied | Locate files by workspace directory and filename; no semantic retrieval                                                                                                                        |
| **Whether AI can modify content** | No; administrators can edit file content in the admin console or upload files again                                                                        | Yes; the Agent can write back to, rename, move, or delete files according to the user's permissions                                                                                            |
| **Versions**                      | No version history                                                                                                                                         | All workspace changes are recorded; the latest 20 versions of file content are retained for editable formats (md, txt, sql, json, csv, docx, xlsx, pptx); other formats do not retain versions |

### Knowledge Base: Index First, Retrieve Chunks When Answering <a href="#knowledge-base-retrieval" id="knowledge-base-retrieval"></a>

Files uploaded to a knowledge base must be parsed, chunked, vectorized, and stored in a vector database before they can be retrieved. When answering, the platform retrieves chunks according to the knowledge base and Agent settings (the Agent's <mark style="color:blue;">Maximum Retrieved Chunks</mark> defaults to 12), reranks them if Reranker is enabled for the knowledge base, and passes them to the model. For the full workflow and configurable parameters, see [RAG Knowledge Base Retrieval System](https://docs.maiagent.ai/tech/en/quickstart/rag.md).

In Agent mode, knowledge bases are provided to the model as tools: the model can retrieve chunks multiple times and use `read_file` to read entire files in the knowledge base in pages (500 lines per call by default, up to 2,000 lines). Plain text files (such as `.txt` and `.md`) are read from the original file; other formats are reconstructed from parsed chunk text, with line numbers based on the reconstructed text. A knowledge base can therefore “read the whole file” too, but only after the file has been parsed and indexed. This is useful for checking details, but is not suited to serving as a workspace for extensive rewriting.

### File Library: Store Originals, Let the Agent Read and Write Entire Files with Tools <a href="#file-library-tools" id="file-library-tools"></a>

File library files are stored in their original form in file workspaces. When a workspace is attached to a conversation, the Agent receives a set of file tools:

| Tool Purpose             | Behavior and Limits                                                                                                                                    |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Browse and find files    | List workspace directories and search by filename (up to 20 results per call)                                                                          |
| Read                     | Load files into the conversation and read their contents; up to 5 files per call, with additional calls available to read more                         |
| Write                    | Write directly to `.md`, `.txt`, `.sql`, `.json`, and `.csv` files; `.docx`, `.xlsx`, and `.pptx` require Code Interpreter to be enabled for the Agent |
| Rename, move, and delete | Up to 20 files per call                                                                                                                                |

When reading content:

* **Plain text files** (txt, md, csv, json, etc.): read in full, up to 50,000 characters per call.
* **PDFs, Office files, audio files, and images**: after parsing, content is read in sections by page, slide, worksheet, or fixed chunk. Each call returns at most 10% of the model's context window, capped at 25,000 tokens; long documents are not read in full at once.
* Files cannot be read while parsing is still in progress; wait until parsing finishes.

The content read is placed in the model's context. Reading many large files in one turn may exceed the context limit, so the Agent processes them in batches. This also explains why using the file library to answer large numbers of repetitive questions can take more time and consume more usage.

***

## Supported Conversation Channels <a href="#channels" id="channels"></a>

| Conversation Channel                                                         | Knowledge Base                                    | File Library                                                                       |
| ---------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------- |
| MaiGPT                                                                       | ✅ Users can choose which knowledge bases to query | ✅ Users attach their own workspaces                                                |
| Agent's <mark style="color:blue;">Internal Conversation</mark>               | ✅                                                 | ✅ According to the Agent's <mark style="color:blue;">File Workspace</mark> setting |
| Other conversation channels, such as web Widgets, LINE, and API integrations | ✅                                                 | ❌ No reading or writing in any of these channels                                   |

A file workspace is available only when all of the following conditions are met. Otherwise, the conversation receives no file tools and cannot see workspace content:

1. The message sender is an organization member account; Contacts and anonymous visitors are not eligible.
2. The organization has the file library enabled.
3. The conversation is in MaiGPT, or in the Agent's <mark style="color:blue;">Internal Conversation</mark> with the Agent's file workspace set to something other than <mark style="color:blue;">Do Not Use</mark>.
4. The Agent's response mode is Agent mode. File tools are provided only in Agent mode; RAG Q\&A mode does not read or write workspaces (MaiGPT itself uses Agent mode).

Always put data needed by external customer service in a knowledge base.

***

## Permissions and Visibility <a href="#permissions" id="permissions"></a>

The two use different permission models: knowledge base access follows the **Agent and query conditions**, while file library access follows the **member who sends the message**.

### Knowledge Base <a href="#knowledge-base-permissions" id="knowledge-base-permissions"></a>

* Management permissions: organization owners can manage all knowledge bases; other members must be granted permissions for each knowledge base through their roles.
* MaiGPT: users can select only knowledge bases their roles allow them to read.
* Knowledge bases attached to an Agent: these apply to all conversations with that Agent, without filtering by the message sender's individual permissions. To restrict retrievable documents by user, use [Query Metadata](https://docs.maiagent.ai/tech/en/identity-and-access/zhi-shi-guan-li-quan-xian-query-metadata-cha-xun-yuan-zi-liao-zong-lan.md) or tag filters; do not rely solely on role instructions.

### File Library <a href="#file-library-permissions" id="file-library-permissions"></a>

* Permissions come from the organization's custom roles. The file library has six permissions (show file library, personal space, view organization space, edit organization space, create shared spaces, and eligibility for shared-space invitations); default roles cannot grant them. For setup instructions, see [File Library: Availability and Permissions](https://docs.maiagent.ai/work/file-library#availability-and-permissions) in the user manual.
* Spaces: <mark style="color:blue;">My Files</mark> is available only to its owner; <mark style="color:blue;">Organization Shared Files</mark> follows organization-space view/edit permissions; shared spaces are available to authorized roles. AI-generated files are saved by default to the <mark style="color:blue;">Temporary Area</mark> in the user's own <mark style="color:blue;">My Files</mark>.
* When an Agent is bound to a workspace:
  * The person configuring the binding needs edit permission for that workspace and cannot bind directly to the top level of a space.
  * Each message is evaluated against **the sender's own file library permissions**. For users with edit permission, the Agent can read and write the workspace. For users with view permission only, the Agent reads without modifying and saves outputs to their own temporary area. For users without view permission, the conversation does not reference workspace content and informs the user of this.

{% hint style="info" %}
Because the file library checks the message sender's own permissions, different colleagues asking the same workspace-bound Agent the same question may receive information from different scopes. Knowledge bases work differently: the Agent queries whatever knowledge bases are attached, unless Query Metadata further restricts the scope.
{% endhint %}

***

## Capacity and File Formats <a href="#limits" id="limits"></a>

| Item              | Knowledge Base                                                                                                                                                                                  | File Library                                                                                                                                                                         |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| File size limit   | Configurable by the platform; 100 MB by default                                                                                                                                                 | 10 MB                                                                                                                                                                                |
| Supported formats | Documents (PDF, Word, PowerPoint, Excel, CSV, ODF, EPUB, HTML, Markdown, TXT, JSON/JSONL), email (EML, MSG), images (PNG, JPG, GIF, WebP, BMP, TIFF), audio and video (WAV, MP3, M4A, AAC, MP4) | PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, CSV, TXT, MD, JSON, HTML, PNG, JPG, JPEG, GIF, WebP, MP3, WAV, M4A, MP4                                                                        |
| Other             | Read up to the first 100,000 rows of each Excel worksheet                                                                                                                                       | Folders up to 10 levels deep; batch move/delete up to 200 files per operation; retain the latest 20 versions of content for editable formats (see the table above on how they work)  |
| Online editing    | Not available                                                                                                                                                                                   | `.docx`, `.xlsx`, `.pptx` (currently SaaS only); see [Office Online Editing in the File Library](https://docs.maiagent.ai/tech/en/platform-development/onlyoffice-online-editing.md) |

***

## Billing Differences <a href="#billing" id="billing"></a>

|                | Knowledge Base                                                                                                                             | File Library                                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| On upload      | Parsing and vectorization (Embedding) are billed                                                                                           | Only parsing, such as image recognition and OCR for scanned pages, is billed; no vectorization, including for new versions                 |
| Storage        | Original file storage fees + vector storage fees                                                                                           | File library storage fees and storage fees for files derived during parsing; no vector storage fees                                        |
| When answering | Question vectorization for each retrieval and Reranker (when enabled) are billed; only chunks are sent to the model, keeping input shorter | All content read counts toward the model's input tokens; reading PDFs, Office files, audio files, or images incurs additional parsing fees |

For rates, see [Credits Billing](https://docs.maiagent.ai/others/credits) and its [File Library Storage Fees](https://docs.maiagent.ai/others/credits#file-library-storage) section in the user manual. Put simply, **knowledge bases spend on preparation to make each answer cheaper; the file library requires little preparation but incurs costs each time files are read**. Knowledge bases therefore suit frequent, repetitive Q\&A, while the file library suits occasional tasks that need complete original files.

***

## Architecture for Using Both with One Agent <a href="#use-together" id="use-together"></a>

In the <mark style="color:blue;">Knowledge and Data</mark> group of Agent settings, you can configure both <mark style="color:blue;">Knowledge Base Settings</mark> and <mark style="color:blue;">File Workspace</mark>. File workspaces have three options:

| Option                                                      | Behavior                                                                      |
| ----------------------------------------------------------- | ----------------------------------------------------------------------------- |
| <mark style="color:blue;">Do Not Use</mark>                 | Default; neither reads nor writes a workspace                                 |
| <mark style="color:blue;">Bind Workspace</mark>             | Work in a fixed workspace for both reading and output; users cannot change it |
| <mark style="color:blue;">Let Users Attach Their Own</mark> | Users choose a file workspace to attach within the conversation               |

MaiGPT always uses “Let Users Attach Their Own.” When both are configured, the Agent receives knowledge base tools and file tools in the same <mark style="color:blue;">Internal Conversation</mark> turn, and the model decides which to call based on the question. Knowledge base retrieval does not search workspace files, and file tools cannot read knowledge bases. External conversation channels and RAG Q\&A mode use only knowledge bases.

Content does not sync automatically between the two: to let an Agent use a finalized document edited in the file library for external responses, upload it to a knowledge base separately.

Three common architectures:

| Architecture               | Configuration                                                                                                                  | Suitable For                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| External customer service  | Attach only a knowledge base; set the file workspace to <mark style="color:blue;">Do Not Use</mark>                            | Q\&A on websites, LINE, and API integrations                                 |
| Project assistant          | Attach a knowledge base for policies and FAQs, then <mark style="color:blue;">Bind Workspace</mark> for original project files | A team looking up guidelines and writing documents in internal conversations |
| General internal assistant | Attach a knowledge base; set the file workspace to <mark style="color:blue;">Let Users Attach Their Own</mark>                 | Each colleague brings their own workspace                                    |

***

## Suggested Customer Explanations <a href="#talking-points" id="talking-points"></a>

When explaining the options to customers, use the following consistent framing:

> **A knowledge base is a cheat sheet for an exam; the file library is the entire textbook you keep beside you while doing homework.** Answering external questions is like taking an exam: you need a cheat sheet that helps you find answers quickly, so organizing FAQs and cleaning data takes effort. Writing internal documents is like doing homework: you need the complete original files, which are ready to use once uploaded.

Common customer follow-up questions:

* **“Do we still need a knowledge base if we have the file library?”** Yes. The file library works only in MaiGPT and the Agent's internal conversations; web Widgets, LINE, and API integrations cannot read it. Also, reading entire files for every answer makes frequent Q\&A slow and expensive.
* **“Can't a knowledge base read entire files too?”** In Agent mode, files in a knowledge base can be read in pages, but they must first be parsed and indexed. AI cannot modify them, and there is no version history. Use the file library for AI rewriting and consolidating original files.
* **“Do we need to put the same data in both?”** It depends on the use case. Maintain originals in the file library, then upload finalized documents or FAQs to a knowledge base. The two do not sync automatically.
* **“Can different departments see different data?”** The file library checks each colleague's own permissions; knowledge bases use Query Metadata or tag filters to restrict the scope.

For selection guidance and common placement mistakes, share [Knowledge Base vs. File Library: Differences in Purpose and When to Use Each](https://docs.maiagent.ai/work/file-library/vs-knowledge-base) from the user manual with customers. It includes a “What do I want to do → Where should I put it?” decision table.

***

## Related Pages <a href="#related" id="related"></a>

* [RAG Knowledge Base Retrieval System](https://docs.maiagent.ai/tech/en/quickstart/rag.md): knowledge base parsing, retrieval, and configurable parameters
* [Function Calling](https://docs.maiagent.ai/tech/en/advanced-genai-tech/function-calling.md): tool calls and execution limits in Agent mode
* [Office Online Editing in the File Library (ONLYOFFICE Docs Integration)](https://docs.maiagent.ai/tech/en/platform-development/onlyoffice-online-editing.md)
* User manual: [Knowledge Base vs. File Library: Differences in Purpose and When to Use Each](https://docs.maiagent.ai/work/file-library/vs-knowledge-base)
* User manual: [File Library](https://docs.maiagent.ai/work/file-library), [Knowledge Base](https://docs.maiagent.ai/build/knowledge-base)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/tech/en/quickstart/knowledge-base-vs-file-library.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
