KnowledgeProviderConfig

Runtime-level knowledge configuration. Configured once on the Runtime, inherited by all agents. Per-agent overrides via AgentKnowledgeOverrides can only reduce capabilities (e.g., disable compiled knowledge, restrict topK, filter by metadata).

Properties

cache?

optional cache?: object;

Retrieval cache configuration. When omitted, a default configuration is used (maxEntries: 256, ttlMs: 300000, similarityThreshold: 0.85).

Name	Type	Description
maxEntries?	number	Maximum entries in the LRU cache. Default: 256.
similarityThreshold?	number	Minimum cosine similarity for a cache hit. Default: 0.85.
ttlMs?	number	Cache entry TTL in milliseconds. Default: 300000 (5 minutes).

---

compiled?

optional compiled?: string;

Pre-compiled knowledge content (Layer 1). Injected into the system prompt every turn with zero search latency. Produced offline by KnowledgeCompiler.

---

defaults?

optional defaults?: object;

Default retrieval options applied to all agents unless overridden.

Name	Type	Description
includeEmbeddings?	boolean	Whether to include embedding vectors in results (for cache writeback). Default: true.
maxOutputTokens?	number	Maximum tokens for retrieval context in the system prompt. Default: 2000.
topK?	number	Maximum results from Layer 3 search. Default: 5.

---

embedder?

optional embedder?: KnowledgeEmbedderAdapter;

Embedder for cache similarity lookup. Required when retriever is provided (needed for cache population and query embedding).

---

prefetch?

optional prefetch?: object;

Predictive pre-fetch configuration. When enabled, the system predicts follow-up topics from the conversation window and pre-fetches relevant content into the session cache.

Name	Type	Description
conversationWindow?	number	Number of recent messages to analyze. Default: 5.
enabled?	boolean	Enable predictive pre-fetching. Default: false.
maxKeywords?	number	Number of keywords to extract per prediction. Default: 3.

---

qualityCheck?

optional qualityCheck?: object;

Retrieval quality checking configuration. When configured, retrieval results are evaluated using score distribution (sub-millisecond). For text agents, low-quality results trigger inline reformulation. For voice agents, low-quality results trigger background reformulation via the pre-fetcher.

Name	Type	Description
highThreshold?	number	Minimum top-result score to consider quality “high”. Default: 0.5.
mediumThreshold?	number	Minimum top-result score to consider quality “medium”. Default: 0.3.
reformulate()?	(query, results) => Promise<string>	Query reformulator callback. When provided and quality is “low”, the system rewrites the query and re-retrieves.

---

renderCitations?

optional renderCitations?: "inline" | "footnotes" | "off";

How retrieved source references should be rendered into the model prompt. Defaults to ‘footnotes’.

---

retriever?

optional retriever?: KnowledgeRetrieverAdapter;

Retriever for hybrid search (Layer 3). Any object implementing the Retriever interface from @kuralle-agents/rag. When not provided, only compiled knowledge and cache are available.