Knowledge Categories

ContractSpec classifies knowledge into four categories based on trust level, source authority, and intended use. This classification determines how knowledge can be used in workflows, policy decisions, and agent responses.

The four categories

type KnowledgeCategory =
  | "canonical"   // Internal ground truth
  | "operational" // Internal operational docs
  | "external"    // Third-party reference
  | "ephemeral";  // Temporary context

1. Canonical

Trust level: Highest - Authoritative ground truth

What it contains:

Official product specifications and schemas
Company policies and procedures
Legal terms and compliance requirements
Pricing rules and business logic
Data classification and security policies

How it's used:

Policy decisions - Can drive PDP decisions
Validation - Used to validate user inputs and operations
Code generation - Source of truth for generated code
Compliance - Reference for audit and regulatory checks

Examples:

// Product Canon space
{
  id: "product-canon",
  category: "canonical",
  sources: [
    "database-schema.sql",
    "product-catalog.yaml",
    "pricing-rules.json"
  ]
}

// Policy Canon space
{
  id: "policy-canon",
  category: "canonical",
  sources: [
    "data-classification.yaml",
    "access-policies.rego",
    "compliance-requirements.md"
  ]
}

⚠️ Important: Canonical knowledge is immutable once indexed. Changes require re-sync and versioning.

2. Operational

Trust level: High - Internal but not authoritative

What it contains:

Support ticket history and resolutions
Internal runbooks and playbooks
Sales materials and customer communications
Product management docs and roadmaps
Team wikis and knowledge bases

How it's used:

Context - Provides helpful context for decisions
Suggestions - Informs recommendations, not requirements
Learning - Helps agents learn from past interactions
Troubleshooting - Guides problem-solving workflows

Examples:

// Support History space
{
  id: "support-history",
  category: "operational",
  sources: [
    "gmail:support@company.com",
    "zendesk:tickets",
    "slack:support-channel"
  ]
}

// Internal Docs space
{
  id: "internal-docs",
  category: "operational",
  sources: [
    "notion:engineering-wiki",
    "confluence:product-docs",
    "google-drive:runbooks"
  ]
}

3. External

Trust level: Medium - Reference only

What it contains:

Third-party integration documentation (Stripe, Twilio)
Regulatory and compliance documents
Industry standards and best practices
Public API documentation
External knowledge bases

How it's used:

Reference - Consulted but not authoritative
Integration help - Guides external API usage
Compliance context - Provides regulatory background
Never for policy - Cannot drive policy decisions

Examples:

// External Provider Docs space
{
  id: "provider-docs",
  category: "external",
  sources: [
    "url:https://stripe.com/docs",
    "url:https://twilio.com/docs",
    "url:https://openai.com/docs"
  ]
}

// Regulatory Docs space
{
  id: "regulatory-docs",
  category: "external",
  sources: [
    "url:https://gdpr.eu/",
    "url:https://www.hhs.gov/hipaa",
    "pdf:SOC2-requirements.pdf"
  ]
}

⚠️ Note: External knowledge should be clearly marked in agent responses as "according to [source]" to indicate it's not internal authority.

4. Ephemeral

Trust level: Low - Temporary context only

What it contains:

Agent conversation history and scratchpads
Session-specific context and state
Draft documents and work-in-progress
Temporary calculations and intermediate results
User-provided context for current task

How it's used:

Session continuity - Maintains conversation context
Working memory - Stores intermediate results
Never persisted long-term - Auto-purged after session
Never for decisions - Cannot influence policy or validation

Examples:

// Agent Scratchpad space
{
  id: "agent-scratchpad",
  category: "ephemeral",
  retentionPolicy: { days: 1 },
  sources: [
    "session:current-conversation",
    "memory:agent-working-memory"
  ]
}

// User Session space
{
  id: "user-session",
  category: "ephemeral",
  retentionPolicy: { days: 7 },
  sources: [
    "session:user-uploads",
    "session:form-drafts"
  ]
}

⚠️ Critical: Ephemeral knowledge is never used for policy decisions, compliance checks, or any authoritative purpose.

Category comparison

Feature	Canonical	Operational	External	Ephemeral
Trust Level	Highest	High	Medium	Low
Policy Impact	✅ Can drive decisions	⚠️ Can inform	❌ Reference only	❌ Never used
Mutability	Immutable	Mutable	Mutable	Temporary
Retention	Permanent	Long-term	Long-term	Short-term
Audit Level	Full audit	Full audit	Basic audit	Minimal audit

Best practices

Use canonical for anything that affects policy, pricing, or compliance
Use operational for context that helps but doesn't dictate decisions
Use external for reference material that's helpful but not authoritative
Use ephemeral for temporary working memory that shouldn't persist
Never mix categories in a single knowledge space - keep them separate
Document the category and purpose of each knowledge space clearly

Back to Knowledge Knowledge Spaces