Skip to main content
When an AI agent answers from a knowledge base, two questions matter as much as answer quality: whose content was retrieved, and whether the answer actually rests on it. This page walks one retrieval turn end to end — the scoping applied to every query, the isolation layers that keep workspaces apart, the post-check that ties answers back to retrieved chunks, and the redaction applied to retrieved context before it reaches the model.

​
1. Anatomy of a retrieval turn

Every turn that touches a knowledge base runs the same sequence:
  1. The question is embedded. The customer’s message is converted to a vector, together with a few rephrased variations of the same question for better recall. The vectors, not keywords, are what get matched against your stored chunks.
  2. Every search carries a scope. Each attached knowledge base is queried with a mandatory filter: a chunk is a candidate only if it carries your tenant identifier (the same schema-scoped tenant name written at ingest time, stored on the chunk as the tenantId payload field) and the knowledge base’s own identifier (knowledgeBaseId). A chunk that matches neither your workspace nor the queried knowledge base is excluded regardless of how high its similarity score is.
  3. Top-K and score threshold resolve in a fixed order. A per-knowledge-base override beats the agent-level retrieval setting, which beats the platform default. Values are clamped to platform bounds and malformed values are rejected, so a misconfigured agent can never widen retrieval past the platform’s limits.
  4. Attached knowledge bases are capped per turn. The workspace setting max_knowledge_bases_per_agent limits how many of an agent’s attached knowledge bases are queried in one turn. It defaults to 3, clamps to 1–10, and if the setting cannot be read the turn proceeds with the legacy default of 3.
The cap and the filter together define a turn’s retrieval surface: which knowledge bases are queried at all, and which chunks inside them are candidates.

​
2. The isolation layers

Scoping is layered, and each layer has a distinct job:
  • Per-workspace collections. Knowledge bases are indexed into a collection named for your organization. This is the primary isolation guard: a retrieval against your collection physically cannot see chunks stored under another organization’s collection.
  • Payload filters on the shared collection. Some retrieval paths query the platform’s shared chunk collection, where the only scoping is the payload filter from section 1 — the tenant and knowledge-base match clauses. Correctness on those paths rests on the filter being complete on every call.
  • Strict isolation as defense in depth. The workspace setting strict_rag_isolation adds a third mandatory clause — your organization identifier — to shared-collection queries. With the toggle on, even a hypothetical filter bug that dropped the other clauses could not return another workspace’s chunks, because the organization clause is required independently of them.
Strict isolation is on by default for workspaces created after late May 2026. Workspaces whose knowledge bases were indexed before the organization identifier was recorded at ingest time default to off: enabling the toggle for them would filter out their own content, because those older chunks carry no organization field. You can enable it per workspace at any time, and a change takes effect on subsequent turns within about 30 seconds.

​
3. Grounding integrity

After the model answers, a post-check re-embeds the answer and matches it against the same knowledge base’s chunks, under the same scoping discipline as retrieval: the tenant and knowledge-base clauses are mandatory, and a call that lacks a tenant scope aborts the check rather than running an unscoped search. The top three matches are averaged; when the average similarity falls below the 0.7 floor, the answer is flagged as potentially unsupported by the knowledge base. The check is only as good as its filter’s field names. The match clauses must use exactly the payload keys the indexer writes — camelCase tenantId and knowledgeBaseId. An earlier version of the check matched on a key style the indexer never wrote, so it found zero chunks and every answer scored as consistent regardless of content; the mismatch was caught in an April 2026 audit and fixed. The current contract keeps retrieval and the post-check on one shared scoping discipline so the two cannot drift apart. The fail-open contract is deliberate: when the check cannot run — no knowledge base attached, an embedding failure, or zero matching chunks — the answer proceeds instead of being blocked. The post-check is a quality and observability layer, not a retrieval gate. The scoping in sections 1 and 2 is the part that never fails open.

​
4. PII redaction of retrieved context

Retrieved chunks pass two independent gates before entering the model context, and redaction is disabled only when both gates allow it:
  • The workspace setting rag_pii_redaction, on by default.
  • The per-agent safety setting pii_redaction, on by default.
Explicitly turning both off disables redaction of retrieved context; leaving either one on keeps it. The same two-gate model governs tool arguments and the agent’s other egress paths; the full model is in PII egress guard model.

​
5. Tenant-owned configuration

​
These controls are posture, not certification

Every setting above is tenant-owned: you tune how retrieval behaves and how strictly it is scoped for your workspace. They configure your retrieval posture; they are not a compliance certification, and switching one off neither adds nor removes any regulatory obligation. The platform-wide boundary these controls sit inside is described in Tenant isolation.

​
Cross-references