@elizaos/plugin-knowledge 1.5.11 → 1.5.12

package/README.md

@@ -2,6 +2,67 @@
 
 Give your AI agent the ability to learn from documents and answer questions based on that knowledge. Works out of the box with zero configuration!
 
+## 📦 Installation Modes
+
+The Knowledge plugin supports multiple deployment modes to fit your use case:
+
+### **Full Mode** (Default - With UI & Routes)
+
+Perfect for standard deployments with the full web interface:
+
+```typescript
+import { knowledgePlugin } from '@elizaos/plugin-knowledge';
+// or
+import knowledgePlugin from '@elizaos/plugin-knowledge';
+
+export const character = {
+  plugins: [knowledgePlugin],
+};
+```
+
+### **Headless Mode** (Service + Provider + Actions, No UI)
+
+For server deployments without frontend:
+
+```typescript
+import { knowledgePluginHeadless } from '@elizaos/plugin-knowledge';
+
+export const character = {
+  plugins: [knowledgePluginHeadless],
+};
+```
+
+### **Core Mode** (Service + Provider Only)
+
+For cloud runtimes or minimal deployments (no routes, no UI, no actions):
+
+```typescript
+import { knowledgePluginCore } from '@elizaos/plugin-knowledge';
+
+export const character = {
+  plugins: [knowledgePluginCore],
+};
+```
+
+### **Custom Configuration**
+
+Create your own configuration:
+
+```typescript
+import { createKnowledgePlugin } from '@elizaos/plugin-knowledge';
+
+const customPlugin = createKnowledgePlugin({
+  enableUI: false, // Disable frontend UI
+  enableRoutes: false, // Disable HTTP routes
+  enableActions: true, // Keep actions enabled
+  enableTests: false, // Disable tests
+});
+
+export const character = {
+  plugins: [customPlugin],
+};
+```
+
 ## 🚀 Getting Started (Beginner-Friendly)
 
 ### Step 1: Add the Plugin
@@ -14,7 +75,7 @@ export const character = {
   name: 'MyAgent',
   plugins: [
     '@elizaos/plugin-openai', // ← Make sure you have this
-    '@elizaos/plugin-knowledge', // ← Add this line
+    '@elizaos/plugin-knowledge', // ← Add this line (full mode)
     // ... your other plugins
   ],
   // ... rest of your character config
@@ -192,28 +253,68 @@ MAX_OUTPUT_TOKENS=4096             # Response size limit
 ```typescript
 import { KnowledgeService } from '@elizaos/plugin-knowledge';
 
+// Get the service from runtime
+const knowledgeService = runtime.getService<KnowledgeService>(KnowledgeService.serviceType);
+
 // Add knowledge programmatically
 const result = await knowledgeService.addKnowledge({
-  clientDocumentId: 'unique-doc-id',
+  agentId: runtime.agentId,
+  clientDocumentId: '' as UUID, // Auto-generated based on content
   content: documentContent, // Base64 for PDFs, plain text for others
   contentType: 'application/pdf',
   originalFilename: 'document.pdf',
-  worldId: runtime.worldId,
-  roomId: runtime.roomId,
-  entityId: runtime.entityId,
+  worldId: runtime.agentId,
+  roomId: runtime.agentId,
+  entityId: runtime.agentId,
   metadata: {
-    // Optional
+    // Optional custom metadata
     source: 'upload',
     author: 'John Doe',
   },
 });
 
-// Search knowledge
-const searchResults = await knowledgeService.searchKnowledge({
-  query: 'quantum computing',
+// The provider automatically retrieves relevant knowledge during conversations
+// But you can also search directly:
+const knowledgeItems = await knowledgeService.getKnowledge(
+  message, // The message/query
+  {
+    roomId: runtime.agentId,
+    worldId: runtime.agentId,
+    entityId: runtime.agentId,
+  }
+);
+```
+
+### Cloud/Custom Runtime Usage
+
+For cloud deployments or custom runtimes, use the core mode and access the service directly:
+
+```typescript
+import { knowledgePluginCore, KnowledgeService } from '@elizaos/plugin-knowledge';
+
+// In your cloud runtime setup
+const runtime = await createRuntime({
+  // ... your runtime config
+  plugins: [knowledgePluginCore], // Core mode: no routes, no UI
+});
+
+// Access the service
+const knowledgeService = runtime.getService<KnowledgeService>(KnowledgeService.serviceType);
+
+// Add documents
+await knowledgeService.addKnowledge({
   agentId: runtime.agentId,
-  limit: 10,
+  clientDocumentId: '' as UUID,
+  content: base64Content,
+  contentType: 'application/pdf',
+  originalFilename: 'company-docs.pdf',
+  worldId: runtime.agentId,
+  roomId: runtime.agentId,
+  entityId: runtime.agentId,
 });
+
+// The knowledge provider will automatically inject relevant context
+// into the agent's conversations based on the query
 ```
 
 </details>

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { UUID, Plugin } from '@elizaos/core';
+import { UUID, Service, Metadata, IAgentRuntime, Memory, KnowledgeItem, Provider, Plugin } from '@elizaos/core';
 import z from 'zod';
 
 declare const ModelConfigSchema: z.ZodObject<{
@@ -179,6 +179,146 @@ interface ExtendedMemoryMetadata extends Record<string, any> {
     url?: string;
 }
 
+/**
+ * Knowledge Service - Provides retrieval augmented generation capabilities
+ */
+declare class KnowledgeService extends Service {
+    static readonly serviceType = "knowledge";
+    config: Metadata;
+    private knowledgeConfig;
+    capabilityDescription: string;
+    private knowledgeProcessingSemaphore;
+    /**
+     * Create a new Knowledge service
+     * @param runtime Agent runtime
+     */
+    constructor(runtime: IAgentRuntime, config?: Partial<KnowledgeConfig>);
+    private loadInitialDocuments;
+    /**
+     * Start the Knowledge service
+     * @param runtime Agent runtime
+     * @returns Initialized Knowledge service
+     */
+    static start(runtime: IAgentRuntime): Promise<KnowledgeService>;
+    /**
+     * Stop the Knowledge service
+     * @param runtime Agent runtime
+     */
+    static stop(runtime: IAgentRuntime): Promise<void>;
+    /**
+     * Stop the service
+     */
+    stop(): Promise<void>;
+    /**
+     * Add knowledge to the system
+     * @param options Knowledge options
+     * @returns Promise with document processing result
+     */
+    addKnowledge(options: AddKnowledgeOptions): Promise<{
+        clientDocumentId: string;
+        storedDocumentMemoryId: UUID;
+        fragmentCount: number;
+    }>;
+    /**
+     * Process a document regardless of type - Called by public addKnowledge
+     * @param options Document options
+     * @returns Promise with document processing result
+     */
+    private processDocument;
+    private handleProcessingError;
+    checkExistingKnowledge(knowledgeId: UUID): Promise<boolean>;
+    getKnowledge(message: Memory, scope?: {
+        roomId?: UUID;
+        worldId?: UUID;
+        entityId?: UUID;
+    }): Promise<KnowledgeItem[]>;
+    /**
+     * 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
+     */
+    enrichConversationMemoryWithRAG(memoryId: UUID, ragMetadata: {
+        retrievedFragments: Array<{
+            fragmentId: UUID;
+            documentTitle: string;
+            similarityScore?: number;
+            contentPreview: string;
+        }>;
+        queryText: string;
+        totalFragments: number;
+        retrievalTimestamp: number;
+    }): Promise<void>;
+    /**
+     * Set the current response memory ID for RAG tracking
+     * This is called by the knowledge provider to track which response memory to enrich
+     */
+    private 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: any): void;
+    /**
+     * Try to enrich recent conversation memories with pending RAG metadata
+     * This is called periodically to catch memories that were created after RAG retrieval
+     */
+    enrichRecentMemoriesWithPendingRAG(): Promise<void>;
+    processCharacterKnowledge(items: string[]): Promise<void>;
+    _internalAddKnowledge(item: KnowledgeItem, // item.id here is expected to be the ID of the "document"
+    options?: {
+        targetTokens: number;
+        overlap: number;
+        modelContextSize: number;
+    }, scope?: {
+        roomId: `${string}-${string}-${string}-${string}-${string}`;
+        entityId: `${string}-${string}-${string}-${string}-${string}`;
+        worldId: `${string}-${string}-${string}-${string}-${string}`;
+    }): Promise<void>;
+    private processDocumentFragment;
+    private splitAndCreateFragments;
+    /**
+     * Retrieves memories, typically documents, for the agent.
+     * Corresponds to GET /plugins/knowledge/documents
+     */
+    getMemories(params: {
+        tableName: string;
+        roomId?: UUID;
+        count?: number;
+        offset?: number;
+        end?: number;
+    }): Promise<Memory[]>;
+    /**
+     * Counts memories for pagination.
+     * Corresponds to counting documents or fragments.
+     */
+    countMemories(params: {
+        tableName: string;
+        roomId?: UUID;
+        unique?: boolean;
+    }): Promise<number>;
+    /**
+     * 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.
+     */
+    deleteMemory(memoryId: UUID): Promise<void>;
+}
+
+/**
+ * Represents a knowledge provider that retrieves knowledge from the knowledge base.
+ * @type {Provider}
+ * @property {string} name - The name of the knowledge provider.
+ * @property {string} description - The description of the knowledge provider.
+ * @property {boolean} dynamic - Indicates if the knowledge provider is dynamic or static.
+ * @property {Function} get - Asynchronously retrieves knowledge from the knowledge base.
+ * @param {IAgentRuntime} runtime - The agent runtime object.
+ * @param {Memory} message - The message containing the query for knowledge retrieval.
+ * @returns {Object} An object containing the retrieved knowledge data, values, and text.
+ */
+declare const knowledgeProvider: Provider;
+
 /**
  * Knowledge Plugin - Main Entry Point
  *
@@ -186,8 +326,69 @@ interface ExtendedMemoryMetadata extends Record<string, any> {
  */
 
 /**
- * Knowledge Plugin - Provides Retrieval Augmented Generation capabilities
+ * Configuration options for the Knowledge Plugin
+ */
+interface KnowledgePluginConfig {
+    /**
+     * Enable frontend UI and routes
+     * Set to false for cloud/server-only deployments
+     * @default true
+     */
+    enableUI?: boolean;
+    /**
+     * Enable HTTP routes for document management
+     * Set to false for browser-only or minimal deployments
+     * @default true
+     */
+    enableRoutes?: boolean;
+    /**
+     * Enable actions (PROCESS_KNOWLEDGE, SEARCH_KNOWLEDGE)
+     * @default true
+     */
+    enableActions?: boolean;
+    /**
+     * Enable tests
+     * @default true
+     */
+    enableTests?: boolean;
+}
+/**
+ * Create a Knowledge Plugin with custom configuration
+ * @param config Plugin configuration options
+ * @returns Configured Plugin instance
+ *
+ * @example
+ * // Cloud runtime mode (service + provider only)
+ * const plugin = createKnowledgePlugin({
+ *   enableUI: false,
+ *   enableRoutes: false,
+ * });
+ *
+ * @example
+ * // Browser-only mode (no routes)
+ * const plugin = createKnowledgePlugin({
+ *   enableRoutes: false,
+ * });
+ *
+ * @example
+ * // Full mode (default)
+ * const plugin = createKnowledgePlugin();
+ */
+declare function createKnowledgePlugin(config?: KnowledgePluginConfig): Plugin;
+/**
+ * Knowledge Plugin - Core mode (Service + Provider only)
+ * Use this for cloud runtimes or minimal deployments
+ */
+declare const knowledgePluginCore: Plugin;
+/**
+ * Knowledge Plugin - Headless mode (Service + Provider + Actions, no UI)
+ * Use this for server deployments without frontend
+ */
+declare const knowledgePluginHeadless: Plugin;
+/**
+ * Knowledge Plugin - Full mode (default)
+ * Includes everything: Service, Provider, Actions, Routes, UI, Tests
  */
 declare const knowledgePlugin: Plugin;
 
-export { type AddKnowledgeOptions, type ExtendedMemoryMetadata, type KnowledgeConfig, type KnowledgeDocumentMetadata, KnowledgeServiceType, type LoadResult, type ModelConfig, ModelConfigSchema, type ProviderRateLimits, type TextGenerationOptions, knowledgePlugin as default, knowledgePlugin };
+export { type AddKnowledgeOptions, type ExtendedMemoryMetadata, type KnowledgeConfig, type KnowledgeDocumentMetadata, type KnowledgePluginConfig, KnowledgeService, KnowledgeServiceType, type LoadResult, type ModelConfig, ModelConfigSchema, type ProviderRateLimits, type TextGenerationOptions, createKnowledgePlugin, knowledgePlugin as default, knowledgePlugin, knowledgePluginCore, knowledgePluginHeadless, knowledgeProvider };

package/dist/index.js

@@ -1,3 +1,6 @@
+// src/index.ts
+import { logger as logger10 } from "@elizaos/core";
+
 // src/service.ts
 import {
   createUniqueUuid,
@@ -5136,20 +5139,56 @@ var knowledgeRoutes = [
 ];
 
 // src/index.ts
-var knowledgePlugin = {
-  name: "knowledge",
-  description: "Plugin for Retrieval Augmented Generation, including knowledge management and embedding.",
-  services: [KnowledgeService],
-  providers: [knowledgeProvider],
-  routes: knowledgeRoutes,
-  actions: knowledgeActions,
-  tests: [tests_default]
-};
+function createKnowledgePlugin(config = {}) {
+  const { enableUI = true, enableRoutes = true, enableActions = true, enableTests = true } = config;
+  const plugin = {
+    name: "knowledge",
+    description: "Plugin for Retrieval Augmented Generation, including knowledge management and embedding.",
+    services: [KnowledgeService],
+    providers: [knowledgeProvider]
+  };
+  if (enableUI || enableRoutes) {
+    plugin.routes = knowledgeRoutes;
+    logger10.debug("[Knowledge Plugin] Routes enabled");
+  } else {
+    logger10.info("[Knowledge Plugin] Running in headless mode (no routes or UI)");
+  }
+  if (enableActions) {
+    plugin.actions = knowledgeActions;
+  }
+  if (enableTests) {
+    plugin.tests = [tests_default];
+  }
+  return plugin;
+}
+var knowledgePluginCore = createKnowledgePlugin({
+  enableUI: false,
+  enableRoutes: false,
+  enableActions: false,
+  enableTests: false
+});
+var knowledgePluginHeadless = createKnowledgePlugin({
+  enableUI: false,
+  enableRoutes: false,
+  enableActions: true,
+  enableTests: false
+});
+var knowledgePlugin = createKnowledgePlugin({
+  enableUI: true,
+  enableRoutes: true,
+  enableActions: true,
+  enableTests: true
+});
 var index_default = knowledgePlugin;
 export {
+  KnowledgeService,
   KnowledgeServiceType,
   ModelConfigSchema,
+  createKnowledgePlugin,
   index_default as default,
-  knowledgePlugin
+  knowledgePlugin,
+  knowledgePluginCore,
+  knowledgePluginHeadless,
+  knowledgeProvider
 };
 //# sourceMappingURL=index.js.map