Canon RAG with citations

# Canon RAG with citations

Companion and MCP clients retrieve Canon-grounded answers from the HUMΛN Knowledge Base — not the open web. Search results are filtered by the caller's classification ceiling; responses should surface human://kb/{doc_id} citations so humans can verify claims.

Overview

Search API — GET /v1/companion/kb/search?q=&limit=&classification=

Access engine — @human/companion-kb (KbIndex.search) enforces maxClassification from delegation scopes

MCP tool — human.companion.kb_search (same route)

MCP resources — human://kb/{doc_id} reads for full doc bodies when scope allows

Implementation: apps/api/src/routes/companion/index.ts (kb/search), packages/companion-kb/.

Classification gate

Every search derives the maximum visible classification from the delegation token:

Documents above the ceiling never appear in results — the gate is enforced in @human/companion-kb, not by prompt instructions.

KB classification (alias: kb/classification)

Community links to /docs/patterns/kb/classification resolve here. The gate rules are:

governanceTier (Canon vs Working) is separate from classification (Public / ExternalPartner / Internal / FoundersOnly).

Companion RAG filters on classification via KbAccessContext.maxClassification.

FoundersOnly docs require appropriate passport kind + scope — they do not leak through generic search.

Optional query override ?classification=ExternalPartner only lowers the ceiling for partner-scoped tokens; it cannot elevate access.

Prefer this page (companion/canon-rag) in new links. Thin alias: kb/classification.

Try it

Rendering citations in Companion UX

When Companion classifies a turn as question, include citations in the UI:

interface KbCitation {
  uri: string;   // human://kb/22_humanos_orchestration_core
  title: string;
}
function renderAnswer(text: string, citations: KbCitation[]) {
  return {
    body: text,
    sources: citations.map((c) => ({
      label: c.title,
      href: /docs/kb/${c.uri.replace('human://kb/', '')},
    })),
  };
}

Fourth Law: if search returns zero hits above confidence threshold, say so — do not fabricate Canon.

MCP consumption

// Tool: human.companion.kb_search — same as GET /v1/companion/kb/search
// Resource: human://kb/{doc_id} — full document when classification permits

Scopes: kb:read:public, kb:read:internal, kb:read:* per org delegation vocabulary (kb/175).

Use cases

Companion widget — ground answers in KB before proposing intent_action.

Internal Console — delegation with kb:read:internal for engineering runbooks.

Partner portal — ExternalPartner ceiling for vetted external docs only.

Security considerations

See also

Intent modes

KB classification (alias)

Community: KB access control explainer

Package: @human/companion-kb

Same route in the other SDKs

The TypeScript tab above is the contract. These calls hit that same route.