Skip to main content
HUMΛN

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:

Delegation scope Max classification visible
Default (public companion) Public
kb:read:internal Internal
Query param classification=ExternalPartner Caps at ExternalPartner when token allows

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:

  1. governanceTier (Canon vs Working) is separate from classification (Public / ExternalPartner / Internal / FoundersOnly).
  2. Companion RAG filters on classification via KbAccessContext.maxClassification.
  3. FoundersOnly docs require appropriate passport kind + scope — they do not leak through generic search.
  4. 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

>
SDK:

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

DO

Pass delegation tokens with least classification needed

Show classification badge on each cited doc in UI

DON'T

Bypass KbIndex with raw filesystem reads in product code

Echo FoundersOnly content to public companion deployments

See also

← All patterns