> For the complete documentation index, see [llms.txt](https://docs.blockbrain.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blockbrain.ai/for-users/all-about-knowledge-management.md).
# All about Knowledge Management
This page covers everything you need to know about Knowledge Management in Blockbrain - from knowledge bases, search, sharing, configuration, and more.
### What is a Knowledge Base
A **Knowledge Base (KB)** is a searchable collection of documents. Upload your files - PDFs, Word documents, spreadsheets, presentations, images, ZIP archives, and more - and Blockbrain processes them so that AI agents, chat assistants, and data rooms can retrieve relevant information from them.
When you (or an AI agent) ask a question, Blockbrain doesn't re-read the raw files. Instead, it searches the processed knowledge base and returns the most relevant passages, tables, and images - each with a full citation back to the source document and page number.
{% hint style="info" %}
**Standard and Smart.** When you create a knowledge base you choose its type: **Standard** (the original, reliable and feature complete) or **Smart** (the newer generation with smarter document processing, first class folders, richer retrieval, and knowledge graph understanding).
{% endhint %}
#### Basic Settings
| Field | Required | Notes |
| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Knowledge base type** | Yes | **Standard** or **Smart**. You cannot change the type later, so choose it up front. |
| **Name** | Yes | Identifies the knowledge base in lists and in chat citations. |
| **Description** | No | A short note about the knowledge base's purpose. It also helps an AI assistant that has access to many knowledge bases pick the right one, even before you have added any documents. |
| **Source type** | No | How documents get in: **Upload** (the default), **SharePoint**, or **API**. |
You also choose the **embedding model** here, the model that turns text into the vectors used for retrieval. Each option shows a short description, and the picker notes that the embedding model is set at creation and cannot be changed later. Select **Create Database** to finish. You can change the name, description, and most settings afterwards with **Update Database**, but not the type or the embedding model.
#### What can a Knowledge Base be attached to?
| Attach to | What it enables |
| ----------------- | -------------------------------------------------------------------- |
| **Conversations** | The AI assistant answers questions grounded in your documents. |
| **Data Rooms** | All participants and agents in the room share the same knowledge. |
| **Bots** | A bot always has access to a specific set of documents when invoked. |
### Creating a Knowledge Base
**Where:** **Knowledge Management** section → **My Databases** → **+ New Database Source**
### Uploading Documents
#### Supported File Types
| Type | Formats |
| --------- | ------------------------------------------------------------------------ |
| Documents | PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, ODT, ODS, ODP |
| Text | TXT, MD, HTML, RTF, CSV |
| Images | PNG, JPG, JPEG, GIF, TIFF, BMP, WEBP |
| Archives | ZIP *(recursively extracted — each file inside is processed separately)* |
| Notebooks | IPYNB |
| OneNote | ONE |
How to Upload
1. Open the knowledge base.
2. Click **Upload** or drag files onto the upload area.
3. Optionally provide a **relative path** (e.g. `reports/q1/analysis.pdf`) to place the file inside a folder hierarchy automatically. Folders that don't exist yet are created for you.
4. The file is stored immediately. Processing happens in the background.
#### Large files
There is no file size you need to worry about. Small and medium files upload in one go, and larger files (including a big ZIP export, such as a whole Confluence space) are uploaded in parts automatically and reassembled for you. The progress bar reflects the whole transfer, and cancelling a large upload cleans up the partial data.
#### Uploading a ZIP
When you upload a ZIP, it appears in the list right away as a processing item, so you get immediate feedback. The archive is then unpacked in the background, and each file inside is processed on its own. The extracted files appear under a folder named after the archive (`myfiles.zip` becomes a `myfiles` folder), keeping the folder structure that was inside the ZIP. Once the files are extracted, the original ZIP placeholder disappears, because it has effectively become that folder.
Files that cannot be processed (for example a password protected PDF or an unsupported format) are marked as failed with an error message, so nothing silently vanishes. ZIPs inside ZIPs are unpacked too, and generous safety limits protect against oversized archives. If a nested archive is refused because it is too large or too deeply nested, it shows up as a failed entry that explains which limit it hit.
#### Duplicate detection
Before processing starts, Blockbrain checks whether the file has changed since you last uploaded it. If it has not, the file is skipped, so re-uploading the same file does not create duplicates. Uploading a changed version updates the document in place. To force a fresh run on an unchanged file, delete the document and upload it again.
{% hint style="info" %}
**To force re-processing** of an unchanged file, delete the document first, then re-upload it.
{% endhint %}
### Organizing with Folders
Folders let you structure a knowledge base just like a file system. In Blockbrain, folders are **first-class entities** - they have their own identity, AI-generated summaries, and can be used as a scope for search.
#### Creating a Folder
* **From the KB browser:** Click **New Folder** and enter a name.
* **During upload:** Provide a relative path like `reports/q1/` - folders are created automatically if they don't exist.
{% hint style="info" %}
Folder names must be unique within their parent directory.
{% endhint %}
#### Renaming and Moving Folders
* Right-click a folder → **Rename** or **Move**.
* All documents and subfolders inside move with it.
* Conversations, data rooms, and bots attached to the folder continue to work — attachments track the folder by **ID**, not path, so renaming or moving never breaks them.
#### Deleting Folders
Deleting a folder permanently deletes all subfolders and documents inside it. Deleted documents are removed from the KB and can no longer be retrieved.
{% hint style="info" %}
This action is permanent and cannot be undone.
{% endhint %}
#### Folder summaries
Once the documents in a folder are processed, Blockbrain writes a summary of the folder's content. The summary rolls up **both the documents directly in the folder and the summaries of its subfolders**, so a folder reflects everything nested under it. This summary:
* Appears in the browser as the folder's description.
* Makes the folder findable by concept, even for content held in a subfolder.
* Helps an AI assistant decide which folder to favour (a ranking boost, never a hard filter, so nothing outside the folder is excluded).
Moving a document or folder refreshes the summaries of the folder it left and the folder it lands in, so neither goes stale. The refresh runs in the background just after the move.
#### Finding a file or folder by name
The search box at the top of the browser finds documents and folders **by name across the whole knowledge base**, not just the folder you are in. Start typing and the list narrows to every matching file and folder, each showing its **Location**. This matches names only. Retrieval of the text *inside* your documents is what powers AI answers (see How your documents get searched).
#### Filtering
Two filters let you narrow a large knowledge base:
* **Source**: where a file came from. Values: **Upload**, **SharePoint**, **API**, **ZIP**, **Unknown / legacy**.
* **File Type**: a coarse category. Values: **PDF**, **Spreadsheet**, **Document**, **Image**, **Email**, **Video**, **Text**, **Code**, **Other**.
Each filter accepts several values, and the two combine (for example SharePoint and PDF shows only SharePoint PDFs). While a filter is active, the browser shows documents only. If nothing matches you see "No documents match these filters".
### Browsing Your Knowledge Base
The KB browser displays the full folder and file hierarchy. From here you can:
* **Navigate** into folders.
* **Preview** a document — view its extracted text and metadata.
* **Check ingestion status** — each file shows `ready`, `processing`, `pending`, or `failed`.
* **View structured tags** — if the KB extracts structured metadata, values are shown per document.
* **Delete** individual documents.
* **Retry** failed documents
### Searching Within a Knowledge Base
#### How to Search
1. Open a KB.
2. Click the **Search** tab.
3. Type a natural-language question or keyword.
Results display ranked passages showing the source document, page number, chunk text, and a relevance indicator. If enabled, a short AI-generated summary of each passage is also shown.
### Attaching a knowledge base to conversations
Attaching a knowledge base to a conversation makes its content available to the AI assistant there. When you ask a question, the assistant retrieves the most relevant passages from the attached knowledge bases and grounds its answer in them.
#### How to attach
1. Open a conversation.
2. Open its **Database Sources** panel.
3. Connect one or more knowledge bases.
4. Optionally narrow to a specific folder or document.
#### View the original page
When an answer cites a passage from a **PDF**, open the **Reference Documents** panel for that answer and use **View original page**. Blockbrain shows the source page exactly as it appears in the PDF, with the cited passage **highlighted** in place, so you can confirm the answer in its original context. This is available for PDF sources.
#### Detaching
Open the **Database Sources** panel on the conversation and disconnect the knowledge base. Your conversation history is kept. Only future questions stop using that knowledge base.
### Attaching a knowledge base to data rooms
A data room is a shared workspace. Attaching a knowledge base to a data room makes it available to everyone and every agent in that room.
Open the data room, go to its **Knowledge** section, and connect one or more of the knowledge bases you can access. You can optionally narrow to a folder or document. All conversations and agents inside the data room then share the attached knowledge automatically. Only people with edit access to the data room can connect or disconnect a knowledge base.
### Attaching a knowledge base to bots
A bot can carry knowledge bases as part of its configuration. Every conversation the bot takes part in then has access to the bot's knowledge, on top of anything connected to the conversation directly.
Open the bot's configuration, go to the **Database Sources** tab, and connect one or more knowledge bases. You can optionally narrow to a folder or document. Both bot templates and running bots support attachments. A bot created from a template inherits the template's knowledge bases, and can then add or remove its own.
### Narrowing scope: folders and files
Instead of connecting a whole knowledge base, you can narrow it to a specific folder or a single document. This helps when a knowledge base is large and only part of it is relevant, when you want a bot to see only one section, or when different data rooms need different slices of the same knowledge base without keeping separate copies.
When you connect a knowledge base you can choose:
* **Whole knowledge base** (the default): everything is in scope.
* **Folder scope**: only documents inside a chosen folder and its subfolders.
* **Document scope**: only a single document.
Retrieval is **strictly limited** to what you connected. Content in folders or files you did not connect is never searched or shown, even when it would otherwise be a strong match. You can connect several folders and files at once, and the searchable set is their combination. The file browser marks each item **Connected** so you can see exactly what is in scope. Folder scope survives a rename or move, because the attachment tracks the folder by its identity.
### Sharing a knowledge base
By default, a knowledge base is visible only to the person who created it. You can share it with other people in your organisation.
#### How to share
1. Open the knowledge base and select **Share**.
2. Under **Add people**, enter the person's name or email.
3. Choose their role.
Roles build on each other:
* **Viewer** can read the knowledge base and attach it to conversations and data rooms.
* **Contributor** can also upload, edit, and delete documents.
* **Content Manager** can additionally manage sharing (add, change, and remove other people).
Only the **Owner** can rename or reset the knowledge base, delete it, or transfer ownership. Role changes take effect immediately. A shared knowledge base appears in the other person's list under **Shared with Me** and **All**, with a **Shared By** column naming who shared it.
#### Transferring ownership
The Owner can hand a knowledge base to someone else with **Transfer Ownership**. After the transfer, the new owner has full control. The previous owner stays on as a Content Manager, so they keep managing content and sharing but can no longer delete or transfer it.
#### Revoking access
From the **Share** dialog, remove the person and confirm. They lose access right away. Any conversations or data rooms where they had connected this knowledge base keep working until the connection is removed. You cannot remove your own access, which stops you from accidentally locking yourself out.
#### Organisation-Wide KBs
Some KBs are accessible to all users in an organisation (managed by an admin). These cannot be deleted or modified by individual users.
#### Retrying
A failed or partial document can be re-queued without re-uploading the file:
* **Retry one:** use the **Retry** action on the document's row (it appears only for failed or partial documents).
* **Retry all failed:** when at least one document has failed, a button re-queues every failed or partial document in the knowledge base at once.
Common causes of failure are password protected or corrupted files, unsupported content such as encrypted PDFs, and temporary model errors that usually clear on retry. If a document keeps failing, open it to read the error message, which points to what went wrong.
### Deleting content
* **Delete a document.** Use **Delete** on the file row and confirm. The document, its searchable content, and the stored file are permanently removed. A file that is still processing cannot be deleted until it finishes.
* **Delete a folder.** Use **Delete** on the folder row and confirm. The folder and everything inside it are permanently removed in one step.
* **Reset a knowledge base.** **Reset knowledge base** deletes all documents and their content but keeps the knowledge base itself, along with its name, settings, and sharing. Anything it is attached to stays attached and simply sees an empty knowledge base. Reset is blocked while documents are still processing.
* **Delete a knowledge base.** Deleting removes the whole knowledge base. Anything that had it connected loses access, though conversation history is not affected. Only the Owner can delete.
{% hint style="info" %}
All of these are permanent.
{% endhint %}
#### Next Steps
* Find out more about [Smart Knowledge Bases](/for-users/all-about-knowledge-management/smart-knowledge-bases.md)
* Explore [Web Crawling](/for-users/all-about-knowledge-management/web-crawling.md)
---
# 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 dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.blockbrain.ai/for-users/all-about-knowledge-management.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.
