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.

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:

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.
A question with several parts is rewritten into sub-queries.
Hybrid search (meaning and keywords, fused) runs with the caller’s permissions as a filter inside the search.
A reranker keeps the best chunks.
For Google Drive, SharePoint and Confluence, the top results are re-checked against the source before the answer.
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.
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). The examples use two bases of the Acme demo organization: acme-engineering (code and issues) and acme-company (handbook, docs and Slack).

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.

Create the base.

CLI
Console

frazer knowledge knowledge-bases create acme-engineering --preset engineering --access source \
  --source github:all --source linear:ENG,OPS --mcp --dry-run

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.

Knowledge bases are also resources in the Terraform and OpenTofu provider.

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.

Ask a question.

frazer knowledge ask acme-company "How do we rotate the payments webhook secret?"

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:

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

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:

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:

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.

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:

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:

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:

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

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.

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.

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.

Knowledge product overview
LLM gateway: every model call a base makes, with budgets
AI and GPUs: the embedding and rerank endpoints on your GPUs
Devboxes: provisioning profiles that put bases in every tool
Integrations: the connections your sources use