ContractSpec docs

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 Spaces

A KnowledgeSpaceSpec defines a logical domain of knowledge with a specific category, storage strategy, and intended audience. Spaces are defined globally and populated per-tenant through knowledge sources.

KnowledgeSpaceSpec

type KnowledgeSpaceSpec = {
  id: string;
  label: string;
  description: string;
  
  // Trust and access
  category: KnowledgeCategory;
  intendedAudience: "agents" | "humans" | "admin-only";
  
  // Storage and indexing
  storageStrategy: "vector" | "search" | "hybrid";
  indexProvider: string;  // e.g., "qdrant", "elasticsearch"
  vectorDimensions?: number;  // For vector storage
  
  // Lifecycle
  retentionPolicy: {
    days?: number;
    versions?: number;
  };
  
  // Metadata
  tags?: string[];
  owner?: string;
  createdAt: string;
  updatedAt: string;
};

Common knowledge spaces

Product Canon

{
  id: "product-canon",
  label: "Product Canon",
  description: "Official product specifications and schemas",
  category: "canonical",
  intendedAudience: "agents",
  storageStrategy: "hybrid",
  indexProvider: "qdrant",
  vectorDimensions: 1536,
  retentionPolicy: { versions: 10 }
}

Use cases: Invoice generation, quote creation, product recommendations, schema validation

Support History

{
  id: "support-history",
  label: "Support History",
  description: "Past support tickets and resolutions",
  category: "operational",
  intendedAudience: "agents",
  storageStrategy: "vector",
  indexProvider: "qdrant",
  vectorDimensions: 1536,
  retentionPolicy: { days: 365 }
}

Use cases: Customer support, troubleshooting, similar issue detection

External Provider Docs

{
  id: "provider-docs",
  label: "External Provider Docs",
  description: "Third-party integration documentation",
  category: "external",
  intendedAudience: "agents",
  storageStrategy: "search",
  indexProvider: "elasticsearch",
  retentionPolicy: { days: 90 }
}

Use cases: Integration help, API reference, troubleshooting external services

Agent Scratchpad

{
  id: "agent-scratchpad",
  label: "Agent Scratchpad",
  description: "Temporary agent working memory",
  category: "ephemeral",
  intendedAudience: "agents",
  storageStrategy: "vector",
  indexProvider: "qdrant",
  vectorDimensions: 1536,
  retentionPolicy: { days: 1 }
}

Use cases: Conversation continuity, intermediate calculations, session state

Storage strategies

Strategy

Best For

Providers

vector

Semantic search, RAG, similarity matching

Qdrant, Pinecone, Weaviate

search

Keyword search, exact matching, filtering

Elasticsearch, Algolia

hybrid

Combined semantic + keyword search

Qdrant + Elasticsearch

Best practices

  • Choose storage strategy based on query patterns - use vector for semantic, search for exact

  • Set appropriate retention policies - canonical is permanent, ephemeral is short-lived

  • Use consistent vector dimensions across spaces that will be queried together

  • Document the intended audience and use cases for each space

  • Monitor space size and query performance - add sharding if needed

Previous: Categories

Knowledge Sources