---
title: "Knowledge"
description: "Company knowledge bases that ingest your sources, follow each source's permissions and answer with citations, through the API, MCP, the console and the Frazer app."
url: https://frazer.ai/docs/knowledge
index: https://frazer.ai/docs/llms.txt
tokens: 5444
---

> For agents: this page is indexed at https://frazer.ai/docs/llms.txt, and every page at https://frazer.ai/llms.txt. Copy commands from this file exactly.

# Knowledge

Frazer Knowledge turns your company’s sources into knowledge bases that people and agents can ask. It ingests code, pull requests, issues, docs, threads, runbooks and incidents, keeps them fresh, and answers with a citation for every claim, or declines and says why. Every chunk carries the permissions of its source, so each person and agent gets only what they could open in the source. Connectors, the query service and the vector engine run in your organization’s data cluster, on your own servers or the Frazer fleet.

Product overview: [Knowledge](https://frazer.ai/knowledge).

## How it works

**Ingestion.** A connector fetches what changed in a source. Each document is parsed (layout, tables and OCR for scans), deduplicated by content hash, split into chunks that follow its structure, given a short context header that places the chunk in its document, and embedded for both meaning (dense vectors) and keywords (BM25). The chunks land in an index version. A deleted document becomes a tombstone and leaves every live index; a permission change updates the chunks in place, without a re-index.

**Questions.** A query is checked in this order:

1.  Frazer authenticates the caller and builds their set of principals: a person, an agent acting for a person (the person’s rights within the agent’s ceiling), or a public key.
2.  A question with several parts is rewritten into sub-queries.
3.  Hybrid search (meaning and keywords, fused) runs with the caller’s permissions as a filter inside the search.
4.  A reranker keeps the best chunks.
5.  For Google Drive, SharePoint and Confluence, the top results are re-checked against the source before the answer.
6.  The answer cites a chunk for every claim, or the base declines; the query is logged without its text by default.

### Key concepts

-   **Knowledge base** (`projects/{project}/knowledgeBases/{kb}`): a preset (company, engineering, support or public), an access mode, an engine, retrieval and answer settings, and its own key on the [LLM gateway](https://frazer.ai/docs/llm-gateway).
-   **Source**: one connector with a scope and a schedule (events, webhooks, polling or daily).
-   **Document**: one unit from a source, such as a file, a Slack thread or an issue with its comments, with its URL, path and permissions.
-   **Index**: a versioned build of the base (parser, chunking, context header, embedding model, quantization and engine), in the state `building`, `gated`, `active` or `retired`.
-   **Evaluation set**: golden questions with the expected chunks and answers, questions the base should decline, and test identities.
-   **Access rule**: who may use the base (a group, an agent or a public key), with which tools and rate limits.

**Access modes.** `source` gives each person what the source lets them open. `group` limits the base to one group, an outer fence applied before everything else. `public` accepts only public sources and answers anyone with the base’s public key.

### Sources

Connections are made once per organization by an admin and reused by any base with a scope of its own.

| Source | One document is | Updates | Permissions come from |
| --- | --- | --- | --- |
| GitHub (Frazer Reader app) | A file (code split by symbol), a README or docs page, an issue with comments, a pull request with its review threads, an ADR | Webhooks | Repository collaborators and teams |
| Google Drive | A file; a Google Doc by heading | Drive push notifications and changes | File sharing (users, groups, domain; anyone with the link counts as the organization) |
| Slack | A thread | Events, with paced history backfill | Channel members; direct messages are excluded |
| Notion | A page, by heading | Webhooks and a 10-minute poll | Page sharing and teamspaces |
| Linear | An issue with comments; a project update | Webhooks | Team membership |
| Website | A page, from the sitemap or a crawl | Daily, or when the sitemap changes | Public |
| Bucket (Frazer Storage or S3) | An object: PDF, Office, HTML or Markdown | Object events | The base’s rule, or an ACL sidecar file |
| Upload and push API | A document | On write | The principals you supply (they must exist in your organization) |
| Frazer catalog | A service entry, runbook, incident timeline or postmortem | Events | Frazer IAM |
| Confluence, Jira | A page; an issue | Webhooks | Space and issue security |
| SharePoint, OneDrive, Gmail | A file; a thread | Change notifications; Gmail push | Item permissions |
| Postgres and other databases | A row rendered by a template from a saved query | Every 15 minutes, on an `updated_at` cursor | A row rule that maps a column to principals |

Anything else arrives through the push API.

### Retrieval defaults

| Step | Default | You can change it to |
| --- | --- | --- |
| Parse | Docling: layout, whole tables, OCR for scans | Fast text, or high-resolution parsing with a vision model through the gateway |
| Chunk | About 480 tokens, by structure: Markdown and Docs by heading, code by symbol, tickets and Slack as threads, tables never split; 10 % overlap for flat prose only | 128 to 1,024 tokens; overrides per source |
| Context header | On for PDFs and long documents: 50 to 100 tokens placing the chunk in its document, generated once on route `fast` with prompt caching | Off |
| Embeddings | Arctic Embed L v2.0 on a Frazer model endpoint, with int8 quantization and rescoring | bge-m3, or an embedding provider through the gateway |
| Keywords | BM25 inside the vector engine | Postgres full-text search on the pgvector engine |
| Fusion | Reciprocal rank fusion with k = 60; weights 0.45 keywords, 0.55 meaning | Weights tuned against your golden set |
| Rerank | bge-reranker-v2-m3 on the top 50, keeping 8 for the answer, at most 3 chunks per document | mxbai-rerank-large-v1, or a rerank provider through the gateway |
| Answer | Route `balanced`; every claim cites a chunk, and uncited sentences are removed | Any route |
| Decline | Answer only when the top rerank score is at least 0.35; declines are logged as gaps | A threshold per base |

## Create a knowledge base

You need a project, an admin who can connect your sources, and the `frazer` CLI signed in ([CLI reference](https://frazer.ai/docs/cli)). The examples use two bases of the Acme demo organization: `acme-engineering` (code and issues) and `acme-company` (handbook, docs and Slack).

1.  **Connect your sources.** An organization admin connects each source once in the organization’s **Settings › Integrations**: GitHub through the Frazer Reader app, Google Drive, Slack, Notion, Linear and the others. The tokens stay in Frazer’s secret store, and connector workers run in your organization’s data cluster, so documents never leave your site.
    
2.  **Create the base.**
    
    ### CLI
    
    ```sh
    frazer knowledge knowledge-bases create acme-engineering --preset engineering --access source \
      --source github:all --source linear:ENG,OPS --mcp --dry-run
    ```
    
    ```text title="Output"
    Plan: create knowledge base acme-engineering in acme-production
      + Knowledge base   acme-engineering · preset engineering · access source
      + Source           github · every repository the Frazer Reader app can read
      + Source           linear · teams ENG, OPS
      + Index            v1 · Qdrant · hybrid search with rerank
      + MCP server       mcp.frazer.ai/knowledge/acme-engineering
      + Gateway key      knowledge/acme-engineering
        First sync       cost estimate for parsing, context headers and embeddings
    ```
    
    Run the command without `--dry-run` to create it.
    
    ### Console
    
    Open **AI and GPUs › Knowledge** and choose **New knowledge base**. Pick a preset, add sources with their scopes, choose the access mode, tick the devbox provisioning profiles that should get the base, and keep the evaluation set the base drafts for you. The plan in the rail shows the first sync’s cost before you choose **Apply**.
    
    Knowledge bases are also resources in the [Terraform and OpenTofu provider](https://frazer.ai/docs/terraform).
    
3.  **Watch the first sync.** The base’s **Sources** tab shows each source’s status and freshness, what is indexed, and how many source users could not be matched to a Frazer identity. Unmatched users get nothing from the base until you link them.
    
4.  **Ask a question.**
    
    ```sh
    frazer knowledge ask acme-company "How do we rotate the payments webhook secret?"
    ```
    
    ```text title="Output"
    Create the new endpoint secret at the payments provider, store it as PAYMENTS_WEBHOOK_SECRET in the
    payments secret store, and deploy with both secrets accepted for one hour [1]. Remove
    the old secret after the dashboard shows no failed deliveries [2]. Payments on-call
    approves the production step [3].
    
    
    [1] runbooks/payments-webhooks.md · acme-payments@main   GitHub
    [2] Payments handbook › Secrets                        Notion
    [3] Thread in #payments-oncall                         Slack
    ```
    
    A contractor on the web team who asks the same question gets an answer built only from the documents they can open, such as the public docs.
    

## Add sources and keep them fresh

Add a source to an existing base:

```sh
frazer knowledge sources add acme-company slack --channels public --dry-run
```

**Identities.** Source users and groups map to Frazer identities by verified email, SCIM external IDs and aliases you set per source (for example `noah@acme.example` to a Slack member ID). Group membership is read from your directory at query time, so a group change takes effect without a re-index. An unmatched user gets nothing, never everything; the **Sources** tab shows how many are unmatched.

**Freshness.** Each source is measured against its target from event timestamps, shown on the **Sources** tab:

| Source kind | Content is fresh within |
| --- | --- |
| Webhook and event sources | 5 minutes |
| Polled sources | 1 hour |
| Crawled websites | 1 day |

Deletes propagate as tombstones within the same targets, and a full re-sync checks deletes every week.

**Stale permissions.** Permissions are tracked separately from content. If a source’s permissions are more than 1 hour stale, only documents that pass the live re-check are used. After 24 hours, the source is left out of answers until it is fixed. A source that fails to sync sends a `frazer.knowledge.sync.failed.v1` event ([Webhooks](https://frazer.ai/docs/webhooks)).

## Connect people, devboxes and agents

Every base has its own MCP server at `mcp.frazer.ai/knowledge/{kb}`, behind the Frazer MCP endpoint. The caller is always the person on the token, or the person within the agent’s ceiling. Print the configuration for a client:

```sh
frazer knowledge mcp config acme-company --client claude-code
```

**Devboxes.** An admin adds the base to a provisioning profile, and every box in scope gets it in every tool:

```yaml title="provisioningProfiles/acme-baseline"
items:
  - kind: knowledge
    ref: knowledgeBases/acme-engineering
    enforcement: locked
  - kind: knowledge
    ref: knowledgeBases/acme-company
    enforcement: default
  - kind: mcp
    ref: frazer
    enforcement: locked
```

The box agent writes the MCP entry into Claude Code, Codex, Hermes, the Frazer app and VS Code-family editors, with a short-lived token for the person using the box. A base a person adds on their own box shows up in the devbox change report. See [Devboxes](https://frazer.ai/docs/devboxes).

**Agents.** Grant `knowledge_bases_search` and `knowledge_bases_ask` with a Viewer ceiling. Retrieved chunks are labeled as untrusted text, so the gateway’s prompt-injection check scores them.

**API.** `SearchService` answers `POST …/knowledgeBases/{kb}:search` (chunks) and `:ask` (an answer), for example `https://api.frazer.ai/knowledge/v1/projects/acme-production/knowledgeBases/acme-company:ask`. Responses carry a `query_id` that feedback refers to. A push API writes documents with their principals.

**Public bases** accept only public sources and answer with a public key that has tight rate limits, for a chat widget on your site. Adding a private source to a public base is refused by the plan check.

## Tune retrieval

Settings that change the vectors (parser, chunking, context header, embedding model, quantization or engine) build a new index version next to the active one, from the same snapshot of your sources. The active index keeps serving, the evaluation gate decides the switch, and the previous version is kept for 7 days so you can roll back:

```sh
frazer knowledge indexes build acme-company --chunk-size 480 --context-header on --dry-run
```

Search-time settings (weights, reranker, how many chunks to keep, the decline threshold) apply without a rebuild, and still run the gate.

**Engines**, chosen per base and changed through a new index version:

| Engine | Use |
| --- | --- |
| Qdrant (default) | Runs in your organization’s data cluster; bases share a collection per embedding model, separated by filter and shard key. A base with `isolation: dedicated` gets its own collection |
| Postgres with pgvector | Small bases, or “keep it in my database”, on a managed Postgres |
| Your own Qdrant Cloud, Pinecone or Turbopuffer | With your credentials; Frazer keeps the pipeline, the permission filter and the evaluations |

**The playground** shows why an answer came out the way it did: the answer with its citations and the judge’s faithfulness score, and the retrieved chunks with their meaning, keyword and rerank scores. Admins can ask as another person or agent, and see how many candidates the permission filter removed; nobody else sees that count. **Save as golden question** adds the query with its expected chunks. From the CLI:

```sh
frazer knowledge ask acme-company "How do we rotate the payments webhook secret?" --as noah --index v15
```

## Evaluate quality

Every base has evaluations, and no index switches without passing them.

-   **Golden set**: 30 questions drafted from your sources and reviewed by a person, then grown to 200 and more from live traffic (low grades and wrongful declines become candidates).
-   **Retrieval metrics**, without a model: Recall@10, MRR@10 and nDCG@10 against labeled documents or chunks.
-   **Answer metrics**, by an LLM judge whose model and prompt are pinned, averaged over 3 passes: faithfulness, answer relevance, citation validity (the cited chunk was retrieved and supports the claim) and decline correctness.
-   **Permission set**: questions asked as test identities, such as a contractor, a legal team member and an agent with a Viewer ceiling. Any leak fails the gate and pages the base’s owner.

The default gate:

| Rule | Threshold |
| --- | --- |
| No metric drops more than 2 points against the active index | −2 points |
| Faithfulness | at least 0.85 |
| Citation validity | at least 0.95 |
| Decline correctness | at least 0.80 |
| Permission leaks | 0 |
| p95 retrieval latency | at most 20 % slower |

Evaluations run on every index build, every search-time setting change, and every night on the active index. Run one yourself:

```sh
frazer knowledge eval-runs create acme-company --set acme-core
```

**Live feedback** (good, weak, wrong, uncited, wrongful decline, correct decline) comes from the console, the API and MCP, and tunes the decline threshold. An online judge samples 1 to 5 % of answers, and an alert fires when faithfulness over 7 days drops 5 points.

## Access and audit

-   **Connections** are made once per organization by an admin; tokens stay in Frazer’s secret store, and connector workers run in your organization’s data cluster.
-   **Permissions on every chunk**: the source’s users and groups are copied onto each chunk, enforced as a filter inside the vector search, and re-checked live against Google Drive, SharePoint and Confluence. Deny wins, and an error drops the document.
-   **Agents** see what the person they act for may see, within the agent’s ceiling.
-   **Proposals** from `knowledge_proposals_create` are accepted by a person or a passing check; agent proposals are never published automatically in production bases.
-   **Query logs** keep the query, a hash of the principals, chunk IDs, scores, latency and cost, not the text. ZDR projects keep no query text at all.
-   **Storage**: text and vectors are encrypted at rest, one organization’s vectors never share an engine with another’s, and deleting a base deletes its points, documents and snapshots after a 7-day grace period.
-   **Cost**: every model call (context headers, embeddings on a provider, answers, the judge) goes through the gateway on the base’s own key, so it shows in gateway spend and your budgets apply.

## Limits and quotas

| Setting | Default |
| --- | --- |
| Chunk size | About 480 tokens (128 to 1,024) |
| Candidates reranked, chunks kept | 50, 8 (at most 3 per document) |
| Decline threshold | Top rerank score of 0.35 |
| Content freshness | 5 minutes (events), 1 hour (polled), 1 day (crawls) |
| Stale permissions | Live re-check only after 1 hour; source excluded after 24 hours |
| Previous index kept for rollback | 7 days |
| Golden set | 30 drafted questions, reviewed by a person |
| Online judge sample | 1 to 5 % of answers |
| Grace period after deleting a base | 7 days |

## Pricing

On your own servers, Knowledge itself is included in the server fee, and embeddings and reranking on your own GPUs cost nothing. On the Frazer fleet, you pay for index storage and for searches and answers, with a free allowance each month. Model calls for context headers, answers and the judge are billed through the [LLM gateway](https://frazer.ai/docs/llm-gateway), and connectors have no fee of their own.

| Knowledge | On your servers | On the Frazer fleet |
| --- | --- | --- |
| Price | **Included** | $0.25 / GB-month + $0.50 per 1,000 queries · first 1 GB and 10,000 free |

Every line, with the estimator: [pricing](https://frazer.ai/pricing#lines).

## Troubleshooting

| Symptom | Cause | Fix |
| --- | --- | --- |
| The base declines a question you know it covers | The top rerank score is below the decline threshold, or the document is not indexed | Check the source’s freshness on the **Sources** tab; grade the answer “wrongful decline” so it becomes a golden-set candidate and tunes the threshold |
| A person gets fewer sources than a colleague | Permissions follow the source, or the person’s source account is not linked | Check the unmatched count on the **Sources** tab and link the alias; ask as that person in the playground (admins) |
| A source is left out of answers | Its permissions have been stale for more than 24 hours, for example after a revoked connection | Reconnect the source in the organization’s **Settings › Integrations**, then check its freshness on the **Sources** tab |
| A new index stays `gated` | It failed the evaluation gate | Open **Evaluations** to compare the two versions and the questions that got worse; fix the setting and build again |
| A source is refused on a public base | Public bases accept only public sources | Use a base with `source` or `group` access |
| The first sync costs more than expected | Context headers and embeddings run over every document once | Read the first-sync estimate in the plan before you apply, and set a budget on the base’s gateway key |

## Reference

### CLI

| Command | What it does |
| --- | --- |
| `frazer knowledge knowledge-bases create` | Create a knowledge base from a preset, with its sources, access mode and an MCP server. |
| `frazer knowledge sources add` | Add a source to a knowledge base. |
| `frazer knowledge ask` | Ask a question and get an answer with citations, or a reasoned decline. |
| `frazer knowledge eval-runs create` | Run an evaluation set against a knowledge base. |
| `frazer knowledge indexes build` | Build a new index version with changed retrieval settings, next to the active one. |
| `frazer knowledge mcp config` | Print the MCP configuration of a knowledge base for a client such as Claude Code. |

All of them: [CLI reference](https://frazer.ai/docs/cli).

### MCP tools

| Tool | What it does |
| --- | --- |
| `knowledge_bases_search` | Search a knowledge base and return the chunks the caller may see. |
| `knowledge_bases_ask` | Answer a question with citations, or decline with a reason. |
| `knowledge_documents_get` | Read one document the caller may open. |
| `knowledge_sources_list` | List the sources of a knowledge base. |
| `knowledge_feedback_create` | Grade an answer (good, weak, wrong, uncited, wrongful decline or correct decline). |
| `knowledge_proposals_create` | Propose a document for the knowledge base; a person or a passing check accepts it. Writes become a plan that waits for approval. |

All of them: [MCP tools reference](https://frazer.ai/docs/mcp).

### Events

| Event type | When it is sent |
| --- | --- |
| `frazer.knowledge.sync.failed.v1` | A source of a knowledge base failed to sync. |

All of them: [Events reference](https://frazer.ai/docs/webhooks).

## Related

-   [Knowledge product overview](https://frazer.ai/knowledge)
-   [LLM gateway](https://frazer.ai/docs/llm-gateway): every model call a base makes, with budgets
-   [AI and GPUs](https://frazer.ai/docs/ai): the embedding and rerank endpoints on your GPUs
-   [Devboxes](https://frazer.ai/docs/devboxes): provisioning profiles that put bases in every tool
-   [Integrations](https://frazer.ai/docs/integrations): the connections your sources use

## Pages in AI

- [AI and GPUs](https://frazer.ai/docs/ai.md)
- [LLM gateway](https://frazer.ai/docs/llm-gateway.md)
- [Knowledge](https://frazer.ai/docs/knowledge.md) (this page)