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 in Platform > Agents > Knowledge. A Needs you strip at the top lists learned facts waiting for approval and sources agents cannot read yet.
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.
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.
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
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.
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.
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 of it.
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.
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.
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.
Select New collection in the page header.
Fill Name and What it holds.
Under Who can read it, choose Everyone in the organization, or pick people and groups. Each document can narrow this further.
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.
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 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.
Each live source shows its status and how many people signed in.
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.
In Sources, select Add source and pick Google Drive, SharePoint, OneDrive, Confluence, Jira or 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: the type, the connection each person signs in through, and the name people see. Shown with sample data.
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.
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.
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.
The Scope tab of a Google Drive source with Only what you pick and nothing picked yet. Shown with sample data.
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 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.
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.
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.
Keep a copy, step by step
Enter the Folder: a Google Drive folder link or id, or for SharePoint and OneDrive the library’s Drive id and Folder item id.
Under Copy into, pick a collection or A new collection.
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 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.
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 with Notion before it is set up: Set up Notion adds Notion for the whole organization. Shown with sample data.
Notion set up: add the source, and each person connects their own Notion account. Shown with sample data.
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.
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.
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 with Custom and REST endpoint: the base URL, an API key in the Authorization header, and the name people see. Shown with sample data.
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.
Custom over an MCP connector: an entry from the Skills registry and the names of its search and read functions. Shown with sample data.
After Add and test: the values your system verifies, and a Test connection that found two items. Shown with sample data.
A custom source's Connection tab: the contract and endpoint, the values your system verifies, and Test connection. Shown with sample data.
Members can create their own collections and Members can share with everyone are off by default; Agents can propose facts is on.
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.
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.
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 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 lists every brain read, including cached ones: who, through which agent, which source and document (with version and page), and the result.
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
The access log: who asked, through which agent, what was read, and the result of each lookup. Shown with sample data.
On a self-hosted install, everything the brain stores and caches stays in your cluster. It is off in the charts by default.
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.
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.
Hybrid (xpander chart)
Air-gapped (xpander-airgap chart)
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.
brain: enabled: true cacheMaxMemory: 512mbglobal: 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
Optional ranking model. Without one, search still answers with its combined text and meaning ranking
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.
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.
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.
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.
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.
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.
A custom source fails Test connection
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), 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
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.
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.
Does the knowledge base API still work?
For a moved knowledge base, the knowledge base API 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.
Was this page helpful?
Assistant
Responses are generated using AI and may contain mistakes.
