Examples & Recipes

Learn how to use the Knowledge Plugin with practical examples that actually work.

How Knowledge Actually Works

The Knowledge Plugin allows agents to learn from documents in three ways:

Auto-load from docs folder (recommended for most use cases)
Upload via Web Interface (best for dynamic content)
Hardcode small snippets (only for tiny bits of info like “hello world”)

Basic Character Examples

Example 1: Document-Based Support Bot

Create a support bot that learns from your documentation:

characters/support-bot.ts

import { type Character } from '@elizaos/core';

export const supportBot: Character = {
  name: 'SupportBot',
  plugins: [
    '@elizaos/plugin-openai', // Required for embeddings
    '@elizaos/plugin-knowledge', // Add knowledge capabilities
  ],
  system: 'You are a friendly customer support agent. Answer questions using the support documentation you have learned. Always search your knowledge base before responding.',
  bio: [
    'Expert in product features and troubleshooting',
    'Answers based on official documentation',
    'Always polite and helpful',
  ],
};

Setup your support docs:

your-project/
├── docs/                           # Create this folder
│   ├── product-manual.pdf         # Your actual product docs
│   ├── troubleshooting-guide.md   # Support procedures
│   ├── faq.txt                    # Common questions
│   └── policies/                  # Organize with subfolders
│       ├── refund-policy.pdf
│       └── terms-of-service.md
├── .env
│   OPENAI_API_KEY=sk-...
│   LOAD_DOCS_ON_STARTUP=true      # Auto-load all docs
└── src/
    └── character.ts

When you start the agent, it will automatically:

Load all documents from the docs folder
Process them into searchable chunks
Use this knowledge to answer questions

Example 2: API Documentation Assistant

For technical documentation:

characters/api-assistant.ts

export const apiAssistant: Character = {
  name: 'APIHelper',
  plugins: [
    '@elizaos/plugin-openai',
    '@elizaos/plugin-knowledge',
  ],
  system: 'You are a technical documentation assistant. Help developers by searching your knowledge base for API documentation, code examples, and best practices.',
  topics: [
    'API endpoints and methods',
    'Authentication and security',
    'Code examples and best practices',
    'Error handling and debugging',
  ],
};

Organize your API docs:

docs/
├── api-reference/
│   ├── authentication.md
│   ├── endpoints.json
│   └── error-codes.csv
├── tutorials/
│   ├── getting-started.md
│   ├── advanced-usage.md
│   └── examples.ts
└── changelog.md

Example 3: Simple Info Bot (Hello World Example)

For very basic, hardcoded information only:

characters/info-bot.json

{
  "name": "InfoBot",
  "plugins": [
    "@elizaos/plugin-openai",
    "@elizaos/plugin-knowledge"
  ],
  "knowledge": [
    "Our office is located at 123 Main St",
    "Business hours: 9 AM to 5 PM EST",
    "Contact: support@example.com"
  ],
  "system": "You are a simple information bot. Answer questions using your basic knowledge."
}

Note: The knowledge array is only for tiny snippets. For real documents, use the docs folder!

Real-World Setup Guide

Step 1: Prepare Your Documents

Create a well-organized docs folder:

docs/
├── products/
│   ├── product-overview.pdf
│   ├── pricing-tiers.md
│   └── feature-comparison.xlsx
├── support/
│   ├── installation-guide.pdf
│   ├── troubleshooting.md
│   └── common-issues.txt
├── legal/
│   ├── terms-of-service.pdf
│   ├── privacy-policy.md
│   └── data-processing.txt
└── README.md  # Optional: describe folder structure

Step 2: Configure Auto-Loading

.env

# Required: Your AI provider
OPENAI_API_KEY=sk-...

# Auto-load documents on startup
LOAD_DOCS_ON_STARTUP=true

# Optional: Custom docs path (default is ./docs)
KNOWLEDGE_PATH=/path/to/your/documents

Step 3: Start Your Agent

elizaos start

The agent will:

Automatically find and load all documents
Process PDFs, text files, markdown, etc.
Create searchable embeddings
Log progress: “Loaded 23 documents from docs folder on startup”

Using the Web Interface

Uploading Documents

Start your agent: elizaos start
Open browser: http://localhost:3000
Select your agent
Click the Knowledge tab
Drag and drop files or click to upload

Best for:

Adding documents while the agent is running
Uploading user-specific content
Testing with different documents
Managing (view/delete) existing documents

What Happens When You Upload

When you upload a document via the web interface:

The file is processed immediately
It’s converted to searchable chunks
The agent can use it right away
You’ll see it listed in the Knowledge tab

How Agents Use Knowledge

Automatic Knowledge Search

When users ask questions, the agent automatically:

// User asks: "What's your refund policy?"
// Agent automatically:
// 1. Searches knowledge base for "refund policy"
// 2. Finds relevant chunks from refund-policy.pdf
// 3. Uses this information to answer

// User asks: "How do I install the software?"
// Agent automatically:
// 1. Searches for "install software"
// 2. Finds installation-guide.pdf content
// 3. Provides step-by-step instructions

The Knowledge Provider

The knowledge plugin includes a provider that automatically injects relevant knowledge into the agent’s context:

// This happens behind the scenes:
// 1. User sends message
// 2. Knowledge provider searches for relevant info
// 3. Found knowledge is added to agent's context
// 4. Agent generates response using this knowledge

Configuration Examples

Production Support Bot

.env

# AI Configuration
OPENAI_API_KEY=sk-...

# Knowledge Configuration
LOAD_DOCS_ON_STARTUP=true
KNOWLEDGE_PATH=/var/app/support-docs

# Optional: For better processing
CTX_KNOWLEDGE_ENABLED=true
OPENROUTER_API_KEY=sk-or-...  # For enhanced context

Development Setup

.env

# Minimal setup for testing
OPENAI_API_KEY=sk-...
LOAD_DOCS_ON_STARTUP=true
# Docs in default ./docs folder

Best Practices

DO: Use the Docs Folder

✅ Recommended approach for most use cases:

Put your documents in the docs folder
Set LOAD_DOCS_ON_STARTUP=true
Start your agent
Documents are automatically loaded

DO: Use Web Upload for Dynamic Content

✅ When to use the web interface:

User-uploaded content
Frequently changing documents
Testing different documents
One-off documents

DON’T: Hardcode Large Content

❌ Avoid this:

{
  "knowledge": [
    "Chapter 1: Introduction... (500 lines)",
    "Chapter 2: Getting Started... (1000 lines)",
    // Don't do this!
  ]
}

✅ Instead, use files:

docs/
├── chapter-1-introduction.md
├── chapter-2-getting-started.md
└── ...

Testing Your Setup

Quick Verification

Check the logs when starting:

[INFO] Loaded 15 documents from docs folder on startup

Ask the agent about your documents:

You: "What documents do you have about pricing?"
Agent: "I have information about pricing from pricing-tiers.md and product-overview.pdf..."

Use the Knowledge tab to see all loaded documents

Troubleshooting

No documents loading?

Check LOAD_DOCS_ON_STARTUP=true is set
Verify docs folder exists and has files
Check file permissions

Agent not finding information?

Ensure documents contain the information
Try more specific questions
Check the Knowledge tab to verify documents are loaded

Summary

For production: Use the docs folder with auto-loading
For dynamic content: Use the web interface
For tiny snippets only: Use the knowledge array
The agent automatically searches knowledge - no special commands needed

Quick Start

Get started in 5 minutes

Getting Started

Core Plugins

LLM Providers

Platform Integrations

DeFi Plugins

How Knowledge Actually Works

Basic Character Examples

Example 1: Document-Based Support Bot

Example 2: API Documentation Assistant

Example 3: Simple Info Bot (Hello World Example)

Real-World Setup Guide

Step 1: Prepare Your Documents

Step 2: Configure Auto-Loading

Step 3: Start Your Agent

Using the Web Interface

Uploading Documents

What Happens When You Upload

How Agents Use Knowledge

Automatic Knowledge Search

The Knowledge Provider

Configuration Examples

Production Support Bot

Development Setup

Best Practices

DO: Use the Docs Folder

DO: Use Web Upload for Dynamic Content

DON’T: Hardcode Large Content

Testing Your Setup

Quick Verification

Troubleshooting

Summary

Quick Start

​How Knowledge Actually Works

​Basic Character Examples

​Example 1: Document-Based Support Bot

​Example 2: API Documentation Assistant

​Example 3: Simple Info Bot (Hello World Example)

​Real-World Setup Guide

​Step 1: Prepare Your Documents

​Step 2: Configure Auto-Loading

​Step 3: Start Your Agent

​Using the Web Interface

​Uploading Documents

​What Happens When You Upload

​How Agents Use Knowledge

​Automatic Knowledge Search

​The Knowledge Provider

​Configuration Examples

​Production Support Bot

​Development Setup

​Best Practices

​DO: Use the Docs Folder

​DO: Use Web Upload for Dynamic Content

​DON’T: Hardcode Large Content

​Testing Your Setup

​Quick Verification

​Troubleshooting

​Summary

Quick Start

How Knowledge Actually Works

Basic Character Examples

Example 1: Document-Based Support Bot

Example 2: API Documentation Assistant

Example 3: Simple Info Bot (Hello World Example)

Real-World Setup Guide

Step 1: Prepare Your Documents

Step 2: Configure Auto-Loading

Step 3: Start Your Agent

Using the Web Interface

Uploading Documents

What Happens When You Upload

How Agents Use Knowledge

Automatic Knowledge Search

The Knowledge Provider

Configuration Examples

Production Support Bot

Development Setup

Best Practices

DO: Use the Docs Folder

DO: Use Web Upload for Dynamic Content

DON’T: Hardcode Large Content

Testing Your Setup

Quick Verification

Troubleshooting

Summary