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

# Review chunks and index knowledge base items

> Item statuses, how to review and edit chunks before they become searchable, index an item, regenerate it with new chunking settings, and fix failures.

Before an item is searchable, Hamsa splits it into chunks, the pieces your agent searches during a call. By default a new item stops at **Pending review** so you can check those pieces, fix them, and then index them. This page explains each status, how to review and index an item, and the chunking settings that decide how it is split.

## Before you start

* To review and index items you need permission to edit the knowledge base (Owners, Admins and Users by default).
* The item must be **Pending review**, **Completed** or **Ingestion failed**. Those are the statuses that offer **Review chunks**.

## Statuses

| Status | What it means | What to do |
| - | - | - |
| **Processing** | Hamsa is reading and chunking the item, or indexing it. | Wait. The list updates itself. You can **Cancel processing** from **Item details**. |
| **Pending review** | Chunked and waiting for you. Not searchable yet. | Open **Review chunks**, then **Index**. |
| **Completed** | Indexed and searchable. Agents can use it. | Attach it to an agent. You can still edit its chunks and index again. |
| **Cancelled** | Processing was stopped. | Add the item again if you need it. |
| **Upload failed** | The item couldn't be processed. | Check the reason, then add the item again. |
| **Reading failed** | The content couldn't be read from the file. | Check the reason and that the file opens, then add it again. |
| **Ingestion failed** | Indexing didn't finish, or processing took too long (the reason starts with "Job killed: exceeded"). | Open **Review chunks** and click **Index** to try again. If there are no chunks, click **Regenerate**, or add the item again. |

Hold the pointer over a failure to see the reason after "Failure reason:".

## Review and index an item

**1. Open the chunks**

In the item's row menu, click **Review chunks**. The editor lists every chunk with its size in tokens and any flags (below).

**2. Edit what needs it**

Edit a chunk's text in place. Use **Insert a chunk after this one** or **Add chunk** to add one, and **Delete chunk** to remove one (**Undo** brings it back). **Search chunks…** finds text across the item.

**3. Save**

Click **Save changes**.

**4. Index**

Click **Index**. The item shows **Processing** while it is indexed, then **Completed**, and the app tells you the item is searchable.

![The Review chunks editor for Price list 2026 at Pending review, with chunks and their token counts, one chunk flagged Very short, and the Save changes and Index buttons](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/knowledge-base/review-chunks-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=88fa972dd95f4957c3fe64143d235732)

**Index** is unavailable while you have unsaved edits ("Save your changes first"). If nothing changed since the last index, you see "Everything is already indexed".

You can come back to a **Completed** item at any time, edit its chunks and click **Index** again. Changed chunks show "Changes not indexed" until you do: your edits reach the agent only after you index.

### Flags

| Flag | What it means |
| - | - |
| **Possibly low value** | The chunk reads unlike the rest of the document, such as a menu, a footer or leftover formatting. Edit or delete it if it isn't useful. |
| **Very short** | Shorter than the minimum chunk size and couldn't be joined to a neighbour. Consider merging it. |
| **Too long** | Longer than the search model can read; the end would be cut off. Split it into two. |
| **Not indexed** | The last index couldn't store this chunk. Shorten or edit it and index again. |

### Limits

* A chunk can hold up to 6,000 characters.
* An item can have up to 5,000 chunks.
* One save can hold up to 500 changes.
* You can't edit chunks while the item is processing.

## Regenerate the chunks

**Regenerate** splits the item again from its original content, with the chunking settings you choose in the dialog. All your edits, saved or not, are replaced by the new chunks. Use it when the split is wrong overall, for example a FAQ that should be split by question.

![The Regenerate all chunks dialog with Chunking method, Chunk size and the switches](https://mintcdn.com/hamsa-452fa79a/Rl78D_qJIpinmg19/images/agents/knowledge-base/regenerate-chunks-light.webp?fit=max\&auto=format\&n=Rl78D_qJIpinmg19\&q=85\&s=f9daec0efa7c9f4c2c0038e6308138a6)

When you pick **AI-guided**, the dialog shows a **Preview** of how the first part of the document would be split.

## Chunking settings

You set these under **Chunking settings** when you add an item, and again when you regenerate. The defaults suit most documents.

### Chunking method

| Option | When to use it |
| - | - |
| **Smart (recommended)** | Most documents. Splits where the topic changes, inside each section. Slowest to process. Default. |
| **Paragraphs** | Fast and predictable. Groups paragraphs up to the chunk size without crossing headings. |
| **AI-guided** | Free-flowing text with no headings or clear paragraphs, such as transcripts. An AI model picks where each chunk starts and gives it a title; your text is kept as written. Slower, and no better on well-structured documents. |
| **Q\&A pairs** | FAQs and support articles: one chunk per question and its answer. |
| **Pages** | Scanned PDFs, or when answers should map to a page: one chunk per page. |
| **Fixed size** | Transcripts and unstructured text: equal pieces that end on sentence boundaries. |

When a method can't be applied, the item is split by **Paragraphs** instead: **Q\&A pairs** when no questions are found, **Pages** for files without pages, and **AI-guided** or **Smart** when their model isn't available. The editor shows the method actually used.

### Size and structure

| Setting | What it does | Default | Range |
| - | - | - | - |
| **Chunk size** | The size each chunk aims for, in tokens (about 0.75 words each in English, fewer in Arabic). Try 200 to 300 for FAQs and short answers, 600 to 800 for manuals. | 400 | 50 to 1,500 |
| **Minimum chunk size** | Smaller chunks are joined to a neighbour, or flagged for review. | 40 | 0 to 500 |
| **Maximum chunk size** | A hard limit. Longer chunks are split at a sentence boundary. | 1,800 | 100 to 1,800 |
| **Overlap** | Repeats the end of one chunk at the start of the next, inside the same section, so an answer across a boundary is still found. Capped at half the chunk size. | 0 | 0 to 300 |
| **Keep sections together** | Never splits across a heading, and adds the section title to each chunk. | On | |
| **Keep lists and code whole** | Lists, numbered steps and code blocks are never cut in the middle. | On | |
| **Split large tables by row** | Splits big tables into groups of rows, each repeating the header row. Turn off when questions compare rows across the whole table. | On | |
| **Add context to each piece** | Adds a short sentence to each chunk saying where it sits in the document. Takes longer and uses [credits](https://docs.tryhamsa.com/overview/billing.md). Not applied in previews. | Off | |
| **Review before indexing** | Stops after chunking so you can review before the item becomes searchable. | On | |

**Minimum chunk size**, **Maximum chunk size**, **Overlap** and the switches below them are under **Advanced settings**.

## Good to know

* With **Review before indexing** off, an item goes straight from **Processing** to **Completed**.
* **Cancel processing** stops an item and removes it from the knowledge base. It isn't possible once processing has finished.
* An item at **Pending review** doesn't appear when you pick items for an agent. If an agent can't find an item you added, check its status first.

## Related

> [card] [Add to the knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/add-items.md)
>
> Add text and documents.

> [card] [Knowledge base](https://docs.tryhamsa.com/agents/knowledge-base/overview.md)
>
> How agents search your items on a call.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.