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!

​
Getting Started (Beginner-Friendly)

​
Step 1: Add the Plugin

The Knowledge plugin works automatically with any elizaOS agent. Just add it to your agent’s plugin list: 
// 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
    // ... your other plugins
  ],
  // ... rest of your character config
};
That’s it! Your agent can now learn from documents. You’ll need an OPENAI_API_KEY in your .env file for embeddings.
Add OPENAI_API_KEY=your-api-key to your .env file. This is used for creating document embeddings, even if you’re using a different AI provider for chat.

​
Step 2: Upload Documents (Optional)

Want your agent to automatically learn from documents when it starts?
  1. Create a docs folder in your project root: 
    your-project/
├── .env
├── docs/           ← Create this folder
│   ├── guide.pdf
│   ├── manual.txt
│   └── notes.md
└── package.json
  2. Add this line to your .env file: 
    LOAD_DOCS_ON_STARTUP=true
  3. Start your agent - it will automatically learn from all documents in the docs folder!

​
Step 3: Ask Questions

Once documents are loaded, just talk to your agent naturally:
  • “What does the guide say about setup?”
  • “Search your knowledge for configuration info”
  • “What do you know about [any topic]?”
Your agent will search through all loaded documents and give you relevant answers!

​
Supported File Types

The plugin can read almost any document:
  • Text Files: .txt, .md, .csv, .json, .xml, .yaml
  • Documents: .pdf, .doc, .docx
  • Code Files: .js, .ts, .py, .java, .cpp, .html, .css and many more

​
Using the Web Interface

The Knowledge Plugin includes a powerful web interface for managing your agent’s knowledge base.

​
Accessing the Knowledge Manager

  1. Start your agent: 
    elizaos start
  2. Open your browser and go to http://localhost:3000
  3. Select your agent from the list (e.g., “Eliza”)
  4. Click the Knowledge tab in the right panel
That’s it! You can now:
  • Upload new documents
  • Search existing documents
  • Delete documents you no longer need
  • See all documents your agent has learned from
You can also drag and drop files directly onto the Knowledge tab to upload them!

​
Agent Actions

Your agent automatically gets these new abilities:
  • PROCESS_KNOWLEDGE - “Remember this document: [file path or text]”
  • SEARCH_KNOWLEDGE - “Search your knowledge for [topic]“

​
Examples in Chat

First, upload a document through the GUI:
  1. Go to http://localhost:3000
  2. Click on your agent and open the Knowledge tab
  3. Upload a document (e.g., company_q3_earnings.pdf)
Then ask your agent about it: 
You: What were the Q3 revenue figures?
Agent: Based on the Q3 earnings report in my knowledge base, the revenue was $2.3M, 
       representing a 15% increase from Q2...

You: Search your knowledge for information about profit margins
Agent: I found relevant information about profit margins: The Q3 report shows gross 
       margins improved to 42%, up from 38% in the previous quarter...

You: What does the report say about future projections?
Agent: According to the earnings report, the company projects Q4 revenue to reach 
       $2.8M with continued margin expansion...

​
Organizing Your Documents

Create subfolders for better organization: 
docs/
├── products/
│   ├── product-guide.pdf
│   └── pricing.md
├── support/
│   ├── faqs.txt
│   └── troubleshooting.md
└── policies/
    └── terms.pdf

​
Basic Configuration (Optional)

​
Custom Document Folder

If you want to use a different folder for documents:
.env
# Custom path to your documents
KNOWLEDGE_PATH=/path/to/your/documents

​
Provider Settings

The plugin automatically uses your existing AI provider. If you’re using OpenRouter: 
// In your character file (e.g., character.ts)
export const character = {
  name: 'MyAgent',
  plugins: [
    '@elizaos/plugin-openrouter',
    '@elizaos/plugin-openai', // ← Make sure you have this as openrouter doesn't support embeddings
    '@elizaos/plugin-knowledge', // ← Add this line
    // ... your other plugins
  ],
  // ... rest of your character config
};
.env
OPENROUTER_API_KEY=your-openrouter-api-key
OPENAI_API_KEY=your-openai-api-key
The plugin automatically uses OpenAI embeddings even when using OpenRouter for text generation.

​
FAQ

Q: Do I need any API keys?
A: For simple setup, only OPENAI_API_KEY. Q: What if I don’t have any AI plugins?
A: You need at least one AI provider plugin (like @elizaos/plugin-openai) for embeddings. Q: Can I upload documents while the agent is running?
A: Yes! Use the web interface or just tell your agent to process a file. Q: How much does this cost? A: Only the cost of generating embeddings (usually pennies per document). Q: Where are my documents stored?
A: Documents are processed and stored in your agent’s database as searchable chunks.

​
Common Issues

​
Documents Not Loading

Make sure:
  • Your docs folder exists in the right location
  • LOAD_DOCS_ON_STARTUP=true is in your .env file
  • Files are in supported formats

​
Can’t Access Web Interface

Check that:
  • Your agent is running (elizaos start)
  • You’re using the correct URL: http://localhost:3000
  • No other application is using port 3000

​
Agent Can’t Find Information

Try:
  • Using simpler search terms
  • Checking if the document was successfully processed
  • Looking in the Knowledge tab to verify the document is there

​
Next Steps

Now that you have the basics working:
  • Try uploading different types of documents
  • Organize your documents into folders
  • Ask your agent complex questions about the content
  • Explore the web interface features

Examples

See the plugin in action

Advanced Guide

Advanced configuration options
The Knowledge Plugin is designed to work out-of-the-box. You only need to adjust settings if you have specific requirements.