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:

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:

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 any embedding model from an OpenAI or Gemini provider your organization has connected.
• 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.

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.

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.

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:

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

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); if no other eligible model is available, the panel says so.

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

Change embedding model? Switching to <model> 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.

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 automatically searches your own user-level knowledge bases. To ground an agent in an organization knowledge base, attach it to a custom agent.

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

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:

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

See Getting Started for the overall Insulin roles and permissions model.

Limits

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.