@elizaos/plugin-knowledge/dist/index.d.ts

Plugin for Knowledge

import { UUID, Service, Metadata, IAgentRuntime, Memory, KnowledgeItem, Provider, Plugin } from '@elizaos/core';
import z from 'zod';

declare const ModelConfigSchema: z.ZodObject<{
    EMBEDDING_PROVIDER: z.ZodOptional<z.ZodEnum<["openai", "google"]>>;
    TEXT_PROVIDER: z.ZodOptional<z.ZodEnum<["openai", "anthropic", "openrouter", "google"]>>;
    OPENAI_API_KEY: z.ZodOptional<z.ZodString>;
    ANTHROPIC_API_KEY: z.ZodOptional<z.ZodString>;
    OPENROUTER_API_KEY: z.ZodOptional<z.ZodString>;
    GOOGLE_API_KEY: z.ZodOptional<z.ZodString>;
    OPENAI_BASE_URL: z.ZodOptional<z.ZodString>;
    ANTHROPIC_BASE_URL: z.ZodOptional<z.ZodString>;
    OPENROUTER_BASE_URL: z.ZodOptional<z.ZodString>;
    GOOGLE_BASE_URL: z.ZodOptional<z.ZodString>;
    TEXT_EMBEDDING_MODEL: z.ZodString;
    TEXT_MODEL: z.ZodOptional<z.ZodString>;
    MAX_INPUT_TOKENS: z.ZodEffects<z.ZodUnion<[z.ZodString, z.ZodNumber]>, number, string | number>;
    MAX_OUTPUT_TOKENS: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
    EMBEDDING_DIMENSION: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
    LOAD_DOCS_ON_STARTUP: z.ZodDefault<z.ZodBoolean>;
    CTX_KNOWLEDGE_ENABLED: z.ZodDefault<z.ZodBoolean>;
    RATE_LIMIT_ENABLED: z.ZodDefault<z.ZodBoolean>;
    MAX_CONCURRENT_REQUESTS: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
    REQUESTS_PER_MINUTE: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
    TOKENS_PER_MINUTE: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
    BATCH_DELAY_MS: z.ZodEffects<z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>, number, string | number | undefined>;
}, "strip", z.ZodTypeAny, {
    TEXT_EMBEDDING_MODEL: string;
    MAX_INPUT_TOKENS: number;
    MAX_OUTPUT_TOKENS: number;
    EMBEDDING_DIMENSION: number;
    LOAD_DOCS_ON_STARTUP: boolean;
    CTX_KNOWLEDGE_ENABLED: boolean;
    RATE_LIMIT_ENABLED: boolean;
    MAX_CONCURRENT_REQUESTS: number;
    REQUESTS_PER_MINUTE: number;
    TOKENS_PER_MINUTE: number;
    BATCH_DELAY_MS: number;
    EMBEDDING_PROVIDER?: "openai" | "google" | undefined;
    TEXT_PROVIDER?: "openai" | "google" | "anthropic" | "openrouter" | undefined;
    OPENAI_API_KEY?: string | undefined;
    ANTHROPIC_API_KEY?: string | undefined;
    OPENROUTER_API_KEY?: string | undefined;
    GOOGLE_API_KEY?: string | undefined;
    OPENAI_BASE_URL?: string | undefined;
    ANTHROPIC_BASE_URL?: string | undefined;
    OPENROUTER_BASE_URL?: string | undefined;
    GOOGLE_BASE_URL?: string | undefined;
    TEXT_MODEL?: string | undefined;
}, {
    TEXT_EMBEDDING_MODEL: string;
    MAX_INPUT_TOKENS: string | number;
    EMBEDDING_PROVIDER?: "openai" | "google" | undefined;
    TEXT_PROVIDER?: "openai" | "google" | "anthropic" | "openrouter" | undefined;
    OPENAI_API_KEY?: string | undefined;
    ANTHROPIC_API_KEY?: string | undefined;
    OPENROUTER_API_KEY?: string | undefined;
    GOOGLE_API_KEY?: string | undefined;
    OPENAI_BASE_URL?: string | undefined;
    ANTHROPIC_BASE_URL?: string | undefined;
    OPENROUTER_BASE_URL?: string | undefined;
    GOOGLE_BASE_URL?: string | undefined;
    TEXT_MODEL?: string | undefined;
    MAX_OUTPUT_TOKENS?: string | number | undefined;
    EMBEDDING_DIMENSION?: string | number | undefined;
    LOAD_DOCS_ON_STARTUP?: boolean | undefined;
    CTX_KNOWLEDGE_ENABLED?: boolean | undefined;
    RATE_LIMIT_ENABLED?: boolean | undefined;
    MAX_CONCURRENT_REQUESTS?: string | number | undefined;
    REQUESTS_PER_MINUTE?: string | number | undefined;
    TOKENS_PER_MINUTE?: string | number | undefined;
    BATCH_DELAY_MS?: string | number | undefined;
}>;
type ModelConfig = z.infer<typeof ModelConfigSchema>;
/**
 * Interface for provider rate limits
 */
interface ProviderRateLimits {
    maxConcurrentRequests: number;
    requestsPerMinute: number;
    tokensPerMinute?: number;
    provider: string;
    rateLimitEnabled: boolean;
    batchDelayMs: number;
}
/**
 * Options for text generation overrides
 */
interface TextGenerationOptions {
    provider?: 'anthropic' | 'openai' | 'openrouter' | 'google';
    modelName?: string;
    maxTokens?: number;
    /**
     * Document to cache for contextual retrieval.
     * When provided (along with an Anthropic model via OpenRouter), this enables prompt caching.
     * The document is cached with the provider and subsequent requests will reuse the cached document,
     * significantly reducing costs for multiple operations on the same document.
     * Most effective with contextual retrieval for Knowledge applications.
     */
    cacheDocument?: string;
    /**
     * Options for controlling the cache behavior.
     * Currently supports { type: 'ephemeral' } which sets up a temporary cache.
     * Cache expires after approximately 5 minutes with Anthropic models.
     * This can reduce costs by up to 90% for reads after the initial cache write.
     */
    cacheOptions?: {
        type: 'ephemeral';
    };
    /**
     * Whether to automatically detect and enable caching for contextual retrieval.
     * Default is true for OpenRouter+Anthropic models with document-chunk prompts.
     * Set to false to disable automatic caching detection.
     */
    autoCacheContextualRetrieval?: boolean;
}
/**
 * Options for adding knowledge to the system
 */
interface AddKnowledgeOptions {
    /** Agent ID from the frontend - if not provided, will use runtime.agentId */
    agentId?: UUID;
    worldId: UUID;
    roomId: UUID;
    entityId: UUID;
    /** Client-provided document ID */
    clientDocumentId: UUID;
    /** MIME type of the file */
    contentType: string;
    /** Original filename */
    originalFilename: string;
    /**
     * Content of the document. Should be:
     * - Base64 encoded string for binary files (PDFs, DOCXs, etc)
     * - Plain text for text files
     */
    content: string;
    /**
     * Optional metadata to associate with the knowledge
     * Used for storing additional information like source URL
     */
    metadata?: Record<string, unknown>;
}
declare module '@elizaos/core' {
    interface ServiceTypeRegistry {
        KNOWLEDGE: 'knowledge';
    }
}
declare const KnowledgeServiceType: {
    KNOWLEDGE: "knowledge";
};
interface KnowledgeDocumentMetadata extends Record<string, any> {
    type: string;
    source: string;
    title?: string;
    filename?: string;
    fileExt?: string;
    fileType?: string;
    fileSize?: number;
}
interface KnowledgeConfig {
    CTX_KNOWLEDGE_ENABLED: boolean;
    LOAD_DOCS_ON_STARTUP: boolean;
    MAX_INPUT_TOKENS?: string | number;
    MAX_OUTPUT_TOKENS?: string | number;
    EMBEDDING_PROVIDER?: string;
    TEXT_PROVIDER?: string;
    TEXT_EMBEDDING_MODEL?: string;
    RATE_LIMIT_ENABLED?: boolean;
    MAX_CONCURRENT_REQUESTS?: number;
    REQUESTS_PER_MINUTE?: number;
    TOKENS_PER_MINUTE?: number;
    BATCH_DELAY_MS?: number;
}
interface LoadResult {
    successful: number;
    failed: number;
    errors?: Array<{
        filename: string;
        error: string;
    }>;
}
/**
 * Extends the base MemoryMetadata from @elizaos/core with additional fields
 */
interface ExtendedMemoryMetadata extends Record<string, any> {
    type?: string;
    title?: string;
    filename?: string;
    path?: string;
    description?: string;
    fileExt?: string;
    timestamp?: number;
    contentType?: string;
    documentId?: string;
    source?: string;
    fileType?: string;
    fileSize?: number;
    position?: number;
    originalFilename?: string;
    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;

/**
 * Represents a static provider that lists available documents in the knowledge base.
 * This provider helps the agent understand which documents are available for retrieval.
 * @type {Provider}
 * @property {string} name - The name of the documents provider.
 * @property {string} description - The description of the documents provider.
 * @property {boolean} dynamic - Indicates if the provider is static (false).
 * @property {Function} get - Asynchronously retrieves the list of available documents.
 * @param {IAgentRuntime} runtime - The agent runtime object.
 * @returns {Object} An object containing the available documents list.
 */
declare const documentsProvider: Provider;

/**
 * Knowledge Plugin - Main Entry Point
 *
 * This file exports all the necessary functions and types for the Knowledge plugin.
 */

/**
 * 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, type KnowledgePluginConfig, KnowledgeService, KnowledgeServiceType, type LoadResult, type ModelConfig, ModelConfigSchema, type ProviderRateLimits, type TextGenerationOptions, createKnowledgePlugin, knowledgePlugin as default, documentsProvider, knowledgePlugin, knowledgePluginCore, knowledgePluginHeadless, knowledgeProvider };