@elizaos/plugin-knowledge 1.0.10 → 1.2.0

package/dist/index.js

@@ -1,17 +1,147 @@
+// src/service.ts
 import {
-  convertPdfToTextFromBuffer,
-  extractTextFromFileBuffer,
-  fetchUrlContent,
-  generateContentBasedId,
-  isBinaryContentType,
-  loadDocsFromPath,
-  looksLikeBase64,
-  normalizeS3Url,
-  v4_default
-} from "./chunk-UOE4LEMH.js";
+  createUniqueUuid,
+  logger as logger6,
+  MemoryType as MemoryType2,
+  ModelType as ModelType2,
+  Semaphore,
+  Service,
+  splitChunks as splitChunks2
+} from "@elizaos/core";
 
-// src/index.ts
-import { logger as logger7 } from "@elizaos/core";
+// src/document-processor.ts
+import {
+  MemoryType,
+  ModelType,
+  logger as logger4,
+  splitChunks
+} from "@elizaos/core";
+
+// node_modules/uuid/dist/esm/regex.js
+var regex_default = /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/i;
+
+// node_modules/uuid/dist/esm/validate.js
+function validate(uuid) {
+  return typeof uuid === "string" && regex_default.test(uuid);
+}
+var validate_default = validate;
+
+// node_modules/uuid/dist/esm/parse.js
+function parse(uuid) {
+  if (!validate_default(uuid)) {
+    throw TypeError("Invalid UUID");
+  }
+  let v;
+  return Uint8Array.of((v = parseInt(uuid.slice(0, 8), 16)) >>> 24, v >>> 16 & 255, v >>> 8 & 255, v & 255, (v = parseInt(uuid.slice(9, 13), 16)) >>> 8, v & 255, (v = parseInt(uuid.slice(14, 18), 16)) >>> 8, v & 255, (v = parseInt(uuid.slice(19, 23), 16)) >>> 8, v & 255, (v = parseInt(uuid.slice(24, 36), 16)) / 1099511627776 & 255, v / 4294967296 & 255, v >>> 24 & 255, v >>> 16 & 255, v >>> 8 & 255, v & 255);
+}
+var parse_default = parse;
+
+// node_modules/uuid/dist/esm/stringify.js
+var byteToHex = [];
+for (let i = 0; i < 256; ++i) {
+  byteToHex.push((i + 256).toString(16).slice(1));
+}
+function unsafeStringify(arr, offset = 0) {
+  return (byteToHex[arr[offset + 0]] + byteToHex[arr[offset + 1]] + byteToHex[arr[offset + 2]] + byteToHex[arr[offset + 3]] + "-" + byteToHex[arr[offset + 4]] + byteToHex[arr[offset + 5]] + "-" + byteToHex[arr[offset + 6]] + byteToHex[arr[offset + 7]] + "-" + byteToHex[arr[offset + 8]] + byteToHex[arr[offset + 9]] + "-" + byteToHex[arr[offset + 10]] + byteToHex[arr[offset + 11]] + byteToHex[arr[offset + 12]] + byteToHex[arr[offset + 13]] + byteToHex[arr[offset + 14]] + byteToHex[arr[offset + 15]]).toLowerCase();
+}
+
+// node_modules/uuid/dist/esm/rng.js
+import { randomFillSync } from "crypto";
+var rnds8Pool = new Uint8Array(256);
+var poolPtr = rnds8Pool.length;
+function rng() {
+  if (poolPtr > rnds8Pool.length - 16) {
+    randomFillSync(rnds8Pool);
+    poolPtr = 0;
+  }
+  return rnds8Pool.slice(poolPtr, poolPtr += 16);
+}
+
+// node_modules/uuid/dist/esm/v35.js
+function stringToBytes(str) {
+  str = unescape(encodeURIComponent(str));
+  const bytes = new Uint8Array(str.length);
+  for (let i = 0; i < str.length; ++i) {
+    bytes[i] = str.charCodeAt(i);
+  }
+  return bytes;
+}
+var DNS = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
+var URL2 = "6ba7b811-9dad-11d1-80b4-00c04fd430c8";
+function v35(version, hash, value, namespace, buf, offset) {
+  const valueBytes = typeof value === "string" ? stringToBytes(value) : value;
+  const namespaceBytes = typeof namespace === "string" ? parse_default(namespace) : namespace;
+  if (typeof namespace === "string") {
+    namespace = parse_default(namespace);
+  }
+  if (namespace?.length !== 16) {
+    throw TypeError("Namespace must be array-like (16 iterable integer values, 0-255)");
+  }
+  let bytes = new Uint8Array(16 + valueBytes.length);
+  bytes.set(namespaceBytes);
+  bytes.set(valueBytes, namespaceBytes.length);
+  bytes = hash(bytes);
+  bytes[6] = bytes[6] & 15 | version;
+  bytes[8] = bytes[8] & 63 | 128;
+  if (buf) {
+    offset = offset || 0;
+    for (let i = 0; i < 16; ++i) {
+      buf[offset + i] = bytes[i];
+    }
+    return buf;
+  }
+  return unsafeStringify(bytes);
+}
+
+// node_modules/uuid/dist/esm/native.js
+import { randomUUID } from "crypto";
+var native_default = { randomUUID };
+
+// node_modules/uuid/dist/esm/v4.js
+function v4(options, buf, offset) {
+  if (native_default.randomUUID && !buf && !options) {
+    return native_default.randomUUID();
+  }
+  options = options || {};
+  const rnds = options.random ?? options.rng?.() ?? rng();
+  if (rnds.length < 16) {
+    throw new Error("Random bytes length must be >= 16");
+  }
+  rnds[6] = rnds[6] & 15 | 64;
+  rnds[8] = rnds[8] & 63 | 128;
+  if (buf) {
+    offset = offset || 0;
+    if (offset < 0 || offset + 16 > buf.length) {
+      throw new RangeError(`UUID byte range ${offset}:${offset + 15} is out of buffer bounds`);
+    }
+    for (let i = 0; i < 16; ++i) {
+      buf[offset + i] = rnds[i];
+    }
+    return buf;
+  }
+  return unsafeStringify(rnds);
+}
+var v4_default = v4;
+
+// node_modules/uuid/dist/esm/sha1.js
+import { createHash } from "crypto";
+function sha1(bytes) {
+  if (Array.isArray(bytes)) {
+    bytes = Buffer.from(bytes);
+  } else if (typeof bytes === "string") {
+    bytes = Buffer.from(bytes, "utf8");
+  }
+  return createHash("sha1").update(bytes).digest();
+}
+var sha1_default = sha1;
+
+// node_modules/uuid/dist/esm/v5.js
+function v5(value, namespace, buf, offset) {
+  return v35(80, sha1_default, value, namespace, buf, offset);
+}
+v5.DNS = DNS;
+v5.URL = URL2;
+var v5_default = v5;
 
 // src/types.ts
 import z from "zod";
@@ -42,6 +172,8 @@ var ModelConfigSchema = z.object({
   // For OpenAI: Only applies to text-embedding-3-small and text-embedding-3-large models
   // Default: 1536 dimensions
   EMBEDDING_DIMENSION: z.string().or(z.number()).optional().transform((val) => val ? typeof val === "string" ? parseInt(val, 10) : val : 1536),
+  // config setting
+  LOAD_DOCS_ON_STARTUP: z.boolean().default(false),
   // Contextual Knowledge settings
   CTX_KNOWLEDGE_ENABLED: z.boolean().default(false)
 });
@@ -52,26 +184,35 @@ var KnowledgeServiceType = {
 // src/config.ts
 import z2 from "zod";
 import { logger } from "@elizaos/core";
+var parseBooleanEnv = (value) => {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value.toLowerCase() === "true";
+  return false;
+};
 function validateModelConfig(runtime) {
   try {
     const getSetting = (key, defaultValue) => {
       if (runtime) {
-        return runtime.getSetting(key) || defaultValue;
+        return runtime.getSetting(key) || process.env[key] || defaultValue;
       }
       return process.env[key] || defaultValue;
     };
-    const ctxKnowledgeEnabled2 = getSetting("CTX_KNOWLEDGE_ENABLED") === "true";
-    logger.debug(`Configuration: CTX_KNOWLEDGE_ENABLED=${ctxKnowledgeEnabled2}`);
+    const ctxKnowledgeEnabled = parseBooleanEnv(getSetting("CTX_KNOWLEDGE_ENABLED", "false"));
+    logger.debug(
+      `[Document Processor] CTX_KNOWLEDGE_ENABLED: '${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 +236,8 @@ 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
+      LOAD_DOCS_ON_STARTUP: parseBooleanEnv(getSetting("LOAD_DOCS_ON_STARTUP")),
+      CTX_KNOWLEDGE_ENABLED: ctxKnowledgeEnabled
     });
     validateConfigRequirements(config, assumePluginOpenAI);
     return config;
@@ -116,13 +258,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 +283,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 +312,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,30 +343,11 @@ async function getProviderRateLimits(runtime) {
         maxConcurrentRequests,
         requestsPerMinute,
         tokensPerMinute,
-        provider: config.EMBEDDING_PROVIDER
+        provider: primaryProvider || "unknown"
       };
   }
 }
 
-// src/service.ts
-import {
-  createUniqueUuid,
-  logger as logger4,
-  MemoryType as MemoryType2,
-  ModelType as ModelType2,
-  Semaphore,
-  Service,
-  splitChunks as splitChunks2
-} from "@elizaos/core";
-
-// src/document-processor.ts
-import {
-  MemoryType,
-  ModelType,
-  logger as logger3,
-  splitChunks
-} from "@elizaos/core";
-
 // src/ctx-embeddings.ts
 var DEFAULT_CHUNK_TOKEN_SIZE = 500;
 var DEFAULT_CHUNK_OVERLAP_TOKENS = 100;
@@ -405,9 +545,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 +616,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 +637,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 +701,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 +750,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();
@@ -641,8 +763,8 @@ 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();
+async function generateText(runtime, prompt, system, overrideConfig) {
+  const config = validateModelConfig(runtime);
   const provider = overrideConfig?.provider || config.TEXT_PROVIDER;
   const modelName = overrideConfig?.modelName || config.TEXT_MODEL;
   const maxTokens = overrideConfig?.maxTokens || config.MAX_OUTPUT_TOKENS;
@@ -650,11 +772,12 @@ async function generateText(prompt, system, overrideConfig) {
   try {
     switch (provider) {
       case "anthropic":
-        return await generateAnthropicText(prompt, system, modelName, maxTokens);
+        return await generateAnthropicText(config, prompt, system, modelName, maxTokens);
       case "openai":
-        return await generateOpenAIText(prompt, system, modelName, maxTokens);
+        return await generateOpenAIText(config, prompt, system, modelName, maxTokens);
       case "openrouter":
         return await generateOpenRouterText(
+          config,
           prompt,
           system,
           modelName,
@@ -669,31 +792,47 @@ 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;
   }
 }
-async function generateAnthropicText(prompt, system, modelName, maxTokens) {
-  const config = validateModelConfig();
+async function generateAnthropicText(config, prompt, system, modelName, maxTokens) {
   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;
+  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((resolve2) => setTimeout(resolve2, delay));
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw new Error("Max retries exceeded for Anthropic text generation");
 }
-async function generateOpenAIText(prompt, system, modelName, maxTokens) {
-  const config = validateModelConfig();
+async function generateOpenAIText(config, prompt, system, modelName, maxTokens) {
   const openai = createOpenAI({
     apiKey: config.OPENAI_API_KEY,
     baseURL: config.OPENAI_BASE_URL
@@ -706,8 +845,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,13 +864,13 @@ 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;
 }
-async function generateOpenRouterText(prompt, system, modelName, maxTokens, cacheDocument, cacheOptions, autoCacheContextualRetrieval = true) {
-  const config = validateModelConfig();
+async function generateOpenRouterText(config, prompt, system, modelName, maxTokens, cacheDocument, cacheOptions, autoCacheContextualRetrieval = true) {
   const openrouter = createOpenRouter({
     apiKey: config.OPENROUTER_API_KEY,
     baseURL: config.OPENROUTER_BASE_URL
@@ -746,7 +886,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 +917,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 +973,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 +988,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 +1000,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 +1040,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 +1063,397 @@ 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/utils.ts
+import { Buffer as Buffer2 } from "buffer";
+import * as mammoth from "mammoth";
+import { logger as logger3 } from "@elizaos/core";
+import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
+import { createHash as createHash2 } from "crypto";
+var PLAIN_TEXT_CONTENT_TYPES = [
+  "application/typescript",
+  "text/typescript",
+  "text/x-python",
+  "application/x-python-code",
+  "application/yaml",
+  "text/yaml",
+  "application/x-yaml",
+  "application/json",
+  "text/markdown",
+  "text/csv"
+];
+var MAX_FALLBACK_SIZE_BYTES = 5 * 1024 * 1024;
+var BINARY_CHECK_BYTES = 1024;
+async function extractTextFromFileBuffer(fileBuffer, contentType, originalFilename) {
+  const lowerContentType = contentType.toLowerCase();
+  logger3.debug(
+    `[TextUtil] Attempting to extract text from ${originalFilename} (type: ${contentType})`
+  );
+  if (lowerContentType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document") {
+    logger3.debug(`[TextUtil] Extracting text from DOCX ${originalFilename} via mammoth.`);
+    try {
+      const result = await mammoth.extractRawText({ buffer: fileBuffer });
+      logger3.debug(
+        `[TextUtil] DOCX text extraction complete for ${originalFilename}. Text length: ${result.value.length}`
+      );
+      return result.value;
+    } catch (docxError) {
+      const errorMsg = `[TextUtil] Failed to parse DOCX file ${originalFilename}: ${docxError.message}`;
+      logger3.error(errorMsg, docxError.stack);
+      throw new Error(errorMsg);
+    }
+  } else if (lowerContentType === "application/msword" || originalFilename.toLowerCase().endsWith(".doc")) {
+    logger3.debug(`[TextUtil] Handling Microsoft Word .doc file: ${originalFilename}`);
+    return `[Microsoft Word Document: ${originalFilename}]
+
+This document was indexed for search but cannot be displayed directly in the browser. The original document content is preserved for retrieval purposes.`;
+  } else if (lowerContentType.startsWith("text/") || PLAIN_TEXT_CONTENT_TYPES.includes(lowerContentType)) {
+    logger3.debug(
+      `[TextUtil] Extracting text from plain text compatible file ${originalFilename} (type: ${contentType})`
+    );
+    return fileBuffer.toString("utf-8");
+  } else {
+    logger3.warn(
+      `[TextUtil] Unsupported content type: "${contentType}" for ${originalFilename}. Attempting fallback to plain text.`
+    );
+    if (fileBuffer.length > MAX_FALLBACK_SIZE_BYTES) {
+      const sizeErrorMsg = `[TextUtil] File ${originalFilename} (type: ${contentType}) exceeds maximum size for fallback (${MAX_FALLBACK_SIZE_BYTES} bytes). Cannot process as plain text.`;
+      logger3.error(sizeErrorMsg);
+      throw new Error(sizeErrorMsg);
+    }
+    const initialBytes = fileBuffer.subarray(0, Math.min(fileBuffer.length, BINARY_CHECK_BYTES));
+    if (initialBytes.includes(0)) {
+      const binaryHeuristicMsg = `[TextUtil] File ${originalFilename} (type: ${contentType}) appears to be binary based on initial byte check. Cannot process as plain text.`;
+      logger3.error(binaryHeuristicMsg);
+      throw new Error(binaryHeuristicMsg);
+    }
+    try {
+      const textContent = fileBuffer.toString("utf-8");
+      if (textContent.includes("\uFFFD")) {
+        const binaryErrorMsg = `[TextUtil] File ${originalFilename} (type: ${contentType}) seems to be binary or has encoding issues after fallback to plain text (detected \uFFFD).`;
+        logger3.error(binaryErrorMsg);
+        throw new Error(binaryErrorMsg);
+      }
+      logger3.debug(
+        `[TextUtil] Successfully processed unknown type ${contentType} as plain text after fallback for ${originalFilename}.`
+      );
+      return textContent;
+    } catch (fallbackError) {
+      const finalErrorMsg = `[TextUtil] Unsupported content type: ${contentType} for ${originalFilename}. Fallback to plain text also failed or indicated binary content.`;
+      logger3.error(finalErrorMsg, fallbackError.message ? fallbackError.stack : void 0);
+      throw new Error(finalErrorMsg);
+    }
+  }
+}
+async function convertPdfToTextFromBuffer(pdfBuffer, filename) {
+  const docName = filename || "unnamed-document";
+  logger3.debug(`[PdfService] Starting conversion for ${docName}`);
+  try {
+    const uint8Array = new Uint8Array(pdfBuffer);
+    const pdf = await getDocument({ data: uint8Array }).promise;
+    const numPages = pdf.numPages;
+    const textPages = [];
+    for (let pageNum = 1; pageNum <= numPages; pageNum++) {
+      logger3.debug(`[PdfService] Processing page ${pageNum}/${numPages}`);
+      const page = await pdf.getPage(pageNum);
+      const textContent = await page.getTextContent();
+      const lineMap = /* @__PURE__ */ new Map();
+      textContent.items.filter(isTextItem).forEach((item) => {
+        const yPos = Math.round(item.transform[5]);
+        if (!lineMap.has(yPos)) {
+          lineMap.set(yPos, []);
+        }
+        lineMap.get(yPos).push(item);
+      });
+      const sortedLines = Array.from(lineMap.entries()).sort((a, b) => b[0] - a[0]).map(
+        ([_, items]) => items.sort((a, b) => a.transform[4] - b.transform[4]).map((item) => item.str).join(" ")
+      );
+      textPages.push(sortedLines.join("\n"));
+    }
+    const fullText = textPages.join("\n\n").replace(/\s+/g, " ").trim();
+    logger3.debug(`[PdfService] Conversion complete for ${docName}, length: ${fullText.length}`);
+    return fullText;
+  } catch (error) {
+    logger3.error(`[PdfService] Error converting PDF ${docName}:`, error.message);
+    throw new Error(`Failed to convert PDF to text: ${error.message}`);
+  }
+}
+function isBinaryContentType(contentType, filename) {
+  const textContentTypes = [
+    "text/",
+    "application/json",
+    "application/xml",
+    "application/javascript",
+    "application/typescript",
+    "application/x-yaml",
+    "application/x-sh"
+  ];
+  const isTextMimeType = textContentTypes.some((type) => contentType.includes(type));
+  if (isTextMimeType) {
+    return false;
+  }
+  const binaryContentTypes = [
+    "application/pdf",
+    "application/msword",
+    "application/vnd.openxmlformats-officedocument",
+    "application/vnd.ms-excel",
+    "application/vnd.ms-powerpoint",
+    "application/zip",
+    "application/x-zip-compressed",
+    "application/octet-stream",
+    "image/",
+    "audio/",
+    "video/"
+  ];
+  const isBinaryMimeType = binaryContentTypes.some((type) => contentType.includes(type));
+  if (isBinaryMimeType) {
+    return true;
+  }
+  const fileExt = filename.split(".").pop()?.toLowerCase() || "";
+  const textExtensions = [
+    "txt",
+    "md",
+    "markdown",
+    "json",
+    "xml",
+    "html",
+    "htm",
+    "css",
+    "js",
+    "ts",
+    "jsx",
+    "tsx",
+    "yaml",
+    "yml",
+    "toml",
+    "ini",
+    "cfg",
+    "conf",
+    "sh",
+    "bash",
+    "zsh",
+    "fish",
+    "py",
+    "rb",
+    "go",
+    "rs",
+    "java",
+    "c",
+    "cpp",
+    "h",
+    "hpp",
+    "cs",
+    "php",
+    "sql",
+    "r",
+    "swift",
+    "kt",
+    "scala",
+    "clj",
+    "ex",
+    "exs",
+    "vim",
+    "env",
+    "gitignore",
+    "dockerignore",
+    "editorconfig",
+    "log",
+    "csv",
+    "tsv",
+    "properties",
+    "gradle",
+    "sbt",
+    "makefile",
+    "dockerfile",
+    "vagrantfile",
+    "gemfile",
+    "rakefile",
+    "podfile",
+    "csproj",
+    "vbproj",
+    "fsproj",
+    "sln",
+    "pom"
+  ];
+  if (textExtensions.includes(fileExt)) {
+    return false;
+  }
+  const binaryExtensions = [
+    "pdf",
+    "docx",
+    "doc",
+    "xls",
+    "xlsx",
+    "ppt",
+    "pptx",
+    "zip",
+    "rar",
+    "7z",
+    "tar",
+    "gz",
+    "bz2",
+    "xz",
+    "jpg",
+    "jpeg",
+    "png",
+    "gif",
+    "bmp",
+    "svg",
+    "ico",
+    "webp",
+    "mp3",
+    "mp4",
+    "avi",
+    "mov",
+    "wmv",
+    "flv",
+    "wav",
+    "flac",
+    "ogg",
+    "exe",
+    "dll",
+    "so",
+    "dylib",
+    "bin",
+    "dat",
+    "db",
+    "sqlite"
+  ];
+  return binaryExtensions.includes(fileExt);
+}
+function isTextItem(item) {
+  return "str" in item;
+}
+function normalizeS3Url(url) {
+  try {
+    const urlObj = new URL(url);
+    return `${urlObj.origin}${urlObj.pathname}`;
+  } catch (error) {
+    logger3.warn(`[URL NORMALIZER] Failed to parse URL: ${url}. Returning original.`);
+    return url;
+  }
+}
+async function fetchUrlContent(url) {
+  logger3.debug(`[URL FETCHER] Fetching content from URL: ${url}`);
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3e4);
+    const response = await fetch(url, {
+      signal: controller.signal,
+      headers: {
+        "User-Agent": "Eliza-Knowledge-Plugin/1.0"
+      }
+    });
+    clearTimeout(timeoutId);
+    if (!response.ok) {
+      throw new Error(`Failed to fetch URL: ${response.status} ${response.statusText}`);
+    }
+    const contentType = response.headers.get("content-type") || "application/octet-stream";
+    logger3.debug(`[URL FETCHER] Content type from server: ${contentType} for URL: ${url}`);
+    const arrayBuffer = await response.arrayBuffer();
+    const buffer = Buffer2.from(arrayBuffer);
+    const base64Content = buffer.toString("base64");
+    logger3.debug(
+      `[URL FETCHER] Successfully fetched content from URL: ${url} (${buffer.length} bytes)`
     );
+    return {
+      content: base64Content,
+      contentType
+    };
+  } catch (error) {
+    logger3.error(`[URL FETCHER] Error fetching content from URL ${url}: ${error.message}`);
+    throw new Error(`Failed to fetch content from URL: ${error.message}`);
+  }
+}
+function looksLikeBase64(content) {
+  if (!content || content.length === 0) return false;
+  const cleanContent = content.replace(/\s/g, "");
+  if (cleanContent.length < 16) return false;
+  if (cleanContent.length % 4 !== 0) return false;
+  const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+  if (!base64Regex.test(cleanContent)) return false;
+  const hasNumbers = /\d/.test(cleanContent);
+  const hasUpperCase = /[A-Z]/.test(cleanContent);
+  const hasLowerCase = /[a-z]/.test(cleanContent);
+  return (hasNumbers || hasUpperCase) && hasLowerCase;
+}
+function generateContentBasedId(content, agentId, options) {
+  const {
+    maxChars = 2e3,
+    // Use first 2000 chars by default
+    includeFilename,
+    contentType
+  } = options || {};
+  let contentForHashing;
+  if (looksLikeBase64(content)) {
+    try {
+      const decoded = Buffer2.from(content, "base64").toString("utf8");
+      if (!decoded.includes("\uFFFD") || contentType?.includes("pdf")) {
+        contentForHashing = content.slice(0, maxChars);
+      } else {
+        contentForHashing = decoded.slice(0, maxChars);
+      }
+    } catch {
+      contentForHashing = content.slice(0, maxChars);
+    }
+  } else {
+    contentForHashing = content.slice(0, maxChars);
   }
+  contentForHashing = contentForHashing.replace(/\r\n/g, "\n").replace(/\r/g, "\n").trim();
+  const componentsToHash = [
+    agentId,
+    // Namespace by agent
+    contentForHashing,
+    // The actual content
+    includeFilename || ""
+    // Optional filename for additional uniqueness
+  ].filter(Boolean).join("::");
+  const hash = createHash2("sha256").update(componentsToHash).digest("hex");
+  const DOCUMENT_NAMESPACE = "6ba7b810-9dad-11d1-80b4-00c04fd430c8";
+  const uuid = v5_default(hash, DOCUMENT_NAMESPACE);
+  logger3.debug(
+    `[generateContentBasedId] Generated UUID ${uuid} for document with content hash ${hash.slice(0, 8)}...`
+  );
+  return uuid;
 }
 
 // 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) {
+    logger4.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 +1474,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,21 +1482,29 @@ async function processFragmentsSynchronously({
   contentType,
   roomId,
   entityId,
-  worldId
+  worldId,
+  documentTitle
 }) {
   if (!fullDocumentText || fullDocumentText.trim() === "") {
-    logger3.warn(`No text content available to chunk for document ${documentId}.`);
+    logger4.warn(`No text content available to chunk for document ${documentId}.`);
     return 0;
   }
   const chunks = await splitDocumentIntoChunks(fullDocumentText);
   if (chunks.length === 0) {
-    logger3.warn(`No chunks generated from text for ${documentId}. No fragments to save.`);
+    logger4.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);
+  logger4.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
+  );
+  logger4.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 +1516,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}`
+    logger4.warn(
+      `[Document Processor] "${docName}": ${failedCount}/${chunks.length} chunks failed processing`
     );
   }
-  logger3.info(`Finished saving ${savedCount} fragments for document ${documentId}.`);
+  logger4.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) {
@@ -1023,15 +1545,15 @@ async function extractTextFromDocument(fileBuffer, contentType, originalFilename
   }
   try {
     if (contentType === "application/pdf") {
-      logger3.debug(`Extracting text from PDF: ${originalFilename}`);
+      logger4.debug(`Extracting text from PDF: ${originalFilename}`);
       return await convertPdfToTextFromBuffer(fileBuffer, originalFilename);
     } else {
-      logger3.debug(`Extracting text from non-PDF: ${originalFilename} (Type: ${contentType})`);
+      logger4.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) {
-          logger3.warn(
+          logger4.warn(
             `Failed to decode ${originalFilename} as UTF-8, falling back to binary extraction`
           );
         }
@@ -1039,7 +1561,7 @@ async function extractTextFromDocument(fileBuffer, contentType, originalFilename
       return await extractTextFromFileBuffer(fileBuffer, contentType, originalFilename);
     }
   } catch (error) {
-    logger3.error(`Error extracting text from ${originalFilename}: ${error.message}`);
+    logger4.error(`Error extracting text from ${originalFilename}: ${error.message}`);
     throw new Error(`Failed to extract text from ${originalFilename}: ${error.message}`);
   }
 }
@@ -1084,7 +1606,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);
-  logger3.debug(
+  logger4.debug(
     `Using core splitChunks with settings: tokenChunkSize=${tokenChunkSize}, tokenChunkOverlap=${tokenChunkOverlap}, charChunkSize=${targetCharChunkSize}, charChunkOverlap=${targetCharChunkOverlap}`
   );
   return await splitChunks(documentText, tokenChunkSize, tokenChunkOverlap);
@@ -1100,7 +1622,8 @@ async function processAndSaveFragments({
   entityId,
   worldId,
   concurrencyLimit,
-  rateLimiter
+  rateLimiter,
+  documentTitle
 }) {
   let savedCount = 0;
   let failedCount = 0;
@@ -1108,15 +1631,16 @@ 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);
-    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)}`
+    logger4.debug(
+      `[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,
@@ -1128,13 +1652,13 @@ async function processAndSaveFragments({
       if (!result.success) {
         failedCount++;
         failedChunks.push(originalChunkIndex);
-        logger3.warn(`Failed to process chunk ${originalChunkIndex} for document ${documentId}`);
+        logger4.warn(`Failed to process chunk ${originalChunkIndex} for document ${documentId}`);
         continue;
       }
       const contextualizedChunkText = result.text;
       const embedding = result.embedding;
       if (!embedding || embedding.length === 0) {
-        logger3.warn(
+        logger4.warn(
           `Zero vector detected for chunk ${originalChunkIndex} (document ${documentId}). Embedding: ${JSON.stringify(result.embedding)}`
         );
         failedCount++;
@@ -1159,12 +1683,15 @@ 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);
+          logger4.info(
+            `[Document Processor] "${docName}": All ${chunks.length} chunks processed successfully`
+          );
+        }
         savedCount++;
       } catch (saveError) {
-        logger3.error(
+        logger4.error(
           `Error saving chunk ${originalChunkIndex} to database: ${saveError.message}`,
           saveError.stack
         );
@@ -1173,7 +1700,7 @@ async function processAndSaveFragments({
       }
     }
     if (i + concurrencyLimit < chunks.length) {
-      await new Promise((resolve) => setTimeout(resolve, 500));
+      await new Promise((resolve2) => setTimeout(resolve2, 500));
     }
   }
   return { savedCount, failedCount, failedChunks };
@@ -1199,7 +1726,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(
@@ -1226,7 +1754,7 @@ async function generateEmbeddingsForChunks(runtime, contextualizedChunks, rateLi
           text: contextualizedChunk.contextualizedText
         };
       } catch (error) {
-        logger3.error(
+        logger4.error(
           `Error generating embedding for chunk ${contextualizedChunk.index}: ${error.message}`
         );
         return {
@@ -1239,37 +1767,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;
+    logger4.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) {
+    logger4.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 config = validateModelConfig();
+  const rateLimiter = createRateLimiter(
+    providerLimits.requestsPerMinute || 60,
+    providerLimits.tokensPerMinute
+  );
+  const config = validateModelConfig(runtime);
   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}`
+  logger4.debug(
+    `[Document Processor] Contextualizing ${chunks.length} chunks with ${config.TEXT_PROVIDER}/${config.TEXT_MODEL} (cache: ${isUsingCacheCapableModel})`
   );
   const promptConfigs = prepareContextPrompts(
     chunks,
@@ -1287,19 +1828,20 @@ 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 () => {
           if (useCustomLLM) {
             if (item.usesCaching) {
-              return await generateText(item.promptText, item.systemPrompt, {
+              return await generateText(runtime, item.promptText, item.systemPrompt, {
                 cacheDocument: item.fullDocumentTextForContext,
                 cacheOptions: { type: "ephemeral" },
                 autoCacheContextualRetrieval: true
               });
             } else {
-              return await generateText(item.prompt);
+              return await generateText(runtime, item.prompt);
             }
           } else {
             if (item.usesCaching) {
@@ -1320,16 +1862,19 @@ 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";
+          logger4.debug(
+            `[Document Processor] "${docName}": Context added for ${item.originalIndex + 1}/${chunks.length} chunks`
+          );
+        }
         return {
           contextualizedText,
           success: true,
           index: item.originalIndex
         };
       } catch (error) {
-        logger3.error(
+        logger4.error(
           `Error generating context for chunk ${item.originalIndex}: ${error.message}`,
           error.stack
         );
@@ -1350,7 +1895,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
       if (isUsingCacheCapableModel) {
         const cachingPromptInfo = contentType ? getCachingPromptForMimeType(contentType, chunkText) : getCachingContextualizationPrompt(chunkText);
         if (cachingPromptInfo.prompt.startsWith("Error:")) {
-          logger3.warn(
+          logger4.warn(
             `Skipping contextualization for chunk ${originalIndex} due to: ${cachingPromptInfo.prompt}`
           );
           return {
@@ -1372,7 +1917,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
       } else {
         const prompt = contentType ? getPromptForMimeType(contentType, fullDocumentText, chunkText) : getContextualizationPrompt(fullDocumentText, chunkText);
         if (prompt.startsWith("Error:")) {
-          logger3.warn(`Skipping contextualization for chunk ${originalIndex} due to: ${prompt}`);
+          logger4.warn(`Skipping contextualization for chunk ${originalIndex} due to: ${prompt}`);
           return {
             prompt: null,
             originalIndex,
@@ -1390,7 +1935,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
         };
       }
     } catch (error) {
-      logger3.error(
+      logger4.error(
         `Error preparing prompt for chunk ${originalIndex}: ${error.message}`,
         error.stack
       );
@@ -1411,7 +1956,7 @@ async function generateEmbeddingWithValidation(runtime, text) {
     });
     const embedding = Array.isArray(embeddingResult) ? embeddingResult : embeddingResult?.embedding;
     if (!embedding || embedding.length === 0) {
-      logger3.warn(`Zero vector detected. Embedding result: ${JSON.stringify(embedding)}`);
+      logger4.warn(`Zero vector detected. Embedding result: ${JSON.stringify(embedding)}`);
       return {
         embedding: null,
         success: false,
@@ -1429,43 +1974,298 @@ async function withRateLimitRetry(operation, errorContext, retryDelay) {
   } catch (error) {
     if (error.status === 429) {
       const delay = retryDelay || error.headers?.["retry-after"] || 5;
-      logger3.warn(`Rate limit hit for ${errorContext}. Retrying after ${delay}s`);
-      await new Promise((resolve) => setTimeout(resolve, delay * 1e3));
+      logger4.warn(`Rate limit hit for ${errorContext}. Retrying after ${delay}s`);
+      await new Promise((resolve2) => setTimeout(resolve2, delay * 1e3));
       try {
         return await operation();
       } catch (retryError) {
-        logger3.error(`Failed after retry for ${errorContext}: ${retryError.message}`);
+        logger4.error(`Failed after retry for ${errorContext}: ${retryError.message}`);
         throw retryError;
       }
     }
     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`);
-        await new Promise((resolve) => setTimeout(resolve, timeToWait));
+        const reason = requestLimitExceeded ? "request" : "token";
+        if (timeToWait > 5e3) {
+          logger4.info(
+            `[Document Processor] Rate limiting: waiting ${Math.round(timeToWait / 1e3)}s due to ${reason} limit`
+          );
+        } else {
+          logger4.debug(
+            `[Document Processor] Rate limiting: ${timeToWait}ms wait (${reason} limit)`
+          );
+        }
+        await new Promise((resolve2) => setTimeout(resolve2, timeToWait));
+      }
+    }
+    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";
+    logger4.info(
+      `[Document Processor] ${status}: ${savedCount}/${totalChunks} chunks, CTX: ${ctxEnabled ? "ON" : "OFF"}, Provider: ${providerLimits.provider}`
+    );
+  }
+  if (failedCount > 0) {
+    logger4.warn(`[Document Processor] ${failedCount} chunks failed processing`);
+  }
+}
+
+// src/docs-loader.ts
+import { logger as logger5 } from "@elizaos/core";
+import * as fs from "fs";
+import * as path from "path";
+function getKnowledgePath() {
+  const envPath = process.env.KNOWLEDGE_PATH;
+  if (envPath) {
+    const resolvedPath = path.resolve(envPath);
+    if (!fs.existsSync(resolvedPath)) {
+      logger5.warn(`Knowledge path from environment variable does not exist: ${resolvedPath}`);
+      logger5.warn("Please create the directory or update KNOWLEDGE_PATH environment variable");
+    }
+    return resolvedPath;
+  }
+  const defaultPath = path.join(process.cwd(), "docs");
+  if (!fs.existsSync(defaultPath)) {
+    logger5.info(`Default docs folder does not exist at: ${defaultPath}`);
+    logger5.info("To use the knowledge plugin, either:");
+    logger5.info('1. Create a "docs" folder in your project root');
+    logger5.info("2. Set KNOWLEDGE_PATH environment variable to your documents folder");
+  }
+  return defaultPath;
+}
+async function loadDocsFromPath(service, agentId, worldId) {
+  const docsPath = getKnowledgePath();
+  if (!fs.existsSync(docsPath)) {
+    logger5.warn(`Knowledge path does not exist: ${docsPath}`);
+    return { total: 0, successful: 0, failed: 0 };
+  }
+  logger5.info(`Loading documents from: ${docsPath}`);
+  const files = getAllFiles(docsPath);
+  if (files.length === 0) {
+    logger5.info("No files found in knowledge path");
+    return { total: 0, successful: 0, failed: 0 };
+  }
+  logger5.info(`Found ${files.length} files to process`);
+  let successful = 0;
+  let failed = 0;
+  for (const filePath of files) {
+    try {
+      const fileName = path.basename(filePath);
+      const fileExt = path.extname(filePath).toLowerCase();
+      if (fileName.startsWith(".")) {
+        continue;
+      }
+      const contentType = getContentType(fileExt);
+      if (!contentType) {
+        logger5.debug(`Skipping unsupported file type: ${filePath}`);
+        continue;
+      }
+      const fileBuffer = fs.readFileSync(filePath);
+      const isBinary = isBinaryContentType(contentType, fileName);
+      const content = isBinary ? fileBuffer.toString("base64") : fileBuffer.toString("utf-8");
+      const knowledgeOptions = {
+        clientDocumentId: "",
+        // Will be generated by the service based on content
+        contentType,
+        originalFilename: fileName,
+        worldId: worldId || agentId,
+        content,
+        roomId: agentId,
+        entityId: agentId
+      };
+      logger5.debug(`Processing document: ${fileName}`);
+      const result = await service.addKnowledge(knowledgeOptions);
+      logger5.info(`\u2705 "${fileName}": ${result.fragmentCount} fragments created`);
+      successful++;
+    } catch (error) {
+      logger5.error(`Failed to process file ${filePath}:`, error);
+      failed++;
+    }
+  }
+  logger5.info(
+    `Document loading complete: ${successful} successful, ${failed} failed out of ${files.length} total`
+  );
+  return {
+    total: files.length,
+    successful,
+    failed
+  };
+}
+function getAllFiles(dirPath, files = []) {
+  try {
+    const entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      if (entry.isDirectory()) {
+        if (!["node_modules", ".git", ".vscode", "dist", "build"].includes(entry.name)) {
+          getAllFiles(fullPath, files);
+        }
+      } else if (entry.isFile()) {
+        files.push(fullPath);
       }
     }
-    requestTimes.push(Date.now());
+  } catch (error) {
+    logger5.error(`Error reading directory ${dirPath}:`, error);
+  }
+  return files;
+}
+function getContentType(extension) {
+  const contentTypes = {
+    // Text documents
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".markdown": "text/markdown",
+    ".tson": "text/plain",
+    ".xml": "application/xml",
+    ".csv": "text/csv",
+    ".tsv": "text/tab-separated-values",
+    ".log": "text/plain",
+    // Web files
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".css": "text/css",
+    ".scss": "text/x-scss",
+    ".sass": "text/x-sass",
+    ".less": "text/x-less",
+    // JavaScript/TypeScript
+    ".js": "text/javascript",
+    ".jsx": "text/javascript",
+    ".ts": "text/typescript",
+    ".tsx": "text/typescript",
+    ".mjs": "text/javascript",
+    ".cjs": "text/javascript",
+    ".vue": "text/x-vue",
+    ".svelte": "text/x-svelte",
+    ".astro": "text/x-astro",
+    // Python
+    ".py": "text/x-python",
+    ".pyw": "text/x-python",
+    ".pyi": "text/x-python",
+    // Java/Kotlin/Scala
+    ".java": "text/x-java",
+    ".kt": "text/x-kotlin",
+    ".kts": "text/x-kotlin",
+    ".scala": "text/x-scala",
+    // C/C++/C#
+    ".c": "text/x-c",
+    ".cpp": "text/x-c++",
+    ".cc": "text/x-c++",
+    ".cxx": "text/x-c++",
+    ".h": "text/x-c",
+    ".hpp": "text/x-c++",
+    ".cs": "text/x-csharp",
+    // Other languages
+    ".php": "text/x-php",
+    ".rb": "text/x-ruby",
+    ".go": "text/x-go",
+    ".rs": "text/x-rust",
+    ".swift": "text/x-swift",
+    ".r": "text/x-r",
+    ".R": "text/x-r",
+    ".m": "text/x-objectivec",
+    ".mm": "text/x-objectivec",
+    ".clj": "text/x-clojure",
+    ".cljs": "text/x-clojure",
+    ".ex": "text/x-elixir",
+    ".exs": "text/x-elixir",
+    ".lua": "text/x-lua",
+    ".pl": "text/x-perl",
+    ".pm": "text/x-perl",
+    ".dart": "text/x-dart",
+    ".hs": "text/x-haskell",
+    ".elm": "text/x-elm",
+    ".ml": "text/x-ocaml",
+    ".fs": "text/x-fsharp",
+    ".fsx": "text/x-fsharp",
+    ".vb": "text/x-vb",
+    ".pas": "text/x-pascal",
+    ".d": "text/x-d",
+    ".nim": "text/x-nim",
+    ".zig": "text/x-zig",
+    ".jl": "text/x-julia",
+    ".tcl": "text/x-tcl",
+    ".awk": "text/x-awk",
+    ".sed": "text/x-sed",
+    // Shell scripts
+    ".sh": "text/x-sh",
+    ".bash": "text/x-sh",
+    ".zsh": "text/x-sh",
+    ".fish": "text/x-fish",
+    ".ps1": "text/x-powershell",
+    ".bat": "text/x-batch",
+    ".cmd": "text/x-batch",
+    // Config files
+    ".json": "application/json",
+    ".yaml": "text/x-yaml",
+    ".yml": "text/x-yaml",
+    ".toml": "text/x-toml",
+    ".ini": "text/x-ini",
+    ".cfg": "text/x-ini",
+    ".conf": "text/x-ini",
+    ".env": "text/plain",
+    ".gitignore": "text/plain",
+    ".dockerignore": "text/plain",
+    ".editorconfig": "text/plain",
+    ".properties": "text/x-properties",
+    // Database
+    ".sql": "text/x-sql",
+    // Binary documents
+    ".pdf": "application/pdf",
+    ".doc": "application/msword",
+    ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
   };
+  return contentTypes[extension] || null;
 }
 
 // src/service.ts
+var parseBooleanEnv2 = (value) => {
+  if (typeof value === "boolean") return value;
+  if (typeof value === "string") return value.toLowerCase() === "true";
+  return false;
+};
 var KnowledgeService = class _KnowledgeService extends Service {
   static serviceType = "knowledge";
-  config;
-  knowledgeConfig;
+  config = {};
+  knowledgeConfig = {};
   capabilityDescription = "Provides Retrieval Augmented Generation capabilities, including knowledge upload and querying.";
   knowledgeProcessingSemaphore;
   /**
@@ -1475,53 +2275,25 @@ var KnowledgeService = class _KnowledgeService extends Service {
   constructor(runtime, config) {
     super(runtime);
     this.knowledgeProcessingSemaphore = new Semaphore(10);
-    const parseBooleanEnv = (value) => {
-      if (typeof value === "boolean") return value;
-      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: loadDocsOnStartup,
-      MAX_INPUT_TOKENS: config?.MAX_INPUT_TOKENS,
-      MAX_OUTPUT_TOKENS: config?.MAX_OUTPUT_TOKENS,
-      EMBEDDING_PROVIDER: config?.EMBEDDING_PROVIDER,
-      TEXT_PROVIDER: config?.TEXT_PROVIDER,
-      TEXT_EMBEDDING_MODEL: config?.TEXT_EMBEDDING_MODEL
-    };
-    this.config = { ...this.knowledgeConfig };
-    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) => {
-        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() {
-    logger4.info(
+    logger6.info(
       `KnowledgeService: Checking for documents to load on startup for agent ${this.runtime.agentId}`
     );
     try {
-      await new Promise((resolve) => setTimeout(resolve, 1e3));
+      await new Promise((resolve2) => setTimeout(resolve2, 1e3));
       const result = await loadDocsFromPath(this, this.runtime.agentId);
       if (result.successful > 0) {
-        logger4.info(
+        logger6.info(
           `KnowledgeService: Loaded ${result.successful} documents from docs folder on startup for agent ${this.runtime.agentId}`
         );
       } else {
-        logger4.info(
+        logger6.info(
           `KnowledgeService: No new documents found to load on startup for agent ${this.runtime.agentId}`
         );
       }
     } catch (error) {
-      logger4.error(
+      logger6.error(
         `KnowledgeService: Error loading documents on startup for agent ${this.runtime.agentId}:`,
         error
       );
@@ -1533,23 +2305,90 @@ var KnowledgeService = class _KnowledgeService extends Service {
    * @returns Initialized Knowledge service
    */
   static async start(runtime) {
-    logger4.info(`Starting Knowledge service for agent: ${runtime.agentId}`);
+    logger6.info(`Starting Knowledge service for agent: ${runtime.agentId}`);
+    logger6.info("Initializing Knowledge Plugin...");
+    let validatedConfig = {};
+    try {
+      logger6.info("Validating model configuration for Knowledge plugin...");
+      logger6.debug(`[Knowledge Plugin] INIT DEBUG:`);
+      logger6.debug(
+        `[Knowledge Plugin] - process.env.CTX_KNOWLEDGE_ENABLED: '${process.env.CTX_KNOWLEDGE_ENABLED}'`
+      );
+      const config = {
+        CTX_KNOWLEDGE_ENABLED: parseBooleanEnv2(runtime.getSetting("CTX_KNOWLEDGE_ENABLED"))
+      };
+      logger6.debug(
+        `[Knowledge Plugin] - config.CTX_KNOWLEDGE_ENABLED: '${config.CTX_KNOWLEDGE_ENABLED}'`
+      );
+      logger6.debug(
+        `[Knowledge Plugin] - runtime.getSetting('CTX_KNOWLEDGE_ENABLED'): '${runtime.getSetting("CTX_KNOWLEDGE_ENABLED")}'`
+      );
+      validatedConfig = validateModelConfig(runtime);
+      const ctxEnabledFromEnv = parseBooleanEnv2(process.env.CTX_KNOWLEDGE_ENABLED);
+      const ctxEnabledFromRuntime = parseBooleanEnv2(runtime.getSetting("CTX_KNOWLEDGE_ENABLED"));
+      const ctxEnabledFromValidated = validatedConfig.CTX_KNOWLEDGE_ENABLED;
+      const finalCtxEnabled = ctxEnabledFromValidated;
+      logger6.debug(`[Knowledge Plugin] CTX_KNOWLEDGE_ENABLED sources:`);
+      logger6.debug(`[Knowledge Plugin] - From env: ${ctxEnabledFromEnv}`);
+      logger6.debug(`[Knowledge Plugin] - From runtime: ${ctxEnabledFromRuntime}`);
+      logger6.debug(`[Knowledge Plugin] - FINAL RESULT: ${finalCtxEnabled}`);
+      if (finalCtxEnabled) {
+        logger6.info("Running in Contextual Knowledge mode with text generation capabilities.");
+        logger6.info(
+          `Using ${validatedConfig.EMBEDDING_PROVIDER || "auto-detected"} for embeddings and ${validatedConfig.TEXT_PROVIDER} for text generation.`
+        );
+        logger6.info(`Text model: ${validatedConfig.TEXT_MODEL}`);
+      } else {
+        const usingPluginOpenAI = !process.env.EMBEDDING_PROVIDER;
+        logger6.warn(
+          "Running in Basic Embedding mode - documents will NOT be enriched with context!"
+        );
+        logger6.info("To enable contextual enrichment:");
+        logger6.info("   - Set CTX_KNOWLEDGE_ENABLED=true");
+        logger6.info("   - Configure TEXT_PROVIDER (anthropic/openai/openrouter/google)");
+        logger6.info("   - Configure TEXT_MODEL and API key");
+        if (usingPluginOpenAI) {
+          logger6.info("Using auto-detected configuration from plugin-openai for embeddings.");
+        } else {
+          logger6.info(
+            `Using ${validatedConfig.EMBEDDING_PROVIDER} for embeddings with ${validatedConfig.TEXT_EMBEDDING_MODEL}.`
+          );
+        }
+      }
+      logger6.success("Model configuration validated successfully.");
+      logger6.success(`Knowledge Plugin initialized for agent: ${runtime.character.name}`);
+      logger6.info(
+        "Knowledge Plugin initialized. Frontend panel should be discoverable via its public route."
+      );
+    } catch (error) {
+      logger6.error("Failed to initialize Knowledge plugin:", error);
+      throw error;
+    }
     const service = new _KnowledgeService(runtime);
+    service.config = validatedConfig;
+    if (service.config.LOAD_DOCS_ON_STARTUP) {
+      logger6.info("LOAD_DOCS_ON_STARTUP is enabled. Loading documents from docs folder...");
+      service.loadInitialDocuments().catch((error) => {
+        logger6.error("Error during initial document loading in KnowledgeService:", error);
+      });
+    } else {
+      logger6.info("LOAD_DOCS_ON_STARTUP is disabled. Skipping automatic document loading.");
+    }
     if (service.runtime.character?.knowledge && service.runtime.character.knowledge.length > 0) {
-      logger4.info(
+      logger6.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) => {
-        logger4.error(
+        logger6.error(
           `KnowledgeService: Error processing character knowledge during startup: ${err.message}`,
           err
         );
       });
     } else {
-      logger4.info(
+      logger6.info(
         `KnowledgeService: No character knowledge to process for agent ${runtime.agentId}.`
       );
     }
@@ -1560,10 +2399,10 @@ var KnowledgeService = class _KnowledgeService extends Service {
    * @param runtime Agent runtime
    */
   static async stop(runtime) {
-    logger4.info(`Stopping Knowledge service for agent: ${runtime.agentId}`);
+    logger6.info(`Stopping Knowledge service for agent: ${runtime.agentId}`);
     const service = runtime.getService(_KnowledgeService.serviceType);
     if (!service) {
-      logger4.warn(`KnowledgeService not found for agent ${runtime.agentId} during stop.`);
+      logger6.warn(`KnowledgeService not found for agent ${runtime.agentId} during stop.`);
     }
     if (service instanceof _KnowledgeService) {
       await service.stop();
@@ -1573,7 +2412,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
    * Stop the service
    */
   async stop() {
-    logger4.info(`Knowledge service stopping for agent: ${this.runtime.agentId}`);
+    logger6.info(`Knowledge service stopping for agent: ${this.runtime.character?.name}`);
   }
   /**
    * Add knowledge to the system
@@ -1588,15 +2427,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}`
-    );
+    logger6.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.`
-        );
+        logger6.info(`"${options.originalFilename}" already exists - skipping`);
         const fragments = await this.runtime.getMemories({
           tableName: "knowledge"
         });
@@ -1610,7 +2445,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         };
       }
     } catch (error) {
-      logger4.debug(
+      logger6.debug(
         `Document ${contentBasedId} not found or error checking existence, proceeding with processing: ${error instanceof Error ? error.message : String(error)}`
       );
     }
@@ -1637,7 +2472,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
   }) {
     const agentId = passedAgentId || this.runtime.agentId;
     try {
-      logger4.debug(
+      logger6.debug(
         `KnowledgeService: Processing document ${originalFilename} (type: ${contentType}) via processDocument for agent: ${agentId}`
       );
       let fileBuffer = null;
@@ -1648,7 +2483,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         try {
           fileBuffer = Buffer.from(content, "base64");
         } catch (e) {
-          logger4.error(
+          logger6.error(
             `KnowledgeService: Failed to convert base64 to buffer for ${originalFilename}: ${e.message}`
           );
           throw new Error(`Invalid base64 content for PDF file ${originalFilename}`);
@@ -1659,7 +2494,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         try {
           fileBuffer = Buffer.from(content, "base64");
         } catch (e) {
-          logger4.error(
+          logger6.error(
             `KnowledgeService: Failed to convert base64 to buffer for ${originalFilename}: ${e.message}`
           );
           throw new Error(`Invalid base64 content for binary file ${originalFilename}`);
@@ -1676,11 +2511,11 @@ var KnowledgeService = class _KnowledgeService extends Service {
             if (invalidCharCount > 0 && invalidCharCount / textLength > 0.1) {
               throw new Error("Decoded content contains too many invalid characters");
             }
-            logger4.debug(`Successfully decoded base64 content for text file: ${originalFilename}`);
+            logger6.debug(`Successfully decoded base64 content for text file: ${originalFilename}`);
             extractedText = decodedText;
             documentContentToStore = decodedText;
           } catch (e) {
-            logger4.error(
+            logger6.error(
               `Failed to decode base64 for ${originalFilename}: ${e instanceof Error ? e.message : String(e)}`
             );
             throw new Error(
@@ -1688,7 +2523,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
             );
           }
         } else {
-          logger4.debug(`Treating content as plain text for file: ${originalFilename}`);
+          logger6.debug(`Treating content as plain text for file: ${originalFilename}`);
           extractedText = content;
           documentContentToStore = content;
         }
@@ -1697,7 +2532,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         const noTextError = new Error(
           `KnowledgeService: No text content extracted from ${originalFilename} (type: ${contentType}).`
         );
-        logger4.warn(noTextError.message);
+        logger6.warn(noTextError.message);
         throw noTextError;
       }
       const documentMemory = createDocumentMemory({
@@ -1723,14 +2558,14 @@ var KnowledgeService = class _KnowledgeService extends Service {
         roomId: roomId || agentId,
         entityId: entityId || agentId
       };
-      logger4.debug(
+      logger6.debug(
         `KnowledgeService: Creating memory with agentId=${agentId}, entityId=${entityId}, roomId=${roomId}, this.runtime.agentId=${this.runtime.agentId}`
       );
-      logger4.debug(
+      logger6.debug(
         `KnowledgeService: memoryWithScope agentId=${memoryWithScope.agentId}, entityId=${memoryWithScope.entityId}`
       );
       await this.runtime.createMemory(memoryWithScope, "documents");
-      logger4.debug(
+      logger6.debug(
         `KnowledgeService: Stored document ${originalFilename} (Memory ID: ${memoryWithScope.id})`
       );
       const fragmentCount = await processFragmentsSynchronously({
@@ -1742,18 +2577,17 @@ 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}`
-      );
+      logger6.debug(`"${originalFilename}" stored with ${fragmentCount} fragments`);
       return {
         clientDocumentId,
         storedDocumentMemoryId: memoryWithScope.id,
         fragmentCount
       };
     } catch (error) {
-      logger4.error(
+      logger6.error(
         `KnowledgeService: Error processing document ${originalFilename}: ${error.message}`,
         error.stack
       );
@@ -1762,7 +2596,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
   }
   // --- Knowledge methods moved from AgentRuntime ---
   async handleProcessingError(error, context) {
-    logger4.error(`KnowledgeService: Error ${context}:`, error?.message || error || "Unknown error");
+    logger6.error(`KnowledgeService: Error ${context}:`, error?.message || error || "Unknown error");
     throw error;
   }
   async checkExistingKnowledge(knowledgeId) {
@@ -1770,9 +2604,9 @@ var KnowledgeService = class _KnowledgeService extends Service {
     return !!existingDocument;
   }
   async getKnowledge(message, scope) {
-    logger4.debug("KnowledgeService: getKnowledge called for message id: " + message.id);
+    logger6.debug("KnowledgeService: getKnowledge called for message id: " + message.id);
     if (!message?.content?.text || message?.content?.text.trim().length === 0) {
-      logger4.warn("KnowledgeService: Invalid or empty message content for knowledge query.");
+      logger6.warn("KnowledgeService: Invalid or empty message content for knowledge query.");
       return [];
     }
     const embedding = await this.runtime.useModel(ModelType2.TEXT_EMBEDDING, {
@@ -1801,9 +2635,104 @@ 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) {
+        logger6.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
+      });
+      logger6.debug(
+        `Enriched conversation memory ${memoryId} with RAG data: ${ragMetadata.totalFragments} fragments`
+      );
+    } catch (error) {
+      logger6.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
+    });
+    logger6.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) {
+      logger6.warn(`Error enriching recent memories with RAG data: ${error.message}`);
+    }
+  }
   async processCharacterKnowledge(items) {
-    await new Promise((resolve) => setTimeout(resolve, 1e3));
-    logger4.info(
+    await new Promise((resolve2) => setTimeout(resolve2, 1e3));
+    logger6.info(
       `KnowledgeService: Processing ${items.length} character knowledge items for agent ${this.runtime.agentId}`
     );
     const processingPromises = items.map(async (item) => {
@@ -1816,12 +2745,12 @@ var KnowledgeService = class _KnowledgeService extends Service {
           // A constant identifier for character knowledge
         });
         if (await this.checkExistingKnowledge(knowledgeId)) {
-          logger4.debug(
+          logger6.debug(
             `KnowledgeService: Character knowledge item with ID ${knowledgeId} already exists. Skipping.`
           );
           return;
         }
-        logger4.debug(
+        logger6.debug(
           `KnowledgeService: Processing character knowledge for ${this.runtime.character?.name} - ${item.slice(0, 100)}`
         );
         let metadata = {
@@ -1872,7 +2801,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
       }
     });
     await Promise.all(processingPromises);
-    logger4.info(
+    logger6.info(
       `KnowledgeService: Finished processing character knowledge for agent ${this.runtime.agentId}.`
     );
   }
@@ -1892,7 +2821,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
       worldId: scope?.worldId ?? this.runtime.agentId,
       entityId: scope?.entityId ?? this.runtime.agentId
     };
-    logger4.debug(`KnowledgeService: _internalAddKnowledge called for item ID ${item.id}`);
+    logger6.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.
@@ -1914,7 +2843,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
     };
     const existingDocument = await this.runtime.getMemoryById(item.id);
     if (existingDocument) {
-      logger4.debug(
+      logger6.debug(
         `KnowledgeService: Document ${item.id} already exists in _internalAddKnowledge, updating...`
       );
       await this.runtime.updateMemory({
@@ -1938,13 +2867,13 @@ var KnowledgeService = class _KnowledgeService extends Service {
         await this.processDocumentFragment(fragment);
         fragmentsProcessed++;
       } catch (error) {
-        logger4.error(
+        logger6.error(
           `KnowledgeService: Error processing fragment ${fragment.id} for document ${item.id}:`,
           error
         );
       }
     }
-    logger4.debug(
+    logger6.debug(
       `KnowledgeService: Processed ${fragmentsProcessed}/${fragments.length} fragments for document ${item.id}.`
     );
   }
@@ -1953,7 +2882,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
       await this.runtime.addEmbeddingToMemory(fragment);
       await this.runtime.createMemory(fragment, "knowledge");
     } catch (error) {
-      logger4.error(
+      logger6.error(
         `KnowledgeService: Error processing fragment ${fragment.id}:`,
         error instanceof Error ? error.message : String(error)
       );
@@ -2018,7 +2947,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
    */
   async deleteMemory(memoryId) {
     await this.runtime.deleteMemory(memoryId);
-    logger4.info(
+    logger6.info(
       `KnowledgeService: Deleted memory ${memoryId} for agent ${this.runtime.agentId}. Assumed it was a document or related fragment.`
     );
   }
@@ -2026,13 +2955,14 @@ var KnowledgeService = class _KnowledgeService extends Service {
 };
 
 // src/provider.ts
-import { addHeader } from "@elizaos/core";
+import { addHeader, logger as logger7 } 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,23 +2972,61 @@ 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) {
+            logger7.warn("RAG memory enrichment failed:", error.message);
+          }
+        }, 2e3);
+      } catch (error) {
+        logger7.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
     };
   }
 };
 
 // src/tests.ts
 import { MemoryType as MemoryType3, ModelType as ModelType3 } from "@elizaos/core";
-import { Buffer as Buffer2 } from "buffer";
-import * as fs from "fs";
-import * as path from "path";
+import { Buffer as Buffer3 } from "buffer";
+import * as fs2 from "fs";
+import * as path2 from "path";
 var mockLogger = {
   info: (() => {
     const fn = (...args) => {
@@ -2192,9 +3160,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(
@@ -2457,9 +3423,9 @@ trailer
 startxref
 ${465 + content.length}
 %%EOF`;
-    return Buffer2.from(pdfContent);
+    return Buffer3.from(pdfContent);
   }
-  return Buffer2.from(content, "utf-8");
+  return Buffer3.from(content, "utf-8");
 }
 var KnowledgeTestSuite = class {
   name = "knowledge";
@@ -2472,10 +3438,10 @@ var KnowledgeTestSuite = class {
         const originalEnv = { ...process.env };
         delete process.env.KNOWLEDGE_PATH;
         try {
-          const docsPath = path.join(process.cwd(), "docs");
-          const docsExists = fs.existsSync(docsPath);
+          const docsPath = path2.join(process.cwd(), "docs");
+          const docsExists = fs2.existsSync(docsPath);
           if (!docsExists) {
-            fs.mkdirSync(docsPath, { recursive: true });
+            fs2.mkdirSync(docsPath, { recursive: true });
           }
           await index_default.init({}, runtime);
           const errorCalls = mockLogger.error.calls;
@@ -2483,7 +3449,7 @@ var KnowledgeTestSuite = class {
             throw new Error(`Unexpected error during init: ${errorCalls[0]}`);
           }
           if (!docsExists) {
-            fs.rmSync(docsPath, { recursive: true, force: true });
+            fs2.rmSync(docsPath, { recursive: true, force: true });
           }
         } finally {
           process.env = originalEnv;
@@ -2496,13 +3462,13 @@ var KnowledgeTestSuite = class {
         const originalEnv = { ...process.env };
         delete process.env.KNOWLEDGE_PATH;
         try {
-          const docsPath = path.join(process.cwd(), "docs");
-          if (fs.existsSync(docsPath)) {
-            fs.renameSync(docsPath, docsPath + ".backup");
+          const docsPath = path2.join(process.cwd(), "docs");
+          if (fs2.existsSync(docsPath)) {
+            fs2.renameSync(docsPath, docsPath + ".backup");
           }
           await index_default.init({}, runtime);
-          if (fs.existsSync(docsPath + ".backup")) {
-            fs.renameSync(docsPath + ".backup", docsPath);
+          if (fs2.existsSync(docsPath + ".backup")) {
+            fs2.renameSync(docsPath + ".backup", docsPath);
           }
         } finally {
           process.env = originalEnv;
@@ -2521,9 +3487,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 +3500,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}"`);
         }
@@ -2549,7 +3509,7 @@ var KnowledgeTestSuite = class {
     {
       name: "Should handle empty file buffer",
       fn: async (runtime) => {
-        const emptyBuffer = Buffer2.alloc(0);
+        const emptyBuffer = Buffer3.alloc(0);
         try {
           await extractTextFromDocument(emptyBuffer, "text/plain", "empty.txt");
           throw new Error("Should have thrown error for empty buffer");
@@ -2612,9 +3572,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");
         }
@@ -2759,19 +3717,15 @@ var KnowledgeTestSuite = class {
           }
         });
         const service = await KnowledgeService.start(knowledgeRuntime);
-        await new Promise((resolve) => setTimeout(resolve, 2e3));
+        await new Promise((resolve2) => setTimeout(resolve2, 2e3));
         const memories = await knowledgeRuntime.getMemories({
           tableName: "documents",
           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 +3827,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 +3857,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,9 +3909,9 @@ var KnowledgeTestSuite = class {
 var tests_default = new KnowledgeTestSuite();
 
 // src/actions.ts
-import { logger as logger5, stringToUuid } from "@elizaos/core";
-import * as fs2 from "fs";
-import * as path2 from "path";
+import { logger as logger8, stringToUuid } from "@elizaos/core";
+import * as fs3 from "fs";
+import * as path3 from "path";
 var processKnowledgeAction = {
   name: "PROCESS_KNOWLEDGE",
   description: "Process and store knowledge from a file path or text content into the knowledge base",
@@ -3014,25 +3962,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"
-      );
+      logger8.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");
       }
@@ -3042,7 +3984,7 @@ var processKnowledgeAction = {
       let response;
       if (pathMatch) {
         const filePath = pathMatch[0];
-        if (!fs2.existsSync(filePath)) {
+        if (!fs3.existsSync(filePath)) {
           response = {
             text: `I couldn't find the file at ${filePath}. Please check the path and try again.`
           };
@@ -3051,9 +3993,9 @@ var processKnowledgeAction = {
           }
           return;
         }
-        const fileBuffer = fs2.readFileSync(filePath);
-        const fileName = path2.basename(filePath);
-        const fileExt = path2.extname(filePath).toLowerCase();
+        const fileBuffer = fs3.readFileSync(filePath);
+        const fileName = path3.basename(filePath);
+        const fileExt = path3.extname(filePath).toLowerCase();
         let contentType = "text/plain";
         if (fileExt === ".pdf") contentType = "application/pdf";
         else if (fileExt === ".docx")
@@ -3075,10 +4017,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 +4045,7 @@ var processKnowledgeAction = {
         await callback(response);
       }
     } catch (error) {
-      logger5.error("Error in PROCESS_KNOWLEDGE action:", error);
+      logger8.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 +4085,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 +4097,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 +4136,7 @@ ${formattedResults}`
         await callback(response);
       }
     } catch (error) {
-      logger5.error("Error in SEARCH_KNOWLEDGE action:", error);
+      logger8.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 +4149,9 @@ ${formattedResults}`
 var knowledgeActions = [processKnowledgeAction, searchKnowledgeAction];
 
 // src/routes.ts
-import { createUniqueUuid as createUniqueUuid2, logger as logger6, ModelType as ModelType4 } from "@elizaos/core";
-import fs3 from "fs";
-import path3 from "path";
+import { createUniqueUuid as createUniqueUuid2, logger as logger9, ModelType as ModelType4 } from "@elizaos/core";
+import fs4 from "fs";
+import path4 from "path";
 import multer from "multer";
 var createUploadMiddleware = (runtime) => {
   const uploadDir = runtime.getSetting("KNOWLEDGE_UPLOAD_DIR") || "/tmp/uploads/";
@@ -3277,11 +4196,11 @@ function sendError(res, status, code, message, details) {
   res.end(JSON.stringify({ success: false, error: { code, message, details } }));
 }
 var cleanupFile = (filePath) => {
-  if (filePath && fs3.existsSync(filePath)) {
+  if (filePath && fs4.existsSync(filePath)) {
     try {
-      fs3.unlinkSync(filePath);
+      fs4.unlinkSync(filePath);
     } catch (error) {
-      logger6.error(`Error cleaning up file ${filePath}:`, error);
+      logger9.error(`Error cleaning up file ${filePath}:`, error);
     }
   }
 };
@@ -3308,15 +4227,15 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       }
       const invalidFiles = files.filter((file) => {
         if (file.size === 0) {
-          logger6.warn(`File ${file.originalname} is empty`);
+          logger9.warn(`File ${file.originalname} is empty`);
           return true;
         }
         if (!file.originalname || file.originalname.trim() === "") {
-          logger6.warn(`File has no name`);
+          logger9.warn(`File has no name`);
           return true;
         }
         if (!file.path) {
-          logger6.warn(`File ${file.originalname} has no path`);
+          logger9.warn(`File ${file.originalname} has no path`);
           return true;
         }
         return false;
@@ -3333,7 +4252,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");
+        logger9.error("[Document Processor] \u274C No agent ID provided in upload request");
         return sendError(
           res,
           400,
@@ -3342,15 +4261,15 @@ async function uploadKnowledgeHandler(req, res, runtime) {
         );
       }
       const worldId = req.body.worldId || agentId;
-      logger6.info(`[KNOWLEDGE UPLOAD HANDLER] Processing upload for agent: ${agentId}`);
+      logger9.info(`[Document Processor] \u{1F4E4} Processing file upload for agent: ${agentId}`);
       const processingPromises = files.map(async (file, index) => {
         const originalFilename = file.originalname;
         const filePath = file.path;
-        logger6.debug(
-          `[KNOWLEDGE UPLOAD HANDLER] File: ${originalFilename}, Agent ID: ${agentId}, World ID: ${worldId}`
+        logger9.debug(
+          `[Document Processor] \u{1F4C4} Processing file: ${originalFilename} (agent: ${agentId})`
         );
         try {
-          const fileBuffer = await fs3.promises.readFile(filePath);
+          const fileBuffer = await fs4.promises.readFile(filePath);
           const base64Content = fileBuffer.toString("base64");
           const addKnowledgeOpts = {
             agentId,
@@ -3381,8 +4300,9 @@ async function uploadKnowledgeHandler(req, res, runtime) {
             status: "success"
           };
         } catch (fileError) {
-          logger6.error(
-            `[KNOWLEDGE UPLOAD HANDLER] Error processing file ${file.originalname}: ${fileError}`
+          logger9.error(
+            `[Document Processor] \u274C Error processing file ${file.originalname}:`,
+            fileError
           );
           cleanupFile(filePath);
           return {
@@ -3403,7 +4323,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");
+        logger9.error("[Document Processor] \u274C No agent ID provided in URL request");
         return sendError(
           res,
           400,
@@ -3411,7 +4331,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}`);
+      logger9.info(`[Document Processor] \u{1F4E4} Processing URL upload for agent: ${agentId}`);
       const processingPromises = fileUrls.map(async (fileUrl) => {
         try {
           const normalizedUrl = normalizeS3Url(fileUrl);
@@ -3419,7 +4339,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}`);
+          logger9.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") {
@@ -3459,8 +4379,8 @@ async function uploadKnowledgeHandler(req, res, runtime) {
               url: normalizedUrl
             }
           };
-          logger6.debug(
-            `[KNOWLEDGE URL HANDLER] Processing knowledge from URL: ${fileUrl} (type: ${contentType})`
+          logger9.debug(
+            `[Document Processor] \u{1F4C4} Processing knowledge from URL: ${originalFilename} (type: ${contentType})`
           );
           const result = await service.addKnowledge(addKnowledgeOpts);
           return {
@@ -3474,7 +4394,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
             status: "success"
           };
         } catch (urlError) {
-          logger6.error(`[KNOWLEDGE URL HANDLER] Error processing URL ${fileUrl}: ${urlError}`);
+          logger9.error(`[Document Processor] \u274C Error processing URL ${fileUrl}:`, urlError);
           return {
             fileUrl,
             status: "error_processing",
@@ -3486,7 +4406,7 @@ async function uploadKnowledgeHandler(req, res, runtime) {
       sendSuccess(res, results);
     }
   } catch (error) {
-    logger6.error("[KNOWLEDGE HANDLER] Error processing knowledge:", error);
+    logger9.error("[Document Processor] \u274C Error processing knowledge:", error);
     if (hasUploadedFiles) {
       cleanupFiles(req.files);
     }
@@ -3504,7 +4424,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;
@@ -3525,8 +4445,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`
+      logger9.debug(
+        `[Document Processor] \u{1F50D} Filtered documents by URLs: ${fileUrls.length} URLs, found ${filteredMemories.length} matching documents`
       );
     }
     const cleanMemories = includeEmbedding ? filteredMemories : filteredMemories.map((memory) => ({
@@ -3540,15 +4460,12 @@ async function getKnowledgeDocumentsHandler(req, res, runtime) {
       totalRequested: fileUrls ? fileUrls.length : 0
     });
   } catch (error) {
-    logger6.error("[KNOWLEDGE GET HANDLER] Error retrieving documents:", error);
+    logger9.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)}
-  `);
+  logger9.debug(`[Document Processor] \u{1F5D1}\uFE0F DELETE request for document: ${req.params.knowledgeId}`);
   const service = runtime.getService(KnowledgeService.serviceType);
   if (!service) {
     return sendError(
@@ -3560,29 +4477,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}`);
+    logger9.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}`
-    );
+    logger9.debug(`[Document Processor] \u{1F5D1}\uFE0F Deleting document: ${typedKnowledgeId}`);
     await service.deleteMemory(typedKnowledgeId);
-    logger6.info(
-      `[KNOWLEDGE DELETE HANDLER] Successfully deleted document with ID: ${typedKnowledgeId}`
-    );
+    logger9.info(`[Document Processor] \u2705 Successfully deleted document: ${typedKnowledgeId}`);
     sendSuccess(res, null, 204);
   } catch (error) {
-    logger6.error(`[KNOWLEDGE DELETE HANDLER] Error deleting document ${knowledgeId}:`, error);
+    logger9.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)}
-  `);
+  logger9.debug(`[Document Processor] \u{1F50D} GET request for document: ${req.params.knowledgeId}`);
   const service = runtime.getService(KnowledgeService.serviceType);
   if (!service) {
     return sendError(
@@ -3594,15 +4504,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}`);
+    logger9.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}`);
+    logger9.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);
@@ -3615,19 +4525,19 @@ async function getKnowledgeByIdHandler(req, res, runtime) {
     };
     sendSuccess(res, { document: cleanDocument });
   } catch (error) {
-    logger6.error(`[KNOWLEDGE GET BY ID HANDLER] Error retrieving document ${knowledgeId}:`, error);
+    logger9.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}`);
+  logger9.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}`);
-    if (fs3.existsSync(frontendPath)) {
-      const html = await fs3.promises.readFile(frontendPath, "utf8");
+    const currentDir = path4.dirname(new URL(import.meta.url).pathname);
+    const frontendPath = path4.join(currentDir, "../dist/index.html");
+    logger9.debug(`[Document Processor] \u{1F310} Looking for frontend at: ${frontendPath}`);
+    if (fs4.existsSync(frontendPath)) {
+      const html = await fs4.promises.readFile(frontendPath, "utf8");
       const injectedHtml = html.replace(
         "<head>",
         `<head>
@@ -3643,10 +4553,10 @@ async function knowledgePanelHandler(req, res, runtime) {
     } else {
       let cssFile = "index.css";
       let jsFile = "index.js";
-      const manifestPath = path3.join(currentDir, "../dist/manifest.json");
-      if (fs3.existsSync(manifestPath)) {
+      const manifestPath = path4.join(currentDir, "../dist/manifest.json");
+      if (fs4.existsSync(manifestPath)) {
         try {
-          const manifestContent = await fs3.promises.readFile(manifestPath, "utf8");
+          const manifestContent = await fs4.promises.readFile(manifestPath, "utf8");
           const manifest = JSON.parse(manifestContent);
           for (const [key, value] of Object.entries(manifest)) {
             if (typeof value === "object" && value !== null) {
@@ -3659,10 +4569,10 @@ async function knowledgePanelHandler(req, res, runtime) {
             }
           }
         } catch (manifestError) {
-          logger6.error("[KNOWLEDGE PANEL] Error reading manifest:", manifestError);
+          logger9.error("[Document Processor] \u274C Error reading manifest:", manifestError);
         }
       }
-      logger6.debug(`[KNOWLEDGE PANEL] Using fallback with CSS: ${cssFile}, JS: ${jsFile}`);
+      logger9.debug(`[Document Processor] \u{1F310} Using fallback with CSS: ${cssFile}, JS: ${jsFile}`);
       const html = `
 <!DOCTYPE html>
 <html lang="en">
@@ -3696,16 +4606,14 @@ async function knowledgePanelHandler(req, res, runtime) {
       res.end(html);
     }
   } catch (error) {
-    logger6.error("[KNOWLEDGE PANEL] Error serving frontend:", error);
+    logger9.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)}`
-    );
-    const currentDir = path3.dirname(new URL(import.meta.url).pathname);
+    logger9.debug(`[Document Processor] \u{1F310} Asset request: ${req.path}`);
+    const currentDir = path4.dirname(new URL(import.meta.url).pathname);
     const assetRequestPath = req.path;
     const assetsMarker = "/assets/";
     const assetsStartIndex = assetRequestPath.indexOf(assetsMarker);
@@ -3721,10 +4629,10 @@ async function frontendAssetHandler(req, res, runtime) {
         `Invalid asset name: '${assetName}' from path ${assetRequestPath}`
       );
     }
-    const assetPath = path3.join(currentDir, "../dist/assets", assetName);
-    logger6.debug(`[KNOWLEDGE ASSET HANDLER] Attempting to serve asset: ${assetPath}`);
-    if (fs3.existsSync(assetPath)) {
-      const fileStream = fs3.createReadStream(assetPath);
+    const assetPath = path4.join(currentDir, "../dist/assets", assetName);
+    logger9.debug(`[Document Processor] \u{1F310} Serving asset: ${assetPath}`);
+    if (fs4.existsSync(assetPath)) {
+      const fileStream = fs4.createReadStream(assetPath);
       let contentType = "application/octet-stream";
       if (assetPath.endsWith(".js")) {
         contentType = "application/javascript";
@@ -3737,7 +4645,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);
+    logger9.error(`[Document Processor] \u274C Error serving asset ${req.url}:`, error);
     sendError(res, 500, "ASSET_ERROR", `Failed to load asset ${req.url}`, error.message);
   }
 }
@@ -3751,8 +4659,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) {
@@ -3798,7 +4706,7 @@ async function getKnowledgeChunksHandler(req, res, runtime) {
       }
     });
   } catch (error) {
-    logger6.error("[KNOWLEDGE CHUNKS GET HANDLER] Error retrieving chunks:", error);
+    logger9.error("[Document Processor] \u274C Error retrieving chunks:", error);
     sendError(res, 500, "RETRIEVAL_ERROR", "Failed to retrieve knowledge chunks", error.message);
   }
 }
@@ -3820,15 +4728,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}`
+      logger9.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}`);
+      logger9.debug(`[Document Processor] \u{1F50D} Limit value ${parsedLimit} was clamped to ${limit}`);
     }
-    logger6.debug(
-      `[KNOWLEDGE SEARCH] Searching for: "${searchText}" with threshold: ${matchThreshold}, limit: ${limit}`
+    logger9.debug(
+      `[Document Processor] \u{1F50D} Searching: "${searchText}" (threshold: ${matchThreshold}, limit: ${limit})`
     );
     const embedding = await runtime.useModel(ModelType4.TEXT_EMBEDDING, {
       text: searchText
@@ -3854,7 +4762,7 @@ async function searchKnowledgeHandler(req, res, runtime) {
               documentFilename = document.metadata.filename || documentFilename;
             }
           } catch (e) {
-            logger6.debug(`Could not fetch document ${documentId} for fragment`);
+            logger9.debug(`Could not fetch document ${documentId} for fragment`);
           }
         }
         return {
@@ -3869,8 +4777,8 @@ async function searchKnowledgeHandler(req, res, runtime) {
         };
       })
     );
-    logger6.info(
-      `[KNOWLEDGE SEARCH] Found ${enhancedResults.length} results for query: "${searchText}"`
+    logger9.info(
+      `[Document Processor] \u{1F50D} Found ${enhancedResults.length} results for: "${searchText}"`
     );
     sendSuccess(res, {
       query: searchText,
@@ -3879,7 +4787,7 @@ async function searchKnowledgeHandler(req, res, runtime) {
       count: enhancedResults.length
     });
   } catch (error) {
-    logger6.error("[KNOWLEDGE SEARCH] Error searching knowledge:", error);
+    logger9.error("[Document Processor] \u274C Error searching knowledge:", error);
     sendError(res, 500, "SEARCH_ERROR", "Failed to search knowledge", error.message);
   }
 }
@@ -3891,7 +4799,7 @@ async function uploadKnowledgeWithMulter(req, res, runtime) {
   );
   uploadArray(req, res, (err) => {
     if (err) {
-      logger6.error("[KNOWLEDGE UPLOAD] Multer error:", err);
+      logger9.error("[Document Processor] \u274C File upload error:", err);
       return sendError(res, 400, "UPLOAD_ERROR", err.message);
     }
     uploadKnowledgeHandler(req, res, runtime);
@@ -3946,70 +4854,6 @@ var knowledgeRoutes = [
 var knowledgePlugin = {
   name: "knowledge",
   description: "Plugin for Retrieval Augmented Generation, including knowledge management and embedding.",
-  config: {
-    // Token limits - these will be read from runtime settings during init
-    MAX_INPUT_TOKENS: "4000",
-    MAX_OUTPUT_TOKENS: "4096",
-    // Contextual Knowledge settings
-    CTX_KNOWLEDGE_ENABLED: "false"
-  },
-  async init(config, runtime) {
-    logger7.info("Initializing Knowledge Plugin...");
-    try {
-      logger7.info("Validating model configuration for Knowledge plugin...");
-      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.`
-        );
-      } else {
-        const usingPluginOpenAI = !process.env.EMBEDDING_PROVIDER;
-        if (usingPluginOpenAI) {
-          logger7.info(
-            "Running in Basic Embedding mode with auto-detected configuration from plugin-openai."
-          );
-        } else {
-          logger7.info(
-            "Running in Basic Embedding mode (CTX_KNOWLEDGE_ENABLED=false). TEXT_PROVIDER and TEXT_MODEL not required."
-          );
-        }
-        logger7.info(
-          `Using ${validatedConfig.EMBEDDING_PROVIDER} for embeddings with ${validatedConfig.TEXT_EMBEDDING_MODEL}.`
-        );
-      }
-      logger7.info("Model configuration validated successfully.");
-      if (runtime) {
-        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);
-              if (service instanceof KnowledgeService) {
-                const { loadDocsFromPath: loadDocsFromPath2 } = await import("./docs-loader-PF5X4UMB.js");
-                const result = await loadDocsFromPath2(service, runtime.agentId);
-                if (result.successful > 0) {
-                  logger7.info(`Loaded ${result.successful} documents from docs folder on startup`);
-                }
-              }
-            } catch (error) {
-              logger7.error("Error loading documents on startup:", error);
-            }
-          }, 5e3);
-        } else {
-          logger7.info("LOAD_DOCS_ON_STARTUP is not enabled. Skipping automatic document loading.");
-        }
-      }
-      logger7.info(
-        "Knowledge Plugin initialized. Frontend panel should be discoverable via its public route."
-      );
-    } catch (error) {
-      logger7.error("Failed to initialize Knowledge plugin:", error);
-      throw error;
-    }
-  },
   services: [KnowledgeService],
   providers: [knowledgeProvider],
   routes: knowledgeRoutes,