Declarative Knowledge Sources

The knowledge_sources top-level config block declares durable knowledge sources that materialize content into the Knowledge Base. Each source defines where content comes from, how often it syncs, and how it binds to configurations.

Use this page when

• You need to declare a knowledge source that syncs content into the Knowledge Base.
• You want to understand the source taxonomy and reference requirements.
• You are configuring sync schedules, bindings, or auto-promotion rules.
• You need to troubleshoot validation errors for connector_ref vs tool_server_ref.

Primary audience

• Primary: Technical Engineers, AI Agents
• Secondary: Technical Leaders

Source taxonomy

Source kind	Description	Required ref
connector_sync	Pulls content from an external connector on schedule	connector_ref
tool_projection	Projects tool output from an MCP tool server	tool_server_ref
upload	Content uploaded directly (API or CLI)	Neither
learning_synthesis	Synthesized from learned sessions	Neither
manual	Manually authored content	Neither

Reference requirements

Each knowledge source must have at most one backing reference:

• connector_ref — references a connector by ID for connector_sync sources.
• tool_server_ref — references a tool_servers[].id for tool_projection sources.

The gateway enforces mutual exclusivity: specifying both connector_ref and tool_server_ref on the same source is a validation error. The gateway also enforces source-kind pairing — connector_sync requires connector_ref, and tool_projection requires tool_server_ref.

Config structure

knowledge_sources:
  - id: "api-docs-sync"
    name: "API Documentation"
    source_kind: connector_sync
    connector_ref: "confluence-main"
    schedule:
      mode: periodic
      interval_minutes: 60
    binding:
      configuration_ids:
        - "prod-gateway-config"
    auto_promote: true
    labels:
      domain: engineering
      freshness: hourly

  - id: "code-index-projection"
    name: "Code Search Index"
    source_kind: tool_projection
    tool_server_ref: "code-search"
    schedule:
      mode: on_change
    binding:
      configuration_ids:
        - "dev-gateway-config"
    auto_promote: false
    labels:
      domain: engineering

  - id: "team-runbooks"
    name: "Team Runbooks"
    source_kind: manual
    binding:
      configuration_ids:
        - "prod-gateway-config"
        - "staging-gateway-config"
    auto_promote: true

Fields

Required

Field	Type	Description
id	string	Unique identifier for this knowledge source.
source_kind	enum	One of connector_sync, tool_projection, upload, learning_synthesis, manual.

Optional

Field	Type	Default	Description
name	string	—	Human-readable display name.
description	string	—	Purpose description.
connector_ref	string	—	Connector ID. Required for connector_sync, forbidden otherwise.
tool_server_ref	string	—	Tool server ID from tool_servers[].id. Required for tool_projection, forbidden otherwise.
schedule	object	—	Sync schedule configuration.
binding	object	—	Configuration binding for Knowledge Base materialization.
auto_promote	boolean	false	Whether synced content is automatically promoted to active status.
labels	map	—	Key-value pairs for ABAC matching and discovery.

Schedule modes

schedule:
  mode: periodic
  interval_minutes: 60

Mode	Description	Additional fields
periodic	Syncs at a fixed interval	interval_minutes (required)
on_change	Syncs when the backing source signals a change	None
manual	Only syncs on explicit trigger	None

If schedule is omitted, the source defaults to manual-trigger-only behavior.

Binding

Binding connects a knowledge source to one or more gateway configurations. When content materializes from the source, it becomes available to the bound configurations' Knowledge Base context.

binding:
  configuration_ids:
    - "config-alpha"
    - "config-beta"

Auto-promotion

When auto_promote: true, newly synced content versions are automatically promoted to active status without requiring manual review. When false (default), new versions land in draft status and require explicit promotion through the console or API.

Referential integrity

The gateway validates that:

1. tool_server_ref values reference an existing entry in the tool_servers block (same config or composed overlay).
2. connector_ref values reference a valid connector known to the control-plane API.

If a tool_server_ref points to a non-existent tool server ID, the config fails to parse with a referential integrity error.

Merge behavior

When multiple config sources are composed (e.g., base + overlay), knowledge sources merge by id. A later declaration with the same id fully replaces the earlier one — there is no partial field merge.

Validation rules summary

Rule	Error message
Both connector_ref and tool_server_ref present	mutually exclusive: connector_ref and tool_server_ref
connector_sync without connector_ref	connector_sync source requires connector_ref
tool_projection without tool_server_ref	tool_projection source requires tool_server_ref
upload/manual/learning_synthesis with either ref	source kind does not accept connector_ref or tool_server_ref
tool_server_ref references unknown ID	tool_server_ref references non-existent tool_servers entry
schedule.mode is periodic without interval_minutes	periodic schedule requires interval_minutes
Duplicate id within the same config file	duplicate knowledge_source id

Common errors

Error	Cause	Fix
mutually exclusive: connector_ref and tool_server_ref	Both refs specified on one source	Remove one — use exactly the ref matching your source_kind.
connector_sync source requires connector_ref	Missing connector_ref on a connector_sync source	Add connector_ref pointing to the connector ID.
tool_server_ref references non-existent tool_servers entry	The referenced tool server ID doesn't exist	Ensure the tool server is declared in tool_servers in the same config scope.
source kind does not accept connector_ref or tool_server_ref	A manual, upload, or learning_synthesis source has a ref	Remove the ref field — these source kinds are self-contained.

Related

• Declarative Tool Servers — tool_server_ref points at entries in tool_servers
• Knowledge Base CLI — managing knowledge assets via kt knowledge-base
• Config Variables — runtime credential resolution for connectors and tool servers