### Install elizaos-plugin-knowledge

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/python/README.md

Install the base package for the knowledge plugin.

```bash
pip install elizaos-plugin-knowledge
```

--------------------------------

### Configure Document Loading on Startup

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Set LOAD_DOCS_ON_STARTUP=true in your .env file to automatically load documents from the 'docs' folder when the agent starts.

```env
LOAD_DOCS_ON_STARTUP=true
```

--------------------------------

### Install Optional Dependencies for Knowledge Plugin

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/python/README.md

Install optional dependencies for specific features like OpenAI, Anthropic, Google AI, PDF, or DOCX support. Use '[all]' to install all optional dependencies.

```bash
# For OpenAI embedding support
pip install elizaos-plugin-knowledge[openai]
```

```bash
# For Anthropic support
pip install elizaos-plugin-knowledge[anthropic]
```

```bash
# For Google AI support
pip install elizaos-plugin-knowledge[google]
```

```bash
# For PDF processing
pip install elizaos-plugin-knowledge[pdf]
```

```bash
# For DOCX processing
pip install elizaos-plugin-knowledge[docx]
```

```bash
# Install all optional dependencies
pip install elizaos-plugin-knowledge[all]
```

--------------------------------

### Basic Knowledge Service Usage

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/python/README.md

Initialize the KnowledgeService with configuration, add plain text knowledge, and perform a semantic search. Ensure you have the necessary embedding provider installed.

```python
from elizaos_plugin_knowledge import KnowledgeService, KnowledgeConfig

# Create configuration
config = KnowledgeConfig(
    embedding_provider="openai",
    embedding_model="text-embedding-3-small",
    embedding_dimension=1536,
)

# Initialize service
service = KnowledgeService(config)

# Add knowledge from text
await service.add_knowledge(
    content="The capital of France is Paris.",
    content_type="text/plain",
    filename="facts.txt",
)

# Search for knowledge
results = await service.search("What is the capital of France?")
for result in results:
    print(f"Score: {result.similarity:.2f} - {result.content}")
```

--------------------------------

### Plugin Registration (Python)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Example of how to register the knowledge plugin within the ElizaOS runtime.

```APIDOC
## Python — Plugin Registration (`elizaOS` runtime)

```python
from elizaos import Plugin, Runtime  # hypothetical elizaos Python SDK
from elizaos_plugin_knowledge import create_knowledge_plugin

plugin: Plugin = create_knowledge_plugin()

runtime = Runtime(plugins=[plugin])
await runtime.start()
```
```

--------------------------------

### Document Loading Configuration

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Configure document loading behavior. Set `LOAD_DOCS_ON_STARTUP` to automatically load documents when the service starts and `KNOWLEDGE_PATH` to specify a custom directory for documents.

```env
LOAD_DOCS_ON_STARTUP=true          # Auto-load from docs folder
KNOWLEDGE_PATH=/custom/path        # Custom document path (default: ./docs)
```

--------------------------------

### Cloud/Custom Runtime Knowledge Service Usage (TypeScript)

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

In cloud or custom runtime environments, include `knowledgePluginCore` and access the `KnowledgeService` directly. This example shows adding documents and relies on the provider to inject context into conversations.

```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,
  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
```

--------------------------------

### Get Available Documents Listing

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use the `documentsProvider.get` method to retrieve a formatted list of all indexed document titles and metadata. This is useful for agents to understand available resources.

```typescript
import { documentsProvider } from "@elizaos/plugin-knowledge";

// Registered automatically; example standalone usage:
const result = await documentsProvider.get(runtime, message, state);

console.log(result.text);
// # Available Documents
// 3 document(s) in knowledge base:
// report.pdf - pdf - 240KB
// notes.txt - txt - 4KB
// specs.docx - docx - 18KB

console.log(result.values.documentsCount); // 3
console.log(result.data.documents);
// [{ id: "...", filename: "report.pdf", fileType: "application/pdf", source: "upload" }, ...]
```

--------------------------------

### Validate Model Configuration and Get Rate Limits (TypeScript)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use `validateModelConfig` to read and validate plugin settings from runtime and environment variables. `getProviderRateLimits` retrieves the resolved rate-limit profile.

```typescript
import { validateModelConfig, getProviderRateLimits } from "@elizaos/plugin-knowledge";

// Read and validate all config from runtime + env
const config = validateModelConfig(runtime);
console.log(config.TEXT_EMBEDDING_MODEL); // "text-embedding-3-small"
console.log(config.CTX_KNOWLEDGE_ENABLED); // false

// Get resolved rate-limit profile
const limits = await getProviderRateLimits(runtime);
console.log(limits);
// { maxConcurrentRequests: 100, requestsPerMinute: 500, tokensPerMinute: 1000000,
//   provider: "openai", rateLimitEnabled: true, batchDelayMs: 100 }
```

--------------------------------

### Knowledge Plugin HTTP REST API - Document Management

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use `curl` to list all documents, get a specific document by its ID, or delete a document from the knowledge base.

```bash
# List all documents
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents"
# => { "success": true, "data": { "memories": [...], "totalFound": 3 } }

# Get a specific document
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents/{knowledgeId}"

# Delete a document
curl -X DELETE "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents/{knowledgeId}"
```

--------------------------------

### Initialize and Use Knowledge Plugin in Rust

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/rust/README.md

Demonstrates how to initialize the KnowledgePlugin with default configuration, add knowledge content, and perform a semantic search. Ensure you have the necessary tokio runtime for async operations.

```rust
use elizaos_plugin_knowledge::{KnowledgePlugin, KnowledgeConfig, AddKnowledgeOptions};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create config with defaults
    let config = KnowledgeConfig::default();

    // Create plugin
    let plugin = KnowledgePlugin::new(config);

    // Add knowledge
    let options = AddKnowledgeOptions {
        content: "This is some knowledge content...".to_string(),
        content_type: "text/plain".to_string(),
        filename: "doc.txt".to_string(),
        ..Default::default()
    };

    let result = plugin.add_knowledge(options).await?;
    println!("Added document: {:?}", result.document_id);

    // Search knowledge
    let results = plugin.search("search query", 5, 0.1).await?;
    for result in results {
        println!("Found: {} (similarity: {:.2})", result.content, result.similarity);
    }

    Ok(())
}
```

--------------------------------

### Plugin Instantiation (TypeScript)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Demonstrates how to create a plugin instance using factory functions like `createKnowledgePlugin` or pre-built presets such as `knowledgePlugin`, `knowledgePluginHeadless`, and `knowledgePluginCore`.

```APIDOC
## Plugin Instantiation (TypeScript)

`createKnowledgePlugin` is the factory function for creating a plugin instance with custom feature flags. Three pre-built variants — `knowledgePlugin` (full), `knowledgePluginHeadless` (no UI/routes), and `knowledgePluginCore` (service + provider only) — cover the most common deployment scenarios.

```typescript
import {
  createKnowledgePlugin,
  knowledgePlugin,
  knowledgePluginHeadless,
  knowledgePluginCore,
  type KnowledgePluginConfig,
} from "@elizaos/plugin-knowledge";
import type { Plugin } from "@elizaos/core";

// ── Pre-built presets ────────────────────────────────────────────────────────
// Full mode: service + provider + actions + HTTP routes + React UI
export const characterFull = { plugins: [knowledgePlugin] };

// Headless: service + provider + actions (no HTTP routes, no UI)
export const characterHeadless = { plugins: [knowledgePluginHeadless] };

// Core: service + provider only (ideal for cloud / serverless runtimes)
export const characterCore = { plugins: [knowledgePluginCore] };

// ── Custom preset ────────────────────────────────────────────────────────────
const customPlugin: Plugin = createKnowledgePlugin({
  enableUI: false,      // Disable the React frontend panel
  enableRoutes: false,  // Disable HTTP REST routes
  enableActions: true,  // Keep PROCESS_KNOWLEDGE / SEARCH_KNOWLEDGE actions
  enableTests: false,
} satisfies KnowledgePluginConfig);

export const characterCustom = { plugins: [customPlugin] };
```
```

--------------------------------

### Instantiate Knowledge Plugin (TypeScript)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Demonstrates creating a plugin instance using `createKnowledgePlugin` with custom feature flags. Pre-built presets like `knowledgePlugin` (full), `knowledgePluginHeadless` (no UI/routes), and `knowledgePluginCore` (service + provider only) are also shown.

```typescript
import {
  createKnowledgePlugin,
  knowledgePlugin,
  knowledgePluginHeadless,
  knowledgePluginCore,
  type KnowledgePluginConfig,
} from "@elizaos/plugin-knowledge";
import type { Plugin } from "@elizaos/core";

// ── Pre-built presets ────────────────────────────────────────────────────────
// Full mode: service + provider + actions + HTTP routes + React UI
export const characterFull = { plugins: [knowledgePlugin] };

// Headless: service + provider + actions (no HTTP routes, no UI)
export const characterHeadless = { plugins: [knowledgePluginHeadless] };

// Core: service + provider only (ideal for cloud / serverless runtimes)
export const characterCore = { plugins: [knowledgePluginCore] };

// ── Custom preset ────────────────────────────────────────────────────────────
const customPlugin: Plugin = createKnowledgePlugin({
  enableUI: false,      // Disable the React frontend panel
  enableRoutes: false,  // Disable HTTP REST routes
  enableActions: true,  // Keep PROCESS_KNOWLEDGE / SEARCH_KNOWLEDGE actions
  enableTests: false,
} satisfies KnowledgePluginConfig);

export const characterCustom = { plugins: [customPlugin] };
```

--------------------------------

### Import Knowledge Plugin (Full Mode)

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Use this import for the default mode, which includes the UI and routes.

```typescript
import { knowledgePlugin } from "@elizaos/plugin-knowledge";
// or
import knowledgePlugin from "@elizaos/plugin-knowledge";

export const character = {
  plugins: [knowledgePlugin],
};
```

--------------------------------

### Import Knowledge Plugin (Headless Mode)

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Import the headless version of the plugin for server deployments without a frontend UI.

```typescript
import { knowledgePluginHeadless } from "@elizaos/plugin-knowledge";

export const character = {
  plugins: [knowledgePluginHeadless],
};
```

--------------------------------

### Import Knowledge Plugin (Core Mode)

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Use the core mode import for minimal deployments, excluding routes and UI.

```typescript
import { knowledgePluginCore } from "@elizaos/plugin-knowledge";

export const character = {
  plugins: [knowledgePluginCore],
};
```

--------------------------------

### Build Project with Cargo

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/rust/README.md

Standard Cargo commands for building the project in debug mode.

```bash
# Build
cargo build
```

--------------------------------

### Build Release Version with Cargo

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/rust/README.md

Compile the project in release mode for optimized performance.

```bash
# Build release
cargo build --release
```

--------------------------------

### Serve the built-in React management UI

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Access the built-in React management UI for the knowledge plugin via this cURL command.

```bash
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/display"
```

--------------------------------

### Integrate Knowledge Plugin with elizaOS Runtime

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/python/README.md

Create and register the knowledge plugin with the elizaOS runtime to enable its functionality within the agent.

```python
from elizaos import Plugin
from elizaos_plugin_knowledge import create_knowledge_plugin

# Create the plugin
plugin = create_knowledge_plugin()

# Register with runtime
runtime.register_plugin(plugin)
```

--------------------------------

### Register and Use knowledgeProvider

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

The knowledgeProvider automatically retrieves relevant knowledge fragments and injects them into the agent's context window as a formatted section. No additional configuration is required beyond registering the plugin.

```typescript
import { knowledgeProvider } from "@elizaos/plugin-knowledge";

// knowledgeProvider is automatically registered by all plugin variants.
// To use it standalone in a custom plugin:
const customPlugin: Plugin = {
  name: "my-plugin",
  providers: [knowledgeProvider],
  // ...
};

// The provider's get() return shape:
// {
//   text: "# Knowledge\n- Fragment 1 text\n- Fragment 2 text...",
//   values: { knowledge: "...", knowledgeUsed: true },
//   data: { knowledge: "...", ragMetadata: { ... }, knowledgeUsed: true }
// }
```

--------------------------------

### Register Knowledge Plugin with ElizaOS Runtime (Python)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

This snippet shows how to register the knowledge plugin with the ElizaOS runtime. It assumes a hypothetical ElizaOS Python SDK for plugin management.

```python
from elizaos import Plugin, Runtime  # hypothetical elizaos Python SDK
from elizaos_plugin_knowledge import create_knowledge_plugin

plugin: Plugin = create_knowledge_plugin()

runtime = Runtime(plugins=[plugin])
await runtime.start()
```

--------------------------------

### Configure OpenRouter with Claude for Cost Savings

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Set environment variables to use OpenRouter with Claude models for optimal results and cost savings through caching. Ensure your API key is set.

```env
TEXT_PROVIDER=openrouter
TEXT_MODEL=anthropic/claude-3.5-sonnet
OPENROUTER_API_KEY=your-openrouter-api-key
```

--------------------------------

### API Keys Configuration

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Set your API keys for various services. Ensure you provide the correct key for each provider you intend to use.

```env
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
OPENROUTER_API_KEY=sk-or-...
GOOGLE_API_KEY=your-key
```

--------------------------------

### Add Knowledge Document (TypeScript)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Shows how to use `KnowledgeService.addKnowledge` to ingest documents. PDFs require base64 encoding, while plain text does not. Submitting duplicate content is a no-op.

```typescript
import { KnowledgeService } from "@elizaos/plugin-knowledge";
import type { UUID } from "@elizaos/core";
import { readFileSync } from "node:fs";

// Obtain the service from the running ElizaOS runtime
const svc = runtime.getService<KnowledgeService>(KnowledgeService.serviceType);

// Upload a PDF document
const pdfBuffer = readFileSync("/path/to/report.pdf");
const result = await svc.addKnowledge({
  agentId: runtime.agentId,
  clientDocumentId: "" as UUID, // auto-generated from content hash
  contentType: "application/pdf",
  originalFilename: "report.pdf",
  content: pdfBuffer.toString("base64"), // PDFs must be base64
  worldId: runtime.agentId,
  roomId: runtime.agentId,
  entityId: runtime.agentId,
  metadata: { source: "upload", author: "Alice" }, // optional custom metadata
});

console.log(result.clientDocumentId);  // deterministic UUID derived from content
console.log(result.fragmentCount);     // number of indexed chunks
// => { clientDocumentId: "3f2a...", storedDocumentMemoryId: "9c1b...", fragmentCount: 42 }

// Upload plain text (no base64 needed)
const textResult = await svc.addKnowledge({
  agentId: runtime.agentId,
  clientDocumentId: "" as UUID,
  contentType: "text/plain",
  originalFilename: "notes.txt",
  content: "The capital of France is Paris.",
  worldId: runtime.agentId,
  roomId: runtime.agentId,
  entityId: runtime.agentId,
});
// Idempotent: submitting the same content again returns the existing record
```

--------------------------------

### Create Custom Knowledge Plugin Configuration

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Configure the knowledge plugin with custom settings for UI, routes, actions, and tests.

```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],
};
```

--------------------------------

### Run Tests with Cargo

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/rust/README.md

Execute all tests defined in the project using the Cargo test command.

```bash
# Test
cargo test
```

--------------------------------

### knowledgeProvider

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

A dynamic ElizaOS provider that automatically injects relevant knowledge fragments into the agent's context window before each response.

```APIDOC
## `knowledgeProvider` — Automatic Context Injection

### Description
The `knowledgeProvider` is a dynamic ElizaOS provider that automatically fires before every agent response. It retrieves the top 5 relevant knowledge fragments for the current message and injects them as a formatted `# Knowledge` section into the agent's context window. No additional configuration is required beyond registering the plugin.

### Usage
The `knowledgeProvider` is automatically registered by all plugin variants. To use it standalone in a custom plugin, include it in the `providers` array.

### Return Shape
```typescript
{
  text: "# Knowledge\n- Fragment 1 text\n- Fragment 2 text...",
  values: { knowledge: "...", knowledgeUsed: true },
  data: { knowledge: "...", ragMetadata: { ... }, knowledgeUsed: true }
}
```

### Example
```typescript
import { knowledgeProvider } from "@elizaos/plugin-knowledge";

// knowledgeProvider is automatically registered by all plugin variants.
// To use it standalone in a custom plugin:
const customPlugin: Plugin = {
  name: "my-plugin",
  providers: [knowledgeProvider],
  // ...
};
```
```

--------------------------------

### KnowledgeService — `addKnowledge`

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

`KnowledgeService.addKnowledge` is the primary ingestion entry point. It accepts a document as a base64 string or plain text, extracts its content, splits it into chunks, generates embeddings, and stores the document and its fragments. Duplicate detection is content-based.

```APIDOC
## KnowledgeService — `addKnowledge`

`KnowledgeService.addKnowledge` is the primary ingestion entry point. It accepts a document as a base64 string (for binary formats) or plain text, extracts its content, splits it into overlapping chunks, generates embeddings, and stores both the document record and all fragment memories. Duplicate detection is content-based: the same file submitted twice is a no-op.

```typescript
import { KnowledgeService } from "@elizaos/plugin-knowledge";
import type { UUID } from "@elizaos/core";
import { readFileSync } from "node:fs";

// Obtain the service from the running ElizaOS runtime
const svc = runtime.getService<KnowledgeService>(KnowledgeService.serviceType);

// Upload a PDF document
const pdfBuffer = readFileSync("/path/to/report.pdf");
const result = await svc.addKnowledge({
  agentId: runtime.agentId,
  clientDocumentId: "" as UUID, // auto-generated from content hash
  contentType: "application/pdf",
  originalFilename: "report.pdf",
  content: pdfBuffer.toString("base64"), // PDFs must be base64
  worldId: runtime.agentId,
  roomId: runtime.agentId,
  entityId: runtime.agentId,
  metadata: { source: "upload", author: "Alice" }, // optional custom metadata
});

console.log(result.clientDocumentId);  // deterministic UUID derived from content
console.log(result.fragmentCount);     // number of indexed chunks
// => { clientDocumentId: "3f2a...", storedDocumentMemoryId: "9c1b...", fragmentCount: 42 }

// Upload plain text (no base64 needed)
const textResult = await svc.addKnowledge({
  agentId: runtime.agentId,
  clientDocumentId: "" as UUID,
  contentType: "text/plain",
  originalFilename: "notes.txt",
  content: "The capital of France is Paris.",
  worldId: runtime.agentId,
  roomId: runtime.agentId,
  entityId: runtime.agentId,
});
// Idempotent: submitting the same content again returns the existing record
```
```

--------------------------------

### Environment Variable Configuration

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Configure the ElizaOS Knowledge Plugin using environment variables. These settings control document loading, embedding providers, contextual enrichment, rate limiting, and token limits.

```bash
# .env — minimal setup (uses existing @elizaos/plugin-openai credentials)
LOAD_DOCS_ON_STARTUP=true
KNOWLEDGE_PATH=/app/docs          # default: ./docs

# Embedding provider (auto-detected from plugin-openai if omitted)
EMBEDDING_PROVIDER=openai          # openai | google | local
TEXT_EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSION=1536

# Contextual enrichment (optional, ~90% cost savings via prompt caching)
CTX_KNOWLEDGE_ENABLED=true
TEXT_PROVIDER=openrouter           # openai | anthropic | openrouter | google
TEXT_MODEL=anthropic/claude-3.5-sonnet
OPENROUTER_API_KEY=sk-or-...

# Rate limiting (defaults shown)
RATE_LIMIT_ENABLED=true
MAX_CONCURRENT_REQUESTS=100
REQUESTS_PER_MINUTE=500
TOKENS_PER_MINUTE=1000000
BATCH_DELAY_MS=100

# Token limits
MAX_INPUT_TOKENS=4000
MAX_OUTPUT_TOKENS=4096

# File upload settings (HTTP route only)
KNOWLEDGE_UPLOAD_DIR=/tmp/uploads
KNOWLEDGE_MAX_FILE_SIZE=52428800   # 50 MB
KNOWLEDGE_MAX_FILES=10
```

--------------------------------

### Generate Contextualization Prompts (TypeScript)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use `getContextualizationPrompt` and `getCachingContextualizationPrompt` to create LLM prompts that situate text chunks within a full document. `getPromptForMimeType` selects prompts based on content type. `getChunkWithContext` combines the original chunk with LLM-generated context.

```typescript
import {
  getContextualizationPrompt,
  getCachingContextualizationPrompt,
  getPromptForMimeType,
  getCachingPromptForMimeType,
  getChunkWithContext,
  DEFAULT_CHUNK_TOKEN_SIZE,   // 500
  DEFAULT_CHUNK_OVERLAP_TOKENS, // 100
} from "@elizaos/plugin-knowledge";

const fullDocument = "Chapter 1: Introduction to Neural Networks...(full text)";
const chunk = "A perceptron is the simplest form of a neural network.";

// Standard (document included in prompt)
const prompt = getContextualizationPrompt(fullDocument, chunk);

// Cache-friendly variant (document passed separately as a cache-able block)
const { prompt: cachedPrompt, systemPrompt } = getCachingContextualizationPrompt(
  chunk,
  "application/pdf"
);

// MIME-type-aware selection (code, PDF, math-PDF, technical, default)
const pdfPrompt = getPromptForMimeType("application/pdf", fullDocument, chunk);
const codePrompt = getPromptForMimeType("text/typescript", fullDocument, chunk);

// After LLM generates context, combine with original chunk
const enriched = getChunkWithContext(chunk, "Neural networks are modeled after biological neurons. " + chunk);
console.log(enriched.slice(0, 80));
// => "Neural networks are modeled after biological neurons. A perceptron is the simpl..."
```

--------------------------------

### Add ElizaOS Knowledge Plugin Dependency

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/rust/README.md

Add the knowledge plugin to your project's Cargo.toml file to include its functionality.

```toml
[dependencies]
elizaos-plugin-knowledge = "1.6.1"
```

--------------------------------

### Text Generation Configuration

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Configure text generation settings for contextual mode. Choose your preferred `TEXT_PROVIDER` and `TEXT_MODEL`.

```env
TEXT_PROVIDER=openrouter           # openai | anthropic | openrouter | google
TEXT_MODEL=anthropic/claude-3.5-sonnet
```

--------------------------------

### Programmatic Knowledge Addition and Retrieval (TypeScript)

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Use the KnowledgeService to programmatically add documents and retrieve relevant knowledge based on a message. Ensure you have access to the runtime service.

```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({
  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.agentId,
  roomId: runtime.agentId,
  entityId: runtime.agentId,
  metadata: {
    // Optional custom metadata
    source: "upload",
    author: "John Doe",
  },
});

// 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,
  },
);
```

--------------------------------

### Performance Tuning Configuration

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Tune performance settings to manage concurrency and rate limits. Adjust `MAX_CONCURRENT_REQUESTS`, `REQUESTS_PER_MINUTE`, `TOKENS_PER_MINUTE`, `MAX_INPUT_TOKENS`, and `MAX_OUTPUT_TOKENS` as needed.

```env
MAX_CONCURRENT_REQUESTS=30         # Parallel processing limit
REQUESTS_PER_MINUTE=60             # Rate limiting
TOKENS_PER_MINUTE=150000           # Token rate limiting
MAX_INPUT_TOKENS=4000              # Chunk size limit
MAX_OUTPUT_TOKENS=4096             # Response size limit
```

--------------------------------

### Knowledge Service (Python)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

The Python implementation of the Knowledge Service provides an interface for adding, searching, retrieving, and deleting knowledge, with pluggable embedding, memory storage, and text generation.

```APIDOC
## Python — `KnowledgeService`

The Python implementation exposes the same `add_knowledge` / `search` / `get_knowledge` / `delete_knowledge` interface through a protocol-based dependency injection design. Embedding, memory storage, and text generation are all pluggable.

```python
import asyncio
from elizaos_plugin_knowledge import KnowledgeService
from elizaos_plugin_knowledge.types import AddKnowledgeOptions, KnowledgeConfig

# ── Configure ────────────────────────────────────────────────────────────────
config = KnowledgeConfig(
    embedding_provider="openai",
    embedding_model="text-embedding-3-small",
    embedding_dimension=1536,
    ctx_knowledge_enabled=False,
    chunk_size=500,
    chunk_overlap=100,
)

# Provide concrete implementations of EmbeddingProvider / MemoryStore protocols
# (or pass None to use keyword-based fallback search)
service = KnowledgeService(config=config)


async def main():
    # ── Add a document ───────────────────────────────────────────────────────
    result = await service.add_knowledge(
        AddKnowledgeOptions(
            content="The Eiffel Tower is 330 metres tall and located in Paris.",
            content_type="text/plain",
            filename="facts.txt",
            agent_id="agent-001",
            metadata={"source": "manual"},
        )
    )
    print(result.document_id, result.fragment_count, result.success)
    # => "3f2a..." 1 True

    # ── Search ───────────────────────────────────────────────────────────────
    results = await service.search("How tall is the Eiffel Tower?", count=5, threshold=0.1)
    for r in results:
        print(f"[{r.similarity:.2f}] {r.content[:60]}")
    # => [0.83] The Eiffel Tower is 330 metres tall and located in...

    # ── Convenience wrapper ──────────────────────────────────────────────────
    items = await service.get_knowledge("Paris landmarks", count=3)
    print(items[0].content)

    # ── Delete ───────────────────────────────────────────────────────────────
    deleted = await service.delete_knowledge(result.document_id)
    print(deleted)  # True

asyncio.run(main())
```
```

--------------------------------

### Enable Enhanced Contextual Knowledge

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Set CTX_KNOWLEDGE_ENABLED=true in your environment variables to enable enhanced contextual understanding for complex documents.

```env
# Enable enhanced contextual understanding
CTX_KNOWLEDGE_ENABLED=true
```

--------------------------------

### Load Documents from Path (TypeScript)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

The `loadDocsFromPath` function scans a directory recursively and ingests supported files. It's called automatically when `LOAD_DOCS_ON_STARTUP` is true, or can be invoked programmatically.

```typescript
import { loadDocsFromPath, getKnowledgePath } from "@elizaos/plugin-knowledge/docs-loader";

const svc = runtime.getService<KnowledgeService>(KnowledgeService.serviceType);

// Resolve the effective docs directory
const docsDir = getKnowledgePath(runtime.getSetting("KNOWLEDGE_PATH") ?? undefined);
// => "/app/docs"

// Ingest everything in the directory
const result = await loadDocsFromPath(
  svc,
  runtime.agentId,
  runtime.agentId,  // worldId
  "/app/docs"       // optional override; defaults to KNOWLEDGE_PATH or ./docs
);

console.log(`Loaded ${result.successful}/${result.total} files (${result.failed} failed)`);
// => Loaded 12/13 files (1 failed)
// Supported extensions include: .txt, .md, .pdf, .docx, .json, .yaml, .csv,
// .js, .ts, .py, .java, .rs, .go, .cpp, .html, .css, and 60+ more.
```

--------------------------------

### List all knowledge chunks

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use this cURL command to retrieve a list of all knowledge chunks (fragments) for a specific agent and document.

```bash
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/knowledges?documentId={docId}"
```

--------------------------------

### Knowledge Service Operations (Python)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

The `KnowledgeService` in Python allows adding, searching, retrieving, and deleting knowledge. It supports pluggable embedding providers and memory stores. Configure the service with `KnowledgeConfig` and use `AddKnowledgeOptions` for adding documents.

```python
import asyncio
from elizaos_plugin_knowledge import KnowledgeService
from elizaos_plugin_knowledge.types import AddKnowledgeOptions, KnowledgeConfig

# ── Configure ────────────────────────────────────────────────────────────────
config = KnowledgeConfig(
    embedding_provider="openai",
    embedding_model="text-embedding-3-small",
    embedding_dimension=1536,
    ctx_knowledge_enabled=False,
    chunk_size=500,
    chunk_overlap=100,
)

# Provide concrete implementations of EmbeddingProvider / MemoryStore protocols
# (or pass None to use keyword-based fallback search)
service = KnowledgeService(config=config)


async def main():
    # ── Add a document ───────────────────────────────────────────────────────
    result = await service.add_knowledge(
        AddKnowledgeOptions(
            content="The Eiffel Tower is 330 metres tall and located in Paris.",
            content_type="text/plain",
            filename="facts.txt",
            agent_id="agent-001",
            metadata={"source": "manual"},
        )
    )
    print(result.document_id, result.fragment_count, result.success)
    # => "3f2a..." 1 True

    # ── Search ───────────────────────────────────────────────────────────────
    results = await service.search("How tall is the Eiffel Tower?", count=5, threshold=0.1)
    for r in results:
        print(f"[{r.similarity:.2f}] {r.content[:60]}")
    # => [0.83] The Eiffel Tower is 330 metres tall and located in...

    # ── Convenience wrapper ──────────────────────────────────────────────────
    items = await service.get_knowledge("Paris landmarks", count=3)
    print(items[0].content)

    # ── Delete ───────────────────────────────────────────────────────────────
    deleted = await service.delete_knowledge(result.document_id)
    print(deleted)  # True

asyncio.run(main())
```

--------------------------------

### PROCESS_KNOWLEDGE Action

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Handles natural-language requests to ingest documents. It detects file paths in the message text and reads them from the filesystem, or treats the message body itself as inline text knowledge.

```APIDOC
## `PROCESS_KNOWLEDGE` Action

The `processKnowledgeAction` handles natural-language requests to ingest documents. It detects file paths in the message text and reads them from the filesystem, or treats the message body itself as inline text knowledge.

```typescript
// Registered automatically by knowledgePlugin / knowledgePluginHeadless.
// Triggered when the agent message contains keywords like "process", "upload",
// "learn", "remember", or includes a file path pattern.

// Agent interaction (file path):
// User: "Process the document at /home/alice/reports/q3.pdf"
// => KnowledgeService.addKnowledge({ contentType: "application/pdf", ... })
// => "I've successfully processed the document 'q3.pdf'. It has been split into
//     42 searchable fragments and added to my knowledge base."

// Agent interaction (inline text):
// User: "Remember this: Our SLA target is 99.9% uptime."
// => KnowledgeService.addKnowledge({ contentType: "text/plain", ... })
// => "I've added that information to my knowledge base."

import { processKnowledgeAction } from "@elizaos/plugin-knowledge";

// Manual invocation for testing:
const response = await processKnowledgeAction.handler(
  runtime,
  {
    id: "msg-1" as UUID,
    agentId: runtime.agentId,
    roomId: runtime.agentId,
    entityId: runtime.agentId,
    content: { text: "Add this to your knowledge: Deployment window is Fridays 10pm UTC." },
    metadata: { type: "message", timestamp: Date.now() },
  },
  undefined,
  undefined,
  async (response) => console.log(response.text)
);
// => { success: true, text: "I've added that information to my knowledge base." }
```
```

--------------------------------

### Add Knowledge Plugin to Agent Configuration

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Integrate the Knowledge plugin into your agent's plugin list in the character file.

```typescript
// In your character file (e.g., character.ts)
export const character = {
  name: "MyAgent",
  plugins: [
    "@elizaos/plugin-openai", // ← Make sure you have this
    "@elizaos/plugin-knowledge", // ← Add this line (full mode)
    // ... your other plugins
  ],
  // ... rest of your character config
};
```

--------------------------------

### documentsProvider

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Provides a formatted list of all indexed document titles and metadata to the agent's context, enabling the agent to know available resources.

```APIDOC
## `documentsProvider` — Available Documents Listing

The `documentsProvider` injects a formatted list of all indexed document titles and metadata into the agent's context. This lets the agent know what resources are available before a user query.

```typescript
import { documentsProvider } from "@elizaos/plugin-knowledge";

// Registered automatically; example standalone usage:
const result = await documentsProvider.get(runtime, message, state);

console.log(result.text);
// # Available Documents
// 3 document(s) in knowledge base:
// report.pdf - pdf - 240KB
// notes.txt - txt - 4KB
// specs.docx - docx - 18KB

console.log(result.values.documentsCount); // 3
console.log(result.data.documents);
// [{ id: "...", filename: "report.pdf", fileType: "application/pdf", source: "upload" }, ...]
```
```

--------------------------------

### Fetch Remote URL Content with @elizaos/plugin-knowledge

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use fetchUrlContent to retrieve content from a remote URL. The function returns the content as a base64 string along with its content type.

```typescript
// Fetch a remote document and return it as base64
const { content, contentType } = await fetchUrlContent("https://example.com/spec.pdf");
// => { content: "<base64>", contentType: "application/pdf" }
```

--------------------------------

### Expand document into its fragments

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use this cURL command to expand a document into its constituent knowledge fragments.

```bash
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/graph/expand/{documentId}"
```

--------------------------------

### Knowledge Plugin HTTP REST API - Upload Documents

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Use `curl` to upload one or more files via multipart/form-data or upload documents from URLs using JSON payload.

```bash
# Upload one or more files (multipart/form-data)
curl -X POST "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents" \
  -F "files=@report.pdf" \
  -F "files=@notes.txt" \
  -F "agentId={agentId}"

# Upload from URLs (application/json)
curl -X POST "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"{agentId}","fileUrls":["https://example.com/doc.pdf"]}'
```

--------------------------------

### Contextual Embeddings (TypeScript)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Functions for generating contextual prompts for LLM embeddings, including standard and cache-friendly variants, and MIME-type aware selection.

```APIDOC
## Contextual Embeddings — `getContextualizationPrompt` / `getCachingContextualizationPrompt`

The contextual enrichment subsystem constructs LLM prompts that ask the model to situate each chunk within the full document before embedding. The prompt strategy is automatically selected based on MIME type (PDF, code, math, technical docs, or general text).

```typescript
import {
  getContextualizationPrompt,
  getCachingContextualizationPrompt,
  getPromptForMimeType,
  getCachingPromptForMimeType,
  getChunkWithContext,
  DEFAULT_CHUNK_TOKEN_SIZE,   // 500
  DEFAULT_CHUNK_OVERLAP_TOKENS, // 100
} from "@elizaos/plugin-knowledge";

const fullDocument = "Chapter 1: Introduction to Neural Networks...(full text)";
const chunk = "A perceptron is the simplest form of a neural network.";

// Standard (document included in prompt)
const prompt = getContextualizationPrompt(fullDocument, chunk);

// Cache-friendly variant (document passed separately as a cache-able block)
const { prompt: cachedPrompt, systemPrompt } = getCachingContextualizationPrompt(
  chunk,
  "application/pdf"
);

// MIME-type-aware selection (code, PDF, math-PDF, technical, default)
const pdfPrompt = getPromptForMimeType("application/pdf", fullDocument, chunk);
const codePrompt = getPromptForMimeType("text/typescript", fullDocument, chunk);

// After LLM generates context, combine with original chunk
const enriched = getChunkWithContext(chunk, "Neural networks are modeled after biological neurons. " + chunk);
console.log(enriched.slice(0, 80));
// => "Neural networks are modeled after biological neurons. A perceptron is the simpl..."
```
```

--------------------------------

### Detect Binary Content Type with @elizaos/plugin-knowledge

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Employ isBinaryContentType to determine if a given content type and filename indicate a binary file. This helps in deciding whether base64 encoding is necessary for submission.

```typescript
// Detect if a file should be base64-encoded before submission
const needsBase64 = isBinaryContentType("application/pdf", "report.pdf"); // true
const noBase64    = isBinaryContentType("text/markdown",   "notes.md");   // false
```

--------------------------------

### Knowledge graph nodes (paginated)

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Retrieve paginated knowledge graph nodes for a given agent using this cURL command.

```bash
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/graph/nodes?page=1&limit=20"
```

--------------------------------

### HTTP REST API Routes

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Registers HTTP endpoints for managing documents and performing searches within the knowledge plugin.

```APIDOC
## HTTP REST API Routes (TypeScript)

The `knowledgeRoutes` array registers eleven HTTP endpoints under the `/api/agents/{agentId}/plugins/knowledge/` prefix when the plugin is used in full or headless mode.

```bash
# Upload one or more files (multipart/form-data)
curl -X POST "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents" \
  -F "files=@report.pdf" \
  -F "files=@notes.txt" \
  -F "agentId={agentId}"

# Upload from URLs (application/json)
curl -X POST "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"{agentId}","fileUrls":["https://example.com/doc.pdf"]}'

# List all documents
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents"
# => { "success": true, "data": { "memories": [...], "totalFound": 3 } }

# Get a specific document
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents/{knowledgeId}"

# Delete a document
curl -X DELETE "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/documents/{knowledgeId}"

# Semantic search
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/search?q=Q3+revenue&threshold=0.5&limit=10"
```
```

--------------------------------

### Graph node details

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Fetch detailed information about a specific knowledge graph node by its ID using this cURL command.

```bash
curl "http://localhost:3000/api/agents/{agentId}/plugins/knowledge/graph/node/{nodeId}"
```

--------------------------------

### Embedding Configuration

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

Configure embedding settings if not using a standard AI plugin. Specify the `EMBEDDING_PROVIDER`, `TEXT_EMBEDDING_MODEL`, and `EMBEDDING_DIMENSION`.

```env
# Only needed if you're not using a standard AI plugin
EMBEDDING_PROVIDER=openai          # openai | google
TEXT_EMBEDDING_MODEL=text-embedding-3-small
EMBEDDING_DIMENSION=1536           # Vector dimension
```

--------------------------------

### Heuristic Base64 Detection with @elizaos/plugin-knowledge

Source: https://context7.com/elizaos-plugins/plugin-knowledge/llms.txt

Utilize looksLikeBase64 for a heuristic check to determine if a string appears to be base64 encoded. This is a quick check and not a definitive validation.

```typescript
// Heuristic base64 detection
const isB64 = looksLikeBase64("SGVsbG8gV29ybGQ="); // true
const isPlain = looksLikeBase64("Hello, world!");   // false
```

--------------------------------

### HTTP Endpoints for Knowledge Management

Source: https://github.com/elizaos-plugins/plugin-knowledge/blob/alpha/README.md

These are the available HTTP endpoints for managing knowledge documents within an agent.

```APIDOC
## POST /api/agents/{agentId}/plugins/knowledge/documents

### Description
Upload documents to the knowledge base.

### Method
POST

### Endpoint
/api/agents/{agentId}/plugins/knowledge/documents

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.

#### Request Body
- **content** (string) - Required - The document content (Base64 for PDFs, plain text for others).
- **contentType** (string) - Required - The MIME type of the document (e.g., "application/pdf", "text/plain").
- **originalFilename** (string) - Required - The original name of the document file.
- **clientDocumentId** (string) - Optional - A client-generated ID for the document.
- **metadata** (object) - Optional - Custom metadata for the document.
  - **source** (string) - Optional - The source of the document.
  - **author** (string) - Optional - The author of the document.

### Response
#### Success Response (200)
- **documentId** (string) - The unique identifier of the uploaded document.
- **message** (string) - Confirmation message.
```

```APIDOC
## GET /api/agents/{agentId}/plugins/knowledge/documents

### Description
List all documents associated with an agent.

### Method
GET

### Endpoint
/api/agents/{agentId}/plugins/knowledge/documents

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.

### Response
#### Success Response (200)
- **documents** (array) - A list of document objects.
  - **documentId** (string) - The unique identifier of the document.
  - **originalFilename** (string) - The original name of the document file.
  - **contentType** (string) - The MIME type of the document.
  - **createdAt** (string) - The timestamp when the document was created.
```

```APIDOC
## GET /api/agents/{agentId}/plugins/knowledge/documents/{id}

### Description
Retrieve a specific document by its ID.

### Method
GET

### Endpoint
/api/agents/{agentId}/plugins/knowledge/documents/{id}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.
- **id** (string) - Required - The ID of the document to retrieve.

### Response
#### Success Response (200)
- **documentId** (string) - The unique identifier of the document.
- **content** (string) - The content of the document.
- **contentType** (string) - The MIME type of the document.
- **originalFilename** (string) - The original name of the document file.
- **createdAt** (string) - The timestamp when the document was created.
```

```APIDOC
## DELETE /api/agents/{agentId}/plugins/knowledge/documents/{id}

### Description
Delete a specific document by its ID.

### Method
DELETE

### Endpoint
/api/agents/{agentId}/plugins/knowledge/documents/{id}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.
- **id** (string) - Required - The ID of the document to delete.

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the document was deleted.
```

```APIDOC
## GET /api/agents/{agentId}/plugins/knowledge/display

### Description
Access the web interface for knowledge management.

### Method
GET

### Endpoint
/api/agents/{agentId}/plugins/knowledge/display

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The ID of the agent.
```