@elizaos/plugin-knowledge 1.0.6 → 1.0.7

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 } from "./chunk-536BD2UA.js";
 
 // src/index.ts
-import { logger as logger6 } from "@elizaos/core";
+import { logger as logger7 } from "@elizaos/core";
 
 // src/types.ts
 import z from "zod";
@@ -18,7 +18,7 @@ var ModelConfigSchema = z.object({
   // NOTE: If EMBEDDING_PROVIDER is not specified, the plugin automatically assumes
   // plugin-openai is being used and will use OPENAI_EMBEDDING_MODEL and
   // OPENAI_EMBEDDING_DIMENSIONS for configuration
-  EMBEDDING_PROVIDER: z.enum(["openai", "google"]),
+  EMBEDDING_PROVIDER: z.enum(["openai", "google"]).optional(),
   TEXT_PROVIDER: z.enum(["openai", "anthropic", "openrouter", "google"]).optional(),
   // API keys
   OPENAI_API_KEY: z.string().optional(),
@@ -66,14 +66,14 @@ function validateModelConfig(runtime) {
       const openaiApiKey2 = getSetting("OPENAI_API_KEY");
       const openaiEmbeddingModel = getSetting("OPENAI_EMBEDDING_MODEL");
       if (openaiApiKey2 && openaiEmbeddingModel) {
-        logger.info("EMBEDDING_PROVIDER not specified, using configuration from plugin-openai");
+        logger.debug("EMBEDDING_PROVIDER not specified, using configuration from plugin-openai");
       } else {
-        logger.warn(
-          "EMBEDDING_PROVIDER not specified, but plugin-openai configuration incomplete. Check OPENAI_API_KEY and OPENAI_EMBEDDING_MODEL."
+        logger.debug(
+          "EMBEDDING_PROVIDER not specified. Assuming embeddings are provided by another plugin (e.g., plugin-google-genai)."
         );
       }
     }
-    const finalEmbeddingProvider = embeddingProvider || "openai";
+    const finalEmbeddingProvider = embeddingProvider;
     const textEmbeddingModel = getSetting("TEXT_EMBEDDING_MODEL") || getSetting("OPENAI_EMBEDDING_MODEL") || "text-embedding-3-small";
     const embeddingDimension = getSetting("EMBEDDING_DIMENSION") || getSetting("OPENAI_EMBEDDING_DIMENSIONS") || "1536";
     const openaiApiKey = getSetting("OPENAI_API_KEY");
@@ -106,23 +106,21 @@ function validateModelConfig(runtime) {
   }
 }
 function validateConfigRequirements(config, assumePluginOpenAI) {
-  if (!assumePluginOpenAI) {
-    if (config.EMBEDDING_PROVIDER === "openai" && !config.OPENAI_API_KEY) {
-      throw new Error('OPENAI_API_KEY is required when EMBEDDING_PROVIDER is set to "openai"');
-    }
-    if (config.EMBEDDING_PROVIDER === "google" && !config.GOOGLE_API_KEY) {
-      throw new Error('GOOGLE_API_KEY is required when EMBEDDING_PROVIDER is set to "google"');
-    }
-  } else {
-    if (!config.OPENAI_API_KEY) {
-      throw new Error("OPENAI_API_KEY is required when using plugin-openai configuration");
-    }
-    if (!config.TEXT_EMBEDDING_MODEL) {
-      throw new Error("OPENAI_EMBEDDING_MODEL is required when using plugin-openai configuration");
-    }
+  const embeddingProvider = config.EMBEDDING_PROVIDER;
+  if (embeddingProvider === "openai" && !config.OPENAI_API_KEY) {
+    throw new Error('OPENAI_API_KEY is required when EMBEDDING_PROVIDER is set to "openai"');
+  }
+  if (embeddingProvider === "google" && !config.GOOGLE_API_KEY) {
+    throw new Error('GOOGLE_API_KEY is required when EMBEDDING_PROVIDER is set to "google"');
+  }
+  if (!embeddingProvider) {
+    logger.debug("No EMBEDDING_PROVIDER specified. Embeddings will be handled by the runtime.");
+  }
+  if (assumePluginOpenAI && config.OPENAI_API_KEY && !config.TEXT_EMBEDDING_MODEL) {
+    throw new Error("OPENAI_EMBEDDING_MODEL is required when using plugin-openai configuration");
   }
   if (config.CTX_KNOWLEDGE_ENABLED) {
-    logger.info("Contextual Knowledge is enabled. Validating text generation settings...");
+    logger.debug("Contextual Knowledge is enabled. Validating text generation settings...");
     if (config.TEXT_PROVIDER === "openai" && !config.OPENAI_API_KEY) {
       throw new Error('OPENAI_API_KEY is required when TEXT_PROVIDER is set to "openai"');
     }
@@ -138,18 +136,18 @@ function validateConfigRequirements(config, assumePluginOpenAI) {
     if (config.TEXT_PROVIDER === "openrouter") {
       const modelName = config.TEXT_MODEL?.toLowerCase() || "";
       if (modelName.includes("claude") || modelName.includes("gemini")) {
-        logger.info(
+        logger.debug(
           `Using ${modelName} with OpenRouter. This configuration supports document caching for improved performance.`
         );
       }
     }
   } else {
     if (assumePluginOpenAI) {
-      logger.info(
-        "Contextual Knowledge is disabled. Using embedding configuration from plugin-openai."
+      logger.debug(
+        "Contextual Knowledge is disabled. Embeddings will be handled by the runtime (e.g., plugin-openai, plugin-google-genai)."
       );
     } else {
-      logger.info("Contextual Knowledge is disabled. Using basic embedding-only configuration.");
+      logger.debug("Contextual Knowledge is disabled. Using configured embedding provider.");
     }
   }
 }
@@ -192,7 +190,7 @@ async function getProviderRateLimits(runtime) {
 // src/service.ts
 import {
   createUniqueUuid,
-  logger as logger3,
+  logger as logger4,
   MemoryType as MemoryType2,
   ModelType as ModelType2,
   Semaphore,
@@ -204,7 +202,7 @@ import {
 import {
   MemoryType,
   ModelType,
-  logger as logger2,
+  logger as logger3,
   splitChunks
 } from "@elizaos/core";
 
@@ -687,12 +685,342 @@ ${chunkContent}`;
   return generatedContext.trim();
 }
 
+// src/llm.ts
+import { generateText as aiGenerateText, embed } from "ai";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import { google } from "@ai-sdk/google";
+import { logger as logger2 } from "@elizaos/core";
+async function generateText(prompt, system, overrideConfig) {
+  const config = validateModelConfig();
+  const provider = overrideConfig?.provider || config.TEXT_PROVIDER;
+  const modelName = overrideConfig?.modelName || config.TEXT_MODEL;
+  const maxTokens = overrideConfig?.maxTokens || config.MAX_OUTPUT_TOKENS;
+  const autoCacheContextualRetrieval = overrideConfig?.autoCacheContextualRetrieval !== false;
+  try {
+    switch (provider) {
+      case "anthropic":
+        return await generateAnthropicText(prompt, system, modelName, maxTokens);
+      case "openai":
+        return await generateOpenAIText(prompt, system, modelName, maxTokens);
+      case "openrouter":
+        return await generateOpenRouterText(
+          prompt,
+          system,
+          modelName,
+          maxTokens,
+          overrideConfig?.cacheDocument,
+          overrideConfig?.cacheOptions,
+          autoCacheContextualRetrieval
+        );
+      case "google":
+        return await generateGoogleText(prompt, system, modelName, maxTokens, config);
+      default:
+        throw new Error(`Unsupported text provider: ${provider}`);
+    }
+  } catch (error) {
+    logger2.error(`[LLM Service - ${provider}] Error generating text with ${modelName}:`, error);
+    throw error;
+  }
+}
+async function generateAnthropicText(prompt, system, modelName, maxTokens) {
+  const config = validateModelConfig();
+  const anthropic = createAnthropic({
+    apiKey: config.ANTHROPIC_API_KEY,
+    baseURL: config.ANTHROPIC_BASE_URL
+  });
+  const modelInstance = anthropic(modelName);
+  const result = await aiGenerateText({
+    model: modelInstance,
+    prompt,
+    system,
+    temperature: 0.3,
+    maxTokens
+  });
+  logger2.debug(
+    `[LLM Service - Anthropic] Text generated with ${modelName}. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+  );
+  return result;
+}
+async function generateOpenAIText(prompt, system, modelName, maxTokens) {
+  const config = validateModelConfig();
+  const openai = createOpenAI({
+    apiKey: config.OPENAI_API_KEY,
+    baseURL: config.OPENAI_BASE_URL
+  });
+  const modelInstance = openai.chat(modelName);
+  const result = await aiGenerateText({
+    model: modelInstance,
+    prompt,
+    system,
+    temperature: 0.3,
+    maxTokens
+  });
+  logger2.debug(
+    `[LLM Service - OpenAI] Text generated with ${modelName}. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+  );
+  return result;
+}
+async function generateGoogleText(prompt, system, modelName, maxTokens, config) {
+  const googleProvider = google;
+  if (config.GOOGLE_API_KEY) {
+    process.env.GOOGLE_GENERATIVE_AI_API_KEY = config.GOOGLE_API_KEY;
+  }
+  const modelInstance = googleProvider(modelName);
+  const result = await aiGenerateText({
+    model: modelInstance,
+    prompt,
+    system,
+    temperature: 0.3,
+    maxTokens
+  });
+  logger2.debug(
+    `[LLM Service - Google] Text generated with ${modelName}. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+  );
+  return result;
+}
+async function generateOpenRouterText(prompt, system, modelName, maxTokens, cacheDocument, cacheOptions, autoCacheContextualRetrieval = true) {
+  const config = validateModelConfig();
+  const openrouter = createOpenRouter({
+    apiKey: config.OPENROUTER_API_KEY,
+    baseURL: config.OPENROUTER_BASE_URL
+  });
+  const modelInstance = openrouter.chat(modelName);
+  const isClaudeModel = modelName.toLowerCase().includes("claude");
+  const isGeminiModel = modelName.toLowerCase().includes("gemini");
+  const isGemini25Model = modelName.toLowerCase().includes("gemini-2.5");
+  const supportsCaching = isClaudeModel || isGeminiModel;
+  let documentForCaching = cacheDocument;
+  if (!documentForCaching && autoCacheContextualRetrieval && supportsCaching) {
+    const docMatch = prompt.match(/<document>([\s\S]*?)<\/document>/);
+    if (docMatch && docMatch[1]) {
+      documentForCaching = docMatch[1].trim();
+      logger2.debug(
+        `[LLM Service - OpenRouter] Auto-detected document for caching (${documentForCaching.length} chars)`
+      );
+    }
+  }
+  if (documentForCaching && supportsCaching) {
+    const effectiveCacheOptions = cacheOptions || { type: "ephemeral" };
+    let promptText = prompt;
+    if (promptText.includes("<document>")) {
+      promptText = promptText.replace(/<document>[\s\S]*?<\/document>/, "").trim();
+    }
+    if (isClaudeModel) {
+      return await generateClaudeWithCaching(
+        promptText,
+        system,
+        modelInstance,
+        modelName,
+        maxTokens,
+        documentForCaching
+      );
+    } else if (isGeminiModel) {
+      return await generateGeminiWithCaching(
+        promptText,
+        system,
+        modelInstance,
+        modelName,
+        maxTokens,
+        documentForCaching,
+        isGemini25Model
+      );
+    }
+  }
+  logger2.debug("[LLM Service - OpenRouter] Using standard request without caching");
+  return await generateStandardOpenRouterText(prompt, system, modelInstance, modelName, maxTokens);
+}
+async function generateClaudeWithCaching(promptText, system, modelInstance, modelName, maxTokens, documentForCaching) {
+  logger2.debug(
+    `[LLM Service - OpenRouter] Using explicit prompt caching with Claude model ${modelName}`
+  );
+  const messages = [
+    // System message with cached document (if system is provided)
+    system ? {
+      role: "system",
+      content: [
+        {
+          type: "text",
+          text: system
+        },
+        {
+          type: "text",
+          text: documentForCaching,
+          cache_control: {
+            type: "ephemeral"
+          }
+        }
+      ]
+    } : (
+      // User message with cached document (if no system message)
+      {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: "Document for context:"
+          },
+          {
+            type: "text",
+            text: documentForCaching,
+            cache_control: {
+              type: "ephemeral"
+            }
+          },
+          {
+            type: "text",
+            text: promptText
+          }
+        ]
+      }
+    ),
+    // Only add user message if system was provided (otherwise we included user above)
+    system ? {
+      role: "user",
+      content: [
+        {
+          type: "text",
+          text: promptText
+        }
+      ]
+    } : null
+  ].filter(Boolean);
+  logger2.debug("[LLM Service - OpenRouter] Using Claude-specific caching structure");
+  const result = await aiGenerateText({
+    model: modelInstance,
+    messages,
+    temperature: 0.3,
+    maxTokens,
+    providerOptions: {
+      openrouter: {
+        usage: {
+          include: true
+        }
+      }
+    }
+  });
+  logCacheMetrics(result);
+  logger2.debug(
+    `[LLM Service - OpenRouter] Text generated with ${modelName} using Claude caching. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+  );
+  return result;
+}
+async function generateGeminiWithCaching(promptText, system, modelInstance, modelName, maxTokens, documentForCaching, isGemini25Model) {
+  const usingImplicitCaching = isGemini25Model;
+  const estimatedDocTokens = Math.ceil(documentForCaching.length / 4);
+  const minTokensForImplicitCache = modelName.toLowerCase().includes("flash") ? 1028 : 2048;
+  const likelyTriggersCaching = estimatedDocTokens >= minTokensForImplicitCache;
+  if (usingImplicitCaching) {
+    logger2.debug(
+      `[LLM Service - OpenRouter] Using Gemini 2.5 implicit caching with model ${modelName}`
+    );
+    logger2.debug(
+      `[LLM Service - OpenRouter] Gemini 2.5 models automatically cache large prompts (no cache_control needed)`
+    );
+    if (likelyTriggersCaching) {
+      logger2.debug(
+        `[LLM Service - OpenRouter] Document size ~${estimatedDocTokens} tokens exceeds minimum ${minTokensForImplicitCache} tokens for implicit caching`
+      );
+    } else {
+      logger2.debug(
+        `[LLM Service - OpenRouter] Warning: Document size ~${estimatedDocTokens} tokens may not meet minimum ${minTokensForImplicitCache} token threshold for implicit caching`
+      );
+    }
+  } else {
+    logger2.debug(
+      `[LLM Service - OpenRouter] Using standard prompt format with Gemini model ${modelName}`
+    );
+    logger2.debug(
+      `[LLM Service - OpenRouter] Note: Only Gemini 2.5 models support automatic implicit caching`
+    );
+  }
+  const geminiSystemPrefix = system ? `${system}
+
+` : "";
+  const geminiPrompt = `${geminiSystemPrefix}${documentForCaching}
+
+${promptText}`;
+  const result = await aiGenerateText({
+    model: modelInstance,
+    prompt: geminiPrompt,
+    temperature: 0.3,
+    maxTokens,
+    providerOptions: {
+      openrouter: {
+        usage: {
+          include: true
+          // Include usage info to see cache metrics
+        }
+      }
+    }
+  });
+  logCacheMetrics(result);
+  logger2.debug(
+    `[LLM Service - OpenRouter] Text generated with ${modelName} using ${usingImplicitCaching ? "implicit" : "standard"} caching. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+  );
+  return result;
+}
+async function generateStandardOpenRouterText(prompt, system, modelInstance, modelName, maxTokens) {
+  const result = await aiGenerateText({
+    model: modelInstance,
+    prompt,
+    system,
+    temperature: 0.3,
+    maxTokens,
+    providerOptions: {
+      openrouter: {
+        usage: {
+          include: true
+          // Include usage info to see cache metrics
+        }
+      }
+    }
+  });
+  logger2.debug(
+    `[LLM Service - OpenRouter] Text generated with ${modelName}. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+  );
+  return result;
+}
+function logCacheMetrics(result) {
+  if (result.usage && result.usage.cacheTokens) {
+    logger2.debug(
+      `[LLM Service - OpenRouter] Cache metrics - Cached tokens: ${result.usage.cacheTokens}, Cache discount: ${result.usage.cacheDiscount}`
+    );
+  }
+}
+
 // src/document-processor.ts
 var ctxKnowledgeEnabled = process.env.CTX_KNOWLEDGE_ENABLED === "true" || process.env.CTX_KNOWLEDGE_ENABLED === "True";
+function shouldUseCustomLLM() {
+  const textProvider = process.env.TEXT_PROVIDER;
+  const textModel = process.env.TEXT_MODEL;
+  if (!textProvider || !textModel) {
+    return false;
+  }
+  switch (textProvider.toLowerCase()) {
+    case "openrouter":
+      return !!process.env.OPENROUTER_API_KEY;
+    case "openai":
+      return !!process.env.OPENAI_API_KEY;
+    case "anthropic":
+      return !!process.env.ANTHROPIC_API_KEY;
+    case "google":
+      return !!process.env.GOOGLE_API_KEY;
+    default:
+      return false;
+  }
+}
+var useCustomLLM = shouldUseCustomLLM();
 if (ctxKnowledgeEnabled) {
-  logger2.info(`Document processor starting with Contextual Knowledge ENABLED`);
+  logger3.info(`Document processor starting with Contextual Knowledge ENABLED`);
+  if (useCustomLLM) {
+    logger3.info(`Using Custom LLM with provider: ${process.env.TEXT_PROVIDER}, model: ${process.env.TEXT_MODEL}`);
+  } else {
+    logger3.info(`Using ElizaOS Runtime LLM (default behavior)`);
+  }
 } else {
-  logger2.info(`Document processor starting with Contextual Knowledge DISABLED`);
+  logger3.info(`Document processor starting with Contextual Knowledge DISABLED`);
 }
 async function processFragmentsSynchronously({
   runtime,
@@ -705,15 +1033,15 @@ async function processFragmentsSynchronously({
   worldId
 }) {
   if (!fullDocumentText || fullDocumentText.trim() === "") {
-    logger2.warn(`No text content available to chunk for document ${documentId}.`);
+    logger3.warn(`No text content available to chunk for document ${documentId}.`);
     return 0;
   }
   const chunks = await splitDocumentIntoChunks(fullDocumentText);
   if (chunks.length === 0) {
-    logger2.warn(`No chunks generated from text for ${documentId}. No fragments to save.`);
+    logger3.warn(`No chunks generated from text for ${documentId}. No fragments to save.`);
     return 0;
   }
-  logger2.info(`Split content into ${chunks.length} chunks for document ${documentId}`);
+  logger3.info(`Split content into ${chunks.length} chunks for document ${documentId}`);
   const providerLimits = await getProviderRateLimits();
   const CONCURRENCY_LIMIT = Math.min(30, providerLimits.maxConcurrentRequests || 30);
   const rateLimiter = createRateLimiter(providerLimits.requestsPerMinute || 60);
@@ -731,11 +1059,11 @@ async function processFragmentsSynchronously({
     rateLimiter
   });
   if (failedCount > 0) {
-    logger2.warn(
+    logger3.warn(
       `Failed to process ${failedCount} chunks out of ${chunks.length} for document ${documentId}`
     );
   }
-  logger2.info(`Finished saving ${savedCount} fragments for document ${documentId}.`);
+  logger3.info(`Finished saving ${savedCount} fragments for document ${documentId}.`);
   return savedCount;
 }
 async function extractTextFromDocument(fileBuffer, contentType, originalFilename) {
@@ -744,15 +1072,15 @@ async function extractTextFromDocument(fileBuffer, contentType, originalFilename
   }
   try {
     if (contentType === "application/pdf") {
-      logger2.debug(`Extracting text from PDF: ${originalFilename}`);
+      logger3.debug(`Extracting text from PDF: ${originalFilename}`);
       return await convertPdfToTextFromBuffer(fileBuffer, originalFilename);
     } else {
-      logger2.debug(`Extracting text from non-PDF: ${originalFilename} (Type: ${contentType})`);
+      logger3.debug(`Extracting text from non-PDF: ${originalFilename} (Type: ${contentType})`);
       if (contentType.includes("text/") || contentType.includes("application/json") || contentType.includes("application/xml")) {
         try {
           return fileBuffer.toString("utf8");
         } catch (textError) {
-          logger2.warn(
+          logger3.warn(
             `Failed to decode ${originalFilename} as UTF-8, falling back to binary extraction`
           );
         }
@@ -760,7 +1088,7 @@ async function extractTextFromDocument(fileBuffer, contentType, originalFilename
       return await extractTextFromFileBuffer(fileBuffer, contentType, originalFilename);
     }
   } catch (error) {
-    logger2.error(`Error extracting text from ${originalFilename}: ${error.message}`);
+    logger3.error(`Error extracting text from ${originalFilename}: ${error.message}`);
     throw new Error(`Failed to extract text from ${originalFilename}: ${error.message}`);
   }
 }
@@ -805,7 +1133,7 @@ async function splitDocumentIntoChunks(documentText) {
   const tokenChunkOverlap = DEFAULT_CHUNK_OVERLAP_TOKENS;
   const targetCharChunkSize = Math.round(tokenChunkSize * DEFAULT_CHARS_PER_TOKEN);
   const targetCharChunkOverlap = Math.round(tokenChunkOverlap * DEFAULT_CHARS_PER_TOKEN);
-  logger2.debug(
+  logger3.debug(
     `Using core splitChunks with settings: tokenChunkSize=${tokenChunkSize}, tokenChunkOverlap=${tokenChunkOverlap}, charChunkSize=${targetCharChunkSize}, charChunkOverlap=${targetCharChunkOverlap}`
   );
   return await splitChunks(documentText, tokenChunkSize, tokenChunkOverlap);
@@ -829,7 +1157,7 @@ async function processAndSaveFragments({
   for (let i = 0; i < chunks.length; i += concurrencyLimit) {
     const batchChunks = chunks.slice(i, i + concurrencyLimit);
     const batchOriginalIndices = Array.from({ length: batchChunks.length }, (_, k) => i + k);
-    logger2.debug(
+    logger3.debug(
       `Processing batch of ${batchChunks.length} chunks for document ${documentId}. Starting original index: ${batchOriginalIndices[0]}, batch ${Math.floor(i / concurrencyLimit) + 1}/${Math.ceil(chunks.length / concurrencyLimit)}`
     );
     const contextualizedChunks = await getContextualizedChunks(
@@ -849,13 +1177,13 @@ async function processAndSaveFragments({
       if (!result.success) {
         failedCount++;
         failedChunks.push(originalChunkIndex);
-        logger2.warn(`Failed to process chunk ${originalChunkIndex} for document ${documentId}`);
+        logger3.warn(`Failed to process chunk ${originalChunkIndex} for document ${documentId}`);
         continue;
       }
       const contextualizedChunkText = result.text;
       const embedding = result.embedding;
       if (!embedding || embedding.length === 0) {
-        logger2.warn(
+        logger3.warn(
           `Zero vector detected for chunk ${originalChunkIndex} (document ${documentId}). Embedding: ${JSON.stringify(result.embedding)}`
         );
         failedCount++;
@@ -880,12 +1208,12 @@ async function processAndSaveFragments({
           }
         };
         await runtime.createMemory(fragmentMemory, "knowledge");
-        logger2.debug(
+        logger3.debug(
           `Saved fragment ${originalChunkIndex + 1} for document ${documentId} (Fragment ID: ${fragmentMemory.id})`
         );
         savedCount++;
       } catch (saveError) {
-        logger2.error(
+        logger3.error(
           `Error saving chunk ${originalChunkIndex} to database: ${saveError.message}`,
           saveError.stack
         );
@@ -900,8 +1228,26 @@ async function processAndSaveFragments({
   return { savedCount, failedCount, failedChunks };
 }
 async function generateEmbeddingsForChunks(runtime, contextualizedChunks, rateLimiter) {
+  const validChunks = contextualizedChunks.filter((chunk) => chunk.success);
+  const failedChunks = contextualizedChunks.filter((chunk) => !chunk.success);
+  if (validChunks.length === 0) {
+    return failedChunks.map((chunk) => ({
+      success: false,
+      index: chunk.index,
+      error: new Error("Chunk processing failed"),
+      text: chunk.contextualizedText
+    }));
+  }
   return await Promise.all(
     contextualizedChunks.map(async (contextualizedChunk) => {
+      if (!contextualizedChunk.success) {
+        return {
+          success: false,
+          index: contextualizedChunk.index,
+          error: new Error("Chunk processing failed"),
+          text: contextualizedChunk.contextualizedText
+        };
+      }
       await rateLimiter();
       try {
         const generateEmbeddingOperation = async () => {
@@ -929,7 +1275,7 @@ async function generateEmbeddingsForChunks(runtime, contextualizedChunks, rateLi
           text: contextualizedChunk.contextualizedText
         };
       } catch (error) {
-        logger2.error(
+        logger3.error(
           `Error generating embedding for chunk ${contextualizedChunk.index}: ${error.message}`
         );
         return {
@@ -944,7 +1290,7 @@ async function generateEmbeddingsForChunks(runtime, contextualizedChunks, rateLi
 }
 async function getContextualizedChunks(runtime, fullDocumentText, chunks, contentType, batchOriginalIndices) {
   if (ctxKnowledgeEnabled && fullDocumentText) {
-    logger2.debug(`Generating contexts for ${chunks.length} chunks`);
+    logger3.debug(`Generating contexts for ${chunks.length} chunks`);
     return await generateContextsInBatch(
       runtime,
       fullDocumentText,
@@ -989,17 +1335,31 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
       try {
         let llmResponse;
         const generateTextOperation = async () => {
-          if (item.usesCaching) {
-            return await runtime.useModel(ModelType.TEXT_LARGE, {
-              prompt: item.promptText,
-              system: item.systemPrompt
-              // cacheDocument: item.fullDocumentTextForContext, // Not directly supported by useModel
-              // cacheOptions: { type: 'ephemeral' }, // Not directly supported by useModel
-            });
+          if (useCustomLLM) {
+            if (item.usesCaching) {
+              return await generateText(
+                item.promptText,
+                item.systemPrompt,
+                {
+                  cacheDocument: item.fullDocumentTextForContext,
+                  cacheOptions: { type: "ephemeral" },
+                  autoCacheContextualRetrieval: true
+                }
+              );
+            } else {
+              return await generateText(item.prompt);
+            }
           } else {
-            return await runtime.useModel(ModelType.TEXT_LARGE, {
-              prompt: item.prompt
-            });
+            if (item.usesCaching) {
+              return await runtime.useModel(ModelType.TEXT_LARGE, {
+                prompt: item.promptText,
+                system: item.systemPrompt
+              });
+            } else {
+              return await runtime.useModel(ModelType.TEXT_LARGE, {
+                prompt: item.prompt
+              });
+            }
           }
         };
         llmResponse = await withRateLimitRetry(
@@ -1008,7 +1368,7 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
         );
         const generatedContext = llmResponse.text;
         const contextualizedText = getChunkWithContext(item.chunkText, generatedContext);
-        logger2.debug(
+        logger3.debug(
           `Context added for chunk ${item.originalIndex}. New length: ${contextualizedText.length}`
         );
         return {
@@ -1017,7 +1377,7 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
           index: item.originalIndex
         };
       } catch (error) {
-        logger2.error(
+        logger3.error(
           `Error generating context for chunk ${item.originalIndex}: ${error.message}`,
           error.stack
         );
@@ -1038,7 +1398,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
       if (isUsingCacheCapableModel) {
         const cachingPromptInfo = contentType ? getCachingPromptForMimeType(contentType, chunkText) : getCachingContextualizationPrompt(chunkText);
         if (cachingPromptInfo.prompt.startsWith("Error:")) {
-          logger2.warn(
+          logger3.warn(
             `Skipping contextualization for chunk ${originalIndex} due to: ${cachingPromptInfo.prompt}`
           );
           return {
@@ -1060,7 +1420,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
       } else {
         const prompt = contentType ? getPromptForMimeType(contentType, fullDocumentText, chunkText) : getContextualizationPrompt(fullDocumentText, chunkText);
         if (prompt.startsWith("Error:")) {
-          logger2.warn(`Skipping contextualization for chunk ${originalIndex} due to: ${prompt}`);
+          logger3.warn(`Skipping contextualization for chunk ${originalIndex} due to: ${prompt}`);
           return {
             prompt: null,
             originalIndex,
@@ -1078,7 +1438,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
         };
       }
     } catch (error) {
-      logger2.error(
+      logger3.error(
         `Error preparing prompt for chunk ${originalIndex}: ${error.message}`,
         error.stack
       );
@@ -1099,7 +1459,7 @@ async function generateEmbeddingWithValidation(runtime, text) {
     });
     const embedding = Array.isArray(embeddingResult) ? embeddingResult : embeddingResult?.embedding;
     if (!embedding || embedding.length === 0) {
-      logger2.warn(`Zero vector detected. Embedding result: ${JSON.stringify(embeddingResult)}`);
+      logger3.warn(`Zero vector detected. Embedding result: ${JSON.stringify(embedding)}`);
       return {
         embedding: null,
         success: false,
@@ -1117,12 +1477,12 @@ async function withRateLimitRetry(operation, errorContext, retryDelay) {
   } catch (error) {
     if (error.status === 429) {
       const delay = retryDelay || error.headers?.["retry-after"] || 5;
-      logger2.warn(`Rate limit hit for ${errorContext}. Retrying after ${delay}s`);
+      logger3.warn(`Rate limit hit for ${errorContext}. Retrying after ${delay}s`);
       await new Promise((resolve) => setTimeout(resolve, delay * 1e3));
       try {
         return await operation();
       } catch (retryError) {
-        logger2.error(`Failed after retry for ${errorContext}: ${retryError.message}`);
+        logger3.error(`Failed after retry for ${errorContext}: ${retryError.message}`);
         throw retryError;
       }
     }
@@ -1141,7 +1501,7 @@ function createRateLimiter(requestsPerMinute) {
       const oldestRequest = requestTimes[0];
       const timeToWait = Math.max(0, oldestRequest + intervalMs - now);
       if (timeToWait > 0) {
-        logger2.debug(`Rate limiting applied, waiting ${timeToWait}ms before next request`);
+        logger3.debug(`Rate limiting applied, waiting ${timeToWait}ms before next request`);
         await new Promise((resolve) => setTimeout(resolve, timeToWait));
       }
     }
@@ -1168,9 +1528,10 @@ var KnowledgeService = class _KnowledgeService extends Service {
       if (typeof value === "string") return value.toLowerCase() === "true";
       return false;
     };
+    const loadDocsOnStartup = parseBooleanEnv(config?.LOAD_DOCS_ON_STARTUP) || process.env.LOAD_DOCS_ON_STARTUP === "true";
     this.knowledgeConfig = {
       CTX_KNOWLEDGE_ENABLED: parseBooleanEnv(config?.CTX_KNOWLEDGE_ENABLED),
-      LOAD_DOCS_ON_STARTUP: parseBooleanEnv(config?.LOAD_DOCS_ON_STARTUP),
+      LOAD_DOCS_ON_STARTUP: loadDocsOnStartup,
       MAX_INPUT_TOKENS: config?.MAX_INPUT_TOKENS,
       MAX_OUTPUT_TOKENS: config?.MAX_OUTPUT_TOKENS,
       EMBEDDING_PROVIDER: config?.EMBEDDING_PROVIDER,
@@ -1178,34 +1539,37 @@ var KnowledgeService = class _KnowledgeService extends Service {
       TEXT_EMBEDDING_MODEL: config?.TEXT_EMBEDDING_MODEL
     };
     this.config = { ...this.knowledgeConfig };
-    logger3.info(
+    logger4.info(
       `KnowledgeService initialized for agent ${this.runtime.agentId} with config:`,
       this.knowledgeConfig
     );
     if (this.knowledgeConfig.LOAD_DOCS_ON_STARTUP) {
+      logger4.info("LOAD_DOCS_ON_STARTUP is enabled. Loading documents from docs folder...");
       this.loadInitialDocuments().catch((error) => {
-        logger3.error("Error during initial document loading in KnowledgeService:", error);
+        logger4.error("Error during initial document loading in KnowledgeService:", error);
       });
+    } else {
+      logger4.info("LOAD_DOCS_ON_STARTUP is disabled. Skipping automatic document loading.");
     }
   }
   async loadInitialDocuments() {
-    logger3.info(
+    logger4.info(
       `KnowledgeService: Checking for documents to load on startup for agent ${this.runtime.agentId}`
     );
     try {
       await new Promise((resolve) => setTimeout(resolve, 1e3));
       const result = await loadDocsFromPath(this, this.runtime.agentId);
       if (result.successful > 0) {
-        logger3.info(
+        logger4.info(
           `KnowledgeService: Loaded ${result.successful} documents from docs folder on startup for agent ${this.runtime.agentId}`
         );
       } else {
-        logger3.info(
+        logger4.info(
           `KnowledgeService: No new documents found to load on startup for agent ${this.runtime.agentId}`
         );
       }
     } catch (error) {
-      logger3.error(
+      logger4.error(
         `KnowledgeService: Error loading documents on startup for agent ${this.runtime.agentId}:`,
         error
       );
@@ -1217,23 +1581,23 @@ var KnowledgeService = class _KnowledgeService extends Service {
    * @returns Initialized Knowledge service
    */
   static async start(runtime) {
-    logger3.info(`Starting Knowledge service for agent: ${runtime.agentId}`);
+    logger4.info(`Starting Knowledge service for agent: ${runtime.agentId}`);
     const service = new _KnowledgeService(runtime);
     if (service.runtime.character?.knowledge && service.runtime.character.knowledge.length > 0) {
-      logger3.info(
+      logger4.info(
         `KnowledgeService: Processing ${service.runtime.character.knowledge.length} character knowledge items.`
       );
       const stringKnowledge = service.runtime.character.knowledge.filter(
         (item) => typeof item === "string"
       );
       await service.processCharacterKnowledge(stringKnowledge).catch((err) => {
-        logger3.error(
+        logger4.error(
           `KnowledgeService: Error processing character knowledge during startup: ${err.message}`,
           err
         );
       });
     } else {
-      logger3.info(
+      logger4.info(
         `KnowledgeService: No character knowledge to process for agent ${runtime.agentId}.`
       );
     }
@@ -1244,10 +1608,10 @@ var KnowledgeService = class _KnowledgeService extends Service {
    * @param runtime Agent runtime
    */
   static async stop(runtime) {
-    logger3.info(`Stopping Knowledge service for agent: ${runtime.agentId}`);
+    logger4.info(`Stopping Knowledge service for agent: ${runtime.agentId}`);
     const service = runtime.getService(_KnowledgeService.serviceType);
     if (!service) {
-      logger3.warn(`KnowledgeService not found for agent ${runtime.agentId} during stop.`);
+      logger4.warn(`KnowledgeService not found for agent ${runtime.agentId} during stop.`);
     }
     if (service instanceof _KnowledgeService) {
       await service.stop();
@@ -1257,7 +1621,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
    * Stop the service
    */
   async stop() {
-    logger3.info(`Knowledge service stopping for agent: ${this.runtime.agentId}`);
+    logger4.info(`Knowledge service stopping for agent: ${this.runtime.agentId}`);
   }
   /**
    * Add knowledge to the system
@@ -1266,13 +1630,13 @@ var KnowledgeService = class _KnowledgeService extends Service {
    */
   async addKnowledge(options) {
     const agentId = options.agentId || this.runtime.agentId;
-    logger3.info(
+    logger4.info(
       `KnowledgeService processing document for agent: ${agentId}, file: ${options.originalFilename}, type: ${options.contentType}`
     );
     try {
       const existingDocument = await this.runtime.getMemoryById(options.clientDocumentId);
       if (existingDocument && existingDocument.metadata?.type === MemoryType2.DOCUMENT) {
-        logger3.info(
+        logger4.info(
           `Document ${options.originalFilename} with ID ${options.clientDocumentId} already exists. Skipping processing.`
         );
         const fragments = await this.runtime.getMemories({
@@ -1291,7 +1655,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         };
       }
     } catch (error) {
-      logger3.debug(
+      logger4.debug(
         `Document ${options.clientDocumentId} not found or error checking existence, proceeding with processing: ${error instanceof Error ? error.message : String(error)}`
       );
     }
@@ -1315,7 +1679,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
   }) {
     const agentId = passedAgentId || this.runtime.agentId;
     try {
-      logger3.debug(
+      logger4.debug(
         `KnowledgeService: Processing document ${originalFilename} (type: ${contentType}) via processDocument for agent: ${agentId}`
       );
       let fileBuffer = null;
@@ -1326,7 +1690,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         try {
           fileBuffer = Buffer.from(content, "base64");
         } catch (e) {
-          logger3.error(
+          logger4.error(
             `KnowledgeService: Failed to convert base64 to buffer for ${originalFilename}: ${e.message}`
           );
           throw new Error(`Invalid base64 content for PDF file ${originalFilename}`);
@@ -1337,7 +1701,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         try {
           fileBuffer = Buffer.from(content, "base64");
         } catch (e) {
-          logger3.error(
+          logger4.error(
             `KnowledgeService: Failed to convert base64 to buffer for ${originalFilename}: ${e.message}`
           );
           throw new Error(`Invalid base64 content for binary file ${originalFilename}`);
@@ -1354,11 +1718,11 @@ var KnowledgeService = class _KnowledgeService extends Service {
             if (invalidCharCount > 0 && invalidCharCount / textLength > 0.1) {
               throw new Error("Decoded content contains too many invalid characters");
             }
-            logger3.debug(`Successfully decoded base64 content for text file: ${originalFilename}`);
+            logger4.debug(`Successfully decoded base64 content for text file: ${originalFilename}`);
             extractedText = decodedText;
             documentContentToStore = decodedText;
           } catch (e) {
-            logger3.error(
+            logger4.error(
               `Failed to decode base64 for ${originalFilename}: ${e instanceof Error ? e.message : String(e)}`
             );
             throw new Error(
@@ -1366,7 +1730,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
             );
           }
         } else {
-          logger3.debug(`Treating content as plain text for file: ${originalFilename}`);
+          logger4.debug(`Treating content as plain text for file: ${originalFilename}`);
           extractedText = content;
           documentContentToStore = content;
         }
@@ -1375,7 +1739,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         const noTextError = new Error(
           `KnowledgeService: No text content extracted from ${originalFilename} (type: ${contentType}).`
         );
-        logger3.warn(noTextError.message);
+        logger4.warn(noTextError.message);
         throw noTextError;
       }
       const documentMemory = createDocumentMemory({
@@ -1401,14 +1765,14 @@ var KnowledgeService = class _KnowledgeService extends Service {
         roomId: roomId || agentId,
         entityId: entityId || agentId
       };
-      logger3.debug(
+      logger4.debug(
         `KnowledgeService: Creating memory with agentId=${agentId}, entityId=${entityId}, roomId=${roomId}, this.runtime.agentId=${this.runtime.agentId}`
       );
-      logger3.debug(
+      logger4.debug(
         `KnowledgeService: memoryWithScope agentId=${memoryWithScope.agentId}, entityId=${memoryWithScope.entityId}`
       );
       await this.runtime.createMemory(memoryWithScope, "documents");
-      logger3.debug(
+      logger4.debug(
         `KnowledgeService: Stored document ${originalFilename} (Memory ID: ${memoryWithScope.id})`
       );
       const fragmentCount = await processFragmentsSynchronously({
@@ -1422,7 +1786,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         entityId: entityId || agentId,
         worldId: worldId || agentId
       });
-      logger3.info(
+      logger4.info(
         `KnowledgeService: Document ${originalFilename} processed with ${fragmentCount} fragments for agent ${agentId}`
       );
       return {
@@ -1431,7 +1795,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         fragmentCount
       };
     } catch (error) {
-      logger3.error(
+      logger4.error(
         `KnowledgeService: Error processing document ${originalFilename}: ${error.message}`,
         error.stack
       );
@@ -1440,7 +1804,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
   }
   // --- Knowledge methods moved from AgentRuntime ---
   async handleProcessingError(error, context) {
-    logger3.error(`KnowledgeService: Error ${context}:`, error?.message || error || "Unknown error");
+    logger4.error(`KnowledgeService: Error ${context}:`, error?.message || error || "Unknown error");
     throw error;
   }
   async checkExistingKnowledge(knowledgeId) {
@@ -1448,9 +1812,9 @@ var KnowledgeService = class _KnowledgeService extends Service {
     return !!existingDocument;
   }
   async getKnowledge(message, scope) {
-    logger3.debug("KnowledgeService: getKnowledge called for message id: " + message.id);
+    logger4.debug("KnowledgeService: getKnowledge called for message id: " + message.id);
     if (!message?.content?.text || message?.content?.text.trim().length === 0) {
-      logger3.warn("KnowledgeService: Invalid or empty message content for knowledge query.");
+      logger4.warn("KnowledgeService: Invalid or empty message content for knowledge query.");
       return [];
     }
     const embedding = await this.runtime.useModel(ModelType2.TEXT_EMBEDDING, {
@@ -1481,7 +1845,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
   }
   async processCharacterKnowledge(items) {
     await new Promise((resolve) => setTimeout(resolve, 1e3));
-    logger3.info(
+    logger4.info(
       `KnowledgeService: Processing ${items.length} character knowledge items for agent ${this.runtime.agentId}`
     );
     const processingPromises = items.map(async (item) => {
@@ -1489,12 +1853,12 @@ var KnowledgeService = class _KnowledgeService extends Service {
       try {
         const knowledgeId = createUniqueUuid(this.runtime.agentId + item, item);
         if (await this.checkExistingKnowledge(knowledgeId)) {
-          logger3.debug(
+          logger4.debug(
             `KnowledgeService: Character knowledge item with ID ${knowledgeId} already exists. Skipping.`
           );
           return;
         }
-        logger3.debug(
+        logger4.debug(
           `KnowledgeService: Processing character knowledge for ${this.runtime.character?.name} - ${item.slice(0, 100)}`
         );
         let metadata = {
@@ -1545,7 +1909,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
       }
     });
     await Promise.all(processingPromises);
-    logger3.info(
+    logger4.info(
       `KnowledgeService: Finished processing character knowledge for agent ${this.runtime.agentId}.`
     );
   }
@@ -1565,7 +1929,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
       worldId: scope?.worldId ?? this.runtime.agentId,
       entityId: scope?.entityId ?? this.runtime.agentId
     };
-    logger3.debug(`KnowledgeService: _internalAddKnowledge called for item ID ${item.id}`);
+    logger4.debug(`KnowledgeService: _internalAddKnowledge called for item ID ${item.id}`);
     const documentMemory = {
       id: item.id,
       // This ID should be the unique ID for the document being added.
@@ -1587,7 +1951,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
     };
     const existingDocument = await this.runtime.getMemoryById(item.id);
     if (existingDocument) {
-      logger3.debug(
+      logger4.debug(
         `KnowledgeService: Document ${item.id} already exists in _internalAddKnowledge, updating...`
       );
       await this.runtime.updateMemory({
@@ -1611,13 +1975,13 @@ var KnowledgeService = class _KnowledgeService extends Service {
         await this.processDocumentFragment(fragment);
         fragmentsProcessed++;
       } catch (error) {
-        logger3.error(
+        logger4.error(
           `KnowledgeService: Error processing fragment ${fragment.id} for document ${item.id}:`,
           error
         );
       }
     }
-    logger3.debug(
+    logger4.debug(
       `KnowledgeService: Processed ${fragmentsProcessed}/${fragments.length} fragments for document ${item.id}.`
     );
   }
@@ -1626,7 +1990,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
       await this.runtime.addEmbeddingToMemory(fragment);
       await this.runtime.createMemory(fragment, "knowledge");
     } catch (error) {
-      logger3.error(
+      logger4.error(
         `KnowledgeService: Error processing fragment ${fragment.id}:`,
         error instanceof Error ? error.message : String(error)
       );
@@ -1691,7 +2055,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
    */
   async deleteMemory(memoryId) {
     await this.runtime.deleteMemory(memoryId);
-    logger3.info(
+    logger4.info(
       `KnowledgeService: Deleted memory ${memoryId} for agent ${this.runtime.agentId}. Assumed it was a document or related fragment.`
     );
   }
@@ -2634,7 +2998,7 @@ var KnowledgeTestSuite = class {
 var tests_default = new KnowledgeTestSuite();
 
 // src/actions.ts
-import { logger as logger4, stringToUuid } from "@elizaos/core";
+import { logger as logger5, stringToUuid } from "@elizaos/core";
 import * as fs2 from "fs";
 import * as path2 from "path";
 var processKnowledgeAction = {
@@ -2694,7 +3058,7 @@ var processKnowledgeAction = {
     const hasPath = pathPattern.test(text);
     const service = runtime.getService(KnowledgeService.serviceType);
     if (!service) {
-      logger4.warn(
+      logger5.warn(
         "Knowledge service not available for PROCESS_KNOWLEDGE action"
       );
       return false;
@@ -2779,7 +3143,7 @@ var processKnowledgeAction = {
         await callback(response);
       }
     } catch (error) {
-      logger4.error("Error in PROCESS_KNOWLEDGE action:", error);
+      logger5.error("Error in PROCESS_KNOWLEDGE action:", error);
       const errorResponse = {
         text: `I encountered an error while processing the knowledge: ${error instanceof Error ? error.message : "Unknown error"}`
       };
@@ -2890,7 +3254,7 @@ ${formattedResults}`
         await callback(response);
       }
     } catch (error) {
-      logger4.error("Error in SEARCH_KNOWLEDGE action:", error);
+      logger5.error("Error in SEARCH_KNOWLEDGE action:", error);
       const errorResponse = {
         text: `I encountered an error while searching the knowledge base: ${error instanceof Error ? error.message : "Unknown error"}`
       };
@@ -2903,7 +3267,7 @@ ${formattedResults}`
 var knowledgeActions = [processKnowledgeAction, searchKnowledgeAction];
 
 // src/routes.ts
-import { createUniqueUuid as createUniqueUuid2, logger as logger5, ModelType as ModelType4 } from "@elizaos/core";
+import { createUniqueUuid as createUniqueUuid2, logger as logger6, ModelType as ModelType4 } from "@elizaos/core";
 import fs3 from "fs";
 import path3 from "path";
 import multer from "multer";
@@ -2954,7 +3318,7 @@ var cleanupFile = (filePath) => {
     try {
       fs3.unlinkSync(filePath);
     } catch (error) {
-      logger5.error(`Error cleaning up file ${filePath}:`, error);
+      logger6.error(`Error cleaning up file ${filePath}:`, error);
     }
   }
 };
@@ -2981,7 +3345,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       }
       const agentId = req.body.agentId || req.query.agentId;
       if (!agentId) {
-        logger5.error("[KNOWLEDGE UPLOAD HANDLER] No agent ID provided in request");
+        logger6.error("[KNOWLEDGE UPLOAD HANDLER] No agent ID provided in request");
         return sendError(
           res,
           400,
@@ -2990,13 +3354,13 @@ async function uploadKnowledgeHandler(req, res, runtime) {
         );
       }
       const worldId = req.body.worldId || agentId;
-      logger5.info(`[KNOWLEDGE UPLOAD HANDLER] Processing upload for agent: ${agentId}`);
+      logger6.info(`[KNOWLEDGE UPLOAD HANDLER] Processing upload for agent: ${agentId}`);
       const processingPromises = files.map(async (file, index) => {
         let knowledgeId;
         const originalFilename = file.originalname;
         const filePath = file.path;
         knowledgeId = req.body?.documentIds && req.body.documentIds[index] || req.body?.documentId || createUniqueUuid2(runtime, `knowledge-${originalFilename}-${Date.now()}`);
-        logger5.debug(
+        logger6.debug(
           `[KNOWLEDGE UPLOAD HANDLER] File: ${originalFilename}, Agent ID: ${agentId}, World ID: ${worldId}, Knowledge ID: ${knowledgeId}`
         );
         try {
@@ -3030,7 +3394,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
             status: "success"
           };
         } catch (fileError) {
-          logger5.error(
+          logger6.error(
             `[KNOWLEDGE UPLOAD HANDLER] Error processing file ${file.originalname}: ${fileError}`
           );
           cleanupFile(filePath);
@@ -3051,7 +3415,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       }
       const agentId = req.body.agentId || req.query.agentId;
       if (!agentId) {
-        logger5.error("[KNOWLEDGE URL HANDLER] No agent ID provided in request");
+        logger6.error("[KNOWLEDGE URL HANDLER] No agent ID provided in request");
         return sendError(
           res,
           400,
@@ -3059,7 +3423,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
           "Agent ID is required for uploading knowledge from URLs"
         );
       }
-      logger5.info(`[KNOWLEDGE URL HANDLER] Processing URL upload for agent: ${agentId}`);
+      logger6.info(`[KNOWLEDGE URL HANDLER] Processing URL upload for agent: ${agentId}`);
       const processingPromises = fileUrls.map(async (fileUrl) => {
         try {
           const normalizedUrl = normalizeS3Url(fileUrl);
@@ -3068,7 +3432,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
           const pathSegments = urlObject.pathname.split("/");
           const encodedFilename = pathSegments[pathSegments.length - 1] || "document.pdf";
           const originalFilename = decodeURIComponent(encodedFilename);
-          logger5.info(`[KNOWLEDGE URL HANDLER] Fetching content from URL: ${fileUrl}`);
+          logger6.info(`[KNOWLEDGE URL HANDLER] Fetching content from URL: ${fileUrl}`);
           const { content, contentType: fetchedContentType } = await fetchUrlContent(fileUrl);
           let contentType = fetchedContentType;
           if (contentType === "application/octet-stream") {
@@ -3107,7 +3471,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
               url: normalizedUrl
             }
           };
-          logger5.debug(
+          logger6.debug(
             `[KNOWLEDGE URL HANDLER] Processing knowledge from URL: ${fileUrl} (type: ${contentType})`
           );
           const result = await service.addKnowledge(addKnowledgeOpts);
@@ -3121,7 +3485,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
             status: "success"
           };
         } catch (urlError) {
-          logger5.error(`[KNOWLEDGE URL HANDLER] Error processing URL ${fileUrl}: ${urlError}`);
+          logger6.error(`[KNOWLEDGE URL HANDLER] Error processing URL ${fileUrl}: ${urlError}`);
           return {
             fileUrl,
             status: "error_processing",
@@ -3133,7 +3497,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       sendSuccess(res, results);
     }
   } catch (error) {
-    logger5.error("[KNOWLEDGE HANDLER] Error processing knowledge:", error);
+    logger6.error("[KNOWLEDGE HANDLER] Error processing knowledge:", error);
     if (hasUploadedFiles) {
       cleanupFiles(req.files);
     }
@@ -3172,7 +3536,7 @@ async function getKnowledgeDocumentsHandler(req, res, runtime) {
         // Or if the URL is stored in the metadata (check if it exists)
         memory.metadata && "url" in memory.metadata && typeof memory.metadata.url === "string" && normalizedRequestUrls.includes(normalizeS3Url(memory.metadata.url))
       );
-      logger5.debug(
+      logger6.debug(
         `[KNOWLEDGE GET HANDLER] Filtered documents by URLs: ${fileUrls.length} URLs, found ${filteredMemories.length} matching documents`
       );
     }
@@ -3187,12 +3551,12 @@ async function getKnowledgeDocumentsHandler(req, res, runtime) {
       totalRequested: fileUrls ? fileUrls.length : 0
     });
   } catch (error) {
-    logger5.error("[KNOWLEDGE GET HANDLER] Error retrieving documents:", error);
+    logger6.error("[KNOWLEDGE GET HANDLER] Error retrieving documents:", error);
     sendError(res, 500, "RETRIEVAL_ERROR", "Failed to retrieve documents", error.message);
   }
 }
 async function deleteKnowledgeDocumentHandler(req, res, runtime) {
-  logger5.debug(`[KNOWLEDGE DELETE HANDLER] Received DELETE request:
+  logger6.debug(`[KNOWLEDGE DELETE HANDLER] Received DELETE request:
     - path: ${req.path}
     - params: ${JSON.stringify(req.params)}
   `);
@@ -3207,26 +3571,26 @@ async function deleteKnowledgeDocumentHandler(req, res, runtime) {
   }
   const knowledgeId = req.params.knowledgeId;
   if (!knowledgeId || knowledgeId.length < 36) {
-    logger5.error(`[KNOWLEDGE DELETE HANDLER] Invalid knowledge ID format: ${knowledgeId}`);
+    logger6.error(`[KNOWLEDGE DELETE HANDLER] Invalid knowledge ID format: ${knowledgeId}`);
     return sendError(res, 400, "INVALID_ID", "Invalid Knowledge ID format");
   }
   try {
     const typedKnowledgeId = knowledgeId;
-    logger5.debug(
+    logger6.debug(
       `[KNOWLEDGE DELETE HANDLER] Attempting to delete document with ID: ${typedKnowledgeId}`
     );
     await service.deleteMemory(typedKnowledgeId);
-    logger5.info(
+    logger6.info(
       `[KNOWLEDGE DELETE HANDLER] Successfully deleted document with ID: ${typedKnowledgeId}`
     );
     sendSuccess(res, null, 204);
   } catch (error) {
-    logger5.error(`[KNOWLEDGE DELETE HANDLER] Error deleting document ${knowledgeId}:`, error);
+    logger6.error(`[KNOWLEDGE DELETE HANDLER] Error deleting document ${knowledgeId}:`, error);
     sendError(res, 500, "DELETE_ERROR", "Failed to delete document", error.message);
   }
 }
 async function getKnowledgeByIdHandler(req, res, runtime) {
-  logger5.debug(`[KNOWLEDGE GET BY ID HANDLER] Received GET request:
+  logger6.debug(`[KNOWLEDGE GET BY ID HANDLER] Received GET request:
     - path: ${req.path}
     - params: ${JSON.stringify(req.params)}
   `);
@@ -3241,11 +3605,11 @@ async function getKnowledgeByIdHandler(req, res, runtime) {
   }
   const knowledgeId = req.params.knowledgeId;
   if (!knowledgeId || knowledgeId.length < 36) {
-    logger5.error(`[KNOWLEDGE GET BY ID HANDLER] Invalid knowledge ID format: ${knowledgeId}`);
+    logger6.error(`[KNOWLEDGE GET BY ID HANDLER] Invalid knowledge ID format: ${knowledgeId}`);
     return sendError(res, 400, "INVALID_ID", "Invalid Knowledge ID format");
   }
   try {
-    logger5.debug(`[KNOWLEDGE GET BY ID HANDLER] Retrieving document with ID: ${knowledgeId}`);
+    logger6.debug(`[KNOWLEDGE GET BY ID HANDLER] Retrieving document with ID: ${knowledgeId}`);
     const agentId = req.query.agentId;
     const memories = await service.getMemories({
       tableName: "documents",
@@ -3262,17 +3626,17 @@ async function getKnowledgeByIdHandler(req, res, runtime) {
     };
     sendSuccess(res, { document: cleanDocument });
   } catch (error) {
-    logger5.error(`[KNOWLEDGE GET BY ID HANDLER] Error retrieving document ${knowledgeId}:`, error);
+    logger6.error(`[KNOWLEDGE GET BY ID HANDLER] Error retrieving document ${knowledgeId}:`, error);
     sendError(res, 500, "RETRIEVAL_ERROR", "Failed to retrieve document", error.message);
   }
 }
 async function knowledgePanelHandler(req, res, runtime) {
   const agentId = runtime.agentId;
-  logger5.debug(`[KNOWLEDGE PANEL] Serving panel for agent ${agentId}, request path: ${req.path}`);
+  logger6.debug(`[KNOWLEDGE PANEL] Serving panel for agent ${agentId}, request path: ${req.path}`);
   try {
     const currentDir = path3.dirname(new URL(import.meta.url).pathname);
     const frontendPath = path3.join(currentDir, "../dist/index.html");
-    logger5.debug(`[KNOWLEDGE PANEL] Looking for frontend at: ${frontendPath}`);
+    logger6.debug(`[KNOWLEDGE PANEL] Looking for frontend at: ${frontendPath}`);
     if (fs3.existsSync(frontendPath)) {
       const html = await fs3.promises.readFile(frontendPath, "utf8");
       const injectedHtml = html.replace(
@@ -3306,10 +3670,10 @@ async function knowledgePanelHandler(req, res, runtime) {
             }
           }
         } catch (manifestError) {
-          logger5.error("[KNOWLEDGE PANEL] Error reading manifest:", manifestError);
+          logger6.error("[KNOWLEDGE PANEL] Error reading manifest:", manifestError);
         }
       }
-      logger5.debug(`[KNOWLEDGE PANEL] Using fallback with CSS: ${cssFile}, JS: ${jsFile}`);
+      logger6.debug(`[KNOWLEDGE PANEL] Using fallback with CSS: ${cssFile}, JS: ${jsFile}`);
       const html = `
 <!DOCTYPE html>
 <html lang="en">
@@ -3343,13 +3707,13 @@ async function knowledgePanelHandler(req, res, runtime) {
       res.end(html);
     }
   } catch (error) {
-    logger5.error("[KNOWLEDGE PANEL] Error serving frontend:", error);
+    logger6.error("[KNOWLEDGE PANEL] Error serving frontend:", error);
     sendError(res, 500, "FRONTEND_ERROR", "Failed to load knowledge panel", error.message);
   }
 }
 async function frontendAssetHandler(req, res, runtime) {
   try {
-    logger5.debug(
+    logger6.debug(
       `[KNOWLEDGE ASSET HANDLER] Called with req.path: ${req.path}, req.originalUrl: ${req.originalUrl}, req.params: ${JSON.stringify(req.params)}`
     );
     const currentDir = path3.dirname(new URL(import.meta.url).pathname);
@@ -3369,7 +3733,7 @@ async function frontendAssetHandler(req, res, runtime) {
       );
     }
     const assetPath = path3.join(currentDir, "../dist/assets", assetName);
-    logger5.debug(`[KNOWLEDGE ASSET HANDLER] Attempting to serve asset: ${assetPath}`);
+    logger6.debug(`[KNOWLEDGE ASSET HANDLER] Attempting to serve asset: ${assetPath}`);
     if (fs3.existsSync(assetPath)) {
       const fileStream = fs3.createReadStream(assetPath);
       let contentType = "application/octet-stream";
@@ -3384,7 +3748,7 @@ async function frontendAssetHandler(req, res, runtime) {
       sendError(res, 404, "NOT_FOUND", `Asset not found: ${req.url}`);
     }
   } catch (error) {
-    logger5.error(`[KNOWLEDGE ASSET HANDLER] Error serving asset ${req.url}:`, error);
+    logger6.error(`[KNOWLEDGE ASSET HANDLER] Error serving asset ${req.url}:`, error);
     sendError(res, 500, "ASSET_ERROR", `Failed to load asset ${req.url}`, error.message);
   }
 }
@@ -3408,7 +3772,7 @@ async function getKnowledgeChunksHandler(req, res, runtime) {
     ) : chunks;
     sendSuccess(res, { chunks: filteredChunks });
   } catch (error) {
-    logger5.error("[KNOWLEDGE CHUNKS GET HANDLER] Error retrieving chunks:", error);
+    logger6.error("[KNOWLEDGE CHUNKS GET HANDLER] Error retrieving chunks:", error);
     sendError(res, 500, "RETRIEVAL_ERROR", "Failed to retrieve knowledge chunks", error.message);
   }
 }
@@ -3430,14 +3794,14 @@ async function searchKnowledgeHandler(req, res, runtime) {
       return sendError(res, 400, "INVALID_QUERY", "Search query cannot be empty");
     }
     if (req.query.threshold && (parsedThreshold < 0 || parsedThreshold > 1)) {
-      logger5.debug(
+      logger6.debug(
         `[KNOWLEDGE SEARCH] Threshold value ${parsedThreshold} was clamped to ${matchThreshold}`
       );
     }
     if (req.query.limit && (parsedLimit < 1 || parsedLimit > 100)) {
-      logger5.debug(`[KNOWLEDGE SEARCH] Limit value ${parsedLimit} was clamped to ${limit}`);
+      logger6.debug(`[KNOWLEDGE SEARCH] Limit value ${parsedLimit} was clamped to ${limit}`);
     }
-    logger5.debug(
+    logger6.debug(
       `[KNOWLEDGE SEARCH] Searching for: "${searchText}" with threshold: ${matchThreshold}, limit: ${limit}`
     );
     const embedding = await runtime.useModel(ModelType4.TEXT_EMBEDDING, {
@@ -3464,7 +3828,7 @@ async function searchKnowledgeHandler(req, res, runtime) {
               documentFilename = document.metadata.filename || documentFilename;
             }
           } catch (e) {
-            logger5.debug(`Could not fetch document ${documentId} for fragment`);
+            logger6.debug(`Could not fetch document ${documentId} for fragment`);
           }
         }
         return {
@@ -3479,7 +3843,7 @@ async function searchKnowledgeHandler(req, res, runtime) {
         };
       })
     );
-    logger5.info(
+    logger6.info(
       `[KNOWLEDGE SEARCH] Found ${enhancedResults.length} results for query: "${searchText}"`
     );
     sendSuccess(res, {
@@ -3489,7 +3853,7 @@ async function searchKnowledgeHandler(req, res, runtime) {
       count: enhancedResults.length
     });
   } catch (error) {
-    logger5.error("[KNOWLEDGE SEARCH] Error searching knowledge:", error);
+    logger6.error("[KNOWLEDGE SEARCH] Error searching knowledge:", error);
     sendError(res, 500, "SEARCH_ERROR", "Failed to search knowledge", error.message);
   }
 }
@@ -3501,7 +3865,7 @@ async function uploadKnowledgeWithMulter(req, res, runtime) {
   );
   uploadArray(req, res, (err) => {
     if (err) {
-      logger5.error("[KNOWLEDGE UPLOAD] Multer error:", err);
+      logger6.error("[KNOWLEDGE UPLOAD] Multer error:", err);
       return sendError(res, 400, "UPLOAD_ERROR", err.message);
     }
     uploadKnowledgeHandler(req, res, runtime);
@@ -3564,35 +3928,36 @@ var knowledgePlugin = {
     CTX_KNOWLEDGE_ENABLED: "false"
   },
   async init(config, runtime) {
-    logger6.info("Initializing Knowledge Plugin...");
+    logger7.info("Initializing Knowledge Plugin...");
     try {
-      logger6.info("Validating model configuration for Knowledge plugin...");
+      logger7.info("Validating model configuration for Knowledge plugin...");
       const validatedConfig = validateModelConfig(runtime);
       if (validatedConfig.CTX_KNOWLEDGE_ENABLED) {
-        logger6.info("Running in Contextual Knowledge mode with text generation capabilities.");
-        logger6.info(
+        logger7.info("Running in Contextual Knowledge mode with text generation capabilities.");
+        logger7.info(
           `Using ${validatedConfig.EMBEDDING_PROVIDER} for embeddings and ${validatedConfig.TEXT_PROVIDER} for text generation.`
         );
       } else {
         const usingPluginOpenAI = !process.env.EMBEDDING_PROVIDER;
         if (usingPluginOpenAI) {
-          logger6.info(
+          logger7.info(
             "Running in Basic Embedding mode with auto-detected configuration from plugin-openai."
           );
         } else {
-          logger6.info(
+          logger7.info(
             "Running in Basic Embedding mode (CTX_KNOWLEDGE_ENABLED=false). TEXT_PROVIDER and TEXT_MODEL not required."
           );
         }
-        logger6.info(
+        logger7.info(
           `Using ${validatedConfig.EMBEDDING_PROVIDER} for embeddings with ${validatedConfig.TEXT_EMBEDDING_MODEL}.`
         );
       }
-      logger6.info("Model configuration validated successfully.");
+      logger7.info("Model configuration validated successfully.");
       if (runtime) {
-        logger6.info(`Knowledge Plugin initialized for agent: ${runtime.agentId}`);
-        const loadDocsOnStartup = config.LOAD_DOCS_ON_STARTUP !== "false" && process.env.LOAD_DOCS_ON_STARTUP !== "false";
+        logger7.info(`Knowledge Plugin initialized for agent: ${runtime.agentId}`);
+        const loadDocsOnStartup = config.LOAD_DOCS_ON_STARTUP === "true" || process.env.LOAD_DOCS_ON_STARTUP === "true";
         if (loadDocsOnStartup) {
+          logger7.info("LOAD_DOCS_ON_STARTUP is enabled. Scheduling document loading...");
           setTimeout(async () => {
             try {
               const service = runtime.getService(KnowledgeService.serviceType);
@@ -3600,20 +3965,22 @@ var knowledgePlugin = {
                 const { loadDocsFromPath: loadDocsFromPath2 } = await import("./docs-loader-IBTEOAYT.js");
                 const result = await loadDocsFromPath2(service, runtime.agentId);
                 if (result.successful > 0) {
-                  logger6.info(`Loaded ${result.successful} documents from docs folder on startup`);
+                  logger7.info(`Loaded ${result.successful} documents from docs folder on startup`);
                 }
               }
             } catch (error) {
-              logger6.error("Error loading documents on startup:", error);
+              logger7.error("Error loading documents on startup:", error);
             }
           }, 5e3);
+        } else {
+          logger7.info("LOAD_DOCS_ON_STARTUP is not enabled. Skipping automatic document loading.");
         }
       }
-      logger6.info(
+      logger7.info(
         "Knowledge Plugin initialized. Frontend panel should be discoverable via its public route."
       );
     } catch (error) {
-      logger6.error("Failed to initialize Knowledge plugin:", error);
+      logger7.error("Failed to initialize Knowledge plugin:", error);
       throw error;
     }
   },