# Knowledge bases

> Create a knowledge base, add websites, files, text, APIs and MCP servers, keep them fresh, connect them to agents, and fix sources that fail.

Source: https://docs.amomic.in/build/knowledge

---

A knowledge base is a named set of **sources**: your website, your documents, pasted text, your own APIs and MCP servers. Amomic-AI reads each source, splits it into **chunks**, and makes them searchable. Any agent you connect to the knowledge base answers from those chunks.

This page is the how-to for the **Knowledge** page in the console. For how a question finds its chunks, and what to do when an agent says it doesn't know, read [How retrieval works](/build/knowledge-retrieval).

**Who can do what**

| | Owner, Admin | Member |
|---|---|---|
| See knowledge bases, their sources and connected agents | Yes | Yes |
| Use the **Retrieval tester** | Yes | Yes |
| Create, rename or delete a knowledge base | Yes | No |
| Add, edit, re-sync or remove a source | Yes | No |
| Connect or disconnect an agent | Yes | No |

Members get a read-only page: the buttons for writing are not shown at all. A live API source is a tool the agent can call, so changing one is an admin decision.

**Plan limits.** Knowledge is on every plan. The number of knowledge bases you can create is capped by plan: 1 on Free, 3 on Starter, 10 on Growth, and no plan cap on Enterprise. Every workspace also has a hard ceiling of 50. Sources, chunks and crawled pages are not capped by plan. See [Limits and plans](/operate/limits).

## The Knowledge page

Open **Knowledge** in the sidebar. Each knowledge base is a card with its name, its description, how many sources it has and how many chunks they produced.

![The Knowledge page listing four knowledge bases as cards, two of them marked Dynamic, each with a source count and a chunk count](https://docs.amomic.in/screens/knowledge/list.light.webp)

*Each card shows its sources and chunks. Dynamic marks a knowledge base that changes on its own.*

A **Dynamic** badge means the knowledge base contains something that changes without you touching it: an API or MCP source, or any source with a refresh schedule. A knowledge base built only from uploaded files and pasted text never shows it.

**Chunks** are the pieces your content is split into, about 1,600 characters each. The chunk count is a quick way to tell how much the agent can actually draw on. Live API sources and MCP servers add no chunks, because they are called at answer time instead of being stored.

To delete a knowledge base, hover its card and click the trash icon. See [Delete a source or a knowledge base](#delete-a-source-or-a-knowledge-base) before you do.

## Create a knowledge base

::: steps

::: step Open the dialog

On the **Knowledge** page, click **New knowledge base**. In an empty workspace the button reads **Create a knowledge base**.
:::

::: step Name it

Enter a **Name** (required, up to 80 characters). Add a **Description** if it helps your team pick the right one later (up to 500 characters).
:::

::: step Create

Click **Create**. The console opens the new, empty knowledge base. Add your first source from there.
:::

:::

![The New knowledge base dialog with the name Installation guides and a one-line description filled in](https://docs.amomic.in/screens/knowledge/new-dialog.light.webp)

If your plan's limit is reached, the console says `Your plan includes 3 knowledge base(s). Upgrade to add more.` (with your plan's number). At the workspace ceiling it says `Knowledge base limit reached for this organization.`

**Split by topic, not by agent.** One *Warranty & service policy* knowledge base can teach your chat agent, your phone agent and your booking agent at once. That is easier to maintain than three copies.

To rename a knowledge base or change its description, open it and click the pencil next to its name. The **Edit knowledge base** dialog has the same two fields.

## Inside a knowledge base

Click a card to open it. The header shows the description, the source count and the chunk count. Sources are listed on the left. **Connected agents** and the **Retrieval tester** are on the right.

![A knowledge base with ten sources of every type and status, the Connected agents card with three connected agents, and the Retrieval tester](https://docs.amomic.in/screens/knowledge/detail.light.webp)

*Every source type on one page: websites, files, text, API sources, an action, an MCP server, one crawl in progress and one failure.*

Each source row shows:

- **Its title.** For a website this defaults to the address; for a file, the file name; for a live API source, the tool name.
- **Its type and size.** For example `Website · 142 chunks`. A live API source shows its tool name instead of a chunk count. An MCP server shows how many tools it offers.
- **↻ daily**, **↻ weekly** or **↻ monthly** when it refreshes on a schedule.
- **Key secured** when it authenticates with headers you supplied. Hover it to see the header names.
- **Action** (amber) when it can change things in your systems, not only answer questions.
- **Its status**, on the right. See [Source status](#source-status).

Hover a row to reveal its actions: edit (pencil), **Re-sync**, and delete (trash). Edit and re-sync are hidden while the source is syncing.

![A source row for a spare parts price list with its edit, re-sync and delete icons revealed on hover](https://docs.amomic.in/screens/knowledge/row-actions.light.webp)

## Add a source

Click **Add source**. The dialog has five tabs, one per source type.

| Tab | Use it for | Adds chunks | Can refresh on a schedule |
|---|---|---|---|
| **Website** | Anything already published: help centre, FAQ, policy and product pages | Yes | Yes |
| **Files** | Documents that exist as documents: a warranty PDF, a price sheet | Yes | No |
| **Text** | Facts that live nowhere else, such as the exception your team knows by heart | Yes | No |
| **API** | Data from your own systems, either stored on a schedule or fetched live mid-answer | Only when ingested | Only when ingested |
| **MCP** | An MCP server whose tools become abilities for the agent | No | No |

When a source is added, the console says `Source added — syncing now.` and the row starts showing its progress.

### Website

![The Add source dialog on the Website tab, with a website address filled in and Keep it fresh set to Every week](https://docs.amomic.in/screens/knowledge/add-website.light.webp)

| Field | What it does |
|---|---|
| **Website address** | Required. Where the crawl starts. |
| **Keep it fresh** | How often to re-crawl: **Only when I re-sync** (the default), **Every day**, **Every week** or **Every month**. See [Keep it fresh](#keep-it-fresh). |

How the crawler reads a site:

- It renders each page the way a browser does, so content that loads with JavaScript is read.
- It honours `robots.txt`.
- It reads the address you gave first. Then it reads the URLs in the site's `sitemap.xml`, then links it finds on the pages.
- It stays on the same host and its subdomains, ignoring `www.`. Starting at `veloriahome.in` also covers `support.veloriahome.in`. Starting at `support.veloriahome.in` stays on `support.veloriahome.in`.
- It skips cart, checkout and admin paths and non-page files, and treats URLs that differ only by query string (`?utm_source=…`) as the same page.
- It reads **up to 60 pages per source**. There is no page-limit, depth or include/exclude setting in the console.

::: warning A path does not fence the crawl
Starting at `https://yourcompany.com/help` does not keep the crawler under `/help`. After the start page it reads the site's sitemap, which usually lists the whole site, and follows links anywhere on the same host. On a large site, 60 pages can run out before your help pages are reached. To keep a crawl focused, start from a help-centre subdomain, or upload the documents or paste the key facts as text instead.
:::

Two addresses are refused before anything is created:

- `That doesn't look like a valid website address.`
- `That address can't be reached from the crawler.` The crawler only reaches the public internet. A staging site behind a VPN, an intranet or a private IP address can't be crawled.

While it runs, the row shows `Crawling 34/57`: pages read out of pages found so far, which grows as links are discovered.

### Files

Click **Choose files** and pick one or more files. Each uploads separately; when they are all sent, the console says `Files uploading.` and closes the dialog.

| Accepted | Notes |
|---|---|
| PDF, Word (`.docx`, `.doc`), Excel (`.xlsx`, `.xls`), CSV, TXT, Markdown, HTML | Text is extracted. Spreadsheet rows become lines of text. |
| Images: PNG, JPG/JPEG, WEBP, GIF | Read visually and turned into text, so a photo of a price board becomes usable knowledge. |

The limit is **15 MB per file**. A file that's refused shows a toast with the file name and the reason, while the others carry on:

- `Unsupported file type .pages — use PDF, DOCX, XLSX, CSV, TXT, MD or images.`
- `File is too large (max 15 MB).`
- `The file is empty.`

Files are never re-read on a schedule. When a document changes, upload the new version and remove the old one. If both stay, the agent will sometimes quote last year's prices.

::: tip Prefer the real document to a scan
A scanned PDF works, but every page has to be read visually and the chunks come out messier. If you have the original file, upload that. Save older `.doc` and `.xls` files as `.docx` and `.xlsx` first.
:::

### Text

| Field | What it does |
|---|---|
| **Title** | Optional. Defaults to `Pasted text`. A descriptive title helps retrieval: `Commercial-use exception` beats `Notes`. |
| **Content** | Required. Up to 200,000 characters. |

Text sources are where the facts that exist nowhere else belong: the escalation path, the exception you make for commercial customers, the number on the contact page that nobody answers any more. They are often the most valuable chunks you have. Keep each one to a single topic.

### API

Your own HTTPS endpoint, in one of two modes. Choose the mode first; the form changes with it.

![The API tab set to Call it live and Take an action, with method POST, an endpoint URL containing {visit_id}, an Authorization header, the tool name cancel_technician_visit and a description of when to use it](https://docs.amomic.in/screens/knowledge/add-api-action.light.webp)

*An action. The submit button reads Add action, and the source will carry the amber Action badge.*

| Mode | What happens | Submit button |
|---|---|---|
| **Ingest the response** | Fetched now, and on a schedule if you set one. The response is converted to text and stored as chunks. Use it for a product catalogue, a branch list or a rate card. | **Add source** |
| **Call it live** + **Look up data** | Never stored. Registered as a tool the agent calls mid-answer for data that changes by the minute: stock, availability, one order's status. | **Add live tool** |
| **Call it live** + **Take an action** | A tool that changes something for the customer: reschedule a visit, accept a return. | **Add action** |

| Field | What it does |
|---|---|
| **Method** | `GET` or `POST` when ingesting or looking up. `POST`, `PUT`, `PATCH`, `DELETE` or `GET` for an action. |
| **Endpoint URL** | Required, public HTTPS. For an action, put values the agent fills in inside braces: `/visits/{visit_id}/reschedule`. |
| **Headers (optional)** | See [Credentials for authenticated sources](#credentials-for-authenticated-sources). |
| **Keep it fresh** | Ingest mode only. |
| **Tool name** | Live modes, required. Letters, digits and underscores; anything else becomes `_` as you type. Use a short verb: `check_service_request`. |
| **When should the agent use it?** | Live modes. Plain words that tell the agent when to call it. For an action, be specific: this is what stops the agent acting too eagerly. |

Responses larger than 2 MB are refused. A live tool's answer is trimmed to a prompt-sized length before the agent reads it.

[Tools and actions](/build/tools) covers live tools and actions in depth: how the agent decides to call them, and the safety model for actions.

### MCP

Point at an MCP server and the tools it lists become abilities for your agent.

![The MCP tab with a server URL, an Authorization header, Look up data selected, and three allowed tool names](https://docs.amomic.in/screens/knowledge/add-mcp.light.webp)

| Field | What it does |
|---|---|
| **Server URL** | Required, public HTTPS. |
| **Headers (optional)** | Usually an `Authorization` header. |
| **What can this server do?** | **Look up data** or **Take an action**. MCP doesn't say which of a server's tools change data, so you classify the whole server once. If any of its tools change data, choose **Take an action**. |
| **Allowed tools (optional)** | Comma-separated tool names. Leave it empty to allow everything the server lists. |

Click **Connect server**. When the row shows `Connected`, its detail line tells you how many tools were found. At most 20 tools from one server are used.

There is no test-connection button on the API or MCP tabs. Add the source and watch its status: `Connected` (or `Synced ✓` when ingesting) means it worked; `Failed` shows the reason.

## Source status

| What the row shows | Meaning |
|---|---|
| `Syncing…` | Queued, or text extracted and chunks being stored. MCP tool discovery also happens here. |
| `Crawling 34/57` | Website only. Pages read out of pages found so far. |
| `Synced ✓` | Serving. Website, file, text and ingested API sources. |
| `Connected` | Serving. Live API sources and MCP servers, which store no chunks by design. |
| `Failed` | Something went wrong. The reason is printed under the row in red, and on the badge when you hover it. |

The page checks for progress every few seconds while any source is busy, so you don't need to reload.

**Re-syncs are last-good-serving.** When a source is re-read, its old chunks keep answering until the new ones are stored, then they are swapped. A re-crawl never leaves an agent briefly knowing nothing. If the re-read fails, the old chunks stay in place.

A source showing `Connected` with no chunks is working correctly.

## Keep it fresh

Websites and ingested API sources can re-read themselves. Pick the interval in **Keep it fresh** when you add the source, or later by editing it.

| Console label | Interval |
|---|---|
| **Only when I re-sync** | Never automatic. The default. |
| **Every day** | 24 hours |
| **Every week** | 7 days |
| **Every month** | 30 days |

There is no hourly option. If content changes more often than daily, use a live API source, which fetches at answer time.

- The next refresh is scheduled before a refresh starts, so a source that keeps failing retries at its next interval rather than in a loop.
- A source that is already syncing is skipped by the schedule.
- **Re-sync** on a row starts a refresh now. On a source that is already syncing the console says `This source is already syncing.`
- After a successful refresh every connected agent uses the new content straight away. On phone agents the call-time fact sheet is rebuilt too.

**The refresh safety check.** If a source that had at least 8 chunks comes back from a refresh with fewer than a quarter of them, the refresh is rejected and the old chunks keep serving. This protects you from a site redesign or a login wall silently emptying your agent's memory. The row shows `Failed` until the next successful re-read. If the content really did shrink that much, remove the source and add it again.

## Edit a source

Hover the row and click the pencil. You can change a source in place instead of deleting and re-adding it. The source keeps its identity, so a live tool stays the same tool to the agent.

| Type | Dialog | What you can change |
|---|---|---|
| Website | **Edit website source** | **Title**, **Website address**, **Keep it fresh**. A new address re-crawls the site from scratch. |
| Text | **Edit text** | **Title**, and **Replace the content**. Leave the content box empty to change only the title; the current text isn't shown. |
| File | **Rename file** | **Title** only. A file's content can't be edited; upload the new version instead. |
| API | **Edit API source** | Everything on the add form: mode, capability, method, URL, headers, schedule, tool name and description. |
| MCP | **Edit MCP server** | **Server URL**, headers, **What can this server do?**, **Allowed tools**. |

Click **Save changes**. If your edit changed what the source knows (an address, the text, a method, a header), the console says `Saved — re-syncing now.` and reads it again. If you only changed metadata such as a title or a description, it says `Source updated.`

A source that is still syncing can't be edited. The dialog says `This source is still syncing. Once it finishes you can edit it.`

![The Edit API source dialog showing two saved headers with masked values marked unchanged, one of them renamed, and the hint that renamed headers keep their saved value](https://docs.amomic.in/screens/knowledge/edit-api.light.webp)

## Credentials for authenticated sources

API and MCP sources can send up to 10 HTTP headers: an API key, a bearer token, a client id.

- Header values go straight to encrypted secret storage when you save. They are never shown again, in the console or anywhere else. The console keeps only the header names and shows **Key secured** on the row.
- When you edit the source, saved headers show `•••••••• unchanged`. Leave the value empty to keep it. Type a new value only when you are replacing the credential.
- **To fix a mistyped header name**, rename the row and leave its value empty. The saved value moves to the new name: `Renamed headers keep their saved value — you don't need to re-enter it.`
- To remove a header, click the × on its row.
- The form checks each row: `"X Key" isn't a valid header name.`, `Enter a value for Authorization.`, `Two headers have the same name.`, `At most 10 headers.`
- Authentication is header-based only. There is no OAuth flow and no client certificates.

If a stored credential goes missing, the source reports `This source's credentials are missing; re-enter them on the source.` Edit the source and type the value again.

## Connect agents

**An agent answers only from knowledge bases connected to it.** Creating a knowledge base doesn't teach any agent anything. There is no workspace-wide pool.

The **Connected agents** card lists every agent in the workspace, each marked **Live** or **Draft**. **Live** here means the agent's web chat widget is live. An agent that answers only on WhatsApp or the phone reads **Draft**, even while it is taking calls, so check the agent's **Deployments** tab for where it really runs. Click **Connect** or **Disconnect**. You can also attach a knowledge base from the agent's own **Knowledge** tab; see [Agents](/build/agents).

::: warning Connecting and disconnecting take effect immediately
Connect a knowledge base and the agent answers from it on its very next message, on every channel it is deployed to. Disconnect it and the agent stops using it just as quickly. This is true from the agent's **Knowledge** tab too, even though that tab talks about publishing a version: the change is already live when you click. Use the [Retrieval tester](/build/knowledge-retrieval#the-retrieval-tester) and the agent's test chat before you connect a new knowledge base to a live agent.
:::

The same knowledge base can teach several agents. That is the usual shape: one policy knowledge base connected to your chat agent, your phone agent and your booking agent.

**Built-in knowledge.** When you add sources while setting up a web chat widget, they go into a knowledge base named after the agent, such as *Veloria Support knowledge*. It works like any other knowledge base, but it can't be disconnected from its own agent: `This is the bot's built-in knowledge — delete its sources instead of disconnecting.`

Members see the same card with **Connected** or **Not connected** badges instead of buttons.

![The same knowledge base seen by a member: no Add source button or row actions, and Connected or Not connected badges in the Connected agents card](https://docs.amomic.in/screens/knowledge/member-view.light.webp)

*A member's view. Everything is visible and the Retrieval tester works, but nothing can be changed.*

## Delete a source or a knowledge base

::: danger Deleting is immediate, for every agent
Removing a source takes its chunks out of every connected agent's memory at once. The confirmation says how many, for example: *That takes 104 chunks out of your agent's memory. Re-adding the source means crawling it again.* Click **Remove source** to confirm.

Deleting a knowledge base (**Delete** in the confirmation) stops all its chunks serving every connected agent immediately, and its sources are gone. There is no undo for either.
:::

If you only want an agent to stop using a knowledge base, **Disconnect** it instead. The knowledge base and its sources stay intact.

## Limits

| Limit | Value |
|---|---|
| Knowledge bases per workspace | Free 1, Starter 3, Growth 10, Enterprise no plan cap; 50 hard ceiling |
| Knowledge base name / description | 80 / 500 characters |
| Pages per website crawl | 60 |
| File size | 15 MB per file |
| Pasted text | 200,000 characters per source |
| Chunks per source | 1,500 |
| API response size | 2 MB |
| Tools used from one MCP server | 20 |
| Headers per source | 10 |
| Shortest refresh interval | Daily |

## Troubleshooting

| What you see | Why | What to do |
|---|---|---|
| `That address can't be reached from the crawler.` when adding | The address isn't on the public internet. | Use the public address, or upload the documents instead. |
| `Couldn't read any pages from that website.` | The site was reached but no page could be read, often because it blocks automated visitors. | Allow the crawler, or upload or paste the content. |
| `We reached the site but couldn't read any text on it. …` | The pages are images, an unusual embed, or behind a login. | Paste the content as text or upload the documents. |
| `Couldn't reach the endpoint. Check the URL and try again.` | The API didn't answer. | Check the URL and that it's publicly reachable over HTTPS. |
| `The endpoint response is too large (max 2 MB).` | The response is over the limit. | Return a smaller, filtered response, or use a live tool. |
| `The endpoint returned no readable content.` | The response was empty or unreadable. | Check the endpoint returns JSON or text with content. |
| `Couldn't reach the MCP server. Check the URL and try again.` | The server didn't answer. | Check the URL and that it's public. |
| `The MCP server rejected our credentials (401).` | The header is wrong or expired. | Edit the source and re-enter the header value. |
| `Our AI provider was busy. Re-sync to try again.` | A temporary capacity limit while processing. | Click **Re-sync** in a minute. |
| `Something went wrong while processing this source.` | Processing failed. After a scheduled refresh this is also what the [refresh safety check](#keep-it-fresh) looks like. | Click **Re-sync**. If a refresh keeps failing because the content shrank, remove and re-add the source. |
| A source is `Synced ✓` but has very few chunks | Most pages had little readable text, or the crawl spent its 60 pages elsewhere. | Check the pages in a browser, and see [the crawl warning](#website). |
| The agent still doesn't know something | Usually retrieval, not the source. | Follow [When the agent says it doesn't know](/build/knowledge-retrieval#when-the-agent-says-it-doesn-t-know). |

## Where to go next

::: cards

::: card How answers are found
[How retrieval works](/build/knowledge-retrieval): search, the retrieval tester, and fixing "I don't know".
:::

::: card Turn a source into an ability
[Tools and actions](/build/tools): live API sources, MCP servers, and the difference between reading and doing.
:::

::: card Tune the agent that reads it
[Agents](/build/agents): purpose, instructions, and the grounding policy.
:::

:::