Quick Start Guide

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.

​

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:

   Copy

   Ask AI

   your-project/
   ├── .env
   ├── docs/           ← Create this folder
   │   ├── guide.pdf
   │   ├── manual.txt
   │   └── notes.md
   └── package.json
   

2. Add this line to your .env file:

   Copy

   Ask AI

   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:

   Copy

   Ask AI

   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

​

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:

# 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
};

OPENROUTER_API_KEY=your-openrouter-api-key
OPENAI_API_KEY=your-openai-api-key

​

❓ 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