@juspay/neurolink 10.3.1 → 10.4.0

package/dist/lib/types/knowledge.d.ts

@@ -0,0 +1,342 @@
+/**
+ * Knowledge grounding — lexical-first host-supplied knowledge retrieval.
+ *
+ * A host application owns a structured *knowledge registry*: versioned entries
+ * describing concepts, configuration, taxonomies, procedures, and operating
+ * rules. NeuroLink owns the
+ * generic engine that ingests that registry, builds an in-memory lexical
+ * index once per instance, and — independently of tool routing — retrieves a
+ * small, token-bounded set of relevant entries before each main model call.
+ * The selected entries are attached as *ephemeral context*: visible to the
+ * current generation call, never persisted into conversation memory.
+ *
+ * This is retrieval-augmented generation WITHOUT vector retrieval. The first
+ * release ranks with exact identifiers, reviewed aliases, metadata filters,
+ * and weighted field-aware BM25 only. No embedding model, embedding service,
+ * or vector store is initialized. An LLM reranker and semantic retrieval are
+ * deferred behind an explicit evaluation gate.
+ *
+ * Ownership boundary: NeuroLink defines the contracts below and the engine;
+ * it never contains host product content. The host supplies content and
+ * per-request scope. The engine stays provider-neutral.
+ *
+ * Type names are globally prefixed `Knowledge*` to satisfy the repo's
+ * unique-type-name rule and to avoid collision with the pre-existing
+ * web-search `grounding.ts` vocabulary (`EnhancedGroundingMetadata` et al.),
+ * which is a different concept (Google search grounding, not product
+ * knowledge).
+ */
+/** What a knowledge entry primarily is. Drives context labelling, not ranking. */
+export type KnowledgeEntryKind = "concept" | "text" | "configuration" | "tool" | "procedure" | "policy" | "troubleshooting";
+/** Lifecycle state. Only `active` entries are retrievable by default. */
+export type KnowledgeStatus = "draft" | "active" | "deprecated";
+/**
+ * Retrieval mode. Only `"lexical"` is supported in the first release; the
+ * literal is a union of one to reserve a clean upgrade path to `"hybrid"` /
+ * `"vector"` without a breaking change.
+ */
+export type KnowledgeRetrievalMode = "lexical";
+/**
+ * Confidence class returned with every retrieval so the host prompt can
+ * instruct the model to qualify low-confidence answers rather than present
+ * them as authoritative.
+ */
+export type KnowledgeRetrievalConfidence = "high" | "medium" | "low" | "none";
+/** The five weighted text fields used by the field-aware lexical scorer. */
+export type KnowledgeFieldName = "title" | "aliases" | "keywords" | "summary" | "body";
+/**
+ * The record a host author writes. `id`, `title`, `summary`, `domain`, and
+ * `integrations` are required; every other field is optional and omitted
+ * optionals fall back to SDK defaults during normalization.
+ */
+export type KnowledgeEntryInput = {
+    /** Stable unique id (e.g. "account.multi-step-flow"). Drives exact-match lookup and citations. */
+    id: string;
+    /** Human-readable name of the concept/setting. Highest-weighted search field. */
+    title: string;
+    /** One-line searchable description — the short answer when a full body is unnecessary. */
+    summary: string;
+    /** Primary grouping and the main retrieval filter (e.g. "account-settings"). */
+    domain: string;
+    /** Integration identifiers this entry applies to. Empty array = applies to all integrations. */
+    integrations: string[];
+    /** What the entry is (concept, configuration, procedure, …). Default "text". Labels context, not ranking. */
+    kind?: KnowledgeEntryKind;
+    /** Lifecycle state. Default "active"; only active entries are retrievable. */
+    status?: KnowledgeStatus;
+    /** Full explanatory content (Markdown). Use only when the summary is insufficient. */
+    body?: string;
+    /** Reviewed alternate phrasings or raw identifiers that resolve to exact and alias matches. */
+    aliases?: string[];
+    /** Extra search terms that aid recall but are not full aliases. */
+    keywords?: string[];
+    /** Ids of directly related entries, pulled in by bounded relationship expansion. */
+    relatedEntryIds?: string[];
+    /** Id of the parent entry when this is a subtype or child. */
+    parentEntryId?: string;
+};
+/**
+ * The complete, defaults-resolved record NeuroLink indexes and injects. Omitted
+ * optionals are materialized (arrays to `[]`, `body` to `""`, `kind` to "text",
+ * `status` to "active") so downstream code never re-checks the resolution chain.
+ * Field meanings mirror `KnowledgeEntryInput`.
+ */
+export type NormalizedKnowledgeEntry = {
+    id: string;
+    title: string;
+    summary: string;
+    domain: string;
+    integrations: string[];
+    kind: KnowledgeEntryKind;
+    status: KnowledgeStatus;
+    body: string;
+    aliases: string[];
+    keywords: string[];
+    relatedEntryIds: string[];
+    parentEntryId?: string;
+    /** Content version from the source/manifest; appears in citations as [KB:id@version]. */
+    version: string;
+};
+/** One catalog inside a build manifest — a source id and its entries. */
+export type KnowledgeManifestCatalog = {
+    id: string;
+    entries: KnowledgeEntryInput[];
+};
+/**
+ * The versioned build artifact a host emits at build time. NeuroLink can
+ * consume it directly (each catalog becomes a structured source) so hosts do
+ * not need to construct `KnowledgeSource[]` by hand.
+ */
+export type KnowledgeManifest = {
+    schemaVersion: string;
+    contentVersion: string;
+    generatedAt: string;
+    catalogs: KnowledgeManifestCatalog[];
+};
+/**
+ * A configured knowledge source: inline structured entries passed to the
+ * engine. Markdown/provider source kinds were intentionally dropped for now;
+ * re-introduce this as a discriminated union (with a `type` tag) if another
+ * source kind is needed later.
+ */
+export type KnowledgeSource = {
+    id: string;
+    version?: string;
+    entries: KnowledgeEntryInput[];
+};
+/**
+ * Relative weight applied to a lexical match in each field. Title/alias
+ * matches outrank body matches. Tunable through evaluation.
+ */
+export type KnowledgeFieldWeights = {
+    title: number;
+    aliases: number;
+    keywords: number;
+    summary: number;
+    body: number;
+};
+/** Lexical retrieval tuning. All fields optional; the engine supplies defaults. */
+export type KnowledgeRetrievalConfig = {
+    /** Retrieval mode. Default: "lexical". */
+    mode?: KnowledgeRetrievalMode;
+    /** How many scored candidates enter relationship expansion. Default: 24. */
+    candidateLimit?: number;
+    /** How many primary entries survive into the assembled context. Default: 8. */
+    resultLimit?: number;
+    /** Cap on relationship-expanded entries added after primary retrieval. Default: 4. */
+    relationLimit?: number;
+    /** Per-field BM25 weights. */
+    fieldWeights?: KnowledgeFieldWeights;
+    /** Additive boost for an exact entry-id / configuration-key match. Dominant. Default: 100. */
+    exactBoost?: number;
+    /** Additive boost for an exact reviewed-alias phrase match. Default: 60. */
+    aliasBoost?: number;
+};
+/** Ephemeral-context assembly limits. */
+export type KnowledgeContextConfig = {
+    /** Hard token budget for the assembled grounding block. Default: 4000. */
+    maxTokens?: number;
+    /** Emit `[KB:<id>@<version>]` citations. Default: true. */
+    includeCitations?: boolean;
+};
+/**
+ * Constructor-level configuration for knowledge grounding. Sources are fixed
+ * for the lifetime of a NeuroLink instance so the index can be built once.
+ */
+export type KnowledgeGroundingConfig = {
+    /** Master switch. Grounding runs only when true AND at least one source is loaded. */
+    enabled: boolean;
+    /**
+     * Knowledge sources used to build the instance's immutable in-memory index.
+     * Required alongside `enabled`; pass an empty array only when intentionally
+     * configuring no retrievable content.
+     */
+    sources: KnowledgeSource[];
+    /** Exclude these domains from retrieval. Empty/omitted means all domains are eligible. */
+    blockedDomains?: string[];
+    retrieval?: KnowledgeRetrievalConfig;
+    context?: KnowledgeContextConfig;
+    /** Hard ceiling for one grounding operation before it fails open. Default: 800ms. */
+    timeoutMs?: number;
+};
+/**
+ * Per-call scope the host attaches to `GenerateOptions` / `StreamOptions`.
+ * Supplies the enabled integrations for this turn only.
+ */
+export type KnowledgeRequestScope = {
+    /** Installed/enabled integrations used to filter integration-specific entries. */
+    enabledIntegrations?: string[];
+};
+/** One bounded recent conversation turn used to contextualize the query. */
+export type KnowledgeConversationTurn = {
+    role: "user" | "assistant";
+    text: string;
+};
+/**
+ * The fully-resolved retrieval request the engine builds internally from the
+ * user query, a bounded recent window, and host scope.
+ */
+export type KnowledgeRetrievalRequest = {
+    query: string;
+    recentTurns: KnowledgeConversationTurn[];
+    enabledIntegrations: string[];
+};
+/**
+ * The internal search document built from a normalized entry. `exactKeys` and
+ * `fields` hold pre-tokenized normalized text. Internal to NeuroLink.
+ */
+export type IndexedKnowledgeDocument = {
+    id: string;
+    /** Normalized whole-phrase keys for exact/alias resolution. */
+    exactKeys: string[];
+    /** Per-field normalized token arrays fed to the field-aware BM25 scorer. */
+    fields: {
+        title: string[];
+        aliases: string[];
+        keywords: string[];
+        summary: string[];
+        body: string[];
+    };
+};
+/** One lexical match with its per-field score breakdown, for tuning and traces. */
+export type KnowledgeLexicalMatch = {
+    id: string;
+    score: number;
+    fieldScores: Partial<Record<KnowledgeFieldName, number>>;
+};
+/**
+ * Structural contract of the field-aware lexical index held in a snapshot. A
+ * concrete class in the knowledge runtime module satisfies this shape; typing
+ * it structurally keeps this types file free of runtime imports.
+ */
+export type KnowledgeLexicalSearcher = {
+    search: (queryTokens: string[], topK: number, eligibleEntryIds?: ReadonlySet<string>) => KnowledgeLexicalMatch[];
+};
+/**
+ * Immutable, ready-to-query index built once at client construction. Sessions
+ * and turns search this snapshot; it is never mutated in place.
+ */
+export type KnowledgeIndexSnapshot = {
+    entriesById: Map<string, NormalizedKnowledgeEntry>;
+    /** Normalized entry id or title phrase -> entry ids. */
+    exactIndex: Map<string, Set<string>>;
+    /** Normalized reviewed alias phrase -> entry ids. */
+    aliasIndex: Map<string, Set<string>>;
+    /** Entry id -> directly related entry ids, for bounded expansion. */
+    relationIndex: Map<string, string[]>;
+    /** Field-aware BM25 over all documents. */
+    lexical: KnowledgeLexicalSearcher;
+    entryCount: number;
+};
+/** A stable citation to a specific knowledge entry version. */
+export type KnowledgeCitation = {
+    id: string;
+    version: string;
+};
+/**
+ * The result of one retrieval: the selected entries, the assembled ephemeral
+ * context string, a confidence class, and assembly diagnostics.
+ */
+export type KnowledgeRetrievalResult = {
+    entries: NormalizedKnowledgeEntry[];
+    assembledContext: string;
+    confidence: KnowledgeRetrievalConfidence;
+    citations: KnowledgeCitation[];
+    /** Ids of the primary (non-expanded) entries, in final order. */
+    selectedEntryIds: string[];
+    /** Ids added by bounded relationship expansion. */
+    expandedEntryIds: string[];
+    /** Candidates scored before truncation to the result limit. */
+    candidateCount: number;
+    /** Estimated token size of `assembledContext`. */
+    contextTokens: number;
+    /** True when any entry body was truncated or entries were dropped for budget. */
+    truncated: boolean;
+    durationMs: number;
+};
+/**
+ * A block of context assembled for a single generation call without becoming
+ * durable conversation. The NeuroLink call boundary injects its content into
+ * the effective system prompt and never persists it as a user message.
+ */
+export type EphemeralContext = {
+    content: string;
+    kind: "knowledge";
+    /** Host-supplied reviewed content is trusted reference data. */
+    trusted: boolean;
+    citations?: KnowledgeCitation[];
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Aggregate, content-free diagnostics attached to a generation/stream result
+ * so the host can evaluate retrieval without the SDK exposing entry bodies.
+ */
+export type KnowledgeGroundingMetadata = {
+    retrievalMode: KnowledgeRetrievalMode;
+    selectedIds: string[];
+    expandedIds: string[];
+    candidateCount: number;
+    contextTokens: number;
+    truncated: boolean;
+    durationMs: number;
+    confidence?: KnowledgeRetrievalConfidence;
+    /** Present when grounding failed open; names the failure class. */
+    failureReason?: string;
+};
+/** A single validation problem found while normalizing/indexing a source. */
+export type KnowledgeValidationIssue = {
+    level: "error" | "warning";
+    code: string;
+    message: string;
+    entryId?: string;
+    sourceId?: string;
+};
+/** Outcome of validating a set of sources before indexing. */
+export type KnowledgeValidationResult = {
+    ok: boolean;
+    issues: KnowledgeValidationIssue[];
+};
+/** Per-turn input to `KnowledgeGroundingEngine.ground()`. */
+export type KnowledgeGroundingInput = {
+    query: string;
+    recentTurns?: KnowledgeConversationTurn[];
+    scope?: KnowledgeRequestScope;
+};
+/**
+ * The engine's per-turn output: the ephemeral context to inject (null on
+ * no-match, when disabled, or on fail-open), the aggregate metadata for the
+ * result, and the full retrieval for host diagnostics.
+ */
+export type KnowledgeGroundingOutcome = {
+    ephemeralContext: EphemeralContext | null;
+    metadata: KnowledgeGroundingMetadata;
+    retrieval: KnowledgeRetrievalResult | null;
+};
+/** Snapshot of engine health for telemetry and host introspection. */
+export type KnowledgeEngineStatus = {
+    enabled: boolean;
+    ready: boolean;
+    entryCount: number;
+    lastError: string | null;
+    validationIssues: KnowledgeValidationIssue[];
+};

package/dist/lib/types/knowledge.js

@@ -0,0 +1,30 @@
+/**
+ * Knowledge grounding — lexical-first host-supplied knowledge retrieval.
+ *
+ * A host application owns a structured *knowledge registry*: versioned entries
+ * describing concepts, configuration, taxonomies, procedures, and operating
+ * rules. NeuroLink owns the
+ * generic engine that ingests that registry, builds an in-memory lexical
+ * index once per instance, and — independently of tool routing — retrieves a
+ * small, token-bounded set of relevant entries before each main model call.
+ * The selected entries are attached as *ephemeral context*: visible to the
+ * current generation call, never persisted into conversation memory.
+ *
+ * This is retrieval-augmented generation WITHOUT vector retrieval. The first
+ * release ranks with exact identifiers, reviewed aliases, metadata filters,
+ * and weighted field-aware BM25 only. No embedding model, embedding service,
+ * or vector store is initialized. An LLM reranker and semantic retrieval are
+ * deferred behind an explicit evaluation gate.
+ *
+ * Ownership boundary: NeuroLink defines the contracts below and the engine;
+ * it never contains host product content. The host supplies content and
+ * per-request scope. The engine stays provider-neutral.
+ *
+ * Type names are globally prefixed `Knowledge*` to satisfy the repo's
+ * unique-type-name rule and to avoid collision with the pre-existing
+ * web-search `grounding.ts` vocabulary (`EnhancedGroundingMetadata` et al.),
+ * which is a different concept (Google search grounding, not product
+ * knowledge).
+ */
+export {};
+//# sourceMappingURL=knowledge.js.map

package/dist/lib/types/stream.d.ts

@@ -1,6 +1,7 @@
 import type { AIProviderName } from "../constants/enums.js";
 import type { EvaluationData } from "./evaluation.js";
 import type { RAGConfig } from "./rag.js";
+import type { KnowledgeGroundingMetadata, KnowledgeRequestScope } from "./knowledge.js";
 import type { SkillsCallOptions } from "./skills.js";
 import type { AnalyticsData, ToolExecutionEvent, ToolExecutionSummary } from "../types/index.js";
 import type { MiddlewareFactoryOptions, OnChunkCallback, OnErrorCallback, OnFinishCallback } from "../types/middleware.js";
@@ -169,6 +170,17 @@ export type StreamChunk = {
     audio: TTSChunk;
 };
 export type StreamOptions = {
+    /**
+     * Opt this stream call into the knowledge grounding configured on the
+     * NeuroLink instance. Defaults to `false` when omitted.
+     */
+    useKnowledgeGrounding?: boolean;
+    /**
+     * Enabled integrations used to scope knowledge retrieval for this turn.
+     * Used only when `useKnowledgeGrounding` is true and knowledge grounding is
+     * enabled on the NeuroLink instance.
+     */
+    knowledgeContext?: KnowledgeRequestScope;
     input: {
         /** Prompt text. Optional for media-only modes (avatar, music) that are driven by uploaded files rather than a prompt. */
         text?: string;
@@ -552,6 +564,8 @@ export type StreamOptions = {
  * Future-ready for multi-modal outputs while maintaining text focus
  */
 export type StreamResult = {
+    /** Knowledge-grounding diagnostics for this turn (present only when grounding ran). */
+    knowledge?: KnowledgeGroundingMetadata;
     stream: AsyncIterable<{
         content: string;
         reasoning?: string;

package/dist/neurolink.d.ts

@@ -6,7 +6,7 @@
  * Uses real MCP infrastructure for tool discovery and execution.
  */
 import type { AgentDefinition, AgentNetworkConfig, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -107,6 +107,7 @@ export declare class NeuroLink {
     private toolRoutingConfig?;
     private toolRoutingCacheInstance?;
     private toolRoutingVectorCache?;
+    private knowledgeGroundingEngine?;
     private toolDedupConfig?;
     private toolsConfig?;
     /** Session-scoped pins of tools discovered via search_tools (tools.discovery mode). */
@@ -629,6 +630,7 @@ export declare class NeuroLink {
      * @param optionsOrPrompt.maxTokens - Maximum tokens to generate
      * @param optionsOrPrompt.thinkingConfig - Extended thinking configuration (thinkingLevel: 'minimal'|'low'|'medium'|'high')
      * @param optionsOrPrompt.context - Context with conversationId and userId for memory
+     * @param optionsOrPrompt.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      * @returns Promise resolving to generation result with content and metadata
      *
      * @example Basic text generation
@@ -904,6 +906,7 @@ export declare class NeuroLink {
      * @param options.enableEvaluation - Whether to include response quality evaluation
      * @param options.context - Additional context for the request
      * @param options.evaluationDomain - Domain for specialized evaluation
+     * @param options.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      *
      * @returns Promise resolving to StreamResult with an async iterable stream
      *
@@ -989,6 +992,16 @@ export declare class NeuroLink {
      * alone does not activate it.
      */
     setToolRoutingServers(servers: ToolRoutingServerDescriptor[]): void;
+    /** Knowledge-grounding engine health (null when it was not configured). */
+    getKnowledgeStatus(): KnowledgeEngineStatus | null;
+    private appendKnowledgeGroundingBlockToSystemPrompt;
+    /**
+     * Retrieve knowledge grounding for a public generate/stream call without
+     * mutating its options. The outer call boundary decides how to apply the
+     * returned context. Returns undefined when the call does not opt in,
+     * grounding is disabled/not applicable, or retrieval fails open.
+     */
+    private retrieveKnowledgeGrounding;
     private validateStreamRequestOptions;
     private maybeHandleWorkflowStreamRequest;
     private runStandardStreamRequest;

package/dist/neurolink.js

@@ -32,6 +32,7 @@ import { SYSTEM_LIMITS, DEFAULT_TOOL_ROUTING_TIMEOUT_MS, MIN_RECOVERY_TURN_BUDGE
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { buildToolRoutingCatalog, buildRoutingQueryFromHistory, resolveToolRoutingExclusions, } from "./core/toolRouting.js";
 import { ToolRoutingCache } from "./core/toolRoutingCache.js";
+import { DEFAULT_RECENT_TURNS, KnowledgeGroundingEngine, } from "./knowledge/index.js";
 import { AIProviderFactory } from "./core/factory.js";
 import { createToolEventPayload } from "./core/toolEvents.js";
 import { ProviderRegistry } from "./factories/providerRegistry.js";
@@ -405,6 +406,9 @@ export class NeuroLink {
     // vectors are computed once. Cleared when the catalog changes via
     // setToolRoutingServers() so stale vectors are never reused.
     toolRoutingVectorCache;
+    // Knowledge grounding: lexical-first host-supplied retrieval engine. Built
+    // once from constructor config and undefined unless grounding is enabled.
+    knowledgeGroundingEngine;
     // Opt-in tool-signature deduplication config.
     toolDedupConfig;
     toolsConfig;
@@ -837,6 +841,18 @@ export class NeuroLink {
             // multiple NeuroLink instances.
             this.toolRoutingConfig = { ...config.toolRouting };
         }
+        const knowledgeGroundingConfig = config?.knowledgeGrounding;
+        if (knowledgeGroundingConfig?.enabled) {
+            if (Array.isArray(knowledgeGroundingConfig.sources) &&
+                knowledgeGroundingConfig.sources.length > 0) {
+                // The engine builds its immutable index asynchronously; eligible
+                // generate() and stream() calls await readiness before retrieval.
+                this.knowledgeGroundingEngine = new KnowledgeGroundingEngine(knowledgeGroundingConfig);
+            }
+            else {
+                logger.warn("[KnowledgeGrounding] enabled but no sources were provided; grounding disabled for this instance");
+            }
+        }
         if (config?.toolDedup) {
             this.toolDedupConfig = { ...config.toolDedup };
         }
@@ -853,7 +869,9 @@ export class NeuroLink {
         // generate() (marked so it never recursively re-routes). Fails open.
         this.classifierRouter = config?.classifierRouter?.enabled
             ? new ClassifierRouter(config.classifierRouter, {
-                generate: (genOptions) => this.generate(genOptions),
+                generate: (genOptions) => this.generate({
+                    ...genOptions,
+                }),
                 logger: {
                     debug: (message, meta) => logger.debug(message, meta),
                     warn: (message, meta) => logger.warn(message, meta),
@@ -3045,6 +3063,7 @@ Current user's request: ${currentInput}`;
      * @param optionsOrPrompt.maxTokens - Maximum tokens to generate
      * @param optionsOrPrompt.thinkingConfig - Extended thinking configuration (thinkingLevel: 'minimal'|'low'|'medium'|'high')
      * @param optionsOrPrompt.context - Context with conversationId and userId for memory
+     * @param optionsOrPrompt.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      * @returns Promise resolving to generation result with content and metadata
      *
      * @example Basic text generation
@@ -3131,9 +3150,22 @@ Current user's request: ${currentInput}`;
         if (typeof optionsOrPrompt !== "string") {
             optionsOrPrompt = cloneOptionsForCallIsolation(optionsOrPrompt);
         }
+        // Retrieve once at the public call boundary so fallback attempts reuse the
+        // same grounding block and internal preparation cannot inject it twice.
+        const groundingOptions = typeof optionsOrPrompt === "string"
+            ? { input: { text: optionsOrPrompt } }
+            : optionsOrPrompt;
+        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(groundingOptions);
+        if (knowledgeOutcome?.ephemeralContext) {
+            const block = knowledgeOutcome.ephemeralContext.content;
+            optionsOrPrompt = {
+                ...groundingOptions,
+                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(groundingOptions.systemPrompt, block),
+            };
+        }
         const startedAt = Date.now();
         try {
-            return await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => {
+            const result = await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => {
                 // Capture root-ness before startActiveSpan makes generateSpan active.
                 // The actual guest-rescue stamp is deferred to executeGenerateRequest,
                 // AFTER prepareGenerateRequest merges auth/requestContext-derived
@@ -3142,6 +3174,10 @@ Current user's request: ${currentInput}`;
                 const generateIsRoot = !trace.getSpan(context.active());
                 return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan, generateIsRoot));
             });
+            if (knowledgeOutcome) {
+                result.knowledge = knowledgeOutcome.metadata;
+            }
+            return result;
         }
         catch (error) {
             // Lifecycle middleware (wrapGenerate.catch in builtin/lifecycle.ts)
@@ -6204,6 +6240,7 @@ Current user's request: ${currentInput}`;
      * @param options.enableEvaluation - Whether to include response quality evaluation
      * @param options.context - Additional context for the request
      * @param options.evaluationDomain - Domain for specialized evaluation
+     * @param options.useKnowledgeGrounding - Whether to use the instance's configured knowledge for this call
      *
      * @returns Promise resolving to StreamResult with an async iterable stream
      *
@@ -6261,8 +6298,23 @@ Current user's request: ${currentInput}`;
         // top-level keys and left `options.input` shared with the caller.
         options = cloneOptionsForCallIsolation(options);
         const startedAt = Date.now();
+        // Retrieve once before provider/model fallback orchestration. Every fallback
+        // receives the same explicitly enriched options, without the retrieval helper
+        // mutating its input or injecting the same block more than once.
+        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(options);
+        if (knowledgeOutcome?.ephemeralContext) {
+            const block = knowledgeOutcome.ephemeralContext.content;
+            options = {
+                ...options,
+                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(options.systemPrompt, block),
+            };
+        }
         try {
-            return await this.streamWithIterationFallback(options);
+            const result = await this.streamWithIterationFallback(options);
+            if (knowledgeOutcome) {
+                result.knowledge = knowledgeOutcome.metadata;
+            }
+            return result;
         }
         catch (error) {
             // Mirror generate(): fire consumer onError for failures that
@@ -6930,6 +6982,63 @@ Current user's request: ${currentInput}`;
         // to recompute exclusions against the new server/tool set.
         this.toolRoutingCacheInstance = undefined;
     }
+    /** Knowledge-grounding engine health (null when it was not configured). */
+    getKnowledgeStatus() {
+        return this.knowledgeGroundingEngine?.getStatus() ?? null;
+    }
+    appendKnowledgeGroundingBlockToSystemPrompt(systemPrompt, block) {
+        if (typeof systemPrompt === "function") {
+            const originalSystemPrompt = systemPrompt;
+            return async (context) => {
+                const resolved = await resolveDynamicArgument(originalSystemPrompt, context);
+                return resolved.value ? `${resolved.value}\n\n${block}` : block;
+            };
+        }
+        return systemPrompt ? `${systemPrompt}\n\n${block}` : block;
+    }
+    /**
+     * Retrieve knowledge grounding for a public generate/stream call without
+     * mutating its options. The outer call boundary decides how to apply the
+     * returned context. Returns undefined when the call does not opt in,
+     * grounding is disabled/not applicable, or retrieval fails open.
+     */
+    async retrieveKnowledgeGrounding(options) {
+        const engine = this.knowledgeGroundingEngine;
+        if (!engine ||
+            !engine.isEnabled() ||
+            options.useKnowledgeGrounding !== true) {
+            return undefined;
+        }
+        const query = options.input?.text;
+        if (!query) {
+            return undefined;
+        }
+        try {
+            const conversationMessages = options.conversationMessages !== undefined
+                ? options.conversationMessages
+                : await this.fetchRecentRoutingHistory(options);
+            const recentTurns = conversationMessages
+                .filter((message) => message.role === "user" || message.role === "assistant")
+                .slice(-DEFAULT_RECENT_TURNS)
+                .map((message) => ({
+                role: message.role === "assistant"
+                    ? "assistant"
+                    : "user",
+                text: typeof message.content === "string" ? message.content : "",
+            }));
+            return await engine.ground({
+                query,
+                recentTurns,
+                scope: options.knowledgeContext,
+            });
+        }
+        catch (error) {
+            logger.warn("[KnowledgeGrounding] grounding hook failed open", {
+                error: String(error),
+            });
+            return undefined;
+        }
+    }
     async validateStreamRequestOptions(options, startTime) {
         await this.validateStreamInput(options);
         // Input validation for stream

package/dist/types/config.d.ts

@@ -13,6 +13,7 @@ import type { ModelPoolConfig } from "./modelPool.js";
 import type { RequestRouter } from "./requestRouter.js";
 import type { ClassifierRouterConfig } from "./classifierRouter.js";
 import type { SkillsConfig } from "./skills.js";
+import type { KnowledgeGroundingConfig } from "./knowledge.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -130,6 +131,17 @@ export type NeurolinkConstructorConfig = {
      * Opt-in and fails open on read paths. See {@link SkillsConfig}.
      */
     skills?: SkillsConfig;
+    /**
+     * Knowledge grounding: lexical-first host-supplied knowledge retrieval. When
+     * enabled with at least one source, a deterministic in-memory retrieval runs
+     * before each generate()/stream() turn — independently of tool routing — and
+     * attaches a token-bounded, ephemeral knowledge block to the model call. No
+     * embeddings or vector store. Opt-in (`enabled: false` by default) and fails
+     * open: any retrieval failure leaves the turn ungrounded. Sources are fixed
+     * for the lifetime of the instance. See
+     * {@link KnowledgeGroundingConfig}.
+     */
+    knowledgeGrounding?: KnowledgeGroundingConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.