OSS-first docs

These docs teach the open system first: contracts, generated surfaces, runtimes, governance, and incremental adoption. Studio shows up as the operating layer on top, not as the source of truth.

AI index

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

FeatureCanonicalOperationalExternalEphemeral
Trust LevelHighestHighMediumLow
Policy Impact✅ Can drive decisions⚠️ Can inform❌ Reference only❌ Never used
MutabilityImmutableMutableMutableTemporary
RetentionPermanentLong-termLong-termShort-term
Audit LevelFull auditFull auditBasic auditMinimal 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 KnowledgeKnowledge Spaces