@elizaos/plugin-knowledge 1.0.9 → 1.0.11

package/dist/index.js

@@ -8,10 +8,10 @@ import {
   looksLikeBase64,
   normalizeS3Url,
   v4_default
-} from "./chunk-QH7GBNKB.js";
+} from "./chunk-RFXW7QQK.js";
 
 // src/index.ts
-import { logger as logger7 } from "@elizaos/core";
+import { logger as logger8 } from "@elizaos/core";
 
 // src/types.ts
 import z from "zod";
@@ -60,18 +60,24 @@ function validateModelConfig(runtime) {
       }
       return process.env[key] || defaultValue;
     };
-    const ctxKnowledgeEnabled2 = getSetting("CTX_KNOWLEDGE_ENABLED") === "true";
-    logger.debug(`Configuration: CTX_KNOWLEDGE_ENABLED=${ctxKnowledgeEnabled2}`);
+    const ctxKnowledgeEnabledSetting = getSetting("CTX_KNOWLEDGE_ENABLED");
+    const cleanSetting = ctxKnowledgeEnabledSetting?.toString().trim().toLowerCase();
+    const ctxKnowledgeEnabled = cleanSetting === "true";
+    logger.debug(
+      `[Document Processor] CTX_KNOWLEDGE_ENABLED: '${ctxKnowledgeEnabledSetting}' \u2192 ${ctxKnowledgeEnabled} (runtime: ${!!runtime})`
+    );
     const embeddingProvider = getSetting("EMBEDDING_PROVIDER");
     const assumePluginOpenAI = !embeddingProvider;
     if (assumePluginOpenAI) {
       const openaiApiKey2 = getSetting("OPENAI_API_KEY");
       const openaiEmbeddingModel = getSetting("OPENAI_EMBEDDING_MODEL");
       if (openaiApiKey2 && openaiEmbeddingModel) {
-        logger.debug("EMBEDDING_PROVIDER not specified, using configuration from plugin-openai");
+        logger.debug(
+          "[Document Processor] EMBEDDING_PROVIDER not specified, using configuration from plugin-openai"
+        );
       } else {
         logger.debug(
-          "EMBEDDING_PROVIDER not specified. Assuming embeddings are provided by another plugin (e.g., plugin-google-genai)."
+          "[Document Processor] EMBEDDING_PROVIDER not specified. Assuming embeddings are provided by another plugin (e.g., plugin-google-genai)."
         );
       }
     }
@@ -95,7 +101,7 @@ function validateModelConfig(runtime) {
       MAX_INPUT_TOKENS: getSetting("MAX_INPUT_TOKENS", "4000"),
       MAX_OUTPUT_TOKENS: getSetting("MAX_OUTPUT_TOKENS", "4096"),
       EMBEDDING_DIMENSION: embeddingDimension,
-      CTX_KNOWLEDGE_ENABLED: ctxKnowledgeEnabled2
+      CTX_KNOWLEDGE_ENABLED: ctxKnowledgeEnabled
     });
     validateConfigRequirements(config, assumePluginOpenAI);
     return config;
@@ -116,13 +122,15 @@ function validateConfigRequirements(config, assumePluginOpenAI) {
     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.");
+    logger.debug(
+      "[Document Processor] 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.debug("Contextual Knowledge is enabled. Validating text generation settings...");
+    logger.debug("[Document Processor] CTX validation: Checking 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"');
     }
@@ -139,17 +147,21 @@ function validateConfigRequirements(config, assumePluginOpenAI) {
       const modelName = config.TEXT_MODEL?.toLowerCase() || "";
       if (modelName.includes("claude") || modelName.includes("gemini")) {
         logger.debug(
-          `Using ${modelName} with OpenRouter. This configuration supports document caching for improved performance.`
+          `[Document Processor] Using ${modelName} with OpenRouter. This configuration supports document caching for improved performance.`
         );
       }
     }
   } else {
+    logger.info("[Document Processor] Contextual Knowledge is DISABLED!");
+    logger.info("[Document Processor] This means documents will NOT be enriched with context.");
     if (assumePluginOpenAI) {
-      logger.debug(
-        "Contextual Knowledge is disabled. Embeddings will be handled by the runtime (e.g., plugin-openai, plugin-google-genai)."
+      logger.info(
+        "[Document Processor] Embeddings will be handled by the runtime (e.g., plugin-openai, plugin-google-genai)."
       );
     } else {
-      logger.debug("Contextual Knowledge is disabled. Using configured embedding provider.");
+      logger.info(
+        "[Document Processor] Using configured embedding provider for basic embeddings only."
+      );
     }
   }
 }
@@ -164,7 +176,18 @@ async function getProviderRateLimits(runtime) {
   const maxConcurrentRequests = parseInt(getSetting("MAX_CONCURRENT_REQUESTS", "30"), 10);
   const requestsPerMinute = parseInt(getSetting("REQUESTS_PER_MINUTE", "60"), 10);
   const tokensPerMinute = parseInt(getSetting("TOKENS_PER_MINUTE", "150000"), 10);
-  switch (config.EMBEDDING_PROVIDER) {
+  const primaryProvider = config.TEXT_PROVIDER || config.EMBEDDING_PROVIDER;
+  logger.debug(
+    `[Document Processor] Rate limiting for ${primaryProvider}: ${requestsPerMinute} RPM, ${tokensPerMinute} TPM, ${maxConcurrentRequests} concurrent`
+  );
+  switch (primaryProvider) {
+    case "anthropic":
+      return {
+        maxConcurrentRequests,
+        requestsPerMinute,
+        tokensPerMinute,
+        provider: "anthropic"
+      };
     case "openai":
       return {
         maxConcurrentRequests,
@@ -184,7 +207,7 @@ async function getProviderRateLimits(runtime) {
         maxConcurrentRequests,
         requestsPerMinute,
         tokensPerMinute,
-        provider: config.EMBEDDING_PROVIDER
+        provider: primaryProvider || "unknown"
       };
   }
 }
@@ -405,9 +428,7 @@ Create an enriched version of this chunk by adding critical surrounding context.
 Provide ONLY the enriched chunk text in your response:`;
 function getContextualizationPrompt(docContent, chunkContent, minTokens = CONTEXT_TARGETS.DEFAULT.MIN_TOKENS, maxTokens = CONTEXT_TARGETS.DEFAULT.MAX_TOKENS, promptTemplate = CONTEXTUAL_CHUNK_ENRICHMENT_PROMPT_TEMPLATE) {
   if (!docContent || !chunkContent) {
-    console.warn(
-      "Document content or chunk content is missing for contextualization."
-    );
+    console.warn("Document content or chunk content is missing for contextualization.");
     return "Error: Document or chunk content missing.";
   }
   const chunkTokens = Math.ceil(chunkContent.length / DEFAULT_CHARS_PER_TOKEN);
@@ -478,15 +499,8 @@ function getPromptForMimeType(mimeType, docContent, chunkContent) {
     minTokens = CONTEXT_TARGETS.TECHNICAL.MIN_TOKENS;
     maxTokens = CONTEXT_TARGETS.TECHNICAL.MAX_TOKENS;
     promptTemplate = TECHNICAL_PROMPT_TEMPLATE;
-    console.debug("Using technical documentation prompt template");
   }
-  return getContextualizationPrompt(
-    docContent,
-    chunkContent,
-    minTokens,
-    maxTokens,
-    promptTemplate
-  );
+  return getContextualizationPrompt(docContent, chunkContent, minTokens, maxTokens, promptTemplate);
 }
 function getCachingPromptForMimeType(mimeType, chunkContent) {
   let minTokens = CONTEXT_TARGETS.DEFAULT.MIN_TOKENS;
@@ -506,12 +520,7 @@ function getCachingPromptForMimeType(mimeType, chunkContent) {
     minTokens = CONTEXT_TARGETS.TECHNICAL.MIN_TOKENS;
     maxTokens = CONTEXT_TARGETS.TECHNICAL.MAX_TOKENS;
   }
-  return getCachingContextualizationPrompt(
-    chunkContent,
-    mimeType,
-    minTokens,
-    maxTokens
-  );
+  return getCachingContextualizationPrompt(chunkContent, mimeType, minTokens, maxTokens);
 }
 function containsMathematicalContent(content) {
   const latexMathPatterns = [
@@ -575,9 +584,7 @@ function containsMathematicalContent(content) {
     "coefficient"
   ];
   const contentLower = content.toLowerCase();
-  const mathKeywordCount = mathKeywords.filter(
-    (keyword) => contentLower.includes(keyword)
-  ).length;
+  const mathKeywordCount = mathKeywords.filter((keyword) => contentLower.includes(keyword)).length;
   return mathKeywordCount >= 2;
 }
 function isTechnicalDocumentation(content) {
@@ -626,9 +633,7 @@ function isTechnicalDocumentation(content) {
 }
 function getChunkWithContext(chunkContent, generatedContext) {
   if (!generatedContext || generatedContext.trim() === "") {
-    console.warn(
-      "Generated context is empty. Falling back to original chunk content."
-    );
+    console.warn("Generated context is empty. Falling back to original chunk content.");
     return chunkContent;
   }
   return generatedContext.trim();
@@ -669,7 +674,7 @@ async function generateText(prompt, system, overrideConfig) {
         throw new Error(`Unsupported text provider: ${provider}`);
     }
   } catch (error) {
-    logger2.error(`[LLM Service - ${provider}] Error generating text with ${modelName}:`, error);
+    logger2.error(`[Document Processor] ${provider} ${modelName} error:`, error);
     throw error;
   }
 }
@@ -680,17 +685,35 @@ async function generateAnthropicText(prompt, system, modelName, maxTokens) {
     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;
+  const maxRetries = 3;
+  for (let attempt = 0; attempt < maxRetries; attempt++) {
+    try {
+      const result = await aiGenerateText({
+        model: modelInstance,
+        prompt,
+        system,
+        temperature: 0.3,
+        maxTokens
+      });
+      const totalTokens = result.usage.promptTokens + result.usage.completionTokens;
+      logger2.debug(
+        `[Document Processor] ${modelName}: ${totalTokens} tokens (${result.usage.promptTokens}\u2192${result.usage.completionTokens})`
+      );
+      return result;
+    } catch (error) {
+      const isRateLimit = error?.status === 429 || error?.message?.includes("rate limit") || error?.message?.includes("429");
+      if (isRateLimit && attempt < maxRetries - 1) {
+        const delay = Math.pow(2, attempt + 1) * 1e3;
+        logger2.warn(
+          `[Document Processor] Rate limit hit (${modelName}): attempt ${attempt + 1}/${maxRetries}, retrying in ${Math.round(delay / 1e3)}s`
+        );
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error("Max retries exceeded for Anthropic text generation");
 }
 async function generateOpenAIText(prompt, system, modelName, maxTokens) {
   const config = validateModelConfig();
@@ -706,8 +729,9 @@ async function generateOpenAIText(prompt, system, modelName, maxTokens) {
     temperature: 0.3,
     maxTokens
   });
+  const totalTokens = result.usage.promptTokens + result.usage.completionTokens;
   logger2.debug(
-    `[LLM Service - OpenAI] Text generated with ${modelName}. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+    `[Document Processor] OpenAI ${modelName}: ${totalTokens} tokens (${result.usage.promptTokens}\u2192${result.usage.completionTokens})`
   );
   return result;
 }
@@ -724,8 +748,9 @@ async function generateGoogleText(prompt, system, modelName, maxTokens, config)
     temperature: 0.3,
     maxTokens
   });
+  const totalTokens = result.usage.promptTokens + result.usage.completionTokens;
   logger2.debug(
-    `[LLM Service - Google] Text generated with ${modelName}. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+    `[Document Processor] Google ${modelName}: ${totalTokens} tokens (${result.usage.promptTokens}\u2192${result.usage.completionTokens})`
   );
   return result;
 }
@@ -746,7 +771,7 @@ async function generateOpenRouterText(prompt, system, modelName, maxTokens, cach
     if (docMatch && docMatch[1]) {
       documentForCaching = docMatch[1].trim();
       logger2.debug(
-        `[LLM Service - OpenRouter] Auto-detected document for caching (${documentForCaching.length} chars)`
+        `[Document Processor] Auto-detected document for caching (${documentForCaching.length} chars)`
       );
     }
   }
@@ -777,13 +802,11 @@ async function generateOpenRouterText(prompt, system, modelName, maxTokens, cach
       );
     }
   }
-  logger2.debug("[LLM Service - OpenRouter] Using standard request without caching");
+  logger2.debug("[Document Processor] 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}`
-  );
+  logger2.debug(`[Document Processor] Using explicit prompt caching with Claude ${modelName}`);
   const messages = [
     // System message with cached document (if system is provided)
     system ? {
@@ -835,7 +858,7 @@ async function generateClaudeWithCaching(promptText, system, modelInstance, mode
       ]
     } : null
   ].filter(Boolean);
-  logger2.debug("[LLM Service - OpenRouter] Using Claude-specific caching structure");
+  logger2.debug("[Document Processor] Using Claude-specific caching structure");
   const result = await aiGenerateText({
     model: modelInstance,
     messages,
@@ -850,8 +873,9 @@ async function generateClaudeWithCaching(promptText, system, modelInstance, mode
     }
   });
   logCacheMetrics(result);
+  const totalTokens = result.usage.promptTokens + result.usage.completionTokens;
   logger2.debug(
-    `[LLM Service - OpenRouter] Text generated with ${modelName} using Claude caching. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+    `[Document Processor] OpenRouter ${modelName}: ${totalTokens} tokens (${result.usage.promptTokens}\u2192${result.usage.completionTokens})`
   );
   return result;
 }
@@ -861,27 +885,23 @@ async function generateGeminiWithCaching(promptText, system, modelInstance, mode
   const minTokensForImplicitCache = modelName.toLowerCase().includes("flash") ? 1028 : 2048;
   const likelyTriggersCaching = estimatedDocTokens >= minTokensForImplicitCache;
   if (usingImplicitCaching) {
+    logger2.debug(`[Document Processor] Using Gemini 2.5 implicit caching with ${modelName}`);
     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)`
+      `[Document Processor] 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`
+        `[Document Processor] Document ~${estimatedDocTokens} tokens exceeds ${minTokensForImplicitCache} token threshold for caching`
       );
     } else {
       logger2.debug(
-        `[LLM Service - OpenRouter] Warning: Document size ~${estimatedDocTokens} tokens may not meet minimum ${minTokensForImplicitCache} token threshold for implicit caching`
+        `[Document Processor] Document ~${estimatedDocTokens} tokens may not meet ${minTokensForImplicitCache} token threshold for caching`
       );
     }
   } else {
+    logger2.debug(`[Document Processor] Using standard prompt format with Gemini ${modelName}`);
     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`
+      `[Document Processor] Note: Only Gemini 2.5 models support automatic implicit caching`
     );
   }
   const geminiSystemPrefix = system ? `${system}
@@ -905,8 +925,10 @@ ${promptText}`;
     }
   });
   logCacheMetrics(result);
+  const totalTokens = result.usage.promptTokens + result.usage.completionTokens;
+  const cachingType = usingImplicitCaching ? "implicit" : "standard";
   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.`
+    `[Document Processor] OpenRouter ${modelName} (${cachingType} caching): ${totalTokens} tokens (${result.usage.promptTokens}\u2192${result.usage.completionTokens})`
   );
   return result;
 }
@@ -926,21 +948,44 @@ async function generateStandardOpenRouterText(prompt, system, modelInstance, mod
       }
     }
   });
+  const totalTokens = result.usage.promptTokens + result.usage.completionTokens;
   logger2.debug(
-    `[LLM Service - OpenRouter] Text generated with ${modelName}. Usage: ${result.usage.promptTokens} prompt tokens, ${result.usage.completionTokens} completion tokens.`
+    `[Document Processor] OpenRouter ${modelName}: ${totalTokens} tokens (${result.usage.promptTokens}\u2192${result.usage.completionTokens})`
   );
   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}`
+      `[Document Processor] Cache metrics - tokens: ${result.usage.cacheTokens}, discount: ${result.usage.cacheDiscount}`
     );
   }
 }
 
 // src/document-processor.ts
-var ctxKnowledgeEnabled = process.env.CTX_KNOWLEDGE_ENABLED === "true" || process.env.CTX_KNOWLEDGE_ENABLED === "True";
+function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+function getCtxKnowledgeEnabled(runtime) {
+  let result;
+  let source;
+  let rawValue;
+  if (runtime) {
+    rawValue = runtime.getSetting("CTX_KNOWLEDGE_ENABLED");
+    const cleanValue = rawValue?.toString().trim().toLowerCase();
+    result = cleanValue === "true";
+    source = "runtime.getSetting()";
+  } else {
+    rawValue = process.env.CTX_KNOWLEDGE_ENABLED;
+    const cleanValue = rawValue?.toString().trim().toLowerCase();
+    result = cleanValue === "true";
+    source = "process.env";
+  }
+  if (process.env.NODE_ENV === "development" && rawValue && !result) {
+    logger3.debug(`[Document Processor] CTX config mismatch - ${source}: '${rawValue}' \u2192 ${result}`);
+  }
+  return result;
+}
 function shouldUseCustomLLM() {
   const textProvider = process.env.TEXT_PROVIDER;
   const textModel = process.env.TEXT_MODEL;
@@ -961,18 +1006,6 @@ function shouldUseCustomLLM() {
   }
 }
 var useCustomLLM = shouldUseCustomLLM();
-if (ctxKnowledgeEnabled) {
-  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 {
-  logger3.info(`Document processor starting with Contextual Knowledge DISABLED`);
-}
 async function processFragmentsSynchronously({
   runtime,
   documentId,
@@ -981,7 +1014,8 @@ async function processFragmentsSynchronously({
   contentType,
   roomId,
   entityId,
-  worldId
+  worldId,
+  documentTitle
 }) {
   if (!fullDocumentText || fullDocumentText.trim() === "") {
     logger3.warn(`No text content available to chunk for document ${documentId}.`);
@@ -992,10 +1026,17 @@ async function processFragmentsSynchronously({
     logger3.warn(`No chunks generated from text for ${documentId}. No fragments to save.`);
     return 0;
   }
-  logger3.info(`Split content into ${chunks.length} chunks for document ${documentId}`);
+  const docName = documentTitle || documentId.substring(0, 8);
+  logger3.info(`[Document Processor] "${docName}": Split into ${chunks.length} chunks`);
   const providerLimits = await getProviderRateLimits();
   const CONCURRENCY_LIMIT = Math.min(30, providerLimits.maxConcurrentRequests || 30);
-  const rateLimiter = createRateLimiter(providerLimits.requestsPerMinute || 60);
+  const rateLimiter = createRateLimiter(
+    providerLimits.requestsPerMinute || 60,
+    providerLimits.tokensPerMinute
+  );
+  logger3.debug(
+    `[Document Processor] Rate limits: ${providerLimits.requestsPerMinute} RPM, ${providerLimits.tokensPerMinute} TPM (${providerLimits.provider}, concurrency: ${CONCURRENCY_LIMIT})`
+  );
   const { savedCount, failedCount } = await processAndSaveFragments({
     runtime,
     documentId,
@@ -1007,14 +1048,27 @@ async function processFragmentsSynchronously({
     entityId: entityId || agentId,
     worldId: worldId || agentId,
     concurrencyLimit: CONCURRENCY_LIMIT,
-    rateLimiter
+    rateLimiter,
+    documentTitle
   });
+  const successRate = (savedCount / chunks.length * 100).toFixed(1);
   if (failedCount > 0) {
     logger3.warn(
-      `Failed to process ${failedCount} chunks out of ${chunks.length} for document ${documentId}`
+      `[Document Processor] "${docName}": ${failedCount}/${chunks.length} chunks failed processing`
     );
   }
-  logger3.info(`Finished saving ${savedCount} fragments for document ${documentId}.`);
+  logger3.info(
+    `[Document Processor] "${docName}" complete: ${savedCount}/${chunks.length} fragments saved (${successRate}% success)`
+  );
+  logKnowledgeGenerationSummary({
+    documentId,
+    totalChunks: chunks.length,
+    savedCount,
+    failedCount,
+    successRate: parseFloat(successRate),
+    ctxEnabled: getCtxKnowledgeEnabled(runtime),
+    providerLimits
+  });
   return savedCount;
 }
 async function extractTextFromDocument(fileBuffer, contentType, originalFilename) {
@@ -1100,7 +1154,8 @@ async function processAndSaveFragments({
   entityId,
   worldId,
   concurrencyLimit,
-  rateLimiter
+  rateLimiter,
+  documentTitle
 }) {
   let savedCount = 0;
   let failedCount = 0;
@@ -1109,14 +1164,15 @@ async function processAndSaveFragments({
     const batchChunks = chunks.slice(i, i + concurrencyLimit);
     const batchOriginalIndices = Array.from({ length: batchChunks.length }, (_, k) => i + k);
     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)}`
+      `[Document Processor] Batch ${Math.floor(i / concurrencyLimit) + 1}/${Math.ceil(chunks.length / concurrencyLimit)}: processing ${batchChunks.length} chunks (${batchOriginalIndices[0]}-${batchOriginalIndices[batchOriginalIndices.length - 1]})`
     );
     const contextualizedChunks = await getContextualizedChunks(
       runtime,
       fullDocumentText,
       batchChunks,
       contentType,
-      batchOriginalIndices
+      batchOriginalIndices,
+      documentTitle
     );
     const embeddingResults = await generateEmbeddingsForChunks(
       runtime,
@@ -1159,9 +1215,12 @@ async function processAndSaveFragments({
           }
         };
         await runtime.createMemory(fragmentMemory, "knowledge");
-        logger3.debug(
-          `Saved fragment ${originalChunkIndex + 1} for document ${documentId} (Fragment ID: ${fragmentMemory.id})`
-        );
+        if (originalChunkIndex === chunks.length - 1) {
+          const docName = documentTitle || documentId.substring(0, 8);
+          logger3.info(
+            `[Document Processor] "${docName}": All ${chunks.length} chunks processed successfully`
+          );
+        }
         savedCount++;
       } catch (saveError) {
         logger3.error(
@@ -1199,7 +1258,8 @@ async function generateEmbeddingsForChunks(runtime, contextualizedChunks, rateLi
           text: contextualizedChunk.contextualizedText
         };
       }
-      await rateLimiter();
+      const embeddingTokens = estimateTokens(contextualizedChunk.contextualizedText);
+      await rateLimiter(embeddingTokens);
       try {
         const generateEmbeddingOperation = async () => {
           return await generateEmbeddingWithValidation(
@@ -1239,37 +1299,50 @@ async function generateEmbeddingsForChunks(runtime, contextualizedChunks, rateLi
     })
   );
 }
-async function getContextualizedChunks(runtime, fullDocumentText, chunks, contentType, batchOriginalIndices) {
-  if (ctxKnowledgeEnabled && fullDocumentText) {
-    logger3.debug(`Generating contexts for ${chunks.length} chunks`);
+async function getContextualizedChunks(runtime, fullDocumentText, chunks, contentType, batchOriginalIndices, documentTitle) {
+  const ctxEnabled = getCtxKnowledgeEnabled(runtime);
+  if (batchOriginalIndices[0] === 0) {
+    const docName = documentTitle || "Document";
+    const provider = runtime?.getSetting("TEXT_PROVIDER") || process.env.TEXT_PROVIDER;
+    const model = runtime?.getSetting("TEXT_MODEL") || process.env.TEXT_MODEL;
+    logger3.info(
+      `[Document Processor] "${docName}": CTX enrichment ${ctxEnabled ? "ENABLED" : "DISABLED"}${ctxEnabled ? ` (${provider}/${model})` : ""}`
+    );
+  }
+  if (ctxEnabled && fullDocumentText) {
     return await generateContextsInBatch(
       runtime,
       fullDocumentText,
       chunks,
       contentType,
-      batchOriginalIndices
+      batchOriginalIndices,
+      documentTitle
+    );
+  } else if (!ctxEnabled && batchOriginalIndices[0] === 0) {
+    logger3.debug(
+      `[Document Processor] To enable CTX: Set CTX_KNOWLEDGE_ENABLED=true and configure TEXT_PROVIDER/TEXT_MODEL`
     );
-  } else {
-    return chunks.map((chunkText, idx) => ({
-      contextualizedText: chunkText,
-      index: batchOriginalIndices[idx],
-      success: true
-    }));
   }
+  return chunks.map((chunkText, idx) => ({
+    contextualizedText: chunkText,
+    index: batchOriginalIndices[idx],
+    success: true
+  }));
 }
-async function generateContextsInBatch(runtime, fullDocumentText, chunks, contentType, batchIndices) {
-  console.log("####### generateContextsInBatch FULLL DOCUMENT", fullDocumentText);
-  console.log("####### generateContextsInBatch CHUNKS", chunks);
+async function generateContextsInBatch(runtime, fullDocumentText, chunks, contentType, batchIndices, documentTitle) {
   if (!chunks || chunks.length === 0) {
     return [];
   }
   const providerLimits = await getProviderRateLimits();
-  const rateLimiter = createRateLimiter(providerLimits.requestsPerMinute || 60);
+  const rateLimiter = createRateLimiter(
+    providerLimits.requestsPerMinute || 60,
+    providerLimits.tokensPerMinute
+  );
   const config = validateModelConfig();
   const isUsingOpenRouter = config.TEXT_PROVIDER === "openrouter";
   const isUsingCacheCapableModel = isUsingOpenRouter && (config.TEXT_MODEL?.toLowerCase().includes("claude") || config.TEXT_MODEL?.toLowerCase().includes("gemini"));
-  logger3.info(
-    `Using provider: ${config.TEXT_PROVIDER}, model: ${config.TEXT_MODEL}, caching capability: ${isUsingCacheCapableModel}`
+  logger3.debug(
+    `[Document Processor] Contextualizing ${chunks.length} chunks with ${config.TEXT_PROVIDER}/${config.TEXT_MODEL} (cache: ${isUsingCacheCapableModel})`
   );
   const promptConfigs = prepareContextPrompts(
     chunks,
@@ -1287,7 +1360,8 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
           index: item.originalIndex
         };
       }
-      await rateLimiter();
+      const llmTokens = estimateTokens(item.chunkText + (item.prompt || ""));
+      await rateLimiter(llmTokens);
       try {
         let llmResponse;
         const generateTextOperation = async () => {
@@ -1320,9 +1394,12 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
         );
         const generatedContext = typeof llmResponse === "string" ? llmResponse : llmResponse.text;
         const contextualizedText = getChunkWithContext(item.chunkText, generatedContext);
-        logger3.debug(
-          `Context added for chunk ${item.originalIndex}. New length: ${contextualizedText.length}`
-        );
+        if ((item.originalIndex + 1) % Math.max(1, Math.floor(chunks.length / 3)) === 0 || item.originalIndex === chunks.length - 1) {
+          const docName = documentTitle || "Document";
+          logger3.debug(
+            `[Document Processor] "${docName}": Context added for ${item.originalIndex + 1}/${chunks.length} chunks`
+          );
+        }
         return {
           contextualizedText,
           success: true,
@@ -1441,25 +1518,68 @@ async function withRateLimitRetry(operation, errorContext, retryDelay) {
     throw error;
   }
 }
-function createRateLimiter(requestsPerMinute) {
+function createRateLimiter(requestsPerMinute, tokensPerMinute) {
   const requestTimes = [];
+  const tokenUsage = [];
   const intervalMs = 60 * 1e3;
-  return async function rateLimiter() {
+  return async function rateLimiter(estimatedTokens = 1e3) {
     const now = Date.now();
     while (requestTimes.length > 0 && now - requestTimes[0] > intervalMs) {
       requestTimes.shift();
     }
-    if (requestTimes.length >= requestsPerMinute) {
-      const oldestRequest = requestTimes[0];
-      const timeToWait = Math.max(0, oldestRequest + intervalMs - now);
+    while (tokenUsage.length > 0 && now - tokenUsage[0].timestamp > intervalMs) {
+      tokenUsage.shift();
+    }
+    const currentTokens = tokenUsage.reduce((sum, usage) => sum + usage.tokens, 0);
+    const requestLimitExceeded = requestTimes.length >= requestsPerMinute;
+    const tokenLimitExceeded = tokensPerMinute && currentTokens + estimatedTokens > tokensPerMinute;
+    if (requestLimitExceeded || tokenLimitExceeded) {
+      let timeToWait = 0;
+      if (requestLimitExceeded) {
+        const oldestRequest = requestTimes[0];
+        timeToWait = Math.max(timeToWait, oldestRequest + intervalMs - now);
+      }
+      if (tokenLimitExceeded && tokenUsage.length > 0) {
+        const oldestTokenUsage = tokenUsage[0];
+        timeToWait = Math.max(timeToWait, oldestTokenUsage.timestamp + intervalMs - now);
+      }
       if (timeToWait > 0) {
-        logger3.debug(`Rate limiting applied, waiting ${timeToWait}ms before next request`);
+        const reason = requestLimitExceeded ? "request" : "token";
+        if (timeToWait > 5e3) {
+          logger3.info(
+            `[Document Processor] Rate limiting: waiting ${Math.round(timeToWait / 1e3)}s due to ${reason} limit`
+          );
+        } else {
+          logger3.debug(
+            `[Document Processor] Rate limiting: ${timeToWait}ms wait (${reason} limit)`
+          );
+        }
         await new Promise((resolve) => setTimeout(resolve, timeToWait));
       }
     }
-    requestTimes.push(Date.now());
+    requestTimes.push(now);
+    if (tokensPerMinute) {
+      tokenUsage.push({ timestamp: now, tokens: estimatedTokens });
+    }
   };
 }
+function logKnowledgeGenerationSummary({
+  totalChunks,
+  savedCount,
+  failedCount,
+  ctxEnabled,
+  providerLimits
+}) {
+  if (failedCount > 0 || process.env.NODE_ENV === "development") {
+    const status = failedCount > 0 ? "PARTIAL" : "SUCCESS";
+    logger3.info(
+      `[Document Processor] ${status}: ${savedCount}/${totalChunks} chunks, CTX: ${ctxEnabled ? "ON" : "OFF"}, Provider: ${providerLimits.provider}`
+    );
+  }
+  if (failedCount > 0) {
+    logger3.warn(`[Document Processor] ${failedCount} chunks failed processing`);
+  }
+}
 
 // src/service.ts
 var KnowledgeService = class _KnowledgeService extends Service {
@@ -1588,15 +1708,11 @@ var KnowledgeService = class _KnowledgeService extends Service {
       maxChars: 2e3
       // Use first 2KB of content for ID generation
     });
-    logger4.info(
-      `KnowledgeService processing document for agent: ${agentId}, file: ${options.originalFilename}, type: ${options.contentType}, generated ID: ${contentBasedId}`
-    );
+    logger4.info(`Processing "${options.originalFilename}" (${options.contentType})`);
     try {
       const existingDocument = await this.runtime.getMemoryById(contentBasedId);
       if (existingDocument && existingDocument.metadata?.type === MemoryType2.DOCUMENT) {
-        logger4.info(
-          `Document ${options.originalFilename} with ID ${contentBasedId} already exists. Skipping processing.`
-        );
+        logger4.info(`"${options.originalFilename}" already exists - skipping`);
         const fragments = await this.runtime.getMemories({
           tableName: "knowledge"
         });
@@ -1742,11 +1858,10 @@ var KnowledgeService = class _KnowledgeService extends Service {
         contentType,
         roomId: roomId || agentId,
         entityId: entityId || agentId,
-        worldId: worldId || agentId
+        worldId: worldId || agentId,
+        documentTitle: originalFilename
       });
-      logger4.info(
-        `KnowledgeService: Document ${originalFilename} processed with ${fragmentCount} fragments for agent ${agentId}`
-      );
+      logger4.debug(`"${originalFilename}" stored with ${fragmentCount} fragments`);
       return {
         clientDocumentId,
         storedDocumentMemoryId: memoryWithScope.id,
@@ -1801,6 +1916,101 @@ var KnowledgeService = class _KnowledgeService extends Service {
       worldId: fragment.worldId
     }));
   }
+  /**
+   * Enrich a conversation memory with RAG metadata
+   * This can be called after response generation to add RAG tracking data
+   * @param memoryId The ID of the conversation memory to enrich
+   * @param ragMetadata The RAG metadata to add
+   */
+  async enrichConversationMemoryWithRAG(memoryId, ragMetadata) {
+    try {
+      const existingMemory = await this.runtime.getMemoryById(memoryId);
+      if (!existingMemory) {
+        logger4.warn(`Cannot enrich memory ${memoryId} - memory not found`);
+        return;
+      }
+      const updatedMetadata = {
+        ...existingMemory.metadata,
+        knowledgeUsed: true,
+        // Simple flag for UI to detect RAG usage
+        ragUsage: {
+          retrievedFragments: ragMetadata.retrievedFragments,
+          queryText: ragMetadata.queryText,
+          totalFragments: ragMetadata.totalFragments,
+          retrievalTimestamp: ragMetadata.retrievalTimestamp,
+          usedInResponse: true
+        },
+        timestamp: existingMemory.metadata?.timestamp || Date.now(),
+        type: existingMemory.metadata?.type || "message"
+      };
+      await this.runtime.updateMemory({
+        id: memoryId,
+        metadata: updatedMetadata
+      });
+      logger4.debug(
+        `Enriched conversation memory ${memoryId} with RAG data: ${ragMetadata.totalFragments} fragments`
+      );
+    } catch (error) {
+      logger4.warn(
+        `Failed to enrich conversation memory ${memoryId} with RAG data: ${error.message}`
+      );
+    }
+  }
+  /**
+   * Set the current response memory ID for RAG tracking
+   * This is called by the knowledge provider to track which response memory to enrich
+   */
+  pendingRAGEnrichment = [];
+  /**
+   * Store RAG metadata for the next conversation memory that gets created
+   * @param ragMetadata The RAG metadata to associate with the next memory
+   */
+  setPendingRAGMetadata(ragMetadata) {
+    const now = Date.now();
+    this.pendingRAGEnrichment = this.pendingRAGEnrichment.filter(
+      (entry) => now - entry.timestamp < 3e4
+    );
+    this.pendingRAGEnrichment.push({
+      ragMetadata,
+      timestamp: now
+    });
+    logger4.debug(`Stored pending RAG metadata for next conversation memory`);
+  }
+  /**
+   * Try to enrich recent conversation memories with pending RAG metadata
+   * This is called periodically to catch memories that were created after RAG retrieval
+   */
+  async enrichRecentMemoriesWithPendingRAG() {
+    if (this.pendingRAGEnrichment.length === 0) {
+      return;
+    }
+    try {
+      const recentMemories = await this.runtime.getMemories({
+        tableName: "messages",
+        count: 10
+      });
+      const now = Date.now();
+      const recentConversationMemories = recentMemories.filter(
+        (memory) => memory.metadata?.type === "message" && now - (memory.createdAt || 0) < 1e4 && // Created in last 10 seconds
+        !memory.metadata?.ragUsage
+        // Doesn't already have RAG data
+      ).sort((a, b) => (b.createdAt || 0) - (a.createdAt || 0));
+      for (const pendingEntry of this.pendingRAGEnrichment) {
+        const matchingMemory = recentConversationMemories.find(
+          (memory) => (memory.createdAt || 0) > pendingEntry.timestamp
+        );
+        if (matchingMemory && matchingMemory.id) {
+          await this.enrichConversationMemoryWithRAG(matchingMemory.id, pendingEntry.ragMetadata);
+          const index = this.pendingRAGEnrichment.indexOf(pendingEntry);
+          if (index > -1) {
+            this.pendingRAGEnrichment.splice(index, 1);
+          }
+        }
+      }
+    } catch (error) {
+      logger4.warn(`Error enriching recent memories with RAG data: ${error.message}`);
+    }
+  }
   async processCharacterKnowledge(items) {
     await new Promise((resolve) => setTimeout(resolve, 1e3));
     logger4.info(
@@ -2026,13 +2236,14 @@ var KnowledgeService = class _KnowledgeService extends Service {
 };
 
 // src/provider.ts
-import { addHeader } from "@elizaos/core";
+import { addHeader, logger as logger5 } from "@elizaos/core";
 var knowledgeProvider = {
   name: "KNOWLEDGE",
   description: "Knowledge from the knowledge base that the agent knows, retrieved whenever the agent needs to answer a question about their expertise.",
   dynamic: true,
   get: async (runtime, message) => {
-    const knowledgeData = await runtime.getService("knowledge")?.getKnowledge(message);
+    const knowledgeService = runtime.getService("knowledge");
+    const knowledgeData = await knowledgeService?.getKnowledge(message);
     const firstFiveKnowledgeItems = knowledgeData?.slice(0, 5);
     let knowledge = (firstFiveKnowledgeItems && firstFiveKnowledgeItems.length > 0 ? addHeader(
       "# Knowledge",
@@ -2042,14 +2253,52 @@ var knowledgeProvider = {
     if (knowledge.length > 4e3 * tokenLength) {
       knowledge = knowledge.slice(0, 4e3 * tokenLength);
     }
+    let ragMetadata = null;
+    if (knowledgeData && knowledgeData.length > 0) {
+      ragMetadata = {
+        retrievedFragments: knowledgeData.map((fragment) => ({
+          fragmentId: fragment.id,
+          documentTitle: fragment.metadata?.filename || fragment.metadata?.title || "Unknown Document",
+          similarityScore: fragment.similarity,
+          contentPreview: (fragment.content?.text || "No content").substring(0, 100) + "..."
+        })),
+        queryText: message.content?.text || "Unknown query",
+        totalFragments: knowledgeData.length,
+        retrievalTimestamp: Date.now()
+      };
+    }
+    if (knowledgeData && knowledgeData.length > 0 && knowledgeService && ragMetadata) {
+      try {
+        knowledgeService.setPendingRAGMetadata(ragMetadata);
+        setTimeout(async () => {
+          try {
+            await knowledgeService.enrichRecentMemoriesWithPendingRAG();
+          } catch (error) {
+            logger5.warn("RAG memory enrichment failed:", error.message);
+          }
+        }, 2e3);
+      } catch (error) {
+        logger5.warn("RAG memory enrichment failed:", error.message);
+      }
+    }
     return {
       data: {
-        knowledge
+        knowledge,
+        ragMetadata,
+        // 🎯 Include RAG metadata for memory tracking
+        knowledgeUsed: knowledgeData && knowledgeData.length > 0
+        // Simple flag for easy detection
       },
       values: {
-        knowledge
+        knowledge,
+        knowledgeUsed: knowledgeData && knowledgeData.length > 0
+        // Simple flag for easy detection
       },
-      text: knowledge
+      text: knowledge,
+      ragMetadata,
+      // 🎯 Also include at top level for easy access
+      knowledgeUsed: knowledgeData && knowledgeData.length > 0
+      // 🎯 Simple flag at top level too
     };
   }
 };
@@ -2192,9 +2441,7 @@ function createMockRuntime(overrides) {
       return ids.map((id) => memories.get(id)).filter(Boolean);
     },
     async getMemoriesByRoomIds(params) {
-      return Array.from(memories.values()).filter(
-        (m) => params.roomIds.includes(m.roomId)
-      );
+      return Array.from(memories.values()).filter((m) => params.roomIds.includes(m.roomId));
     },
     async searchMemories(params) {
       const fragments = Array.from(memories.values()).filter(
@@ -2521,9 +2768,7 @@ var KnowledgeTestSuite = class {
           throw new Error("Incorrect service capability description");
         }
         runtime.services.set(KnowledgeService.serviceType, service);
-        const retrievedService = runtime.getService(
-          KnowledgeService.serviceType
-        );
+        const retrievedService = runtime.getService(KnowledgeService.serviceType);
         if (retrievedService !== service) {
           throw new Error("Service not properly registered with runtime");
         }
@@ -2536,11 +2781,7 @@ var KnowledgeTestSuite = class {
       fn: async (runtime) => {
         const testContent = "This is a test document with some content.";
         const buffer = createTestFileBuffer(testContent);
-        const extractedText = await extractTextFromDocument(
-          buffer,
-          "text/plain",
-          "test.txt"
-        );
+        const extractedText = await extractTextFromDocument(buffer, "text/plain", "test.txt");
         if (extractedText !== testContent) {
           throw new Error(`Expected "${testContent}", got "${extractedText}"`);
         }
@@ -2612,9 +2853,7 @@ var KnowledgeTestSuite = class {
         if (result.fragmentCount === 0) {
           throw new Error("No fragments created");
         }
-        const storedDoc = await runtime.getMemoryById(
-          result.storedDocumentMemoryId
-        );
+        const storedDoc = await runtime.getMemoryById(result.storedDocumentMemoryId);
         if (!storedDoc) {
           throw new Error("Document not found in storage");
         }
@@ -2765,13 +3004,9 @@ var KnowledgeTestSuite = class {
           entityId: knowledgeRuntime.agentId
         });
         if (memories.length < 3) {
-          throw new Error(
-            `Expected at least 3 character knowledge items, got ${memories.length}`
-          );
+          throw new Error(`Expected at least 3 character knowledge items, got ${memories.length}`);
         }
-        const pathKnowledge = memories.find(
-          (m) => m.content.text?.includes("markdown content")
-        );
+        const pathKnowledge = memories.find((m) => m.content.text?.includes("markdown content"));
         if (!pathKnowledge) {
           throw new Error("Path-based knowledge not found");
         }
@@ -2873,11 +3108,7 @@ var KnowledgeTestSuite = class {
           data: {},
           text: ""
         };
-        const providerResult = await knowledgeProvider.get(
-          runtime,
-          queryMessage,
-          state
-        );
+        const providerResult = await knowledgeProvider.get(runtime, queryMessage, state);
         if (!providerResult.text || !providerResult.text.includes("qubit")) {
           throw new Error("Provider did not return relevant knowledge");
         }
@@ -2907,9 +3138,7 @@ var KnowledgeTestSuite = class {
         };
         const result = await service.addKnowledge(document);
         if (result.fragmentCount < 2) {
-          throw new Error(
-            "Large document should be split into multiple fragments"
-          );
+          throw new Error("Large document should be split into multiple fragments");
         }
         const fragments = await runtime.getMemories({
           tableName: "knowledge",
@@ -2961,7 +3190,7 @@ var KnowledgeTestSuite = class {
 var tests_default = new KnowledgeTestSuite();
 
 // src/actions.ts
-import { logger as logger5, stringToUuid } from "@elizaos/core";
+import { logger as logger6, stringToUuid } from "@elizaos/core";
 import * as fs2 from "fs";
 import * as path2 from "path";
 var processKnowledgeAction = {
@@ -3014,25 +3243,19 @@ var processKnowledgeAction = {
       "ingest",
       "file"
     ];
-    const hasKeyword = knowledgeKeywords.some(
-      (keyword) => text.includes(keyword)
-    );
+    const hasKeyword = knowledgeKeywords.some((keyword) => text.includes(keyword));
     const pathPattern = /(?:\/[\w.-]+)+|(?:[a-zA-Z]:[\\/][\w\s.-]+(?:[\\/][\w\s.-]+)*)/;
     const hasPath = pathPattern.test(text);
     const service = runtime.getService(KnowledgeService.serviceType);
     if (!service) {
-      logger5.warn(
-        "Knowledge service not available for PROCESS_KNOWLEDGE action"
-      );
+      logger6.warn("Knowledge service not available for PROCESS_KNOWLEDGE action");
       return false;
     }
     return hasKeyword || hasPath;
   },
   handler: async (runtime, message, state, options, callback) => {
     try {
-      const service = runtime.getService(
-        KnowledgeService.serviceType
-      );
+      const service = runtime.getService(KnowledgeService.serviceType);
       if (!service) {
         throw new Error("Knowledge service not available");
       }
@@ -3075,10 +3298,7 @@ var processKnowledgeAction = {
           text: `I've successfully processed the document "${fileName}". It has been split into ${result.fragmentCount} searchable fragments and added to my knowledge base.`
         };
       } else {
-        const knowledgeContent = text.replace(
-          /^(add|store|remember|process|learn)\s+(this|that|the following)?:?\s*/i,
-          ""
-        ).trim();
+        const knowledgeContent = text.replace(/^(add|store|remember|process|learn)\s+(this|that|the following)?:?\s*/i, "").trim();
         if (!knowledgeContent) {
           response = {
             text: "I need some content to add to my knowledge base. Please provide text or a file path."
@@ -3106,7 +3326,7 @@ var processKnowledgeAction = {
         await callback(response);
       }
     } catch (error) {
-      logger5.error("Error in PROCESS_KNOWLEDGE action:", error);
+      logger6.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"}`
       };
@@ -3146,25 +3366,10 @@ var searchKnowledgeAction = {
   ],
   validate: async (runtime, message, state) => {
     const text = message.content.text?.toLowerCase() || "";
-    const searchKeywords = [
-      "search",
-      "find",
-      "look up",
-      "query",
-      "what do you know about"
-    ];
-    const knowledgeKeywords = [
-      "knowledge",
-      "information",
-      "document",
-      "database"
-    ];
-    const hasSearchKeyword = searchKeywords.some(
-      (keyword) => text.includes(keyword)
-    );
-    const hasKnowledgeKeyword = knowledgeKeywords.some(
-      (keyword) => text.includes(keyword)
-    );
+    const searchKeywords = ["search", "find", "look up", "query", "what do you know about"];
+    const knowledgeKeywords = ["knowledge", "information", "document", "database"];
+    const hasSearchKeyword = searchKeywords.some((keyword) => text.includes(keyword));
+    const hasKnowledgeKeyword = knowledgeKeywords.some((keyword) => text.includes(keyword));
     const service = runtime.getService(KnowledgeService.serviceType);
     if (!service) {
       return false;
@@ -3173,17 +3378,12 @@ var searchKnowledgeAction = {
   },
   handler: async (runtime, message, state, options, callback) => {
     try {
-      const service = runtime.getService(
-        KnowledgeService.serviceType
-      );
+      const service = runtime.getService(KnowledgeService.serviceType);
       if (!service) {
         throw new Error("Knowledge service not available");
       }
       const text = message.content.text || "";
-      const query = text.replace(
-        /^(search|find|look up|query)\s+(your\s+)?knowledge\s+(base\s+)?(for\s+)?/i,
-        ""
-      ).trim();
+      const query = text.replace(/^(search|find|look up|query)\s+(your\s+)?knowledge\s+(base\s+)?(for\s+)?/i, "").trim();
       if (!query) {
         const response2 = {
           text: "What would you like me to search for in my knowledge base?"
@@ -3217,7 +3417,7 @@ ${formattedResults}`
         await callback(response);
       }
     } catch (error) {
-      logger5.error("Error in SEARCH_KNOWLEDGE action:", error);
+      logger6.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"}`
       };
@@ -3230,9 +3430,44 @@ ${formattedResults}`
 var knowledgeActions = [processKnowledgeAction, searchKnowledgeAction];
 
 // src/routes.ts
-import { createUniqueUuid as createUniqueUuid2, logger as logger6, ModelType as ModelType4 } from "@elizaos/core";
+import { createUniqueUuid as createUniqueUuid2, logger as logger7, ModelType as ModelType4 } from "@elizaos/core";
 import fs3 from "fs";
 import path3 from "path";
+import multer from "multer";
+var createUploadMiddleware = (runtime) => {
+  const uploadDir = runtime.getSetting("KNOWLEDGE_UPLOAD_DIR") || "/tmp/uploads/";
+  const maxFileSize = parseInt(runtime.getSetting("KNOWLEDGE_MAX_FILE_SIZE") || "52428800");
+  const maxFiles = parseInt(runtime.getSetting("KNOWLEDGE_MAX_FILES") || "10");
+  const allowedMimeTypes = runtime.getSetting("KNOWLEDGE_ALLOWED_MIME_TYPES")?.split(",") || [
+    "text/plain",
+    "text/markdown",
+    "application/pdf",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+    "text/html",
+    "application/json",
+    "application/xml",
+    "text/csv"
+  ];
+  return multer({
+    dest: uploadDir,
+    limits: {
+      fileSize: maxFileSize,
+      files: maxFiles
+    },
+    fileFilter: (req, file, cb) => {
+      if (allowedMimeTypes.includes(file.mimetype)) {
+        cb(null, true);
+      } else {
+        cb(
+          new Error(
+            `File type ${file.mimetype} not allowed. Allowed types: ${allowedMimeTypes.join(", ")}`
+          )
+        );
+      }
+    }
+  });
+};
 function sendSuccess(res, data, status = 200) {
   res.writeHead(status, { "Content-Type": "application/json" });
   res.end(JSON.stringify({ success: true, data }));
@@ -3246,17 +3481,13 @@ var cleanupFile = (filePath) => {
     try {
       fs3.unlinkSync(filePath);
     } catch (error) {
-      logger6.error(`Error cleaning up file ${filePath}:`, error);
+      logger7.error(`Error cleaning up file ${filePath}:`, error);
     }
   }
 };
 var cleanupFiles = (files) => {
   if (files) {
-    files.forEach((file) => {
-      if (file.tempFilePath) {
-        cleanupFile(file.tempFilePath);
-      }
-    });
+    files.forEach((file) => cleanupFile(file.path));
   }
 };
 async function uploadKnowledgeHandler(req, res, runtime) {
@@ -3264,50 +3495,35 @@ async function uploadKnowledgeHandler(req, res, runtime) {
   if (!service) {
     return sendError(res, 500, "SERVICE_NOT_FOUND", "KnowledgeService not found");
   }
-  const hasUploadedFiles = req.files && Object.keys(req.files).length > 0;
+  const hasUploadedFiles = req.files && req.files.length > 0;
   const isJsonRequest = !hasUploadedFiles && req.body && (req.body.fileUrl || req.body.fileUrls);
   if (!hasUploadedFiles && !isJsonRequest) {
     return sendError(res, 400, "INVALID_REQUEST", "Request must contain either files or URLs");
   }
   try {
     if (hasUploadedFiles) {
-      let files = [];
-      if (req.files.files) {
-        if (Array.isArray(req.files.files)) {
-          files = req.files.files;
-        } else {
-          files = [req.files.files];
-        }
-      } else if (req.files.file) {
-        files = [req.files.file];
-      } else {
-        files = Object.values(req.files).flat();
-      }
+      const files = req.files;
       if (!files || files.length === 0) {
         return sendError(res, 400, "NO_FILES", "No files uploaded");
       }
       const invalidFiles = files.filter((file) => {
-        if (file.truncated) {
-          logger6.warn(`File ${file.name} was truncated during upload`);
-          return true;
-        }
         if (file.size === 0) {
-          logger6.warn(`File ${file.name} is empty`);
+          logger7.warn(`File ${file.originalname} is empty`);
           return true;
         }
-        if (!file.name || file.name.trim() === "") {
-          logger6.warn(`File has no name`);
+        if (!file.originalname || file.originalname.trim() === "") {
+          logger7.warn(`File has no name`);
           return true;
         }
-        if (!file.data && !file.tempFilePath) {
-          logger6.warn(`File ${file.name} has no data or temp file path`);
+        if (!file.path) {
+          logger7.warn(`File ${file.originalname} has no path`);
           return true;
         }
         return false;
       });
       if (invalidFiles.length > 0) {
         cleanupFiles(files);
-        const invalidFileNames = invalidFiles.map((f) => f.name || "unnamed").join(", ");
+        const invalidFileNames = invalidFiles.map((f) => f.originalname || "unnamed").join(", ");
         return sendError(
           res,
           400,
@@ -3317,8 +3533,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       }
       const agentId = req.body.agentId || req.query.agentId;
       if (!agentId) {
-        logger6.error("[KNOWLEDGE UPLOAD HANDLER] No agent ID provided in request");
-        cleanupFiles(files);
+        logger7.error("[Document Processor] \u274C No agent ID provided in upload request");
         return sendError(
           res,
           400,
@@ -3327,55 +3542,25 @@ async function uploadKnowledgeHandler(req, res, runtime) {
         );
       }
       const worldId = req.body.worldId || agentId;
-      logger6.info(`[KNOWLEDGE UPLOAD HANDLER] Processing upload for agent: ${agentId}`);
+      logger7.info(`[Document Processor] \u{1F4E4} Processing file upload for agent: ${agentId}`);
       const processingPromises = files.map(async (file, index) => {
-        const originalFilename = file.name;
-        const filePath = file.tempFilePath;
-        logger6.debug(
-          `[KNOWLEDGE UPLOAD HANDLER] File: ${originalFilename}, Agent ID: ${agentId}, World ID: ${worldId}`
+        const originalFilename = file.originalname;
+        const filePath = file.path;
+        logger7.debug(
+          `[Document Processor] \u{1F4C4} Processing file: ${originalFilename} (agent: ${agentId})`
         );
         try {
-          let fileBuffer;
-          if (filePath && fs3.existsSync(filePath)) {
-            try {
-              const stats = await fs3.promises.stat(filePath);
-              if (stats.size === 0) {
-                throw new Error("Temporary file is empty");
-              }
-              fileBuffer = await fs3.promises.readFile(filePath);
-              logger6.debug(
-                `[KNOWLEDGE UPLOAD] Read ${fileBuffer.length} bytes from temp file: ${filePath}`
-              );
-            } catch (fsError) {
-              throw new Error(`Failed to read temporary file: ${fsError.message}`);
-            }
-          } else if (file.data && Buffer.isBuffer(file.data)) {
-            fileBuffer = file.data;
-            logger6.debug(`[KNOWLEDGE UPLOAD] Using in-memory buffer of ${fileBuffer.length} bytes`);
-          } else {
-            throw new Error("No file data available - neither temp file nor buffer found");
-          }
-          if (!Buffer.isBuffer(fileBuffer) || fileBuffer.length === 0) {
-            throw new Error("Invalid or empty file buffer");
-          }
-          if (fileBuffer.length !== file.size) {
-            logger6.warn(
-              `File size mismatch for ${originalFilename}: expected ${file.size}, got ${fileBuffer.length}`
-            );
-          }
+          const fileBuffer = await fs3.promises.readFile(filePath);
           const base64Content = fileBuffer.toString("base64");
-          if (!base64Content || base64Content.length === 0) {
-            throw new Error("Failed to convert file to base64");
-          }
           const addKnowledgeOpts = {
             agentId,
             // Pass the agent ID from frontend
             clientDocumentId: "",
             // This will be ignored by the service
             contentType: file.mimetype,
-            // Directly from express-fileupload file object
+            // Directly from multer file object
             originalFilename,
-            // Directly from express-fileupload file object
+            // Directly from multer file object
             content: base64Content,
             // The base64 string of the file
             worldId,
@@ -3385,9 +3570,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
             // Use the correct agent ID
           };
           const result = await service.addKnowledge(addKnowledgeOpts);
-          if (filePath) {
-            cleanupFile(filePath);
-          }
+          cleanupFile(filePath);
           return {
             id: result.clientDocumentId,
             // Use the content-based ID returned by the service
@@ -3398,12 +3581,11 @@ async function uploadKnowledgeHandler(req, res, runtime) {
             status: "success"
           };
         } catch (fileError) {
-          logger6.error(
-            `[KNOWLEDGE UPLOAD HANDLER] Error processing file ${file.name}: ${fileError}`
+          logger7.error(
+            `[Document Processor] \u274C Error processing file ${file.originalname}:`,
+            fileError
           );
-          if (filePath) {
-            cleanupFile(filePath);
-          }
+          cleanupFile(filePath);
           return {
             id: "",
             // No ID since processing failed
@@ -3422,7 +3604,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       }
       const agentId = req.body.agentId || req.query.agentId;
       if (!agentId) {
-        logger6.error("[KNOWLEDGE URL HANDLER] No agent ID provided in request");
+        logger7.error("[Document Processor] \u274C No agent ID provided in URL request");
         return sendError(
           res,
           400,
@@ -3430,7 +3612,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
           "Agent ID is required for uploading knowledge from URLs"
         );
       }
-      logger6.info(`[KNOWLEDGE URL HANDLER] Processing URL upload for agent: ${agentId}`);
+      logger7.info(`[Document Processor] \u{1F4E4} Processing URL upload for agent: ${agentId}`);
       const processingPromises = fileUrls.map(async (fileUrl) => {
         try {
           const normalizedUrl = normalizeS3Url(fileUrl);
@@ -3438,7 +3620,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
           const pathSegments = urlObject.pathname.split("/");
           const encodedFilename = pathSegments[pathSegments.length - 1] || "document.pdf";
           const originalFilename = decodeURIComponent(encodedFilename);
-          logger6.info(`[KNOWLEDGE URL HANDLER] Fetching content from URL: ${fileUrl}`);
+          logger7.debug(`[Document Processor] \u{1F310} Fetching content from URL: ${fileUrl}`);
           const { content, contentType: fetchedContentType } = await fetchUrlContent(fileUrl);
           let contentType = fetchedContentType;
           if (contentType === "application/octet-stream") {
@@ -3478,8 +3660,8 @@ async function uploadKnowledgeHandler(req, res, runtime) {
               url: normalizedUrl
             }
           };
-          logger6.debug(
-            `[KNOWLEDGE URL HANDLER] Processing knowledge from URL: ${fileUrl} (type: ${contentType})`
+          logger7.debug(
+            `[Document Processor] \u{1F4C4} Processing knowledge from URL: ${originalFilename} (type: ${contentType})`
           );
           const result = await service.addKnowledge(addKnowledgeOpts);
           return {
@@ -3493,7 +3675,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
             status: "success"
           };
         } catch (urlError) {
-          logger6.error(`[KNOWLEDGE URL HANDLER] Error processing URL ${fileUrl}: ${urlError}`);
+          logger7.error(`[Document Processor] \u274C Error processing URL ${fileUrl}:`, urlError);
           return {
             fileUrl,
             status: "error_processing",
@@ -3505,10 +3687,9 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       sendSuccess(res, results);
     }
   } catch (error) {
-    logger6.error("[KNOWLEDGE HANDLER] Error processing knowledge:", error);
-    if (hasUploadedFiles && req.files) {
-      const allFiles = Object.values(req.files).flat();
-      cleanupFiles(allFiles);
+    logger7.error("[Document Processor] \u274C Error processing knowledge:", error);
+    if (hasUploadedFiles) {
+      cleanupFiles(req.files);
     }
     sendError(res, 500, "PROCESSING_ERROR", "Failed to process knowledge", error.message);
   }
@@ -3524,7 +3705,7 @@ async function getKnowledgeDocumentsHandler(req, res, runtime) {
     );
   }
   try {
-    const limit = req.query.limit ? Number.parseInt(req.query.limit, 10) : 20;
+    const limit = req.query.limit ? Number.parseInt(req.query.limit, 10) : 1e4;
     const before = req.query.before ? Number.parseInt(req.query.before, 10) : Date.now();
     const includeEmbedding = req.query.includeEmbedding === "true";
     const agentId = req.query.agentId;
@@ -3545,8 +3726,8 @@ 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))
       );
-      logger6.debug(
-        `[KNOWLEDGE GET HANDLER] Filtered documents by URLs: ${fileUrls.length} URLs, found ${filteredMemories.length} matching documents`
+      logger7.debug(
+        `[Document Processor] \u{1F50D} Filtered documents by URLs: ${fileUrls.length} URLs, found ${filteredMemories.length} matching documents`
       );
     }
     const cleanMemories = includeEmbedding ? filteredMemories : filteredMemories.map((memory) => ({
@@ -3560,15 +3741,12 @@ async function getKnowledgeDocumentsHandler(req, res, runtime) {
       totalRequested: fileUrls ? fileUrls.length : 0
     });
   } catch (error) {
-    logger6.error("[KNOWLEDGE GET HANDLER] Error retrieving documents:", error);
+    logger7.error("[Document Processor] \u274C Error retrieving documents:", error);
     sendError(res, 500, "RETRIEVAL_ERROR", "Failed to retrieve documents", error.message);
   }
 }
 async function deleteKnowledgeDocumentHandler(req, res, runtime) {
-  logger6.debug(`[KNOWLEDGE DELETE HANDLER] Received DELETE request:
-    - path: ${req.path}
-    - params: ${JSON.stringify(req.params)}
-  `);
+  logger7.debug(`[Document Processor] \u{1F5D1}\uFE0F DELETE request for document: ${req.params.knowledgeId}`);
   const service = runtime.getService(KnowledgeService.serviceType);
   if (!service) {
     return sendError(
@@ -3580,29 +3758,22 @@ async function deleteKnowledgeDocumentHandler(req, res, runtime) {
   }
   const knowledgeId = req.params.knowledgeId;
   if (!knowledgeId || knowledgeId.length < 36) {
-    logger6.error(`[KNOWLEDGE DELETE HANDLER] Invalid knowledge ID format: ${knowledgeId}`);
+    logger7.error(`[Document Processor] \u274C Invalid knowledge ID format: ${knowledgeId}`);
     return sendError(res, 400, "INVALID_ID", "Invalid Knowledge ID format");
   }
   try {
     const typedKnowledgeId = knowledgeId;
-    logger6.debug(
-      `[KNOWLEDGE DELETE HANDLER] Attempting to delete document with ID: ${typedKnowledgeId}`
-    );
+    logger7.debug(`[Document Processor] \u{1F5D1}\uFE0F Deleting document: ${typedKnowledgeId}`);
     await service.deleteMemory(typedKnowledgeId);
-    logger6.info(
-      `[KNOWLEDGE DELETE HANDLER] Successfully deleted document with ID: ${typedKnowledgeId}`
-    );
+    logger7.info(`[Document Processor] \u2705 Successfully deleted document: ${typedKnowledgeId}`);
     sendSuccess(res, null, 204);
   } catch (error) {
-    logger6.error(`[KNOWLEDGE DELETE HANDLER] Error deleting document ${knowledgeId}:`, error);
+    logger7.error(`[Document Processor] \u274C Error deleting document ${knowledgeId}:`, error);
     sendError(res, 500, "DELETE_ERROR", "Failed to delete document", error.message);
   }
 }
 async function getKnowledgeByIdHandler(req, res, runtime) {
-  logger6.debug(`[KNOWLEDGE GET BY ID HANDLER] Received GET request:
-    - path: ${req.path}
-    - params: ${JSON.stringify(req.params)}
-  `);
+  logger7.debug(`[Document Processor] \u{1F50D} GET request for document: ${req.params.knowledgeId}`);
   const service = runtime.getService(KnowledgeService.serviceType);
   if (!service) {
     return sendError(
@@ -3614,15 +3785,15 @@ async function getKnowledgeByIdHandler(req, res, runtime) {
   }
   const knowledgeId = req.params.knowledgeId;
   if (!knowledgeId || knowledgeId.length < 36) {
-    logger6.error(`[KNOWLEDGE GET BY ID HANDLER] Invalid knowledge ID format: ${knowledgeId}`);
+    logger7.error(`[Document Processor] \u274C Invalid knowledge ID format: ${knowledgeId}`);
     return sendError(res, 400, "INVALID_ID", "Invalid Knowledge ID format");
   }
   try {
-    logger6.debug(`[KNOWLEDGE GET BY ID HANDLER] Retrieving document with ID: ${knowledgeId}`);
+    logger7.debug(`[Document Processor] \u{1F50D} Retrieving document: ${knowledgeId}`);
     const agentId = req.query.agentId;
     const memories = await service.getMemories({
       tableName: "documents",
-      count: 1e3
+      count: 1e4
     });
     const typedKnowledgeId = knowledgeId;
     const document = memories.find((memory) => memory.id === typedKnowledgeId);
@@ -3635,17 +3806,17 @@ async function getKnowledgeByIdHandler(req, res, runtime) {
     };
     sendSuccess(res, { document: cleanDocument });
   } catch (error) {
-    logger6.error(`[KNOWLEDGE GET BY ID HANDLER] Error retrieving document ${knowledgeId}:`, error);
+    logger7.error(`[Document Processor] \u274C 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;
-  logger6.debug(`[KNOWLEDGE PANEL] Serving panel for agent ${agentId}, request path: ${req.path}`);
+  logger7.debug(`[Document Processor] \u{1F310} Serving knowledge panel for agent ${agentId}`);
   try {
     const currentDir = path3.dirname(new URL(import.meta.url).pathname);
     const frontendPath = path3.join(currentDir, "../dist/index.html");
-    logger6.debug(`[KNOWLEDGE PANEL] Looking for frontend at: ${frontendPath}`);
+    logger7.debug(`[Document Processor] \u{1F310} Looking for frontend at: ${frontendPath}`);
     if (fs3.existsSync(frontendPath)) {
       const html = await fs3.promises.readFile(frontendPath, "utf8");
       const injectedHtml = html.replace(
@@ -3679,10 +3850,10 @@ async function knowledgePanelHandler(req, res, runtime) {
             }
           }
         } catch (manifestError) {
-          logger6.error("[KNOWLEDGE PANEL] Error reading manifest:", manifestError);
+          logger7.error("[Document Processor] \u274C Error reading manifest:", manifestError);
         }
       }
-      logger6.debug(`[KNOWLEDGE PANEL] Using fallback with CSS: ${cssFile}, JS: ${jsFile}`);
+      logger7.debug(`[Document Processor] \u{1F310} Using fallback with CSS: ${cssFile}, JS: ${jsFile}`);
       const html = `
 <!DOCTYPE html>
 <html lang="en">
@@ -3716,15 +3887,13 @@ async function knowledgePanelHandler(req, res, runtime) {
       res.end(html);
     }
   } catch (error) {
-    logger6.error("[KNOWLEDGE PANEL] Error serving frontend:", error);
+    logger7.error("[Document Processor] \u274C Error serving frontend:", error);
     sendError(res, 500, "FRONTEND_ERROR", "Failed to load knowledge panel", error.message);
   }
 }
 async function frontendAssetHandler(req, res, runtime) {
   try {
-    logger6.debug(
-      `[KNOWLEDGE ASSET HANDLER] Called with req.path: ${req.path}, req.originalUrl: ${req.originalUrl}, req.params: ${JSON.stringify(req.params)}`
-    );
+    logger7.debug(`[Document Processor] \u{1F310} Asset request: ${req.path}`);
     const currentDir = path3.dirname(new URL(import.meta.url).pathname);
     const assetRequestPath = req.path;
     const assetsMarker = "/assets/";
@@ -3742,7 +3911,7 @@ async function frontendAssetHandler(req, res, runtime) {
       );
     }
     const assetPath = path3.join(currentDir, "../dist/assets", assetName);
-    logger6.debug(`[KNOWLEDGE ASSET HANDLER] Attempting to serve asset: ${assetPath}`);
+    logger7.debug(`[Document Processor] \u{1F310} Serving asset: ${assetPath}`);
     if (fs3.existsSync(assetPath)) {
       const fileStream = fs3.createReadStream(assetPath);
       let contentType = "application/octet-stream";
@@ -3757,7 +3926,7 @@ async function frontendAssetHandler(req, res, runtime) {
       sendError(res, 404, "NOT_FOUND", `Asset not found: ${req.url}`);
     }
   } catch (error) {
-    logger6.error(`[KNOWLEDGE ASSET HANDLER] Error serving asset ${req.url}:`, error);
+    logger7.error(`[Document Processor] \u274C Error serving asset ${req.url}:`, error);
     sendError(res, 500, "ASSET_ERROR", `Failed to load asset ${req.url}`, error.message);
   }
 }
@@ -3771,8 +3940,8 @@ async function getKnowledgeChunksHandler(req, res, runtime) {
     const documentsOnly = req.query.documentsOnly === "true";
     const documents = await service.getMemories({
       tableName: "documents",
-      count: 1e3,
-      // Reasonable limit for documents
+      count: 1e4,
+      // High limit to get all documents
       end: Date.now()
     });
     if (documentsOnly) {
@@ -3818,7 +3987,7 @@ async function getKnowledgeChunksHandler(req, res, runtime) {
       }
     });
   } catch (error) {
-    logger6.error("[KNOWLEDGE CHUNKS GET HANDLER] Error retrieving chunks:", error);
+    logger7.error("[Document Processor] \u274C Error retrieving chunks:", error);
     sendError(res, 500, "RETRIEVAL_ERROR", "Failed to retrieve knowledge chunks", error.message);
   }
 }
@@ -3840,15 +4009,15 @@ 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)) {
-      logger6.debug(
-        `[KNOWLEDGE SEARCH] Threshold value ${parsedThreshold} was clamped to ${matchThreshold}`
+      logger7.debug(
+        `[Document Processor] \u{1F50D} Threshold value ${parsedThreshold} was clamped to ${matchThreshold}`
       );
     }
     if (req.query.limit && (parsedLimit < 1 || parsedLimit > 100)) {
-      logger6.debug(`[KNOWLEDGE SEARCH] Limit value ${parsedLimit} was clamped to ${limit}`);
+      logger7.debug(`[Document Processor] \u{1F50D} Limit value ${parsedLimit} was clamped to ${limit}`);
     }
-    logger6.debug(
-      `[KNOWLEDGE SEARCH] Searching for: "${searchText}" with threshold: ${matchThreshold}, limit: ${limit}`
+    logger7.debug(
+      `[Document Processor] \u{1F50D} Searching: "${searchText}" (threshold: ${matchThreshold}, limit: ${limit})`
     );
     const embedding = await runtime.useModel(ModelType4.TEXT_EMBEDDING, {
       text: searchText
@@ -3874,7 +4043,7 @@ async function searchKnowledgeHandler(req, res, runtime) {
               documentFilename = document.metadata.filename || documentFilename;
             }
           } catch (e) {
-            logger6.debug(`Could not fetch document ${documentId} for fragment`);
+            logger7.debug(`Could not fetch document ${documentId} for fragment`);
           }
         }
         return {
@@ -3889,8 +4058,8 @@ async function searchKnowledgeHandler(req, res, runtime) {
         };
       })
     );
-    logger6.info(
-      `[KNOWLEDGE SEARCH] Found ${enhancedResults.length} results for query: "${searchText}"`
+    logger7.info(
+      `[Document Processor] \u{1F50D} Found ${enhancedResults.length} results for: "${searchText}"`
     );
     sendSuccess(res, {
       query: searchText,
@@ -3899,29 +4068,23 @@ async function searchKnowledgeHandler(req, res, runtime) {
       count: enhancedResults.length
     });
   } catch (error) {
-    logger6.error("[KNOWLEDGE SEARCH] Error searching knowledge:", error);
+    logger7.error("[Document Processor] \u274C Error searching knowledge:", error);
     sendError(res, 500, "SEARCH_ERROR", "Failed to search knowledge", error.message);
   }
 }
-async function handleKnowledgeUpload(req, res, runtime) {
-  logger6.debug("[KNOWLEDGE UPLOAD] Starting upload handler");
-  logger6.debug("[KNOWLEDGE UPLOAD] Request details:", {
-    method: req.method,
-    url: req.url,
-    contentType: req.headers["content-type"],
-    contentLength: req.headers["content-length"],
-    hasFiles: req.files ? Object.keys(req.files).length : 0,
-    hasBody: req.body ? Object.keys(req.body).length : 0
-  });
-  try {
-    logger6.debug("[KNOWLEDGE UPLOAD] Using files parsed by global middleware");
-    await uploadKnowledgeHandler(req, res, runtime);
-  } catch (handlerError) {
-    logger6.error("[KNOWLEDGE UPLOAD] Handler error:", handlerError);
-    if (!res.headersSent) {
-      sendError(res, 500, "HANDLER_ERROR", "Failed to process upload");
+async function uploadKnowledgeWithMulter(req, res, runtime) {
+  const upload = createUploadMiddleware(runtime);
+  const uploadArray = upload.array(
+    "files",
+    parseInt(runtime.getSetting("KNOWLEDGE_MAX_FILES") || "10")
+  );
+  uploadArray(req, res, (err) => {
+    if (err) {
+      logger7.error("[Document Processor] \u274C File upload error:", err);
+      return sendError(res, 400, "UPLOAD_ERROR", err.message);
     }
-  }
+    uploadKnowledgeHandler(req, res, runtime);
+  });
 }
 var knowledgeRoutes = [
   {
@@ -3939,7 +4102,7 @@ var knowledgeRoutes = [
   {
     type: "POST",
     path: "/documents",
-    handler: handleKnowledgeUpload
+    handler: uploadKnowledgeWithMulter
   },
   {
     type: "GET",
@@ -3980,59 +4143,86 @@ var knowledgePlugin = {
     CTX_KNOWLEDGE_ENABLED: "false"
   },
   async init(config, runtime) {
-    logger7.info("Initializing Knowledge Plugin...");
+    logger8.info("Initializing Knowledge Plugin...");
     try {
-      logger7.info("Validating model configuration for Knowledge plugin...");
+      logger8.info("Validating model configuration for Knowledge plugin...");
+      logger8.info(`[Knowledge Plugin] INIT DEBUG:`);
+      logger8.info(`[Knowledge Plugin] - Runtime available: ${!!runtime}`);
+      logger8.info(
+        `[Knowledge Plugin] - process.env.CTX_KNOWLEDGE_ENABLED: '${process.env.CTX_KNOWLEDGE_ENABLED}'`
+      );
+      logger8.info(
+        `[Knowledge Plugin] - config.CTX_KNOWLEDGE_ENABLED: '${config.CTX_KNOWLEDGE_ENABLED}'`
+      );
+      if (runtime) {
+        logger8.info(
+          `[Knowledge Plugin] - runtime.getSetting('CTX_KNOWLEDGE_ENABLED'): '${runtime.getSetting("CTX_KNOWLEDGE_ENABLED")}'`
+        );
+      }
       const validatedConfig = validateModelConfig(runtime);
-      if (validatedConfig.CTX_KNOWLEDGE_ENABLED) {
-        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.`
+      const ctxEnabledFromEnv = process.env.CTX_KNOWLEDGE_ENABLED === "true" || process.env.CTX_KNOWLEDGE_ENABLED === "True";
+      const ctxEnabledFromConfig = config.CTX_KNOWLEDGE_ENABLED === "true" || config.CTX_KNOWLEDGE_ENABLED === "True";
+      const ctxEnabledFromValidated = validatedConfig.CTX_KNOWLEDGE_ENABLED;
+      const ctxEnabledFromRuntime = runtime ? runtime.getSetting("CTX_KNOWLEDGE_ENABLED") === "true" || runtime.getSetting("CTX_KNOWLEDGE_ENABLED") === "True" : false;
+      const finalCtxEnabled = ctxEnabledFromEnv || ctxEnabledFromConfig || ctxEnabledFromValidated || ctxEnabledFromRuntime;
+      logger8.info(`[Knowledge Plugin] CTX_KNOWLEDGE_ENABLED sources:`);
+      logger8.info(`[Knowledge Plugin] - From env: ${ctxEnabledFromEnv}`);
+      logger8.info(`[Knowledge Plugin] - From config: ${ctxEnabledFromConfig}`);
+      logger8.info(`[Knowledge Plugin] - From validated: ${ctxEnabledFromValidated}`);
+      logger8.info(`[Knowledge Plugin] - From runtime: ${ctxEnabledFromRuntime}`);
+      logger8.info(`[Knowledge Plugin] - FINAL RESULT: ${finalCtxEnabled}`);
+      if (finalCtxEnabled) {
+        logger8.info("Running in Contextual Knowledge mode with text generation capabilities.");
+        logger8.info(
+          `Using ${validatedConfig.EMBEDDING_PROVIDER || "auto-detected"} for embeddings and ${validatedConfig.TEXT_PROVIDER || process.env.TEXT_PROVIDER} for text generation.`
         );
+        logger8.info(`Text model: ${validatedConfig.TEXT_MODEL || process.env.TEXT_MODEL}`);
       } else {
         const usingPluginOpenAI = !process.env.EMBEDDING_PROVIDER;
+        logger8.warn(
+          "Running in Basic Embedding mode - documents will NOT be enriched with context!"
+        );
+        logger8.info("To enable contextual enrichment:");
+        logger8.info("   - Set CTX_KNOWLEDGE_ENABLED=true");
+        logger8.info("   - Configure TEXT_PROVIDER (anthropic/openai/openrouter/google)");
+        logger8.info("   - Configure TEXT_MODEL and API key");
         if (usingPluginOpenAI) {
-          logger7.info(
-            "Running in Basic Embedding mode with auto-detected configuration from plugin-openai."
-          );
+          logger8.info("Using auto-detected configuration from plugin-openai for embeddings.");
         } else {
-          logger7.info(
-            "Running in Basic Embedding mode (CTX_KNOWLEDGE_ENABLED=false). TEXT_PROVIDER and TEXT_MODEL not required."
+          logger8.info(
+            `Using ${validatedConfig.EMBEDDING_PROVIDER} for embeddings with ${validatedConfig.TEXT_EMBEDDING_MODEL}.`
           );
         }
-        logger7.info(
-          `Using ${validatedConfig.EMBEDDING_PROVIDER} for embeddings with ${validatedConfig.TEXT_EMBEDDING_MODEL}.`
-        );
       }
-      logger7.info("Model configuration validated successfully.");
+      logger8.info("Model configuration validated successfully.");
       if (runtime) {
-        logger7.info(`Knowledge Plugin initialized for agent: ${runtime.agentId}`);
+        logger8.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...");
+          logger8.info("LOAD_DOCS_ON_STARTUP is enabled. Scheduling document loading...");
           setTimeout(async () => {
             try {
               const service = runtime.getService(KnowledgeService.serviceType);
               if (service instanceof KnowledgeService) {
-                const { loadDocsFromPath: loadDocsFromPath2 } = await import("./docs-loader-5INCF4VJ.js");
+                const { loadDocsFromPath: loadDocsFromPath2 } = await import("./docs-loader-5H4HRYEE.js");
                 const result = await loadDocsFromPath2(service, runtime.agentId);
                 if (result.successful > 0) {
-                  logger7.info(`Loaded ${result.successful} documents from docs folder on startup`);
+                  logger8.info(`Loaded ${result.successful} documents from docs folder on startup`);
                 }
               }
             } catch (error) {
-              logger7.error("Error loading documents on startup:", error);
+              logger8.error("Error loading documents on startup:", error);
             }
           }, 5e3);
         } else {
-          logger7.info("LOAD_DOCS_ON_STARTUP is not enabled. Skipping automatic document loading.");
+          logger8.info("LOAD_DOCS_ON_STARTUP is not enabled. Skipping automatic document loading.");
         }
       }
-      logger7.info(
+      logger8.info(
         "Knowledge Plugin initialized. Frontend panel should be discoverable via its public route."
       );
     } catch (error) {
-      logger7.error("Failed to initialize Knowledge plugin:", error);
+      logger8.error("Failed to initialize Knowledge plugin:", error);
       throw error;
     }
   },