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

# Set up the Company Brain

> Brains, collections, live and custom sources, settings, learned facts, the access log, and self-hosted and hybrid installs, in Platform > Agents > Knowledge.

Admins manage the [Company Brain](https://docs.xpander.ai/use/company-brain.md) in **Platform > Agents > Knowledge**. A **Needs you** strip at the top lists learned facts waiting for approval and sources agents cannot read yet.

![Knowledge page with a Needs you strip (2 learned facts waiting, Review) and the areas Collections, Sources, Brains, Learned facts, Access log and Settings with their statuses](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-knowledge-page.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=0d5ae3923a145ce5431fbb9fa0c71f21)

Platform > Agents > Knowledge: the Needs you strip above the six areas, each with its status. Shown with sample data.

Organization admins manage everything here. A role with view access to the **Knowledge** area sees every area read-only. The access log, the speed figures and flushing the cache are for organization owners and admins.

## Brains

The Company Brain is built in and on every agent. A specific brain, such as Legal, holds only the collections and source paths you pick and serves only the agents it is attached to.

> [accordion] The Company Brain and a specific brain compared
>
> | | The Company Brain | A specific brain |
> | - | - | - |
> | Created by | Built in, one per organization | An admin, with **New brain** in the Brains panel |
> | Holds | Every connected source, collections shared with everyone, approved facts | The collections and source paths you pick |
> | On which agents | Every agent, unless switched off for one | Only the agents it is attached to |
> | Whose access it uses | Always each person's own | Each person's own, or shared agent access |
> | Can be deleted | No | Yes. Agents it was attached to stop using it. Its collections and sources stay |

### Create a specific brain

**1. Describe it**

In **Brains**, select **New brain** and fill **Name** and **What it's for**. Agents use the description to decide when to ask this brain, for example "Contracts, matters and legal policy. Use for anything about terms, liability or clients." The **Owner** approves learned facts proposed for it and keeps its contents current.

**2. Pick what it holds**

Under **Collections**, pick collections. Under **Connected sources**, pick sources and, optionally, narrow each to a path such as `/sites/legal`. A brain can narrow a source, never widen it.

**3. Set access**

Under **Access and sharing**, set **Whose access it uses** (below). Under **Who can attach it**, pick the groups that may add it to their agents; with none picked, anyone who manages knowledge can. Select **Create brain**.

![Legal brain card with Name, What it's for, Collections chips, Connected sources with a /sites/legal path for SharePoint, Owner, and Access and sharing with Whose access it uses set to Each person's own and Who can attach it](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-brain-editor.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=e68f967ccee135ec73f533c9582a029b)

A brain opened from Brains: what it is for, the collections and connected sources it searches, its owner, and under Access and sharing whose access it uses and who can attach it. Shown with sample data.

### Whose access it uses

* **Each person's own** (default): each person gets only what they can open. Use it for any agent your own people sign in to.
* **Shared agent access**: anyone using an agent this brain is attached to can read its collections, signed in or not. Use it for public, embedded and community agents. Connected sources are left out, because they need each person's own sign-in. To include a folder's files, [keep a copy](#keep-a-copy-of-a-folder) of it.

## Collections

A collection is a set of documents stored in xpander, with an owner and an audience (**Who can read it**). Select **New collection** in the page header to create one.

![Collections panel on the Legal playbooks tab with Add documents and four documents showing Ready, Review overdue and Processing statuses](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-collections.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=31a69c72e78e8efb10a26f19a4f2e1f8)

The Collections panel: one tab per collection, who can read it, and each document with its owner, access, version and status. Shown with sample data.

> [accordion] Create a collection, add documents, versions and delete
>
> Documents are split into sections with their heading path and page number, so agents cite them down to the page.
>
> 1. Select **New collection** in the page header.
> 2. Fill **Name** and **What it holds**.
> 3. Under **Who can read it**, choose **Everyone in the organization**, or pick people and groups. Each document can narrow this further.
> 4. Turn on **Let others who can read it add files** to let anyone in the audience add documents. Off, only the owner and admins add files.
> 5. Select **Create collection**. The **Add documents** card opens next.
>
> **Add documents** takes three kinds of content:
>
> * **Upload**: drop files or choose them. PDF, Word, PowerPoint, Excel, Markdown, HTML or images, up to 25 MB each. Scans are read with OCR.
> * **Paste**: a **Title** and the **Text**.
> * **From a URL**: the **Address** of a public page, and an optional **Title** (the address is used when it is empty). Addresses inside your network are refused.
>
> ![Add documents card for Legal playbooks with the Upload, Paste and From a URL tabs and a Choose files button](https://mintcdn.com/xpanderai-099931d1/PE_rYtMHQe3CXVP1/images/use/company-brain/company-brain-add-documents.png?fit=max\&auto=format\&n=PE_rYtMHQe3CXVP1\&q=85\&s=acffb83db98ccb5b3bbd8feb8144cfe7)
>
> Add documents on a collection: Upload, Paste or From a URL. Shown with sample data.
>
> Each document goes **Waiting**, **Processing**, then **Ready**, usually within a minute or two. **Failed** shows the reason.
>
> **The document card.** A document past its **Review by** date shows **Review overdue**. The chunk preview shows how the document was split, with the heading path and page each answer cites. **Only some people**, under **Who can read it**, limits one document to named people and groups inside the collection's audience. An access change applies on the next question, with nothing parsed again.
>
> **Versions.** **New version** adds an upload, paste or URL as the next version. Only the current version is searched, and the previous one keeps answering until the new one is ready. **Make current** (for example **Make v3 current**) rolls back to an older version. If it needs re-indexing first, the current version keeps answering until it is ready.
>
> **Share and delete.** **Edit collection** changes its name, description and **Who can read it**. **Delete collection** removes every document and version, and brains that hold it stop finding them.

## Sources

Each live source shows its status and how many people signed in.

![Sources panel with Add source and rows for Collections (built in), Google Drive, SharePoint, Confluence and Jira marked Ready with signed-in counts](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-sources.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=bda79aeddb536fa3f1020877feff5bc1)

The Sources panel: the built-in collections, then each live source with its status, how many people signed in, and who can read it. Shown with sample data.

### Add a source

**1. Pick the type and connection**

In **Sources**, select **Add source** and pick Google Drive, SharePoint, OneDrive, Confluence, Jira or [Notion](#notion) under **Type**. Under **Connection**, choose the connection people sign in through. It is used only to send each person to their own sign-in.

**2. Name it**

Under **Name**, enter a name people recognize, such as "Legal SharePoint". It appears in citations, the access log and each person's sources. Select **Add source**.

**3. Set its scope**

On the card's **Scope** tab, choose what the brain may read, and select **Save scope**.

![Add source dialog with Type SharePoint, Connection SharePoint (each user signs in), Name Legal SharePoint, and the Add source button](https://mintcdn.com/xpanderai-099931d1/PE_rYtMHQe3CXVP1/images/use/company-brain/company-brain-add-source.png?fit=max\&auto=format\&n=PE_rYtMHQe3CXVP1\&q=85\&s=1bdfc03086f841df0f31530283029613)

Add source: the type, the connection each person signs in through, and the name people see. Shown with sample data.

### Each person signs in once

There is no shared or service account. Each person connects once, from **Settings > Knowledge** in xpander Chat, the source's **Scope** tab, or **Connect** under an answer that skipped the source. Until then, the brain skips that source for them. SharePoint and OneDrive first need [Microsoft tenant admin consent](#troubleshooting-and-faq).

### Scope

The brain still reads only what each person can open.

* **All the user can see**: everything the person can open. Best for wikis and ticket systems.
* **Only what you pick**: only what is under **Include**. Best for file drives, where personal drives add noise.

An item outside the scope is never returned, even to someone who can open it. **Test as a user** runs a **Question** as a **Person** you pick and lists what the brain **Would read** and what was **Left out by the scope**, with reasons.

> [accordion] Include, exclude, users' own files and Test as a user
>
> **Include** opens a picker that browses the source with your own account (for example **Choose shared drives and folders** or **Choose spaces**): shared drives, sites, libraries, folders, spaces, projects or files. Tick what agents search, or use **Add by path**. **Leave out places** under **Exclude** ticks what to leave out.
>
> ![Scope tab with the modes All the user can see and Only what you pick, an Include section with the Choose shared drives and folders button, Exclude with Leave out places and Add rule, Let users add their own files, and Save scope](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-scope.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=83c2feb13d89a290df47f7f15dbd5543)
>
> The Scope tab of a Google Drive source with Only what you pick and nothing picked yet. Shown with sample data.
>
> ![Choose what Google Drive reads dialog with Include and Exclude tabs, a search box, two ticked shared drives, My Drive, Add by path, and Cancel and Done](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-scope-picker.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=4576c276a460b7bd5f59495f0bc6c69a)
>
> The picker: shared drives come first; tick what agents search, or switch to Exclude to tick what they leave out. Shown with sample data.
>
> **Exclude** rules apply in both modes: **Path**, **Label** (for example Confidential), **File type** (for example `xlsx`) or **Modified date** (older than a number of months).
>
> The scope is applied to the query and checked again on every result and read.
>
> **Let users add their own files** (Google Drive, SharePoint and OneDrive) lets each person share single files with the brain through the Google or OneDrive picker. Only the picked files are shared, and exclude rules still apply to them.
>
> ![Test Google Drive as a user dialog with Person, Question, a Would read list of two files and a Left out by the scope list naming an excluded path and a Confidential label, and Run again](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-test-as-user.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=c1a88047f0e40eb769f175f7aa2e8c1b)
>
> Test as a user on a Google Drive source: two items would be read, two were left out by the scope with the reason. Shown with sample data.

> [accordion] Source status, Connection tab, sensitive sources and cache
>
> **Source status.** A ready source shows **Ready** and how many people signed in, for example `188 of 240 people signed in`. **Needs connection** means it has no connection yet. **Needs scope** means it reads only what you pick and nothing is picked.
>
> The source's **Connection** tab shows how many people are connected, the timeout, and whether any content is stored in xpander.
>
> The source's **Speed** tab holds two settings:
>
> * **Sensitive**: results are never cached, so every answer reads the source fresh. Use it for HR, legal and other restricted material. The Sources table marks it with a **Sensitive** badge.
> * **Cache results for**: seconds results are kept for the same person (0 to 3600, default 60, 0 turns it off). Cached results are never shared, so a permission removed in the source can take up to this long to apply.
>
> **Flush cache** on the Speed tab clears one source. **Flush cache** under **Speed** at the bottom of the Sources panel clears the organization's whole brain cache.

### Keep a copy of a folder

The **Keep a copy** tab copies a Google Drive folder, or a SharePoint or OneDrive library folder, into a collection, so a brain with shared agent access can use those files.

> [accordion] Keep a copy, step by step
>
> 1. Enter the **Folder**: a Google Drive folder link or id, or for SharePoint and OneDrive the library's **Drive id** and **Folder item id**.
> 2. Under **Copy into**, pick a collection or **A new collection**.
> 3. Set **Who can read the copy**. It does not follow who can open the folder: everyone in this audience sees every copied file. Confirm that, then select **Keep a copy**.
>
> The folder is read with your own sign-in, and the source's exclude rules apply to every file. It syncs on a schedule, and **Sync now** syncs at once. If your sign-in stops working, the copy shows **Needs reconnect** until you reconnect or another admin turns it on with their own account. **Stop syncing** keeps the copy readable by its audience, or deletes it if you choose **Delete the copy**.

### Notion

Notion is read live through Notion's hosted service with each person's own Notion account, so answers follow their real Notion access. Nothing is copied into xpander and nobody shares pages with xpander.

> [accordion] Notion setup, scope and limits
>
> **1. Set up Notion (once)**
>
> In **Sources**, select **Add source** and pick **Notion** under **Type**. Under **Sign-in**, select **Set up Notion**. This adds Notion to your organization's **Skills registry**, with each person signing in on their own. It is not added to any agent. Setting up Notion takes an admin, or a member of a group your admins allow to manage organization skills. Once it is done, **Sign-in** reads **Notion is set up**.
>
> **2. Add it**
>
> Select **Add source**. The source reads everything each person can open in their own Notion.
>
> **3. Narrow it (optional)**
>
> On the card's **Scope** tab, choose **Only what you pick** and **Add places** to limit it to pages and databases: a picked page covers every page under it. **Leave out places** and **Path** rules drop pages anywhere, by their place in Notion (for example `/Engineering/Interviews`). The places picker searches Notion by name with your own account.
>
> ![Add source dialog with Type Notion, the Sign-in section titled Set up Notion for your organization with a Set up Notion button, and Add source disabled](https://mintcdn.com/xpanderai-099931d1/eg4qa4fuajQHtfMy/images/use/company-brain/company-brain-notion-set-up.png?fit=max\&auto=format\&n=eg4qa4fuajQHtfMy\&q=85\&s=f7d94bb7f51be4e97c4e9f109ea2f994)
>
> Add source with Notion before it is set up: Set up Notion adds Notion for the whole organization. Shown with sample data.
>
> ![Add source dialog with Type Notion, Sign-in reading Notion is set up, Name Notion, and the Add source button](https://mintcdn.com/xpanderai-099931d1/eg4qa4fuajQHtfMy/images/use/company-brain/company-brain-notion-add-source.png?fit=max\&auto=format\&n=eg4qa4fuajQHtfMy\&q=85\&s=09142201bde55fdf96e15d0145e5b32c)
>
> Notion set up: add the source, and each person connects their own Notion account. Shown with sample data.
>
> ![Notion source card on the Scope tab with Only what you pick selected, Include listing Company Handbook and Product Roadmap, and Board notes under Exclude](https://mintcdn.com/xpanderai-099931d1/eg4qa4fuajQHtfMy/images/use/company-brain/company-brain-notion-source.png?fit=max\&auto=format\&n=eg4qa4fuajQHtfMy\&q=85\&s=9adc9455ff24e4641327cba671bd8e4e)
>
> A Notion source's Scope tab, narrowed to a page and a database with one page left out. Shown with sample data.
>
> * **Each person connects.** Someone who has not connected Notion gets nothing from it and is offered **Connect**, as for any source. They connect once from **Settings > Knowledge > My sources** with their own Notion account.
> * **Citations** name the page and link straight to it in Notion.
> * **Search quality** follows each person's Notion plan: with Notion AI, Notion's search understands questions, not just keywords.
> * **Rate limits.** Notion limits how often each person can search (about 30 searches a minute). A person who hits it gets nothing from Notion for a short while; other sources still answer.
> * **Removing** the source changes nothing in Notion and leaves Notion in your organization's **Skills registry**.

## Add a custom source

A custom source puts your own system, such as an internal wiki or ticketing system, in the brain. Each call carries a signed token naming the person, and your system answers only what they may open. Engineers build it to the [custom source contract](https://docs.xpander.ai/api-reference/company-brain-custom-sources.md).

**1. Pick Custom and the contract**

In **Sources**, select **Add source**, pick **Custom** under **Type**, then **REST endpoint** or **MCP server** under **Contract**.

**2. Connect it**

For **REST endpoint**, enter the **Endpoint**, such as `https://kb.example.com/xpander`, and the **Authentication**. For **MCP server**, pick the server and its **Search tool** and **Read tool**.

**3. Name it and copy the identity values**

Enter the **Name** people see, and select **Add and test**. Copy the **Audience (this source's id)**, **JWKS URL** and **Issuer** into your system's configuration.

**4. Test the connection**

Select **Test connection** to run a sample search as you, then **Done**.

![Add source dialog with Type Custom, Contract REST endpoint selected, Endpoint https://kb.acme.example/xpander, Authentication API key, Header Authorization, an API key, Name Acme KB and the Add and test button](https://mintcdn.com/xpanderai-099931d1/DIcTXVn5FKmtw1je/images/use/company-brain/custom-sources-add-rest.png?fit=max\&auto=format\&n=DIcTXVn5FKmtw1je\&q=85\&s=4ade84aeabe12c686061c4a5f3e6ed25)

Add source with Custom and REST endpoint: the base URL, an API key in the Authorization header, and the name people see. Shown with sample data.

> [accordion] Custom source settings
>
> **Authentication** for **REST endpoint**: **API key** (enter the **Header** and the **API key**), **Each person signs in (OAuth)** (pick the **Connection** people sign in through), or **None (the signed identity only)**. For **MCP server**, authentication is the one set on its Skills registry entry, and the **Search tool** and **Read tool** names default to `search` and `read`.
>
> **Name** appears in citations and in the access log. **Test connection** shows what came back or why it failed, and accepts a word you know is in the source under **Sample search**. It runs with your signed identity, and you can run it again any time from the card's **Connection** tab. When the source uses each person's sign-in, **Disconnect** on that tab signs you out of it.
>
> The API key is stored encrypted and never shown again. The card shows only that a key is set and its last four characters; to change it, select **Edit** on the **Connection** tab and type a new one. Leaving the field blank keeps the stored key.
>
> **Scope.** A custom source cannot be browsed, so on the **Scope** tab you use **Add by path** to include or leave out:
>
> * **A ref prefix**, such as `wiki:eng/`. It matches every ref that starts with it at a `/` or `:` boundary: `wiki:eng/` matches `wiki:eng/setup`, not `wiki:engineering`.
> * **A path**, such as `/Engineering/Runbooks`. It matches the `path` your system sends with each item. An item without a `path` is left out when the scope has a path rule.
>
> Every item is checked against the scope on search and again on read, whatever your system answered. **Test as a user** shows which items a question would read for a chosen person, and which the scope left out.
>
> **Shared settings.** The card has the same settings as the built-in sources: **Sensitive** (no cache), the cache time, the timeout, who can read it, and its entries in the access log.
>
> ![Add source dialog with the MCP contract selected, the Acme Wiki MCP entry picked, and the default search and read function names](https://mintcdn.com/xpanderai-099931d1/DIcTXVn5FKmtw1je/images/use/company-brain/custom-sources-add-mcp.png?fit=max\&auto=format\&n=DIcTXVn5FKmtw1je\&q=85\&s=16688e449a5c1dc663f3b57660cd12e7)
>
> Custom over an MCP connector: an entry from the Skills registry and the names of its search and read functions. Shown with sample data.
>
> ![The source is added, with copyable Audience, JWKS URL and Issuer fields, and Test connection showing Connected in 182 ms with two results](https://mintcdn.com/xpanderai-099931d1/DIcTXVn5FKmtw1je/images/use/company-brain/custom-sources-added.png?fit=max\&auto=format\&n=DIcTXVn5FKmtw1je\&q=85\&s=aab5a7069c0698c5ff89e5fa05405fa8)
>
> After Add and test: the values your system verifies, and a Test connection that found two items. Shown with sample data.
>
> ![Acme KB source card on the Connection tab with Contract REST endpoint, Endpoint, Authentication API key in Authorization, the Audience, JWKS URL and Issuer fields, and Test connection](https://mintcdn.com/xpanderai-099931d1/DIcTXVn5FKmtw1je/images/use/company-brain/custom-sources-card.png?fit=max\&auto=format\&n=DIcTXVn5FKmtw1je\&q=85\&s=6d183e214c540c8e46aa1e904b994f61)
>
> A custom source's Connection tab: the contract and endpoint, the values your system verifies, and Test connection. Shown with sample data.

## Settings

**Members can create their own collections** and **Members can share with everyone** are off by default; **Agents can propose facts** is on.

> [accordion] What each setting does
>
> | Setting | Default | What it does |
> | - | - | - |
> | **Members can create their own collections** | Off | Members create, share and delete collections they own from **Settings > Knowledge**. Off, only admins create collections. |
> | **Members can share with everyone** | Off | Members may share their collections with the whole organization. Off, they share only with themselves, groups they are in, or people they pick. Needs the first setting on. |
> | **Agents can propose facts** | On | Agents may suggest facts they learned in a conversation. A person approves each one before any agent uses it. |
>
> Whether others may add files to a collection is set per collection, with **Let others who can read it add files**.

## Learned facts

Agents propose facts, decisions and procedures from conversations. None is used until its reviewer approves it, and then only for its audience. Approve it, edit first (**Save and approve**), or reject it; a rejected fact is never returned.

> [accordion] Who reviews, and conflicts with documents
>
> Learned facts are separate from agent memories, which hold short notes with no approval step. Every decision is recorded in the audit log with the fact before and after.
>
> **Who reviews.** In order: the owner of the collection the fact goes to, the owner of the agent's first attached brain that has one, the Company Brain's owner, then an organization admin. The reviewer gets a notification and also sees the fact under **Settings > Knowledge > Waiting for your approval**.
>
> **Conflicts.** When a proposal contradicts a stored document, the card says **This disagrees with** that document and the button reads **Approve and flag document**. Approving asks the document's owner to update it. Only documents the reviewer can open are named.
>
> ![Learned facts panel with Waiting for your approval (2), the Mine to review and Everyone filters, a fact with Approve, Edit and Reject, and an update shown as a diff with a warning and Approve and flag document](https://mintcdn.com/xpanderai-099931d1/k9UOsTNQoJ3cIiJ7/images/use/company-brain/company-brain-learned.png?fit=max\&auto=format\&n=k9UOsTNQoJ3cIiJ7\&q=85\&s=72bc6eab6688131e225f7c4f92b859b0)
>
> Learned facts waiting for approval. The second proposal updates a stored fact and disagrees with a document, so approving it flags that document. Shown with sample data.

## Access log and speed

**Access log** lists every brain read, including cached ones: who, through which agent, which source and document (with version and page), and the result.

> [accordion] Access log results and brain speed
>
> **Speed**, at the bottom of the **Sources** panel, opens **Brain speed, last 7 days**: ask time at p50 and p95, the cache hit rate, and the model calls the cache saved.
>
> | Result | Meaning |
> | - | - |
> | `read` | The item was opened in full |
> | `cited in answer` | The item was returned as a cited passage |
> | `read from cache` | Served from the cache, still logged |
> | `blocked by a wall` | Blocked by access. The row never says what exists there |
> | `filtered out` | Left out by the source's scope, with the reason |
> | `failed` | The read errored, for example the source timed out or the person is not connected |
>
> ![Access log panel with a search box, an All results filter, and rows with results read, blocked, cited in answer, read from cache and filtered out](https://mintcdn.com/xpanderai-099931d1/PE_rYtMHQe3CXVP1/images/use/company-brain/company-brain-access-log.png?fit=max\&auto=format\&n=PE_rYtMHQe3CXVP1\&q=85\&s=fda935e7da820e54d79095271396c447)
>
> The access log: who asked, through which agent, what was read, and the result of each lookup. Shown with sample data.

## Self-hosted and Hybrid

On a self-hosted install, everything the brain stores and caches stays in your cluster. It is off in the charts by default.

> [accordion] Where the data stays
>
> The Company Brain runs the same way in xpander cloud, on hybrid installs and on air-gapped installs.
>
> | Data | Where |
> | - | - |
> | Brains, collections, documents, versions, access lists, learned facts, sources and their scope | Your Postgres |
> | Searchable sections and their embeddings | Your Postgres (pgvector) |
> | Original files and parsed pages | Your object store |
> | Cache | Your Redis, encrypted per organization, every entry with an expiry |
> | Access log | Your environment |
> | Content of live sources | Nowhere. Read at question time with the person's own account, except folders an admin keeps a copy of |
>
> By default every organization on the install shares the install's Postgres database, and every row carries its organization. To give each organization its own database instead, set `onpremPerOrgDb: true`. Decide before you load content: the setting picks one database per organization and never splits one organization's brain across two.
>
> **Hybrid.** xpander cloud never connects to your database, Redis or object store. A brain call that starts in the cloud (xpander Chat, an MCP client, a Platform page, an upload) is relayed to your install's agent controller, which does the work and returns only the answer. Only usage counts go up. If your install does not answer, the agent is told the company knowledge is offline, and nothing falls back to cloud storage. Live sources are called from your network, so sources that accept only your IP addresses work.
>
> **Air-gapped.** Nothing leaves your environment. Parsing, OCR, embeddings and ranking run on models baked into the images, so nothing is downloaded at run time. Answers are written by the model your install already uses, such as an in-network vLLM, Ollama or NIM endpoint. Usage goes to the local credits ledger when metering is on.

> [accordion] Turn it on: chart values
>
> Turning it on deploys **brain-ingest**, the service that parses, splits and embeds documents, and connects the agent controller to it.
>
> > [tab] Hybrid (xpander chart)
> >
> > ```yaml theme={"dark"}
> > brain:
> >   enabled: true
> >   onpremPerOrgDb: true        # optional: each organization in its own database
> >   ingest:
> >     replicas: 1
> >     objectStore:
> >       type: local             # or s3
> >       local:
> >         persistence:
> >           size: 20Gi
> >       s3:
> >         bucket: ""
> >         region: ""
> >         endpointUrl: ""       # for MinIO and other S3-compatible stores
> >   cacheMaxMemory: 512mb
> > ```
> >
> > With `type: local`, originals are kept on a volume the chart creates and keeps on uninstall. That volume is `ReadWriteOnce`, so more than one replica needs `accessMode: ReadWriteMany` or `type: s3`. The chart refuses the combination otherwise. S3 credentials come from the pod identity or `envFromSecret`.
>
> > [tab] Air-gapped (xpander-airgap chart)
> >
> > ```yaml theme={"dark"}
> > brain:
> >   enabled: true
> >   cacheMaxMemory: 512mb
> > global:
> >   brain:
> >     enabled: true             # must match brain.enabled; the chart refuses them disagreeing
> >     onpremPerOrgDb: true      # recommended: each organization in its own database
> >     ingestReplicas: ""        # keep equal to brain-ingest.replicas (empty means 1)
> > brain-ingest:
> >   replicas: 1
> > ```
> >
> > Originals and parsed pages go to the platform's own object store, in the `kb_files` bucket. The ingest service key is generated and kept across upgrades like every other key. Mirror the `brain-ingest` image with `image_sync.sh` before you install or upgrade.
>
> | Value | Default | What it does |
> | - | - | - |
> | `brain.enabled` | `false` | Deploys brain-ingest and turns the Company Brain on for the install |
> | `onpremPerOrgDb` | `false` | Each organization's brain data in its own database instead of the shared one |
> | `cacheMaxMemory` | `512mb` | The most the brain's cache uses in your Redis. Add it to your Redis memory limit |
> | `replicas` (ingest) | `1` | Parallel parsing and embedding; each replica takes one document at a time |
> | `reranker.backend`, `reranker.url`, `reranker.modelVolume.existingClaim` | `onnx`, empty, empty | Optional ranking model. Without one, search still answers with its combined text and meaning ranking |

> [accordion] Ranking model
>
> A cross-encoder ranking model (bge-reranker-v2-m3) improves the order of results. It is optional. Pick one `reranker.backend`:
>
> * `ingest`: nothing to stage. The brain-ingest image already includes the model and serves it. Ranking waits at most 5 seconds per question, then answers without it.
> * `onnx` (default): stage `model.onnx` and `tokenizer.json` on a volume and name the claim in `reranker.modelVolume.existingClaim`. It is mounted read-only on the agent controller.
> * `http`: set `reranker.url` to a ranking endpoint in your network.
>
> On CPU, ranking adds seconds per question. A GPU endpoint keeps it interactive.

> [accordion] Sizing
>
> Each brain-ingest replica requests 1 vCPU and 4 GiB and may use up to 4 vCPU and 10 GiB. On CPU, one replica with 4 cores embeds about 1.2 sections per second, so a 300-page document takes around 15 minutes. That suits a steady trickle of uploads. For bulk loads, such as moving existing knowledge bases, add replicas or point embedding at a GPU server in your cluster that serves bge-m3.
>
> The brain-ingest image is about 5.2 GB and amd64 only. Budget registry space and the first pull on each node.

> [accordion] Postgres with pgvector
>
> The brain needs the pgvector extension, version 0.8 or newer. The charts' bundled Postgres runs the pgvector build of the official image on the same major version as before (`pgvector/pgvector:0.8.7-pg15-trixie` on hybrid, `0.8.7-pg16-bookworm` on air-gapped), so an upgrade swaps the image on the same volume and the Postgres pod restarts once.
>
> * **Before you upgrade**, mirror the new image and take a restore point: a snapshot of the Postgres volume, or set `postgres.upgradeGuard.backup.pvcName` to an existing claim and the upgrade writes a full dump there first.
> * **During the upgrade**, a guard on the new image refuses to continue if the running server's major version differs from the image's.
> * **After every install and upgrade**, a job creates the `vector` extension in every database and the installer prints one status line, for example `pgvector: ok vector=0.8.7 ok=3 failed=none`. A `degraded` or `failed` line names the databases to look at.
>
> **External Postgres** (such as Amazon RDS): install pgvector 0.8 on the server, and run `CREATE EXTENSION vector` once per database where your user cannot create extensions. Without pgvector, the Company Brain is unavailable and everything else keeps working.

> [accordion] Network
>
> Live sources are reached from your install with each person's own sign-in: Google APIs for Google Drive, Microsoft Graph for SharePoint and OneDrive, and Atlassian's API for Confluence and Jira. On a hybrid install, allow those hosts in your egress policy to use them. **Notion** is read through Notion's hosted service (`mcp.notion.com`), so your agent controller needs outbound access to `mcp.notion.com`. Nothing from Notion is stored.
>
> **Air-gapped installs** cannot use Google Drive, SharePoint, OneDrive, Confluence, Jira or Notion: they need each person to sign in to Google, Microsoft, Atlassian or Notion's cloud service, so **Add source** offers only **Custom**. A custom source is your own system inside your network: xpander calls it over HTTPS (or plain HTTP to an in-network address when agent-controller has `BRAIN_CUSTOM_SOURCES_ALLOW_HTTP=true`), the keys that sign its identity token are served by your own API at `/.well-known/brain-identity-jwks.json`, and nothing leaves the installation. Collections work fully, and with `global.network.internetEgress: false` importing a document from a URL is off as well.
>
> **Custom sources** on a hybrid install may call endpoints inside your network as well as public ones; cloud metadata addresses are never called, and the calls do not use `HTTPS_PROXY`. See [Network rules](https://docs.xpander.ai/api-reference/company-brain-custom-sources.md#network-rules).

## Troubleshooting and FAQ

For a missed file or a skipped source, see the [member troubleshooting](https://docs.xpander.ai/use/company-brain.md#troubleshooting).

> [accordion] SharePoint or OneDrive sign-in fails for everyone
>
> Before anyone can sign in, your Microsoft tenant admin needs to consent to the delegated `Files.Read.All` and `Sites.Read.All` permissions. To exclude files by sensitivity label name, also consent to `SensitivityLabel.Read`. Without it, write label rules as label ids.

> [accordion] Connect is not offered for a source
>
> The source is not fully set up yet. The **Needs you** strip at the top of **Platform > Agents > Knowledge** lists sources that are not set up: **Needs connection** or **Needs scope**.

> [accordion] A custom source fails Test connection
>
> ![Test connection showing The source refused the credential or this person (401/403). Check the API key or sign-in, with the detail the source refused the configured credential](https://mintcdn.com/xpanderai-099931d1/DIcTXVn5FKmtw1je/images/use/company-brain/custom-sources-test-refused.png?fit=max\&auto=format\&n=DIcTXVn5FKmtw1je\&q=85\&s=c116811b2d6360356af749e9e43fbbdb)
>
> Test connection when the source refused the API key: what failed, and the source's own words. Shown with sample data.
>
> | Test connection says | What to check |
> | - | - |
> | The source refused the credential or this person (401/403) | The API key and its **Header**; that your system accepts the token's `aud` (the source's id) and `iss`; that the person's groups are allowed |
> | Sign in to the source first | The source uses each person's sign-in and you have not signed in yet. Use the link, then test again |
> | The source didn't answer within the timeout | Your system's response time, or raise the source's timeout |
> | The source couldn't be reached or answered outside the contract | The detail line names the cause: an address that is refused (see [Network rules](https://docs.xpander.ai/api-reference/company-brain-custom-sources.md#network-rules)), a redirect to another host, an answer over the size limit, an answer that is not JSON or has no `items` list, or an HTTP error |
> | The source isn't fully configured | An MCP connector that left the Skills registry, a server on the SSE transport, or a missing API key: select **Edit** and fix it |

> [accordion] What happens to existing knowledge bases?
>
> Knowledge bases are replaced by the Company Brain. You do not need to upload anything again.
>
> A knowledge base that is attached to an agent and was searched in the last 90 days moves into a brain with the same name. It holds one collection with the same files, owner and editors, and it uses shared agent access, the way knowledge bases work today. It stays attached to the same agents, and each agent keeps its Company Brain setting. The move switches an agent over only once the new search finds at least as much as the old one did on questions drawn from the knowledge base's own content. A brain moved from a knowledge base shows "migrated from" the knowledge base's name on the agent.

> [accordion] What about knowledge bases no agent used?
>
> They are not moved. Each owner gets a notification in xpander and by email with a link to an export of the files, valid for 37 days. The knowledge base is removed no sooner than 30 days after that notice. To keep using the files, create a collection, add them to it, and attach it to your agents.

> [accordion] Does the knowledge base API still work?
>
> For a moved knowledge base, the [knowledge base API](https://docs.xpander.ai/api-reference/v1/knowledge/list-knowledge-bases.md) and the agent's existing knowledge base search keep working for one release, answering from the new collection. Adding or deleting files still needs the owner, an editor or an admin.


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