> For the complete documentation index, see [llms.txt](https://docs.uptiq.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.uptiq.ai/task-guides/create-a-knowledge.md).

# Create a knowledge

Every Knowledge task, from describing a knowledge base to syncing files, testing answers, and attaching it to an agent.

This guide is organized by task. Find what you want to do in the list below, then follow the steps.

A **knowledge base** turns source documents into content that agents can query. Qore builds a table of contents, tags, and embeddings from your files. A **dataset** is a named group of source files that one or more knowledge bases can use.

| Task                                           | Go to                                                                |
| ---------------------------------------------- | -------------------------------------------------------------------- |
| Create a knowledge base by describing it       | [Create from a prompt](#create-a-knowledge-base-from-a-prompt)       |
| Start from a ready-made template               | [Start from a template](#start-from-a-template)                      |
| Build it from files I attach                   | [Attach files](#build-it-from-files-i-attach)                        |
| Build it from datasets I already have          | [Use datasets](#build-it-from-existing-datasets)                     |
| Build knowledge while building an agent        | [From an agent](#build-knowledge-from-the-agent-builder-or-operator) |
| Group source files for reuse                   | [Create a dataset](#create-a-dataset)                                |
| Add files to a dataset                         | [Add files](#add-files-to-a-dataset)                                 |
| Add a website's content                        | [Crawl a website](#crawl-a-website)                                  |
| Replace a file with a newer one                | [Upload a new version](#replace-a-file-with-a-new-version)           |
| Find which dataset holds what I need           | [Discovery](#find-which-dataset-holds-what-i-need)                   |
| Change a knowledge base by chatting            | [Change it](#change-a-knowledge-base-by-chatting)                    |
| Bring new or changed files into the knowledge  | [Sync files](#sync-files)                                            |
| Keep a dataset in sync automatically           | [Auto sync](#turn-on-auto-sync)                                      |
| Fix files that failed or need attention        | [Fix issues](#fix-files-that-need-attention)                         |
| Remove a file or dataset from a knowledge base | [Detach or delete](#detach-or-delete-a-file)                         |
| See how the knowledge base changed             | [Versions](#see-knowledge-versions)                                  |
| Check what Qore extracted from a document      | [Inspect a document](#check-what-qore-extracted)                     |
| Ask the knowledge base questions               | [Try Knowledge](#test-the-knowledge-base)                            |
| Compare answers between versions               | [Compare versions](#compare-answers-between-versions)                |
| Give an agent the knowledge base               | [Attach to an agent](#attach-it-to-an-agent)                         |
| Share a knowledge base                         | [Share it](#share-a-knowledge-base)                                  |
| Find one of my knowledge bases                 | [Find knowledge](#find-one-of-my-knowledge-bases)                    |
| Delete a knowledge base                        | [Delete it](#delete-a-knowledge-base)                                |

***

## <i class="fa-book">:book:</i> Start a new knowledge base

Select **Knowledge** in the Console sidebar. **Create New Knowledge** sits at the top, and **MY KNOWLEDGE** lists the project's knowledge bases below it.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-3b39c294803ab40a8f0025e242f2c6df9170791a%2F020_knowledge_landing_cards.png?alt=media" alt="The Knowledge page: Create New Knowledge with a Describe what this knowledge should hold… prompt, a + button and a Datasets selector, three suggestion chips, and MY KNOWLEDGE below as a grid of cards, each with a name, description, Last updated time, a play button and a ⋮ menu; All Datasets sits top right"><figcaption><p>Knowledge.</p></figcaption></figure>

### Create a knowledge base from a prompt

{% stepper %}
{% step %}

#### Describe the knowledge

In **Describe what this knowledge should hold…**, describe what the knowledge base should cover.
{% endstep %}

{% step %}

#### Add a source

Attach files with **+**, or choose datasets with **Datasets**. See the next two sections.
{% endstep %}

{% step %}

#### Send it

Select the send arrow. Qore sets up the knowledge base from your description.
{% endstep %}
{% endstepper %}

You don't need a dataset first. Describing the knowledge and attaching files in one step is the normal path.

### Start from a template

Select a suggestion chip below the prompt, then edit its description before you send it.

### Build it from files I attach

Select **+** in the prompt to attach files from your computer, a cloud drive, or a website. When you give several website URLs, Qore creates a dataset for each.

### Build it from existing datasets

Select **Datasets** in the prompt, then choose the datasets. Type in **Search datasets…** to find one, or select **+ Create Dataset** to make a new one.

### Build knowledge from the Agent Builder or Operator

* **Agent Builder** — the builder chat can create a knowledge base, add the files you attach to a dataset, sync it, and attach the result to the agent you're building. See [Attaching Knowledge to an Agent](/console/agent-builder/build/attaching-knowledge-to-an-agent.md#build-knowledge-from-the-agent-builder-chat).
* **Console Operator** — ask it for a knowledge base, or give it a URL to build one from a website's content. See [Use the Console Operator](/task-guides/use-the-console-operator.md#build-an-app-agent-or-knowledge-base).

***

## <i class="fa-database">:database:</i> Datasets and files

Select **All Datasets**, top right on the Knowledge page, to manage datasets.

### Create a dataset

Select **Create Dataset**, then enter:

* **Name** — required.
* **Description** — optional. Use it to tell similar datasets apart.
* **Source Assets** — optional. Add them now or later, from **Upload**, **Cloud storage**, or **Website**.

Uploads can be up to 15 MB per file, and up to 25 files at once. **Cloud storage** adds files from **Google Drive**, **OneDrive**, or **SharePoint**.

### Add files to a dataset

Select **Upload files to dataset** for the dataset, then use **Attach Files** to upload, choose a cloud provider, or add a website.

New files show **Ready to sync**. They don't contribute to answers until you sync them.

### Crawl a website

In **Attach Files**, choose **Website**, then set:

| Setting           | Default | Range     |
| ----------------- | ------- | --------- |
| **Website URL**   | —       | Valid URL |
| **Maximum pages** | `25`    | `1`–`200` |
| **Link depth**    | `2`     | `1`–`10`  |

Select **Start crawl**. Crawling runs in the background, and the crawled site is added as one file.

{% hint style="warning" %}
Set the page limit before you start. A crawl that reaches its limit holds only part of the site.
{% endhint %}

### Replace a file with a new version

Select **⋮** on the file, then **Upload new version**, and choose the replacement from your computer, Google Drive, OneDrive, SharePoint, or a website. The file keeps its name and gets the next version number. **Version history** lists earlier versions.

{% hint style="warning" %}
Changes in Google Drive, OneDrive, or SharePoint don't sync on their own. Upload the new version, then sync it.
{% endhint %}

### Find which dataset holds what I need

Files are indexed for discovery, which searches by meaning, not by name.

* On a dataset's page, use **Search this dataset**.
* In the Knowledge Builder chat or the Agent Builder chat, ask for it in your own words.

Only files marked **Discoverable** are found. A file still **Preparing for discovery** doesn't appear yet.

***

## <i class="fa-book-open-reader">:book-open-reader:</i> Work on a knowledge base

Select a knowledge base in **MY KNOWLEDGE** to open it. The chat is on the left, and the knowledge base's **Datasets** and **Content** tabs are on the right, with the version menu (**vN ▾**), **+ Attach**, and **▷ Try Knowledge** above them.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-491dd87a09edef3945934f3a269541a72315a904%2F006_knowledge_base_datasets_view.png?alt=media" alt="A knowledge base on the Datasets tab: a summary of 4 of 19 files attached, 13 ready to sync and 2 failed, a 3 files need attention banner with Review, a search box, a Needs attention filter, Sync 13 ready files, and datasets with their files, versions, discovery and sync statuses; the chat is on the left"><figcaption><p>A knowledge base, on the Datasets tab.</p></figcaption></figure>

### Change a knowledge base by chatting

Type in **Type here…** to add sources or change the knowledge base's scope. Each reply shows its credit usage. To switch to another knowledge base, select the name at the top of the chat.

### Sync files

A knowledge base changes only when you sync. Each file that syncs creates a new knowledge version, and agents use the latest completed version. On the **Datasets** tab, choose the scope:

* **Sync ready files** — every ready file across the knowledge base.
* **Sync N ready** on a dataset — only that dataset's ready files. **Re-sync all** when none are ready but the dataset needs syncing again.
* The dataset's **⋮** menu — **Sync all preprocessed files**, **Force re-sync everything**, or **Retry failed files only**.

{% hint style="info" %}
A completed sync is live. There's no draft or publish stage. Check important updates in [Try Knowledge](#test-the-knowledge-base) first.
{% endhint %}

### Turn on auto sync

On the dataset's **⋮** menu, enable **Auto sync**. New eligible files then sync without manual action.

### Fix files that need attention

A banner such as *3 files need attention — 2 failed, 1 stale* appears when files failed or a newer version is available.

{% stepper %}
{% step %}

#### Review the items

Select **Review**, or filter by **All**, **Needs attention**, **Ready to sync**, **Processing**, or **Synced**.
{% endstep %}

{% step %}

#### Check the error

Select a failed file to see its error and the stage that stopped, such as `TOC_GENERATION`.
{% endstep %}

{% step %}

#### Retry or replace

Select **Retry**, or **⋮** › **Retry failed files only** on the dataset. When retries run out, **Retry** is unavailable: correct the source file, then upload a new version.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
For a provider rate limit, wait before retrying. An immediate retry usually meets the same limit. Qore also retries automatically within two hours.
{% endhint %}

### Detach or delete a file

Select **⋮** on the file.

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-f9a283fd5cbdf2f6019c7cfb11479eb22e94c86e%2F010_file_actions_menu.png?alt=media" alt="The file ⋮ menu open on a Datasets tab row: View document, Upload new version, Version history, View extracted content, Download original, Detach from knowledge and Delete from dataset"><figcaption><p>The file actions menu.</p></figcaption></figure>

* **Detach from knowledge** — removes the file from this knowledge base only. It stays in the dataset.
* **Delete from dataset** — removes the file from the dataset.

To stop using a whole dataset, select its **⋮**, then **Detach dataset**.

### See knowledge versions

Select **vN ▾** to see each knowledge version, newest first, and what created it. Version numbers only increase. You can query earlier versions in Try Knowledge, but you can't make an earlier version current.

### Check what Qore extracted

On the **Content** tab, select a document, then a view:

* **Content** — the sections Qore found, in document order, each with its chunk count.
* **Tags** — labels in the form `NAMESPACE:VALUE`, such as `DOCUMENT_TYPE` or `SECTION_TYPE`.
* **Raw extraction** — the plain text Qore read. Select **Download** to save it.
* **Summary** — a short description of the whole document.

You can also open a dataset file with **⋮** › **View extracted content**. See [Document processing](/console/knowledge/document-processing.md).

***

## <i class="fa-magnifying-glass">:magnifying-glass:</i> Test and use

### Test the knowledge base

{% stepper %}
{% step %}

#### Open Try Knowledge

Select **▷ Try Knowledge** in the knowledge base, or **▷** on its card in **MY KNOWLEDGE**.
{% endstep %}

{% step %}

#### Ask a question

Type a question in the wording your users would use, and send it.
{% endstep %}

{% step %}

#### Check the evidence

Open **Execution Report**, then select the answer's **Evaluation Report**. **Knowledge Chunks and Citations** lists the chunks behind it, most relevant first, each with its rank, title, **Score** from `0` to `1`, and tags.
{% endstep %}
{% endstepper %}

<figure><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-68b78c43241b58b024d89bb36840dcc879236afa%2F015_try_knowledge_chunks_citations.png?alt=media" alt="Try Knowledge: the v6 version menu and a refresh icon above a conversation with Evaluation Report on each answer, and on the right Knowledge Chunks and Citations listing ranked chunks, each with a score and tags"><figcaption><p>Try Knowledge, with the chunks behind an answer.</p></figcaption></figure>

Try Knowledge answers from the selected version only. It doesn't use agent instructions, tools, or other knowledge. To clear the conversation and start again, select the refresh icon.

### Compare answers between versions

In Try Knowledge, select a version from the version menu, then ask the same question. The selection affects only this test. Agents always use the latest version.

### Attach it to an agent

In the agent's builder, select **+ Add Knowledge** on the **Knowledge** card. See [Create an agent › Add knowledge](/task-guides/create-an-agent.md#add-knowledge).

### Share a knowledge base

Each knowledge base has its own URL. Anyone opening it needs access to the same project.

***

## <i class="fa-folder-gear">:folder-gear:</i> Manage your knowledge bases

### Find one of my knowledge bases

* Type part of the name or description in **Search knowledge…**. It doesn't search document contents.
* Use the list and grid icons to switch views.

### Delete a knowledge base

Select **⋮** on its card, then delete it.

{% hint style="danger" %}
Deleting a knowledge base can't be undone. It removes the table of contents, tags, and embeddings. The source files stay in their datasets.
{% endhint %}

***

## <i class="fa-triangle-exclamation">:triangle-exclamation:</i> Common issues

* **The agent still gives the old answer after I uploaded a new version.** The new version isn't synced. Sync it on the **Datasets** tab.
* **A file shows Sync failed.** Select it to see the error and the stage that stopped, then retry or upload a corrected version.
* **Processing failed with "The provider rate limited the request".** Wait before retrying. Repeated failures across knowledge bases usually mean a tenant-wide throttle; check with your administrator.
* **Search doesn't find text inside my documents.** Search matches names and descriptions. Use Try Knowledge, or discovery, to search by content.
* **Try Knowledge answers differently from my agent.** Try Knowledge uses only the selected version, with no agent instructions or tools.

***

## <i class="fa-link">:link:</i> Related pages

* [Knowledge](/console/knowledge.md), [Datasets](/console/knowledge/datasets.md), and [Sync & versions](/console/knowledge/sync-and-versions.md)
* [Try Knowledge](/console/knowledge/try-knowledge.md), [Document processing](/console/knowledge/document-processing.md), and [Knowledge: FAQs & Troubleshooting](/console/knowledge/faqs.md)
* Use the knowledge: [Create an agent](/task-guides/create-an-agent.md)

***

{% columns %}
{% column width="83.33333333333334%" %}

<p align="right"><em>Maintained by</em> <mark style="color:green;">Abhishek Paul</mark><br><code>AI-assisted, human-approved</code></p>
{% endcolumn %}

{% column width="16.666666666666664%" %}

<div align="left"><img src="https://1326225582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0qmgQjJ5aArDTj2ACFHG%2Fuploads%2Fgit-blob-d034645b4f8f8ee661985f5306b60ded3289653c%2Fmaintainer-abhishek-paul.png?alt=media" alt="" width="60"></div>
{% endcolumn %}
{% endcolumns %}


---

# 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.uptiq.ai/task-guides/create-a-knowledge.md?ask=<question>&goal=<endgoal>
```

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