# Knowledge Bases

Knowledge bases are searchable collections of your own documents that agents can retrieve for grounded, trusted context.

---

## What Are Knowledge Bases?

A knowledge base is a named collection of documents that agents can search when answering. Instead of relying only on the model's general knowledge, an agent can pull in your product docs, runbooks, tickets, contracts, or notes and ground its response in your organization's actual content.

Each knowledge base:

- Belongs to one organization and is owned by a **user** or the **organization**.
- Holds documents from three source types — uploaded or pasted **files**, crawled **websites**, and synced **connectors** (GitHub, ClickUp, Google Drive).
- Indexes every document so it can be searched with hybrid vector + keyword search.

Prefer video? Watch a quick overview:

<iframe width="100%" height="480" src="https://www.youtube.com/embed/ZWBqTUGRTNE" title="Suger Insulin — Knowledge Bases overview" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>

![The Knowledge Base app — the knowledge base list on the left, and a detail view with the Files, Websites, and Connectors tabs (Files shown, with an indexed document and its per-row Deprecate and Delete actions)](images/09-insulin-knowledge-base.png)

## Opening the Knowledge Base App

Knowledge Base is a built-in Insulin app. Open it from the **Knowledge Base** tile pinned to the desktop dock, or navigate directly to its window. Like other workspace apps, it opens as a resizable window with the knowledge base list on the left and a detail panel on the right.

## Creating a Knowledge Base

1. Click the **+** button in the Knowledge Bases list (or **Create one** on the empty state)
2. Configure the following:

| Field | Description |
|-------|-------------|
| **Name** | A descriptive name for the knowledge base |
| **Description** | Optional summary of what it contains |
| **Visibility** | **User** (only visible to you) or **Organization** (shareable with your team). Creating an organization knowledge base requires org admin access. |
| **Embedding model** | The model used to index and search documents. The options depend on who owns the knowledge base — see [Choosing an embedding model](#choosing-an-embedding-model) below. |
| **Search mode** | **Hybrid** (recommended), **Vector only**, or **Keyword only** |

3. Click **Create**

### Choosing an embedding model

Every document is embedded with the knowledge base's embedding model, and searches use that same model. Which models you can pick depends on who owns the knowledge base:

- **Organization knowledge bases** can always use a **Suger-hosted** model — **BGE-M3** or **Qwen3 Embedding 0.6B**, served on Suger's own key with nothing to set up — plus the embedding models Suger registers for each connected organization provider: **OpenAI** (text-embedding-3-small and -large), **Gemini**, **OpenRouter** (BGE-M3), **DeepInfra** (BGE-M3, Qwen3 Embedding 0.6B), **Fireworks** (Nomic Embed v1.5), and **Together** (multilingual-e5-large-instruct).
- **User (personal) knowledge bases** can use **only** the embedding models from providers **you** have personally connected. Suger-hosted models and organization providers are never offered for a private knowledge base. If you have no personal provider connected, the picker reads *"Connect a personal AI provider to use a private knowledge base,"* and **Create stays disabled** until you connect one.

Each option is labelled with its provider, vector size, and hosting — for example `openai · 1536 dims · BYOK` or `deepinfra · 1024 dims · Suger-hosted`.

![The New Knowledge Base dialog with the owner-scoped Embedding model chooser — an Organization knowledge base showing a model labelled google · 1536 dims · BYOK](images/kb-create-embedding-model.png)

:::info
You can change the embedding model later from **Settings** — see [Changing the embedding model](#changing-the-embedding-model). Because changing it re-indexes every document, it's best to pick the model you expect to use up front.
:::

## Adding Content

Open a knowledge base to reach its detail panel, which has three tabs: **Files**, **Websites**, and **Connectors**.

### Files

Upload documents directly or paste text.

- **Upload file** — Select files, or drag and drop them onto the panel. Supported formats: PDF, DOCX, and text formats including `.txt`, `.md`, `.csv`, `.tsv`, `.log`, `.json`, `.html`, `.xml`, and `.yaml`. Maximum **25 MB** per file.
- **Paste text** — Paste raw content and give it a name. Maximum **2 MB** of text.

Uploading a file with the same name replaces the existing document in place. The file list shows each document's **Name, Pages, Chunks, Size,** and **Status**.

### Websites

Add a public URL to crawl its pages into the knowledge base.

1. Enter a URL (for example, `https://docs.example.com`)
2. Set the **Depth** — how many link levels to follow (1–10, default 3). Depth 1 is the start page only; depth 3 follows links three levels deep.
3. Click **Add**

The crawler imports up to 100 pages of main content as documents. Websites re-crawl only when you trigger a **Re-sync** manually — they do not sync automatically. The list shows **URL, Docs, Depth, Last Sync,** and **Status**, with per-row sync and remove actions.

### Connectors

Connectors keep a knowledge base in sync with issues, tasks, and files from your connected integrations. You can add **one connector per integration** per knowledge base.

| Connector | What it syncs | What you configure |
|-----------|---------------|--------------------|
| **GitHub** | Issues and pull requests as Markdown (no source code) | Repositories; toggle **Issues** and **Pull requests**; optional max items per repo |
| **ClickUp** | Tasks and Doc pages | Spaces; toggle **Tasks** and **Docs**; optional max tasks per list |
| **Google Drive** | Documents and files (Google-native docs exported to text) | Folders (synced recursively) and individual files, via search-as-you-type |

*Notion is not yet available as of July 2026 (no target date committed).*

To add a connector:

1. Open the **Connectors** tab and pick a provider card
2. If the underlying integration is not connected yet, the card shows **Set up the integration first** — connect it in **Settings**, then return
3. Click **Connect**, select the scope (repositories, spaces, or folders/files)
4. Choose whether to **Auto-sync** the connector
5. Click **Connect** to start the first sync

A connected card shows a scope summary (for example, "3 repos"), an indexed count (`Indexed items: X/Y`), and the last sync time. You can **Re-sync**, **Stop sync**, **Edit scope**, or **Remove** the connector.

:::info
Organization knowledge bases support only the **Google Drive** connector. GitHub and ClickUp connectors are available on user knowledge bases.
:::

## Syncing and Indexing

**Manual sync** — Trigger a sync, stop an in-progress sync, or re-index a single document at any time from the tab actions.

**Automatic sync** — Only connectors with **Auto-sync** enabled are kept current automatically. Insulin sweeps due connectors about once an hour: it runs a full reconcile when the last full sync was more than 24 hours ago, and an incremental sync when the last sync was more than an hour ago. Websites and individual files do not auto-sync.

As documents are added, Insulin splits each one into chunks, generates embeddings, and stores them for search. Only documents that finish indexing become searchable. Each document and connector shows a status:

| Status | Meaning |
|--------|---------|
| **Pending** | Queued, not yet processed |
| **Indexing** | Being parsed and embedded (a progress bar shows percent complete) |
| **Indexed** | Successfully indexed and searchable |
| **Failed** | Indexing or sync failed — hover the alert icon for the error |
| **Deprecated** | Retired from search but not deleted — chunks are preserved and it can be restored |
| **Deleted** | Removed from the knowledge base |

Lists refresh automatically while anything is pending, indexing, or syncing.

A knowledge base can also show a **Re-indexing** state at the whole-knowledge-base level — distinct from the per-document statuses above — while it rebuilds every document's embeddings after an [embedding-model change](#changing-the-embedding-model). Search is paused for the entire knowledge base until it finishes.

### Retiring a document

You can retire an indexed **file** without deleting it. Use **Deprecate** on an indexed file to drop it from search results while keeping its document and chunks intact, then **Restore** it later to bring it back into search — no re-upload needed. Deprecate and Restore apply to files only; website and connector documents cannot be deprecated. Deprecate is offered only once a file has finished indexing.

## Testing Search

Use **Test search** in the detail panel to preview what an agent would retrieve before attaching the knowledge base. Enter a query, set the number of results (Top K, up to **20** here), pick a search mode, and adjust the vector weight. Results show the matching content, its source document, and a relevance score.

The Test-search cap of 20 applies only to this preview. The knowledge base's persisted **default Top K** is set in Settings and can be as high as **50**, and an agent searching at query time can request up to **100** results.

## Settings

Open the **Settings** (gear) panel from a knowledge base's detail view to adjust how it is described, chunked, and searched.

| Setting | What it controls |
|---------|------------------|
| **Name** | The knowledge base's display name |
| **Description** | Optional summary of its contents |
| **Chunk strategy** | **Fixed size** or **Semantic** — how new documents are split before indexing |
| **Search mode** | **Hybrid** (vector + keyword), **Vector only**, or **Keyword only** |
| **Top K results** | The persisted default number of results (1–50) |
| **Vector weight** | For hybrid search, how much to favor vector vs. keyword matches (0–1) |
| **Embedding model** | The knowledge base's **Current model**, with a **Change model** control to switch to another eligible model (re-indexes every document — see [Changing the embedding model](#changing-the-embedding-model)) |

:::info
Changing the **chunk strategy** applies to **new syncs only**. Existing documents are not re-indexed, so a mix of chunk strategies can coexist until you re-index or re-sync a document.
:::

### Changing the embedding model

The **Embedding model** section of Settings shows the knowledge base's **Current model**. To switch it, choose another model under **Change to** and click **Change model**. The list offers only models *other* than the current one, scoped to the knowledge base's owner (see [Choosing an embedding model](#choosing-an-embedding-model)); if no other eligible model is available, the panel says so.

![The Embedding model section of Settings — the Current model, a Change to picker of other eligible models, and the Change model button that starts a re-index](images/kb-change-embedding-model.png)

Because switching is a heavy operation, Insulin asks you to confirm:

> **Change embedding model?** Switching to *&lt;model&gt;* re-indexes every document in this knowledge base. Search is paused for this knowledge base until the rebuild finishes. This can take a while for large collections.

Once you confirm:

- The knowledge base **re-indexes its documents** into the new model, and the section shows an amber **Re-indexing** badge. A document that can't be processed is marked **Failed** and skipped, so the rebuild always finishes.
- **Search is paused** for the whole knowledge base while it rebuilds. An agent that searches it during this window is told the knowledge base is re-indexing and to try again shortly, so results are never mixed across two models.
- You **can't change the model again** until the rebuild finishes.
- When the rebuild finishes, the knowledge base **switches to the new model automatically** and search resumes — no further action needed.

:::info
**Organization** knowledge bases can fall back automatically: if the selected model's provider isn't available when the knowledge base first indexes its content, it falls back to a Suger-hosted model and notes it in Settings (*"Fell back to a Suger-hosted model."*). **User** knowledge bases have no fallback — they only ever use your own connected providers.
:::

The **Danger Zone** at the bottom of Settings holds **Delete Knowledge Base**, which removes the knowledge base and all of its documents, chunks, and embeddings. This cannot be undone.

## Connecting a Knowledge Base to an Agent

Agents retrieve context by searching the knowledge bases available to them:

- **Custom agents** search the knowledge bases explicitly attached to them. In the agent's create or edit form, the **Knowledge Bases** section lists eligible knowledge bases as checkboxes — select one or more. A user-level agent can attach your user-level knowledge bases; an org-level agent can attach organization knowledge bases.
- The built-in **Insulin** assistant searches your own knowledge bases automatically. You can also pick an explicit set — see [Choosing which knowledge bases Insulin uses](#choosing-which-knowledge-bases-insulin-uses) below.

At query time an agent can search up to three knowledge bases and cites the source document for each result. See [Agents](./3.agents.md) for how to create and configure custom agents.

### Choosing which knowledge bases Insulin uses

Open **Chat**, select the **Insulin** agent, and click the pencil button in the conversation header (labelled *Insulin model settings*). Its **Knowledge Bases** section controls what Insulin can search.

By default the section shows an **Automatic** badge and Insulin searches every knowledge base you own, read-only. Ticking or unticking any row switches to an explicit selection, which then takes over completely:

| Selection | What Insulin searches |
|-----------|-----------------------|
| **Automatic** (default) | Every knowledge base you own, read-only |
| One or more ticked | Exactly the ticked knowledge bases |
| Nothing ticked | No knowledge base at all |

The list covers every knowledge base you can reach — the ones you own, plus organization knowledge bases shared with you, each marked with a **Shared** badge. Grounding Insulin in an organization knowledge base no longer requires a custom agent.

Each ticked row also carries an access mode, **Read** or **Edit**, with the same meaning as for a custom agent (see [Agents](./3.agents.md)). Choosing **Edit** only expresses intent: Suger re-checks your own role on that knowledge base immediately before every write, so picking **Edit** on one you can only read grants you nothing, and access revoked mid-conversation stops the next write.

Select **Reset to automatic** to discard the selection and go back to the default.

:::info
This selection is personal to you and applies only to the built-in Insulin assistant. Custom agents keep their own attachments, and [Inbox](./9.inbox.md) has a separate, read-only selection it uses when drafting email replies.
:::

<!-- screenshot needed: the Insulin agent panel's Knowledge Bases section — the Automatic badge, the per-knowledge-base checkboxes with a Shared badge, and the Read/Edit selector on a ticked row (app-only) -->

## Sharing and Roles

Knowledge bases follow Insulin's role-based access control.

**Your org role does not, by itself, grant access to any organization knowledge base.** Access to an org knowledge base comes only from a **per-knowledge-base share** (added as Admin, Editor, or User) or from **org-wide sharing** (as Editor or User). Even an organization admin cannot open an org knowledge base they were not shared on. Org admin access is required only to *create* an organization knowledge base — not to open existing ones.

**Knowledge base role** — Each knowledge base grants members one of four roles:

| Role | Search & read | Add / sync content | Delete & manage sharing | Transfer ownership |
|------|:---:|:---:|:---:|:---:|
| **Owner** | Yes | Yes | Yes | Yes |
| **Admin** | Yes | Yes | Yes | No |
| **Editor** | Yes | Yes | No | No |
| **User** | Yes | No | No | No |

- **User** knowledge bases are private to their creator — even organization admins cannot access them unless the knowledge base is shared with them.
- **Organization** knowledge bases start visible only to their creator (the owner). They become reachable to others only through a per-KB share or org-wide sharing, as described above.
- Ownership of an organization knowledge base can be transferred by its owner to another active member of the organization.

When you open the **Settings** of a knowledge base shared with you, they show an owner-and-role banner, and a member below **Editor** (a **User**) sees them **read-only** — including the **Change embedding model** control, which is disabled. See [Working with a Shared Resource](./1.getting-started.md#working-with-a-shared-resource).

See [Getting Started](./1.getting-started.md) for the overall Insulin roles and permissions model.

## Limits

| Limit | Value |
|-------|-------|
| File upload size | 25 MB per file |
| Pasted text size | 2 MB |
| Website crawl depth | 1–10 (default 3) |
| Website pages per crawl | Up to 100 |
| Connectors per knowledge base | One per integration type |
| Test-search results | Up to 20 |
| Persisted default Top K (Settings) | Up to 50 |
| Agent search results per query | Up to 100 |
| Knowledge bases searched per agent turn | Up to 3 |
| Knowledge bases selectable for Insulin | Up to 500 |
| Knowledge bases attached to Inbox drafting | Up to 100 |
| Knowledge bases searched per Inbox draft | Up to 3 |
| Results per knowledge base per Inbox draft | Up to 4 |

## Use Cases

- **Product support** — Crawl your public docs site and let a support agent answer with grounded, cited responses.
- **Engineering context** — Connect GitHub repositories so a code or triage agent can reference open issues and pull request discussions.
- **Project knowledge** — Sync ClickUp spaces so a project agent can answer from current tasks and Docs.
- **Team drive** — Connect a Google Drive folder of playbooks, contracts, or reports so agents work from the same source of truth your team uses.