@elizaos/plugin-knowledge 1.0.0-beta.71 → 1.0.0-beta.73

package/dist/index.js

@@ -1,3 +1,10 @@
+import {
+  convertPdfToTextFromBuffer,
+  extractTextFromFileBuffer,
+  isBinaryContentType,
+  loadDocsFromPath
+} from "./chunk-LHJERZV7.js";
+
 // src/index.ts
 import { logger as logger6 } from "@elizaos/core";
 
@@ -25,15 +32,11 @@ var ModelConfigSchema = z.object({
   TEXT_MODEL: z.string().optional(),
   // Token limits
   MAX_INPUT_TOKENS: z.string().or(z.number()).transform((val) => typeof val === "string" ? parseInt(val, 10) : val),
-  MAX_OUTPUT_TOKENS: z.string().or(z.number()).optional().transform(
-    (val) => val ? typeof val === "string" ? parseInt(val, 10) : val : 4096
-  ),
+  MAX_OUTPUT_TOKENS: z.string().or(z.number()).optional().transform((val) => val ? typeof val === "string" ? parseInt(val, 10) : val : 4096),
   // Embedding dimension
   // 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
-  ),
+  EMBEDDING_DIMENSION: z.string().or(z.number()).optional().transform((val) => val ? typeof val === "string" ? parseInt(val, 10) : val : 1536),
   // Contextual Knowledge settings
   CTX_KNOWLEDGE_ENABLED: z.boolean().default(false)
 });
@@ -44,41 +47,48 @@ var KnowledgeServiceType = {
 // src/config.ts
 import z2 from "zod";
 import { logger } from "@elizaos/core";
-function validateModelConfig() {
+function validateModelConfig(runtime) {
   try {
-    const ctxKnowledgeEnabled2 = process.env.CTX_KNOWLEDGE_ENABLED === "true";
+    const getSetting = (key, defaultValue) => {
+      if (runtime) {
+        return runtime.getSetting(key) || defaultValue;
+      }
+      return process.env[key] || defaultValue;
+    };
+    const ctxKnowledgeEnabled2 = getSetting("CTX_KNOWLEDGE_ENABLED") === "true";
     logger.debug(`Configuration: CTX_KNOWLEDGE_ENABLED=${ctxKnowledgeEnabled2}`);
-    const assumePluginOpenAI = !process.env.EMBEDDING_PROVIDER;
+    const embeddingProvider = getSetting("EMBEDDING_PROVIDER");
+    const assumePluginOpenAI = !embeddingProvider;
     if (assumePluginOpenAI) {
-      if (process.env.OPENAI_API_KEY && process.env.OPENAI_EMBEDDING_MODEL) {
-        logger.info(
-          "EMBEDDING_PROVIDER not specified, using configuration from plugin-openai"
-        );
+      const openaiApiKey2 = getSetting("OPENAI_API_KEY");
+      const openaiEmbeddingModel = getSetting("OPENAI_EMBEDDING_MODEL");
+      if (openaiApiKey2 && openaiEmbeddingModel) {
+        logger.info("EMBEDDING_PROVIDER not specified, using configuration from plugin-openai");
       } else {
         logger.warn(
           "EMBEDDING_PROVIDER not specified, but plugin-openai configuration incomplete. Check OPENAI_API_KEY and OPENAI_EMBEDDING_MODEL."
         );
       }
     }
-    const embeddingProvider = process.env.EMBEDDING_PROVIDER || "openai";
-    const textEmbeddingModel = process.env.TEXT_EMBEDDING_MODEL || process.env.OPENAI_EMBEDDING_MODEL || "text-embedding-3-small";
-    const embeddingDimension = process.env.EMBEDDING_DIMENSION || process.env.OPENAI_EMBEDDING_DIMENSIONS || 1536;
-    const openaiApiKey = process.env.OPENAI_API_KEY;
+    const finalEmbeddingProvider = embeddingProvider || "openai";
+    const textEmbeddingModel = getSetting("TEXT_EMBEDDING_MODEL") || getSetting("OPENAI_EMBEDDING_MODEL") || "text-embedding-3-small";
+    const embeddingDimension = getSetting("EMBEDDING_DIMENSION") || getSetting("OPENAI_EMBEDDING_DIMENSIONS") || "1536";
+    const openaiApiKey = getSetting("OPENAI_API_KEY");
     const config = ModelConfigSchema.parse({
-      EMBEDDING_PROVIDER: embeddingProvider,
-      TEXT_PROVIDER: process.env.TEXT_PROVIDER,
+      EMBEDDING_PROVIDER: finalEmbeddingProvider,
+      TEXT_PROVIDER: getSetting("TEXT_PROVIDER"),
       OPENAI_API_KEY: openaiApiKey,
-      ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY,
-      OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY,
-      GOOGLE_API_KEY: process.env.GOOGLE_API_KEY,
-      OPENAI_BASE_URL: process.env.OPENAI_BASE_URL,
-      ANTHROPIC_BASE_URL: process.env.ANTHROPIC_BASE_URL,
-      OPENROUTER_BASE_URL: process.env.OPENROUTER_BASE_URL,
-      GOOGLE_BASE_URL: process.env.GOOGLE_BASE_URL,
+      ANTHROPIC_API_KEY: getSetting("ANTHROPIC_API_KEY"),
+      OPENROUTER_API_KEY: getSetting("OPENROUTER_API_KEY"),
+      GOOGLE_API_KEY: getSetting("GOOGLE_API_KEY"),
+      OPENAI_BASE_URL: getSetting("OPENAI_BASE_URL"),
+      ANTHROPIC_BASE_URL: getSetting("ANTHROPIC_BASE_URL"),
+      OPENROUTER_BASE_URL: getSetting("OPENROUTER_BASE_URL"),
+      GOOGLE_BASE_URL: getSetting("GOOGLE_BASE_URL"),
       TEXT_EMBEDDING_MODEL: textEmbeddingModel,
-      TEXT_MODEL: process.env.TEXT_MODEL,
-      MAX_INPUT_TOKENS: process.env.MAX_INPUT_TOKENS || 4e3,
-      MAX_OUTPUT_TOKENS: process.env.MAX_OUTPUT_TOKENS || 4096,
+      TEXT_MODEL: getSetting("TEXT_MODEL"),
+      MAX_INPUT_TOKENS: getSetting("MAX_INPUT_TOKENS", "4000"),
+      MAX_OUTPUT_TOKENS: getSetting("MAX_OUTPUT_TOKENS", "4096"),
       EMBEDDING_DIMENSION: embeddingDimension,
       CTX_KNOWLEDGE_ENABLED: ctxKnowledgeEnabled2
     });
@@ -95,60 +105,38 @@ function validateModelConfig() {
 function validateConfigRequirements(config, assumePluginOpenAI) {
   if (!assumePluginOpenAI) {
     if (config.EMBEDDING_PROVIDER === "openai" && !config.OPENAI_API_KEY) {
-      throw new Error(
-        'OPENAI_API_KEY is required when EMBEDDING_PROVIDER is set to "openai"'
-      );
+      throw new Error('OPENAI_API_KEY is required when EMBEDDING_PROVIDER is set to "openai"');
     }
     if (config.EMBEDDING_PROVIDER === "google" && !config.GOOGLE_API_KEY) {
-      throw new Error(
-        'GOOGLE_API_KEY is required when EMBEDDING_PROVIDER is set to "google"'
-      );
+      throw new Error('GOOGLE_API_KEY is required when EMBEDDING_PROVIDER is set to "google"');
     }
   } else {
     if (!config.OPENAI_API_KEY) {
-      throw new Error(
-        "OPENAI_API_KEY is required when using plugin-openai configuration"
-      );
+      throw new Error("OPENAI_API_KEY is required when using plugin-openai configuration");
     }
     if (!config.TEXT_EMBEDDING_MODEL) {
-      throw new Error(
-        "OPENAI_EMBEDDING_MODEL is required when using plugin-openai configuration"
-      );
+      throw new Error("OPENAI_EMBEDDING_MODEL is required when using plugin-openai configuration");
     }
   }
   if (config.CTX_KNOWLEDGE_ENABLED) {
-    logger.info(
-      "Contextual Knowledge is enabled. Validating text generation settings..."
-    );
+    logger.info("Contextual Knowledge is enabled. Validating text generation settings...");
     if (!config.TEXT_PROVIDER) {
-      throw new Error(
-        "TEXT_PROVIDER is required when CTX_KNOWLEDGE_ENABLED is true"
-      );
+      throw new Error("TEXT_PROVIDER is required when CTX_KNOWLEDGE_ENABLED is true");
     }
     if (!config.TEXT_MODEL) {
-      throw new Error(
-        "TEXT_MODEL is required when CTX_KNOWLEDGE_ENABLED is true"
-      );
+      throw new Error("TEXT_MODEL is required when CTX_KNOWLEDGE_ENABLED is true");
     }
     if (config.TEXT_PROVIDER === "openai" && !config.OPENAI_API_KEY) {
-      throw new Error(
-        'OPENAI_API_KEY is required when TEXT_PROVIDER is set to "openai"'
-      );
+      throw new Error('OPENAI_API_KEY is required when TEXT_PROVIDER is set to "openai"');
     }
     if (config.TEXT_PROVIDER === "anthropic" && !config.ANTHROPIC_API_KEY) {
-      throw new Error(
-        'ANTHROPIC_API_KEY is required when TEXT_PROVIDER is set to "anthropic"'
-      );
+      throw new Error('ANTHROPIC_API_KEY is required when TEXT_PROVIDER is set to "anthropic"');
     }
     if (config.TEXT_PROVIDER === "openrouter" && !config.OPENROUTER_API_KEY) {
-      throw new Error(
-        'OPENROUTER_API_KEY is required when TEXT_PROVIDER is set to "openrouter"'
-      );
+      throw new Error('OPENROUTER_API_KEY is required when TEXT_PROVIDER is set to "openrouter"');
     }
     if (config.TEXT_PROVIDER === "google" && !config.GOOGLE_API_KEY) {
-      throw new Error(
-        'GOOGLE_API_KEY is required when TEXT_PROVIDER is set to "google"'
-      );
+      throw new Error('GOOGLE_API_KEY is required when TEXT_PROVIDER is set to "google"');
     }
     if (config.TEXT_PROVIDER === "openrouter") {
       const modelName = config.TEXT_MODEL?.toLowerCase() || "";
@@ -164,17 +152,21 @@ function validateConfigRequirements(config, assumePluginOpenAI) {
         "Contextual Knowledge is disabled. Using embedding configuration from plugin-openai."
       );
     } else {
-      logger.info(
-        "Contextual Knowledge is disabled. Using basic embedding-only configuration."
-      );
+      logger.info("Contextual Knowledge is disabled. Using basic embedding-only configuration.");
     }
   }
 }
-async function getProviderRateLimits() {
-  const config = validateModelConfig();
-  const maxConcurrentRequests = getEnvInt("MAX_CONCURRENT_REQUESTS", 30);
-  const requestsPerMinute = getEnvInt("REQUESTS_PER_MINUTE", 60);
-  const tokensPerMinute = getEnvInt("TOKENS_PER_MINUTE", 15e4);
+async function getProviderRateLimits(runtime) {
+  const config = validateModelConfig(runtime);
+  const getSetting = (key, defaultValue) => {
+    if (runtime) {
+      return runtime.getSetting(key) || defaultValue;
+    }
+    return process.env[key] || defaultValue;
+  };
+  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) {
     case "openai":
       return {
@@ -199,14 +191,11 @@ async function getProviderRateLimits() {
       };
   }
 }
-function getEnvInt(envVar, defaultValue) {
-  return process.env[envVar] ? parseInt(process.env[envVar], 10) : defaultValue;
-}
 
 // src/service.ts
 import {
   createUniqueUuid,
-  logger as logger4,
+  logger as logger3,
   MemoryType as MemoryType2,
   ModelType as ModelType2,
   Semaphore,
@@ -218,7 +207,7 @@ import {
 import {
   MemoryType,
   ModelType,
-  logger as logger3,
+  logger as logger2,
   splitChunks
 } from "@elizaos/core";
 
@@ -701,143 +690,12 @@ ${chunkContent}`;
   return generatedContext.trim();
 }
 
-// src/utils.ts
-import * as mammoth from "mammoth";
-import { logger as logger2 } from "@elizaos/core";
-import { getDocument } from "pdfjs-dist/legacy/build/pdf.mjs";
-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();
-  logger2.debug(
-    `[TextUtil] Attempting to extract text from ${originalFilename} (type: ${contentType})`
-  );
-  if (lowerContentType === "application/vnd.openxmlformats-officedocument.wordprocessingml.document") {
-    logger2.debug(
-      `[TextUtil] Extracting text from DOCX ${originalFilename} via mammoth.`
-    );
-    try {
-      const result = await mammoth.extractRawText({ buffer: fileBuffer });
-      logger2.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}`;
-      logger2.error(errorMsg, docxError.stack);
-      throw new Error(errorMsg);
-    }
-  } else if (lowerContentType === "application/msword" || originalFilename.toLowerCase().endsWith(".doc")) {
-    logger2.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)) {
-    logger2.debug(
-      `[TextUtil] Extracting text from plain text compatible file ${originalFilename} (type: ${contentType})`
-    );
-    return fileBuffer.toString("utf-8");
-  } else {
-    logger2.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.`;
-      logger2.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.`;
-      logger2.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).`;
-        logger2.error(binaryErrorMsg);
-        throw new Error(binaryErrorMsg);
-      }
-      logger2.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.`;
-      logger2.error(
-        finalErrorMsg,
-        fallbackError.message ? fallbackError.stack : void 0
-      );
-      throw new Error(finalErrorMsg);
-    }
-  }
-}
-async function convertPdfToTextFromBuffer(pdfBuffer, filename) {
-  const docName = filename || "unnamed-document";
-  logger2.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++) {
-      logger2.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();
-    logger2.debug(
-      `[PdfService] Conversion complete for ${docName}, length: ${fullText.length}`
-    );
-    return fullText;
-  } catch (error) {
-    logger2.error(
-      `[PdfService] Error converting PDF ${docName}:`,
-      error.message
-    );
-    throw new Error(`Failed to convert PDF to text: ${error.message}`);
-  }
-}
-function isTextItem(item) {
-  return "str" in item;
-}
-
 // src/document-processor.ts
 var ctxKnowledgeEnabled = process.env.CTX_KNOWLEDGE_ENABLED === "true" || process.env.CTX_KNOWLEDGE_ENABLED === "True";
 if (ctxKnowledgeEnabled) {
-  logger3.info(`Document processor starting with Contextual Knowledge ENABLED`);
+  logger2.info(`Document processor starting with Contextual Knowledge ENABLED`);
 } else {
-  logger3.info(`Document processor starting with Contextual Knowledge DISABLED`);
+  logger2.info(`Document processor starting with Contextual Knowledge DISABLED`);
 }
 async function processFragmentsSynchronously({
   runtime,
@@ -850,19 +708,19 @@ async function processFragmentsSynchronously({
   worldId
 }) {
   if (!fullDocumentText || fullDocumentText.trim() === "") {
-    logger3.warn(
+    logger2.warn(
       `No text content available to chunk for document ${documentId}.`
     );
     return 0;
   }
   const chunks = await splitDocumentIntoChunks(fullDocumentText);
   if (chunks.length === 0) {
-    logger3.warn(
+    logger2.warn(
       `No chunks generated from text for ${documentId}. No fragments to save.`
     );
     return 0;
   }
-  logger3.info(
+  logger2.info(
     `Split content into ${chunks.length} chunks for document ${documentId}`
   );
   const providerLimits = await getProviderRateLimits();
@@ -885,11 +743,11 @@ async function processFragmentsSynchronously({
     rateLimiter
   });
   if (failedCount > 0) {
-    logger3.warn(
+    logger2.warn(
       `Failed to process ${failedCount} chunks out of ${chunks.length} for document ${documentId}`
     );
   }
-  logger3.info(
+  logger2.info(
     `Finished saving ${savedCount} fragments for document ${documentId}.`
   );
   return savedCount;
@@ -902,17 +760,17 @@ async function extractTextFromDocument(fileBuffer, contentType, originalFilename
   }
   try {
     if (contentType === "application/pdf") {
-      logger3.debug(`Extracting text from PDF: ${originalFilename}`);
+      logger2.debug(`Extracting text from PDF: ${originalFilename}`);
       return await convertPdfToTextFromBuffer(fileBuffer, originalFilename);
     } else {
-      logger3.debug(
+      logger2.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(
+          logger2.warn(
             `Failed to decode ${originalFilename} as UTF-8, falling back to binary extraction`
           );
         }
@@ -924,7 +782,7 @@ async function extractTextFromDocument(fileBuffer, contentType, originalFilename
       );
     }
   } catch (error) {
-    logger3.error(
+    logger2.error(
       `Error extracting text from ${originalFilename}: ${error.message}`
     );
     throw new Error(
@@ -974,7 +832,7 @@ async function splitDocumentIntoChunks(documentText) {
   const targetCharChunkOverlap = Math.round(
     tokenChunkOverlap * DEFAULT_CHARS_PER_TOKEN
   );
-  logger3.debug(
+  logger2.debug(
     `Using core splitChunks with settings: tokenChunkSize=${tokenChunkSize}, tokenChunkOverlap=${tokenChunkOverlap}, charChunkSize=${targetCharChunkSize}, charChunkOverlap=${targetCharChunkOverlap}`
   );
   return await splitChunks(documentText, tokenChunkSize, tokenChunkOverlap);
@@ -1001,7 +859,7 @@ async function processAndSaveFragments({
       { length: batchChunks.length },
       (_, k) => i + k
     );
-    logger3.debug(
+    logger2.debug(
       `Processing batch of ${batchChunks.length} chunks for document ${documentId}. Starting original index: ${batchOriginalIndices[0]}, batch ${Math.floor(i / concurrencyLimit) + 1}/${Math.ceil(chunks.length / concurrencyLimit)}`
     );
     const contextualizedChunks = await getContextualizedChunks(
@@ -1021,7 +879,7 @@ async function processAndSaveFragments({
       if (!result.success) {
         failedCount++;
         failedChunks.push(originalChunkIndex);
-        logger3.warn(
+        logger2.warn(
           `Failed to process chunk ${originalChunkIndex} for document ${documentId}`
         );
         continue;
@@ -1029,7 +887,7 @@ async function processAndSaveFragments({
       const contextualizedChunkText = result.text;
       const embedding = result.embedding;
       if (!embedding || embedding.length === 0) {
-        logger3.warn(
+        logger2.warn(
           `Zero vector detected for chunk ${originalChunkIndex} (document ${documentId}). Embedding: ${JSON.stringify(result.embedding)}`
         );
         failedCount++;
@@ -1054,12 +912,12 @@ async function processAndSaveFragments({
           }
         };
         await runtime.createMemory(fragmentMemory, "knowledge");
-        logger3.debug(
+        logger2.debug(
           `Saved fragment ${originalChunkIndex + 1} for document ${documentId} (Fragment ID: ${fragmentMemory.id})`
         );
         savedCount++;
       } catch (saveError) {
-        logger3.error(
+        logger2.error(
           `Error saving chunk ${originalChunkIndex} to database: ${saveError.message}`,
           saveError.stack
         );
@@ -1103,7 +961,7 @@ async function generateEmbeddingsForChunks(runtime, contextualizedChunks, rateLi
           text: contextualizedChunk.contextualizedText
         };
       } catch (error) {
-        logger3.error(
+        logger2.error(
           `Error generating embedding for chunk ${contextualizedChunk.index}: ${error.message}`
         );
         return {
@@ -1118,7 +976,7 @@ 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`);
+    logger2.debug(`Generating contexts for ${chunks.length} chunks`);
     return await generateContextsInBatch(
       runtime,
       fullDocumentText,
@@ -1143,7 +1001,7 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
   const config = validateModelConfig();
   const isUsingOpenRouter = config.TEXT_PROVIDER === "openrouter";
   const isUsingCacheCapableModel = isUsingOpenRouter && (config.TEXT_MODEL?.toLowerCase().includes("claude") || config.TEXT_MODEL?.toLowerCase().includes("gemini"));
-  logger3.info(
+  logger2.info(
     `Using provider: ${config.TEXT_PROVIDER}, model: ${config.TEXT_MODEL}, caching capability: ${isUsingCacheCapableModel}`
   );
   const promptConfigs = prepareContextPrompts(
@@ -1188,7 +1046,7 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
           item.chunkText,
           generatedContext
         );
-        logger3.debug(
+        logger2.debug(
           `Context added for chunk ${item.originalIndex}. New length: ${contextualizedText.length}`
         );
         return {
@@ -1197,7 +1055,7 @@ async function generateContextsInBatch(runtime, fullDocumentText, chunks, conten
           index: item.originalIndex
         };
       } catch (error) {
-        logger3.error(
+        logger2.error(
           `Error generating context for chunk ${item.originalIndex}: ${error.message}`,
           error.stack
         );
@@ -1218,7 +1076,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
       if (isUsingCacheCapableModel) {
         const cachingPromptInfo = contentType ? getCachingPromptForMimeType(contentType, chunkText) : getCachingContextualizationPrompt(chunkText);
         if (cachingPromptInfo.prompt.startsWith("Error:")) {
-          logger3.warn(
+          logger2.warn(
             `Skipping contextualization for chunk ${originalIndex} due to: ${cachingPromptInfo.prompt}`
           );
           return {
@@ -1240,7 +1098,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
       } else {
         const prompt = contentType ? getPromptForMimeType(contentType, fullDocumentText, chunkText) : getContextualizationPrompt(fullDocumentText, chunkText);
         if (prompt.startsWith("Error:")) {
-          logger3.warn(
+          logger2.warn(
             `Skipping contextualization for chunk ${originalIndex} due to: ${prompt}`
           );
           return {
@@ -1260,7 +1118,7 @@ function prepareContextPrompts(chunks, fullDocumentText, contentType, batchIndic
         };
       }
     } catch (error) {
-      logger3.error(
+      logger2.error(
         `Error preparing prompt for chunk ${originalIndex}: ${error.message}`,
         error.stack
       );
@@ -1281,7 +1139,7 @@ async function generateEmbeddingWithValidation(runtime, text) {
     });
     const embedding = Array.isArray(embeddingResult) ? embeddingResult : embeddingResult?.embedding;
     if (!embedding || embedding.length === 0) {
-      logger3.warn(
+      logger2.warn(
         `Zero vector detected. Embedding result: ${JSON.stringify(embeddingResult)}`
       );
       return {
@@ -1301,14 +1159,14 @@ async function withRateLimitRetry(operation, errorContext, retryDelay) {
   } catch (error) {
     if (error.status === 429) {
       const delay = retryDelay || error.headers?.["retry-after"] || 5;
-      logger3.warn(
+      logger2.warn(
         `Rate limit hit for ${errorContext}. Retrying after ${delay}s`
       );
       await new Promise((resolve) => setTimeout(resolve, delay * 1e3));
       try {
         return await operation();
       } catch (retryError) {
-        logger3.error(
+        logger2.error(
           `Failed after retry for ${errorContext}: ${retryError.message}`
         );
         throw retryError;
@@ -1329,7 +1187,7 @@ function createRateLimiter(requestsPerMinute) {
       const oldestRequest = requestTimes[0];
       const timeToWait = Math.max(0, oldestRequest + intervalMs - now);
       if (timeToWait > 0) {
-        logger3.debug(
+        logger2.debug(
           `Rate limiting applied, waiting ${timeToWait}ms before next request`
         );
         await new Promise((resolve) => setTimeout(resolve, timeToWait));
@@ -1341,42 +1199,87 @@ function createRateLimiter(requestsPerMinute) {
 
 // src/service.ts
 var KnowledgeService = class _KnowledgeService extends Service {
+  static serviceType = "knowledge";
+  config;
+  capabilityDescription = "Provides Retrieval Augmented Generation capabilities, including knowledge upload and querying.";
+  knowledgeProcessingSemaphore;
   /**
    * Create a new Knowledge service
    * @param runtime Agent runtime
    */
-  constructor(runtime) {
+  constructor(runtime, config) {
     super(runtime);
-    this.runtime = runtime;
     this.knowledgeProcessingSemaphore = new Semaphore(10);
-    logger4.info(`KnowledgeService initialized for agent: ${runtime.agentId}`);
+    const parseBooleanEnv = (value) => {
+      if (typeof value === "boolean") return value;
+      if (typeof value === "string") return value.toLowerCase() === "true";
+      return false;
+    };
+    this.config = {
+      CTX_KNOWLEDGE_ENABLED: parseBooleanEnv(config?.CTX_KNOWLEDGE_ENABLED),
+      LOAD_DOCS_ON_STARTUP: parseBooleanEnv(config?.LOAD_DOCS_ON_STARTUP),
+      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
+    };
+    logger3.info(
+      `KnowledgeService initialized for agent ${this.runtime.agentId} with config:`,
+      this.config
+    );
+    if (this.config.LOAD_DOCS_ON_STARTUP) {
+      this.loadInitialDocuments().catch((error) => {
+        logger3.error("Error during initial document loading in KnowledgeService:", error);
+      });
+    }
+  }
+  async loadInitialDocuments() {
+    logger3.info(
+      `KnowledgeService: Checking for documents to load on startup for agent ${this.runtime.agentId}`
+    );
+    try {
+      await new Promise((resolve) => setTimeout(resolve, 1e3));
+      const result = await loadDocsFromPath(this, this.runtime.agentId);
+      if (result.successful > 0) {
+        logger3.info(
+          `KnowledgeService: Loaded ${result.successful} documents from docs folder on startup for agent ${this.runtime.agentId}`
+        );
+      } else {
+        logger3.info(
+          `KnowledgeService: No new documents found to load on startup for agent ${this.runtime.agentId}`
+        );
+      }
+    } catch (error) {
+      logger3.error(
+        `KnowledgeService: Error loading documents on startup for agent ${this.runtime.agentId}:`,
+        error
+      );
+    }
   }
-  static serviceType = KnowledgeServiceType.KNOWLEDGE;
-  capabilityDescription = "Provides Retrieval Augmented Generation capabilities, including knowledge upload and querying.";
-  knowledgeProcessingSemaphore;
   /**
    * Start the Knowledge service
    * @param runtime Agent runtime
    * @returns Initialized Knowledge service
    */
   static async start(runtime) {
-    logger4.info(`Starting Knowledge service for agent: ${runtime.agentId}`);
+    logger3.info(`Starting Knowledge service for agent: ${runtime.agentId}`);
     const service = new _KnowledgeService(runtime);
     if (service.runtime.character?.knowledge && service.runtime.character.knowledge.length > 0) {
-      logger4.info(
+      logger3.info(
         `KnowledgeService: Processing ${service.runtime.character.knowledge.length} character knowledge items.`
       );
       const stringKnowledge = service.runtime.character.knowledge.filter(
         (item) => typeof item === "string"
       );
-      service.processCharacterKnowledge(stringKnowledge).catch((err) => {
-        logger4.error(
+      await service.processCharacterKnowledge(stringKnowledge).catch((err) => {
+        logger3.error(
           `KnowledgeService: Error processing character knowledge during startup: ${err.message}`,
           err
         );
       });
     } else {
-      logger4.info(
+      logger3.info(
         `KnowledgeService: No character knowledge to process for agent ${runtime.agentId}.`
       );
     }
@@ -1387,21 +1290,17 @@ var KnowledgeService = class _KnowledgeService extends Service {
    * @param runtime Agent runtime
    */
   static async stop(runtime) {
-    logger4.info(`Stopping Knowledge service for agent: ${runtime.agentId}`);
+    logger3.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.`
-      );
+      logger3.warn(`KnowledgeService not found for agent ${runtime.agentId} during stop.`);
     }
   }
   /**
    * Stop the service
    */
   async stop() {
-    logger4.info(
-      `Knowledge service stopping for agent: ${this.runtime.agentId}`
-    );
+    logger3.info(`Knowledge service stopping for agent: ${this.runtime.agentId}`);
   }
   /**
    * Add knowledge to the system
@@ -1410,15 +1309,13 @@ var KnowledgeService = class _KnowledgeService extends Service {
    */
   async addKnowledge(options) {
     const agentId = this.runtime.agentId;
-    logger4.info(
+    logger3.info(
       `KnowledgeService (agent: ${agentId}) processing document for public addKnowledge: ${options.originalFilename}, type: ${options.contentType}`
     );
     try {
-      const existingDocument = await this.runtime.getMemoryById(
-        options.clientDocumentId
-      );
+      const existingDocument = await this.runtime.getMemoryById(options.clientDocumentId);
       if (existingDocument && existingDocument.metadata?.type === MemoryType2.DOCUMENT) {
-        logger4.info(
+        logger3.info(
           `Document ${options.originalFilename} with ID ${options.clientDocumentId} already exists. Skipping processing.`
         );
         const fragments = await this.runtime.getMemories({
@@ -1437,7 +1334,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         };
       }
     } catch (error) {
-      logger4.debug(
+      logger3.debug(
         `Document ${options.clientDocumentId} not found or error checking existence, proceeding with processing: ${error instanceof Error ? error.message : String(error)}`
       );
     }
@@ -1459,45 +1356,74 @@ var KnowledgeService = class _KnowledgeService extends Service {
   }) {
     const agentId = this.runtime.agentId;
     try {
-      logger4.debug(
+      logger3.debug(
         `KnowledgeService: Processing document ${originalFilename} (type: ${contentType}) via processDocument`
       );
       let fileBuffer = null;
       let extractedText;
+      let documentContentToStore;
       const isPdfFile = contentType === "application/pdf" || originalFilename.toLowerCase().endsWith(".pdf");
-      const isBinaryFile = this.isBinaryContentType(
-        contentType,
-        originalFilename
-      );
-      if (isBinaryFile) {
+      if (isPdfFile) {
         try {
           fileBuffer = Buffer.from(content, "base64");
         } catch (e) {
-          logger4.error(
+          logger3.error(
             `KnowledgeService: Failed to convert base64 to buffer for ${originalFilename}: ${e.message}`
           );
-          throw new Error(
-            `Invalid base64 content for binary file ${originalFilename}`
+          throw new Error(`Invalid base64 content for PDF file ${originalFilename}`);
+        }
+        extractedText = await extractTextFromDocument(fileBuffer, contentType, originalFilename);
+        documentContentToStore = content;
+      } else if (isBinaryContentType(contentType, originalFilename)) {
+        try {
+          fileBuffer = Buffer.from(content, "base64");
+        } catch (e) {
+          logger3.error(
+            `KnowledgeService: Failed to convert base64 to buffer for ${originalFilename}: ${e.message}`
           );
+          throw new Error(`Invalid base64 content for binary file ${originalFilename}`);
         }
-        extractedText = await extractTextFromDocument(
-          fileBuffer,
-          contentType,
-          originalFilename
-        );
+        extractedText = await extractTextFromDocument(fileBuffer, contentType, originalFilename);
+        documentContentToStore = extractedText;
       } else {
-        extractedText = content;
+        const base64Regex = /^[A-Za-z0-9+/]+=*$/;
+        const looksLikeBase64 = content && content.length > 0 && base64Regex.test(content.replace(/\s/g, ""));
+        if (looksLikeBase64) {
+          try {
+            const decodedBuffer = Buffer.from(content, "base64");
+            const decodedText = decodedBuffer.toString("utf8");
+            const invalidCharCount = (decodedText.match(/\ufffd/g) || []).length;
+            const textLength = decodedText.length;
+            if (invalidCharCount > 0 && invalidCharCount / textLength > 0.1) {
+              throw new Error("Decoded content contains too many invalid characters");
+            }
+            logger3.debug(`Successfully decoded base64 content for text file: ${originalFilename}`);
+            extractedText = decodedText;
+            documentContentToStore = decodedText;
+          } catch (e) {
+            logger3.error(
+              `Failed to decode base64 for ${originalFilename}: ${e instanceof Error ? e.message : String(e)}`
+            );
+            throw new Error(
+              `File ${originalFilename} appears to be corrupted or incorrectly encoded`
+            );
+          }
+        } else {
+          logger3.debug(`Treating content as plain text for file: ${originalFilename}`);
+          extractedText = content;
+          documentContentToStore = content;
+        }
       }
       if (!extractedText || extractedText.trim() === "") {
         const noTextError = new Error(
           `KnowledgeService: No text content extracted from ${originalFilename} (type: ${contentType}).`
         );
-        logger4.warn(noTextError.message);
+        logger3.warn(noTextError.message);
         throw noTextError;
       }
       const documentMemory = createDocumentMemory({
-        text: isPdfFile ? content : extractedText,
-        // Store base64 for PDF, text for others
+        text: documentContentToStore,
+        // Store base64 only for PDFs, plain text for everything else
         agentId,
         clientDocumentId,
         // This becomes the memory.id
@@ -1516,7 +1442,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         entityId: entityId || agentId
       };
       await this.runtime.createMemory(memoryWithScope, "documents");
-      logger4.debug(
+      logger3.debug(
         `KnowledgeService: Stored document ${originalFilename} (Memory ID: ${memoryWithScope.id})`
       );
       const fragmentCount = await processFragmentsSynchronously({
@@ -1530,7 +1456,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
         entityId: entityId || agentId,
         worldId: worldId || agentId
       });
-      logger4.info(
+      logger3.info(
         `KnowledgeService: Document ${originalFilename} processed with ${fragmentCount} fragments for agent ${agentId}`
       );
       return {
@@ -1539,65 +1465,16 @@ var KnowledgeService = class _KnowledgeService extends Service {
         fragmentCount
       };
     } catch (error) {
-      logger4.error(
+      logger3.error(
         `KnowledgeService: Error processing document ${originalFilename}: ${error.message}`,
         error.stack
       );
       throw error;
     }
   }
-  /**
-   * Determines if a file should be treated as binary based on its content type and filename
-   * @param contentType MIME type of the file
-   * @param filename Original filename
-   * @returns True if the file should be treated as binary (base64 encoded)
-   */
-  isBinaryContentType(contentType, filename) {
-    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 binaryExtensions = [
-      "pdf",
-      "docx",
-      "doc",
-      "xls",
-      "xlsx",
-      "ppt",
-      "pptx",
-      "zip",
-      "jpg",
-      "jpeg",
-      "png",
-      "gif",
-      "mp3",
-      "mp4",
-      "wav"
-    ];
-    return binaryExtensions.includes(fileExt);
-  }
   // --- Knowledge methods moved from AgentRuntime ---
   async handleProcessingError(error, context) {
-    logger4.error(
-      `KnowledgeService: Error ${context}:`,
-      error?.message || error || "Unknown error"
-    );
+    logger3.error(`KnowledgeService: Error ${context}:`, error?.message || error || "Unknown error");
     throw error;
   }
   async checkExistingKnowledge(knowledgeId) {
@@ -1605,13 +1482,9 @@ var KnowledgeService = class _KnowledgeService extends Service {
     return !!existingDocument;
   }
   async getKnowledge(message, scope) {
-    logger4.debug(
-      "KnowledgeService: getKnowledge called for message id: " + message.id
-    );
+    logger3.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."
-      );
+      logger3.warn("KnowledgeService: Invalid or empty message content for knowledge query.");
       return [];
     }
     const embedding = await this.runtime.useModel(ModelType2.TEXT_EMBEDDING, {
@@ -1642,7 +1515,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
   }
   async processCharacterKnowledge(items) {
     await new Promise((resolve) => setTimeout(resolve, 1e3));
-    logger4.info(
+    logger3.info(
       `KnowledgeService: Processing ${items.length} character knowledge items for agent ${this.runtime.agentId}`
     );
     const processingPromises = items.map(async (item) => {
@@ -1650,12 +1523,12 @@ var KnowledgeService = class _KnowledgeService extends Service {
       try {
         const knowledgeId = createUniqueUuid(this.runtime.agentId + item, item);
         if (await this.checkExistingKnowledge(knowledgeId)) {
-          logger4.debug(
+          logger3.debug(
             `KnowledgeService: Character knowledge item with ID ${knowledgeId} already exists. Skipping.`
           );
           return;
         }
-        logger4.debug(
+        logger3.debug(
           `KnowledgeService: Processing character knowledge for ${this.runtime.character?.name} - ${item.slice(0, 100)}`
         );
         let metadata = {
@@ -1700,21 +1573,16 @@ var KnowledgeService = class _KnowledgeService extends Service {
           }
         );
       } catch (error) {
-        await this.handleProcessingError(
-          error,
-          "processing character knowledge"
-        );
+        await this.handleProcessingError(error, "processing character knowledge");
       } finally {
         this.knowledgeProcessingSemaphore.release();
       }
     });
     await Promise.all(processingPromises);
-    logger4.info(
+    logger3.info(
       `KnowledgeService: Finished processing character knowledge for agent ${this.runtime.agentId}.`
     );
   }
-  // Renamed from AgentRuntime's addKnowledge
-  // This is the core logic for adding text-based knowledge items and creating fragments.
   async _internalAddKnowledge(item, options = {
     targetTokens: 1500,
     // TODO: Make these configurable, perhaps from plugin config
@@ -1731,9 +1599,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}`
-    );
+    logger3.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.
@@ -1755,7 +1621,7 @@ var KnowledgeService = class _KnowledgeService extends Service {
     };
     const existingDocument = await this.runtime.getMemoryById(item.id);
     if (existingDocument) {
-      logger4.debug(
+      logger3.debug(
         `KnowledgeService: Document ${item.id} already exists in _internalAddKnowledge, updating...`
       );
       await this.runtime.updateMemory({
@@ -1779,16 +1645,28 @@ var KnowledgeService = class _KnowledgeService extends Service {
         await this.processDocumentFragment(fragment);
         fragmentsProcessed++;
       } catch (error) {
-        logger4.error(
+        logger3.error(
           `KnowledgeService: Error processing fragment ${fragment.id} for document ${item.id}:`,
           error
         );
       }
     }
-    logger4.debug(
+    logger3.debug(
       `KnowledgeService: Processed ${fragmentsProcessed}/${fragments.length} fragments for document ${item.id}.`
     );
   }
+  async processDocumentFragment(fragment) {
+    try {
+      await this.runtime.addEmbeddingToMemory(fragment);
+      await this.runtime.createMemory(fragment, "knowledge");
+    } catch (error) {
+      logger3.error(
+        `KnowledgeService: Error processing fragment ${fragment.id}:`,
+        error instanceof Error ? error.message : String(error)
+      );
+      throw error;
+    }
+  }
   async splitAndCreateFragments(document, targetTokens, overlap, scope) {
     if (!document.content.text) {
       return [];
@@ -1827,19 +1705,37 @@ var KnowledgeService = class _KnowledgeService extends Service {
       };
     });
   }
-  async processDocumentFragment(fragment) {
-    try {
-      await this.runtime.addEmbeddingToMemory(fragment);
-      await this.runtime.createMemory(fragment, "knowledge");
-    } catch (error) {
-      logger4.error(
-        `KnowledgeService: Error processing fragment ${fragment.id}:`,
-        error instanceof Error ? error.message : String(error)
+  // ADDED METHODS START
+  /**
+   * Retrieves memories, typically documents, for the agent.
+   * Corresponds to GET /plugins/knowledge/documents
+   */
+  async getMemories(params) {
+    if (params.tableName !== "documents") {
+      logger3.warn(
+        `KnowledgeService.getMemories called with tableName ${params.tableName}, but this service primarily manages 'documents'. Proceeding, but review usage.`
       );
-      throw error;
     }
+    return this.runtime.getMemories({
+      ...params,
+      // includes tableName, roomId, count, end
+      agentId: this.runtime.agentId
+      // Ensure agentId is correctly scoped
+    });
+  }
+  /**
+   * Deletes a specific memory item (knowledge document) by its ID.
+   * Corresponds to DELETE /plugins/knowledge/documents/:knowledgeId
+   * Assumes the memoryId corresponds to an item in the 'documents' table or that
+   * runtime.deleteMemory can correctly identify it.
+   */
+  async deleteMemory(memoryId) {
+    await this.runtime.deleteMemory(memoryId);
+    logger3.info(
+      `KnowledgeService: Deleted memory ${memoryId} for agent ${this.runtime.agentId}. Assumed it was a document or related fragment.`
+    );
   }
-  // --- End of moved knowledge methods ---
+  // ADDED METHODS END
 };
 
 // src/provider.ts
@@ -2415,7 +2311,9 @@ var KnowledgeTestSuite = class {
           contentType: "text/plain",
           originalFilename: "knowledge-test.txt",
           worldId: runtime.agentId,
-          content: "This is test knowledge that should be stored and retrievable."
+          content: "This is test knowledge that should be stored and retrievable.",
+          roomId: runtime.agentId,
+          entityId: runtime.agentId
         };
         const result = await service.addKnowledge(testDocument);
         if (result.clientDocumentId !== testDocument.clientDocumentId) {
@@ -2446,7 +2344,9 @@ var KnowledgeTestSuite = class {
           contentType: "text/plain",
           originalFilename: "duplicate-test.txt",
           worldId: runtime.agentId,
-          content: "This document will be uploaded twice."
+          content: "This document will be uploaded twice.",
+          roomId: runtime.agentId,
+          entityId: runtime.agentId
         };
         const result1 = await service.addKnowledge(testDocument);
         const result2 = await service.addKnowledge(testDocument);
@@ -2470,7 +2370,9 @@ var KnowledgeTestSuite = class {
           contentType: "text/plain",
           originalFilename: "retrieval-test.txt",
           worldId: runtime.agentId,
-          content: "The capital of France is Paris. Paris is known for the Eiffel Tower."
+          content: "The capital of France is Paris. Paris is known for the Eiffel Tower.",
+          roomId: runtime.agentId,
+          entityId: runtime.agentId
         };
         await service.addKnowledge(testDocument);
         const queryMessage = {
@@ -2506,7 +2408,9 @@ var KnowledgeTestSuite = class {
           contentType: "text/plain",
           originalFilename: "provider-test.txt",
           worldId: runtime.agentId,
-          content: "Important fact 1. Important fact 2. Important fact 3."
+          content: "Important fact 1. Important fact 2. Important fact 3.",
+          roomId: runtime.agentId,
+          entityId: runtime.agentId
         };
         await service.addKnowledge(testDocument);
         const message = {
@@ -2604,8 +2508,10 @@ var KnowledgeTestSuite = class {
             contentType: "text/plain",
             originalFilename: "empty.txt",
             worldId: runtime.agentId,
-            content: ""
+            content: "",
             // Empty content should cause an error
+            roomId: runtime.agentId,
+            entityId: runtime.agentId
           });
           throw new Error("Expected error for empty content");
         } catch (error) {
@@ -2618,8 +2524,10 @@ var KnowledgeTestSuite = class {
             contentType: "text/plain",
             originalFilename: "null-content.txt",
             worldId: runtime.agentId,
-            content: null
+            content: null,
             // This should definitely cause an error
+            roomId: runtime.agentId,
+            entityId: runtime.agentId
           });
         } catch (error) {
         }
@@ -2652,7 +2560,9 @@ var KnowledgeTestSuite = class {
             Unlike classical bits, qubits can exist in superposition.
             This allows quantum computers to process many calculations simultaneously.
             Major companies like IBM, Google, and Microsoft are developing quantum computers.
-          `
+          `,
+          roomId: runtime.agentId,
+          entityId: runtime.agentId
         };
         const addResult = await service.addKnowledge(document);
         if (addResult.fragmentCount === 0) {
@@ -2704,7 +2614,9 @@ var KnowledgeTestSuite = class {
           contentType: "text/plain",
           originalFilename: "large-document.txt",
           worldId: runtime.agentId,
-          content: largeContent
+          content: largeContent,
+          roomId: runtime.agentId,
+          entityId: runtime.agentId
         };
         const result = await service.addKnowledge(document);
         if (result.fragmentCount < 2) {
@@ -2730,7 +2642,6 @@ var KnowledgeTestSuite = class {
       name: "Should detect binary content types correctly",
       fn: async (runtime) => {
         const service = await KnowledgeService.start(runtime);
-        const isBinary = service.isBinaryContentType.bind(service);
         const binaryTypes = [
           { type: "application/pdf", filename: "test.pdf", expected: true },
           { type: "image/png", filename: "test.png", expected: true },
@@ -2748,7 +2659,7 @@ var KnowledgeTestSuite = class {
           }
         ];
         for (const test of binaryTypes) {
-          const result = isBinary(test.type, test.filename);
+          const result = isBinaryContentType(test.type, test.filename);
           if (result !== test.expected) {
             throw new Error(
               `Binary detection failed for ${test.type}/${test.filename}. Expected ${test.expected}, got ${result}`
@@ -2763,22 +2674,13 @@ var KnowledgeTestSuite = class {
 var tests_default = new KnowledgeTestSuite();
 
 // src/actions.ts
-import { logger as logger5 } from "@elizaos/core";
+import { logger as logger4, createUniqueUuid as createUniqueUuid2 } from "@elizaos/core";
 import * as fs2 from "fs";
 import * as path2 from "path";
 var processKnowledgeAction = {
   name: "PROCESS_KNOWLEDGE",
   description: "Process and store knowledge from a file path or text content into the knowledge base",
-  similes: [
-    "add knowledge",
-    "upload document",
-    "store information",
-    "add to knowledge base",
-    "learn from document",
-    "ingest file",
-    "process document",
-    "remember this"
-  ],
+  similes: [],
   examples: [
     [
       {
@@ -2832,7 +2734,7 @@ var processKnowledgeAction = {
     const hasPath = pathPattern.test(text);
     const service = runtime.getService(KnowledgeService.serviceType);
     if (!service) {
-      logger5.warn(
+      logger4.warn(
         "Knowledge service not available for PROCESS_KNOWLEDGE action"
       );
       return false;
@@ -2873,7 +2775,7 @@ var processKnowledgeAction = {
         else if ([".txt", ".md", ".tson", ".xml", ".csv"].includes(fileExt))
           contentType = "text/plain";
         const knowledgeOptions = {
-          clientDocumentId: `${runtime.agentId}-${Date.now()}-${fileName}`,
+          clientDocumentId: createUniqueUuid2(runtime.agentId + fileName + Date.now(), fileName),
           contentType,
           originalFilename: fileName,
           worldId: runtime.agentId,
@@ -2900,7 +2802,7 @@ var processKnowledgeAction = {
           return;
         }
         const knowledgeOptions = {
-          clientDocumentId: `${runtime.agentId}-${Date.now()}-text`,
+          clientDocumentId: createUniqueUuid2(runtime.agentId + "text" + Date.now(), "user-knowledge"),
           contentType: "text/plain",
           originalFilename: "user-knowledge.txt",
           worldId: runtime.agentId,
@@ -2917,7 +2819,7 @@ var processKnowledgeAction = {
         await callback(response);
       }
     } catch (error) {
-      logger5.error("Error in PROCESS_KNOWLEDGE action:", error);
+      logger4.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"}`
       };
@@ -3028,7 +2930,7 @@ ${formattedResults}`
         await callback(response);
       }
     } catch (error) {
-      logger5.error("Error in SEARCH_KNOWLEDGE action:", error);
+      logger4.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"}`
       };
@@ -3040,26 +2942,297 @@ ${formattedResults}`
 };
 var knowledgeActions = [processKnowledgeAction, searchKnowledgeAction];
 
+// src/routes.ts
+import { MemoryType as MemoryType4, createUniqueUuid as createUniqueUuid3, logger as logger5 } from "@elizaos/core";
+import fs3 from "fs";
+import path3 from "path";
+function sendSuccess(res, data, status = 200) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ success: true, data }));
+}
+function sendError(res, status, code, message, details) {
+  res.writeHead(status, { "Content-Type": "application/json" });
+  res.end(JSON.stringify({ success: false, error: { code, message, details } }));
+}
+var cleanupFile = (filePath) => {
+  if (filePath && fs3.existsSync(filePath)) {
+    try {
+      fs3.unlinkSync(filePath);
+    } catch (error) {
+      logger5.error(`Error cleaning up file ${filePath}:`, error);
+    }
+  }
+};
+var cleanupFiles = (files) => {
+  if (files) {
+    files.forEach((file) => cleanupFile(file.path));
+  }
+};
+async function uploadKnowledgeHandler(req, res, runtime) {
+  const service = runtime.getService(KnowledgeService.serviceType);
+  if (!service) {
+    return sendError(res, 500, "SERVICE_NOT_FOUND", "KnowledgeService not found");
+  }
+  const files = req.files;
+  if (!files || files.length === 0) {
+    return sendError(res, 400, "NO_FILES", "No files uploaded");
+  }
+  try {
+    const processingPromises = files.map(async (file, index) => {
+      let knowledgeId;
+      const originalFilename = file.originalname;
+      const worldId = req.body.worldId || runtime.agentId;
+      const filePath = file.path;
+      knowledgeId = req.body?.documentIds && req.body.documentIds[index] || req.body?.documentId || createUniqueUuid3(runtime, `knowledge-${originalFilename}-${Date.now()}`);
+      try {
+        const fileBuffer = await fs3.promises.readFile(filePath);
+        const fileExt = file.originalname.split(".").pop()?.toLowerCase() || "";
+        const filename = file.originalname;
+        const title = filename.replace(`.${fileExt}`, "");
+        const base64Content = fileBuffer.toString("base64");
+        const knowledgeItem = {
+          id: knowledgeId,
+          content: {
+            text: base64Content
+          },
+          metadata: {
+            type: MemoryType4.DOCUMENT,
+            timestamp: Date.now(),
+            source: "upload",
+            filename,
+            fileExt,
+            title,
+            path: originalFilename,
+            fileType: file.mimetype,
+            fileSize: file.size
+          }
+        };
+        const addKnowledgeOpts = {
+          clientDocumentId: knowledgeId,
+          // This is knowledgeItem.id
+          contentType: file.mimetype,
+          // Directly from multer file object
+          originalFilename,
+          // Directly from multer file object
+          content: base64Content,
+          // The base64 string of the file
+          worldId,
+          roomId: runtime.agentId,
+          // Or a more specific room ID if available
+          entityId: runtime.agentId
+        };
+        await service.addKnowledge(addKnowledgeOpts);
+        cleanupFile(filePath);
+        return {
+          id: knowledgeId,
+          filename: originalFilename,
+          type: file.mimetype,
+          size: file.size,
+          uploadedAt: Date.now(),
+          status: "success"
+        };
+      } catch (fileError) {
+        logger5.error(
+          `[KNOWLEDGE UPLOAD HANDLER] Error processing file ${file.originalname}: ${fileError}`
+        );
+        cleanupFile(filePath);
+        return {
+          id: knowledgeId,
+          filename: originalFilename,
+          status: "error_processing",
+          error: fileError.message
+        };
+      }
+    });
+    const results = await Promise.all(processingPromises);
+    sendSuccess(res, results);
+  } catch (error) {
+    logger5.error("[KNOWLEDGE UPLOAD HANDLER] Error uploading knowledge:", error);
+    cleanupFiles(files);
+    sendError(res, 500, "UPLOAD_ERROR", "Failed to upload knowledge", error.message);
+  }
+}
+async function getKnowledgeDocumentsHandler(req, res, runtime) {
+  const service = runtime.getService(KnowledgeService.serviceType);
+  if (!service) {
+    return sendError(
+      res,
+      500,
+      "SERVICE_NOT_FOUND",
+      "KnowledgeService not found for getKnowledgeDocumentsHandler"
+    );
+  }
+  try {
+    const limit = req.query.limit ? Number.parseInt(req.query.limit, 10) : 20;
+    const before = req.query.before ? Number.parseInt(req.query.before, 10) : Date.now();
+    const includeEmbedding = req.query.includeEmbedding === "true";
+    const memories = await service.getMemories({
+      tableName: "documents",
+      count: limit,
+      end: before
+    });
+    const cleanMemories = includeEmbedding ? memories : memories.map((memory) => ({
+      ...memory,
+      embedding: void 0
+    }));
+    sendSuccess(res, { memories: cleanMemories });
+  } catch (error) {
+    logger5.error("[KNOWLEDGE GET HANDLER] Error retrieving documents:", error);
+    sendError(res, 500, "RETRIEVAL_ERROR", "Failed to retrieve documents", error.message);
+  }
+}
+async function deleteKnowledgeDocumentHandler(req, res, runtime) {
+  const service = runtime.getService(KnowledgeService.serviceType);
+  if (!service) {
+    return sendError(
+      res,
+      500,
+      "SERVICE_NOT_FOUND",
+      "KnowledgeService not found for deleteKnowledgeDocumentHandler"
+    );
+  }
+  const knowledgeId = req.path.split("/documents/")[1];
+  if (!knowledgeId || knowledgeId.length < 36) {
+    return sendError(res, 400, "INVALID_ID", "Invalid Knowledge ID format");
+  }
+  try {
+    await service.deleteMemory(knowledgeId);
+    sendSuccess(res, null, 204);
+  } catch (error) {
+    logger5.error(`[KNOWLEDGE DELETE HANDLER] Error deleting document ${knowledgeId}:`, error);
+    sendError(res, 500, "DELETE_ERROR", "Failed to delete document", error.message);
+  }
+}
+async function knowledgePanelHandler(req, res, runtime) {
+  try {
+    const currentDir = path3.dirname(new URL(import.meta.url).pathname);
+    const frontendPath = path3.join(currentDir, "../dist/index.html");
+    if (fs3.existsSync(frontendPath)) {
+      const html = await fs3.promises.readFile(frontendPath, "utf8");
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(html);
+    } else {
+      const html = `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>Knowledge</title>
+    <link rel="stylesheet" href="./assets/index-BlRATUqY.css">
+    <style>
+        body { font-family: system-ui, -apple-system, sans-serif; margin: 0; padding: 20px; }
+        .container { max-width: 1200px; margin: 0 auto; }
+        .loading { text-align: center; padding: 40px; color: #666; }
+    </style>
+</head>
+<body>
+    <div class="container">
+        <div id="knowledge-root">
+            <div class="loading">Loading Knowledge Library...</div>
+        </div>
+    </div>
+    <script type="module" src="./assets/index-7riujMow.js"></script>
+</body>
+</html>`;
+      res.writeHead(200, { "Content-Type": "text/html" });
+      res.end(html);
+    }
+  } catch (error) {
+    logger5.error("[KNOWLEDGE PANEL] Error serving frontend:", error);
+    sendError(res, 500, "FRONTEND_ERROR", "Failed to load knowledge panel", error.message);
+  }
+}
+async function frontendAssetHandler(req, res, runtime) {
+  try {
+    logger5.debug(
+      `[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);
+    const assetRequestPath = req.path;
+    const assetsMarker = "/assets/";
+    const assetsStartIndex = assetRequestPath.indexOf(assetsMarker);
+    let assetName = null;
+    if (assetsStartIndex !== -1) {
+      assetName = assetRequestPath.substring(assetsStartIndex + assetsMarker.length);
+    }
+    if (!assetName || assetName.includes("..")) {
+      return sendError(
+        res,
+        400,
+        "BAD_REQUEST",
+        `Invalid asset name: '${assetName}' from path ${assetRequestPath}`
+      );
+    }
+    const assetPath = path3.join(currentDir, "../dist/assets", assetName);
+    logger5.debug(`[KNOWLEDGE ASSET HANDLER] Attempting to serve asset: ${assetPath}`);
+    if (fs3.existsSync(assetPath)) {
+      const fileStream = fs3.createReadStream(assetPath);
+      let contentType = "application/octet-stream";
+      if (assetPath.endsWith(".js")) {
+        contentType = "application/javascript";
+      } else if (assetPath.endsWith(".css")) {
+        contentType = "text/css";
+      }
+      res.writeHead(200, { "Content-Type": contentType });
+      fileStream.pipe(res);
+    } else {
+      sendError(res, 404, "NOT_FOUND", `Asset not found: ${req.url}`);
+    }
+  } catch (error) {
+    logger5.error(`[KNOWLEDGE ASSET HANDLER] Error serving asset ${req.url}:`, error);
+    sendError(res, 500, "ASSET_ERROR", `Failed to load asset ${req.url}`, error.message);
+  }
+}
+var knowledgeRoutes = [
+  {
+    type: "GET",
+    name: "Knowledge",
+    path: "/display",
+    handler: knowledgePanelHandler,
+    public: true
+  },
+  {
+    type: "GET",
+    path: "/assets/*",
+    handler: frontendAssetHandler
+  },
+  {
+    type: "POST",
+    path: "/upload",
+    handler: uploadKnowledgeHandler,
+    isMultipart: true
+  },
+  {
+    type: "GET",
+    path: "/documents",
+    handler: getKnowledgeDocumentsHandler
+  },
+  {
+    type: "DELETE",
+    path: "/documents/*",
+    handler: deleteKnowledgeDocumentHandler
+  }
+];
+
 // src/index.ts
 var knowledgePlugin = {
   name: "knowledge",
   description: "Plugin for Retrieval Augmented Generation, including knowledge management and embedding.",
   config: {
-    // Token limits
-    MAX_INPUT_TOKENS: process.env.MAX_INPUT_TOKENS,
-    MAX_OUTPUT_TOKENS: process.env.MAX_OUTPUT_TOKENS,
+    // 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: process.env.CTX_KNOWLEDGE_ENABLED || "false"
+    CTX_KNOWLEDGE_ENABLED: "false"
   },
   async init(config, runtime) {
     logger6.info("Initializing Knowledge Plugin...");
     try {
       logger6.info("Validating model configuration for Knowledge plugin...");
-      const validatedConfig = validateModelConfig();
+      const validatedConfig = validateModelConfig(runtime);
       if (validatedConfig.CTX_KNOWLEDGE_ENABLED) {
-        logger6.info(
-          "Running in Contextual Knowledge mode with text generation capabilities."
-        );
+        logger6.info("Running in Contextual Knowledge mode with text generation capabilities.");
         logger6.info(
           `Using ${validatedConfig.EMBEDDING_PROVIDER} for embeddings and ${validatedConfig.TEXT_PROVIDER} for text generation.`
         );
@@ -3080,21 +3253,17 @@ var knowledgePlugin = {
       }
       logger6.info("Model configuration validated successfully.");
       if (runtime) {
-        logger6.info(
-          `Knowledge Plugin initialized for agent: ${runtime.agentId}`
-        );
+        logger6.info(`Knowledge Plugin initialized for agent: ${runtime.agentId}`);
         const loadDocsOnStartup = config.LOAD_DOCS_ON_STARTUP !== "false" && process.env.LOAD_DOCS_ON_STARTUP !== "false";
         if (loadDocsOnStartup) {
           setTimeout(async () => {
             try {
               const service = runtime.getService(KnowledgeService.serviceType);
               if (service instanceof KnowledgeService) {
-                const { loadDocsFromPath } = await import("./docs-loader-3LDO3WCY.js");
-                const result = await loadDocsFromPath(service, runtime.agentId);
+                const { loadDocsFromPath: loadDocsFromPath2 } = await import("./docs-loader-25N4HXDV.js");
+                const result = await loadDocsFromPath2(service, runtime.agentId);
                 if (result.successful > 0) {
-                  logger6.info(
-                    `Loaded ${result.successful} documents from docs folder on startup`
-                  );
+                  logger6.info(`Loaded ${result.successful} documents from docs folder on startup`);
                 }
               }
             } catch (error) {
@@ -3103,7 +3272,9 @@ var knowledgePlugin = {
           }, 5e3);
         }
       }
-      logger6.info("Knowledge Plugin initialized.");
+      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;
@@ -3111,11 +3282,14 @@ var knowledgePlugin = {
   },
   services: [KnowledgeService],
   providers: [knowledgeProvider],
+  routes: knowledgeRoutes,
   actions: knowledgeActions,
   tests: [tests_default]
 };
 var index_default = knowledgePlugin;
 export {
+  KnowledgeServiceType,
+  ModelConfigSchema,
   index_default as default,
   knowledgePlugin
 };