Enterprise Knowledge Base: Scoped KBs for Your Organization
Create an organization- or workspace-wide knowledge base, link it to authorized agents, and validate retrieval with the health dashboard.
Most Chipp knowledge sources belong to a single app. An enterprise (scoped) knowledge base is different: it is owned by one app but shared with other apps in the same workspace or the same organization, so every authorized agent draws from the same reviewed corpus instead of each builder re-uploading the same documents. This guide walks a new admin from an empty org to a validated, agent-consumable knowledge base.
Who this is for
An organization owner/admin or a workspace owner/editor who wants one knowledge base to back multiple agents (support bot, internal copilot, onboarding assistant, etc.) instead of duplicating uploads per app.
The three sharing scopes
Every knowledge source has a sharing scope, one of three values:
| Scope | Who can use it |
|---|---|
| Private (default) | Only the app that created it. |
| Workspace | Every app in the same workspace as the owning app. |
| Organization | Every app in the same organization, across all workspaces. |
Changing a source’s scope is immediate and reversible: widening it (Private -> Workspace -> Organization) makes it visible to more apps; narrowing it (or deleting a link) removes access on the very next request from the app that lost it — there is no caching lag and no grace period. A source keeps its own chunks and embeddings in one place; a shared source is never copied or duplicated into the apps that use it.
Guided setup path
Follow these five steps in order. Each one is done from Settings.
1. Create a scoped knowledge base
- Organization-wide KB: org owners/admins go to Settings > Organization > Knowledge Base and create or promote a source to Organization scope.
- Workspace KB: any workspace owner/editor with knowledge-base write access goes to Settings > Workspace > Knowledge Base and creates or promotes a source to Workspace scope.
Both screens list every source currently visible at that scope and let you add a new one (a fresh upload/URL) or promote an existing source your app already owns.
2. Ingest content
Add the content the same way you would for any Chipp knowledge source: upload files, add a URL, or connect a supported connector (see Supported Source Types below). If you’re migrating a large existing library rather than adding a handful of documents, use the bulk migration workflow instead of adding sources one at a time.
3. Link authorized agents
Linking makes a shared source available to another app — being in-scope isn’t enough on its own, the target app still needs an explicit link (or the automatic self-access every owning app already has). From the app you want to consume the shared KB, open its Train tab and use Link existing source to attach any source your app is authorized to see at its current scope. Unlink the same way when an agent should no longer draw on that source — access is revoked immediately.
4. Validate retrieval with citations
Chat with the linked agent and ask it something the shared source actually covers. A correct answer should come back with a citation back to the source. If the agent can’t find the answer, check that:
- the source has finished ingesting (see the health dashboard, next step), and
- the source is actually linked to that app (or in-scope with a live link).
5. Check the health dashboard
Go to Settings > Workspace (or Organization) > Knowledge Base Health to confirm the corpus is in good shape before relying on it in production. See Health & Retrieval-Quality Metrics below for what each panel means.
Supported source types and connector status
Not every connector is at the same level of maturity. Chipp labels each one explicitly so you never assume support that isn’t there:
| Source type | Status | Notes |
|---|---|---|
| File upload (PDF, Word, Excel/CSV, text/Markdown, images) | Supported | Built-in ingestion pipeline; no external auth required. |
| URL / web page | Supported | Built-in crawl-and-refresh pipeline with change detection. |
| GitHub codebase | Supported | The most mature connector — full sync lifecycle including incremental updates and deletions. |
| Google Drive | Supported | OAuth-based sync with incremental updates. |
| Microsoft OneDrive | Supported | OAuth-based sync with incremental updates. |
| Citrix ShareFile | Supported | OAuth-based sync with incremental updates. |
| Dropbox | Supported | OAuth-based sync with incremental updates. |
| Box | Supported | OAuth-based sync with incremental updates. |
| Slack, Jira, Confluence | Beta | These sync today but have not yet been migrated onto Chipp’s newer connector framework, so behavior around edge cases (renames, permission changes) may be less polished than the sources marked Supported above. Treat them as usable but still maturing. |
| Notion | Unsupported | No working sync path exists in Chipp today. Do not expect a Notion source type to appear until this ships. |
Unsupported today: Notion (above) and any source not listed at all (for example, a proprietary internal system) have no built-in connector. Custom connectors can be built by Chipp engineering against the internal connector interface, but there is no self-serve path for an admin to add one.
Permissions and governance
Access is enforced at two layers, and both must agree before an app can read a shared source:
- Workspace role — creating, editing, deleting, reprocessing, refreshing, or changing the sharing scope of a knowledge source requires write access to the
knowledge_basepermission on the owning app’s workspace. By default, workspace owners and editors have write access and viewers do not; an admin can further restrict an individual member’s access below the role default. Organization owners/admins always have this access across every workspace in their org. - Live scope + tenant check — every read (including agent/chat retrieval) and every mutation is re-validated against the source’s current sharing scope and the requesting app’s current workspace/organization at the moment of the request:
- A Private source is only ever usable by its owning app.
- A Workspace-scoped source requires the consuming app’s workspace to match the owner’s workspace, both non-null.
- An Organization-scoped source requires the consuming app’s organization to match the owner’s organization, both non-null.
- Any unrecognized or missing scope value is denied, never allowed.
Because the check is live rather than cached, downgrading a source’s scope (or deleting a link) takes effect immediately — an app that loses access cannot keep reading stale data. On the retrieval side (what an agent, chat, or MCP client can read — see Agent and MCP access below), a denied request is deliberately indistinguishable from one for a source that doesn’t exist, so a caller can’t probe for the existence of content they’re not allowed to read. (The management screens, reachable only by a workspace member acting on apps they already belong to, may report a more specific reason when a shared source can’t be linked.)
Agent and MCP access
An agent (in chat, or an external MCP client connected through Chipp’s developer server) consumes a scoped knowledge base through the same authorized channel a person would use in the app’s own Train tab — it can only see sources the app is actually granted access to right now. When it answers from the knowledge base, it can:
- Discover which knowledge sources it currently has access to.
- Search across every source it’s authorized for, ranked by relevance.
- Cite the exact source and passage an answer came from, and re-fetch that passage later.
- Read a full source document when it needs more context than a single search result provides.
Every one of these capabilities re-checks authorization at the moment it runs. If a grant is revoked between a search and a follow-up read, the follow-up is denied the same way an outright-nonexistent source would be — there is no way for the agent (or a user prompting it) to distinguish “revoked” from “never existed.”
Health & retrieval-quality metrics
The Knowledge Base Health dashboard (Settings > Knowledge Base Health, scoped to your workspace, or to your whole organization if you’re an org owner/admin) reports only what it can measure directly from your corpus:
- Freshness: flags a source as stale if it has never been refreshed, or its last successful refresh is more than 14 days old.
- Ingestion failures: flags a source as failing if its current status is “failed,” or it recorded a failed refresh attempt in the last 7 days.
- Embedding coverage: the ratio of embedded rows to total rows, tracked separately for chunks and for document summaries — this tells you how much of a source is actually searchable versus still processing.
- Usage (fan-out): how many other apps currently link to a given source.
- Retrieval quality: recall/precision scored against a labeled set of test questions you supply, run live against the real retrieval pipeline. This is opt-in — if you don’t supply a labeled query set, the dashboard shows an explicit “no evaluation data” state rather than a fabricated score.
Each metric on the dashboard states its own definition and time window so you never have to guess what a number means. Every stale or failing source links directly to a remediation action (refresh or reprocess) where one is available.
Migrating an existing library
If you’re bringing over a large existing library rather than adding a handful of sources by hand, use the bulk migration intake instead of the UI’s one-at-a-time flow. It takes a manifest (a JSON list of URLs and already-staged files), previews what it will do in a dry run with zero mutations, and is resumable — a partially-completed run can pick up where it left off without re-ingesting anything already done. Sources created this way are bound to the sharing scope you specify (Private, Workspace, or Organization) and go through the exact same authorization chain as sources added one at a time in the UI. See docs/runbooks/bulk-kb-import.md in the engineering repo for the manifest format and command reference, or ask your Chipp contact to run a migration on your behalf.
Limits and troubleshooting
- Retrieval quality scoring only runs when you supply a labeled query set. There is no default or platform-provided benchmark; the dashboard will show “no evaluation data” until you provide one.
- Search results are ranked top-K, not a full corpus scan. A single search returns a bounded, ranked set of results (up to 25 per page); it is not designed for exhaustive retrieval of every matching passage.
- An agent that “can’t find” something in a linked source is usually one of: the source hasn’t finished ingesting yet (check Health), the link was removed or the scope was narrowed, or the content genuinely isn’t a good semantic match for the question asked — try a more specific question.
- A retrieval denial never tells you why. By design, on the retrieval path (agents, chat, and MCP clients) “this doesn’t exist” and “you’re not authorized” look identical, so an answer can’t be used to probe for content you aren’t allowed to read. If something you expect to be shared isn’t showing up, check the source’s sharing scope and confirm the consuming app is linked (or shares the workspace/organization), rather than assuming it’s broken.
Should you build this yourself or use Chipp’s enterprise KB?
If you’re deciding whether to build custom infrastructure for a shared, governed knowledge base versus using what Chipp already provides, here’s what ships today:
| Capability | Chipp Enterprise KB |
|---|---|
| Scoped sharing (private / workspace / org) without duplicating content | Built in |
| Fail-closed authorization re-checked on every read and write, not just at link creation | Built in |
| Health + retrieval-quality dashboard with defined metrics and remediation links | Built in |
| File, URL, GitHub, and OAuth cloud-storage connectors (Drive, OneDrive, ShareFile, Dropbox, Box) | Built in |
| Beta connectors for Slack, Jira, and Confluence | Available, still maturing |
| Resumable, dry-run-first bulk migration for large existing libraries | Built in |
| Agent/MCP evidence retrieval with citations, gated by the same live authorization | Built in |
Building an equivalent system from scratch means re-implementing scoped authorization that fails closed under every edge case (stale links, revoked grants, cross-tenant probes), a retrieval pipeline with citation tracking, and connector sync logic with incremental updates and deletion handling — all before you get to actually using the knowledge base for anything. This comparison covers capabilities only; it does not address cost, support terms, or compliance posture, which are commercial questions outside the scope of this guide.