Knowledge Base Management

A well-organized knowledge base makes your AI agents smarter and more accurate. Learn how to upload, organize, and optimize documents so your agents have the right context to make informed decisions.

Understanding Knowledge Bases

What is a Knowledge Base?

A knowledge base is a collection of documents that your AI agent can reference when making decisions or answering questions. Think of it as your agent's reference library.

What agents use knowledge bases for:

• Understanding your company's processes and policies
• Learning about your products or services
• Following your team's style guides and conventions
• Accessing historical context and past decisions
• Finding relevant information to complete tasks accurately

Example: A "Customer Support Agent" with a knowledge base containing:

• Product documentation and feature guides
• Common troubleshooting steps
• Company policies on refunds and returns
• FAQs and their approved answers

How Knowledge Bases Work

When your agent receives a task or question:

1. Query Analysis: Agent identifies key information needed
2. Document Search: Relevant documents are retrieved from the knowledge base
3. Context Building: Agent reads relevant sections of documents
4. Action/Response: Agent uses this context to make informed decisions

Search technology: Verk uses semantic search (understanding meaning) rather than keyword matching, so your agent finds relevant information even when exact words don't match.

Adding Documents

Upload Methods

Drag and Drop

1. Navigate to your agent → Knowledge Base tab
2. Drag files from your computer
3. Drop them into the upload area
4. Wait for processing to complete

File Browser

1. Click Upload Documents
2. Select one or multiple files
3. Click Open
4. Processing begins automatically

URL Import

1. Click Add from URL
2. Paste the web page URL
3. Click Import
4. The page content is extracted and added

Supported File Types

Documents:

• PDF (.pdf) - Best for manuals, guides, and formatted documents
• Microsoft Word (.docx) - Good for policies and procedures
• Plain text (.txt) - Simple text files
• Markdown (.md) - Technical documentation

Spreadsheets:

• CSV (.csv) - Data tables and structured information
• Excel (.xlsx) - Data with multiple sheets

Web Content:

• Web pages (via URL) - Documentation sites, wikis, articles
• Notion pages (public URLs)
• Google Docs (with public access)

Other:

• Rich Text Format (.rtf)
• OpenDocument Text (.odt)

** Important**: Ensure you have permission to upload any documents. Don't upload copyrighted or confidential material without authorization.

File Size Limits

Free Plan:

• 5 MB per file
• 10 files per agent
• 50 total pages across all documents

Pro Plan:

• 20 MB per file
• 100 files per agent
• 500 total pages per agent

Enterprise Plan:

• 100 MB per file
• Unlimited files per agent
• Unlimited total pages

Processing time:

• Small files (<1 MB): 10-30 seconds
• Medium files (1-5 MB): 30-60 seconds
• Large files (5-20 MB): 1-3 minutes
• Very large files (20+ MB): 3-10 minutes

Batch Upload

Upload multiple documents at once:

1. Select all relevant files (hold Ctrl/Cmd)
2. Drag and drop or use file browser
3. All files process in parallel
4. Monitor progress bar for each file
5. Review completion status

Bulk upload limits:

• Maximum 20 files per batch upload
• Combined size under 100 MB per batch
• Processing happens in parallel for speed

Document Organization

Naming Conventions

Use clear, descriptive names that help you identify content:

Good naming:

• product_user_guide_v2.1.pdf
• refund_policy_2024.docx
• team_style_guide.md
• sales_process_overview.txt

Avoid:

• document1.pdf
• untitled.docx
• finalfinal.txt
• doc.pdf

Categories and Tags

Organize documents with categories for easier management:

Setting categories:

1. Click document → Edit Details
2. Select or create a category
3. Add relevant tags
4. Save changes

Common category structures:

By Department:

• Sales
• Marketing
• Engineering
• Customer Support
• Operations

By Content Type:

• Policies
• Procedures
• Guidelines
• Templates
• Reference Materials

By Project:

• Product Launch Q1
• Website Redesign
• Client Onboarding
• Marketing Campaign

Document Metadata

Add descriptions to help your agent understand document content:

1. Select a document
2. Click Add Description
3. Write a brief summary (50-200 words)
4. Include key topics covered
5. Save

Example description:

"This document outlines our customer refund policy, including eligibility criteria (30-day window), refund methods (original payment method), processing time (5-7 business days), and special cases (defective products, subscription cancellations). Last updated: January 2024."

Optimizing Document Content

Format for AI Readability

Use clear structure:

• Start with an overview or summary
• Use headings and subheadings
• Break content into logical sections
• Include table of contents for long documents

Keep it concise:

• Remove redundant information
• Use bullet points for lists
• Avoid excessive formatting that obscures content
• Focus on actionable information

Be explicit:

• Define acronyms and terminology
• Include complete context
• Avoid references like "as mentioned above" (agents may not process sequentially)
• State key information directly

Example: Before and After

Before (harder for agents):

The refund thing is pretty simple. Just check if it's been 30 days or less
since they bought it. If yes, do the refund. If no, explain why we can't.
For the broken stuff, always refund regardless of time.

After (optimized for agents):

# Refund Policy Guidelines

## Eligibility Criteria
- Purchase date: Within 30 days
- Condition: Product unused or defective
- Proof: Original receipt required

## Standard Refund Process
1. Verify purchase date (must be ≤30 days)
2. Check product condition
3. Process refund to original payment method
4. Processing time: 5-7 business days

## Special Cases
- Defective products: Always refund, regardless of purchase date
- Opened software: No refund (license activated)
- Custom orders: Contact manager for approval

Document Length Best Practices

Ideal lengths by document type:

Quick Reference (1-2 pages)

• Policies and rules
• Step-by-step procedures
• FAQ responses
• Template guidelines

Comprehensive Guides (5-10 pages)

• Product documentation
• Process overviews
• Training materials
• Technical specifications

Reference Materials (10+ pages)

• Complete manuals
• Historical records
• Detailed specifications
• Research documents

** Pro Tip**: Split very long documents (50+ pages) into smaller, topic-specific files. Agents retrieve information more accurately from focused documents.

Managing Your Knowledge Base

Updating Documents

Keep your knowledge base current:

Replace existing documents:

1. Find the document to update
2. Click three-dot menu → Replace
3. Upload the new version
4. Old version is archived automatically

Track changes:

• Version history shows all updates
• Click View Versions to see past versions
• Restore previous version if needed

Update schedule recommendations:

• Policies: Review quarterly
• Product docs: Update with each release
• Procedures: Review annually or when changed
• Templates: Update as processes evolve

Archiving Documents

Keep your knowledge base clean without losing historical information:

Archive process:

1. Select outdated document
2. Click Archive
3. Document is hidden from agent but preserved
4. View archived documents in Archived tab

When to archive:

• Outdated policies or procedures
• Superseded versions of documents
• Deprecated product documentation
• Completed project materials

Restore archived documents:

1. Navigate to Archived tab
2. Find the document
3. Click Restore
4. Document returns to active knowledge base

Deleting Documents

Permanently remove documents when needed:

1. Select document
2. Click three-dot menu → Delete
3. Confirm deletion
4. Document is permanently removed

** Important**: Deletion is permanent. Archive documents instead if you might need them later.

Search and Filter

Find documents quickly:

Search by:

• Document name
• Content (full-text search)
• Category or tag
• Upload date
• File size

Filter options:

• Date range (uploaded in last week/month/year)
• File type (PDF, Word, text, etc.)
• Category
• Status (active or archived)

Knowledge Base Testing

Test Retrieval Quality

Verify your agent can find the right information:

Testing process:

1. Navigate to Knowledge Base → Test Retrieval
2. Enter sample questions your agent might receive
3. Review which documents are retrieved
4. Check if the right information is found
5. Adjust documents or queries based on results

Example test queries:

For a customer support agent:

• "What is our refund policy?"
• "How do I process a return for a defective item?"
• "What should I tell customers about shipping times?"

Evaluate results:

• Right documents retrieved
• Relevant sections highlighted
• Complete information provided
• Irrelevant documents appear
• Missing crucial information
• Wrong document ranked highest

Improve Retrieval Accuracy

If testing reveals issues:

Problem: Wrong documents retrieved Solution:

• Add more specific titles and descriptions
• Use consistent terminology across documents
• Add relevant keywords to document metadata

Problem: Missing information Solution:

• Upload additional documents covering the gap
• Enhance existing documents with more detail
• Add cross-references between related documents

Problem: Information spread across too many documents Solution:

• Consolidate related information into fewer documents
• Create a summary document with cross-references
• Organize related documents into clear categories

Advanced Features

Document Permissions

Control which agents can access specific documents:

Setting permissions:

1. Select document → Permissions
2. Choose access level:

• All agents - Any agent in organization can access
• Specific agents - Only selected agents
• Private - Only you can manage

3. Save changes

Use cases for restricted access:

• Confidential client information
• Department-specific procedures
• Experimental or draft documents
• Sensitive company data

Version Control

Track changes to documents over time:

View version history:

1. Select document
2. Click Version History
3. See all uploaded versions with dates
4. Preview any version
5. Restore previous version if needed

Version notes: Add notes when uploading new versions:

• "Updated refund policy to extend window to 60 days"
• "Added section on international shipping"
• "Fixed typos in step 3"

Document Analytics

See how your agent uses knowledge base documents:

Metrics available:

• Most referenced documents
• Least used documents
• Retrieval success rate
• Average relevance score
• Search patterns

Navigate to analytics: Agent settings → Knowledge Base → Analytics

Use insights to:

• Identify gaps in documentation
• Remove unused documents
• Improve frequently-used documents
• Optimize document organization

Bulk Operations

Manage multiple documents at once:

Bulk actions:

• Update category for multiple documents
• Add tags to several documents
• Archive outdated documents
• Delete multiple files

Process:

1. Select documents (checkboxes)
2. Click Bulk Actions
3. Choose action
4. Confirm changes

Integration with External Systems

Sync with Documentation Platforms

Keep knowledge base automatically updated:

Supported integrations:

• Notion (sync specific pages or databases)
• Confluence (sync spaces or pages)
• Google Drive (sync folders)
• Dropbox (sync folders)
• GitHub (sync markdown documentation)

Setup sync:

1. Navigate to Knowledge Base → Integrations
2. Select platform
3. Authenticate and authorize access
4. Choose content to sync
5. Set sync frequency (hourly, daily, weekly)

Sync options:

• One-way sync (external → Verk only)
• Scheduled sync (automatic updates)
• Manual sync (on-demand updates)

API Access

Programmatically manage knowledge base:

Available endpoints:

• Upload documents via API
• Update document metadata
• Search knowledge base
• Delete or archive documents

Example API usage:

# Upload document
curl -X POST https://api.verk.com/v1/agents/{agent_id}/knowledge-base \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -F "file=@document.pdf" \
 -F "category=policies"

# Search knowledge base
curl https://api.verk.com/v1/agents/{agent_id}/knowledge-base/search \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -d '{"query": "refund policy"}'

See API Reference for complete documentation.

Best Practices

Start Small and Focused

Begin with essential documents:

1. Upload 3-5 core documents
2. Test agent performance
3. Identify gaps or issues
4. Add additional documents as needed
5. Remove or archive unused documents

Use Consistent Formatting

Standardize document structure:

• Use the same heading styles
• Follow consistent naming conventions
• Apply uniform categorization
• Use standard terminology across documents

Keep Documents Current

Maintain accuracy:

• Set quarterly review reminders
• Update documents when processes change
• Archive outdated versions
• Document the last review date

Monitor Usage Patterns

Regularly review analytics:

• Check which documents agents reference most
• Identify rarely-used documents for removal
• Look for repeated queries that aren't well-answered
• Optimize high-traffic documents

Secure Sensitive Information

Protect confidential data:

• Review documents for sensitive information before upload
• Use permission controls for confidential materials
• Regularly audit knowledge base access
• Remove documents when no longer needed

Document Your Knowledge Base

Keep a registry of your documents:

• Maintain a list of what's in the knowledge base
• Note the purpose of each document
• Track review dates and owners
• Document any special considerations

Troubleshooting

Document Upload Fails

Common causes:

• File too large for your plan
• Unsupported file format
• Corrupted file
• Network connection issues

Solutions:

1. Check file size against plan limits
2. Convert to supported format (PDF, DOCX, TXT)
3. Try re-saving or re-exporting the file
4. Check internet connection and retry

Agent Can't Find Information

Common causes:

• Document not properly indexed
• Information too deeply buried in document
• Inconsistent terminology
• Document not in knowledge base

Solutions:

1. Wait for indexing to complete (check status)
2. Create a summary document with key points
3. Standardize terminology across documents
4. Verify document is uploaded and active

Poor Retrieval Quality

Common causes:

• Documents too long or unfocused
• Too much irrelevant information
• Unclear document structure
• Insufficient document descriptions

Solutions:

1. Split long documents into focused topics
2. Remove unnecessary content
3. Add clear headings and structure
4. Write detailed document descriptions

Slow Agent Responses

Common causes:

• Too many documents (>100)
• Very large documents (>50 pages each)
• Complex document formats
• High retrieval load

Solutions:

1. Archive unused documents
2. Split large documents
3. Convert to simpler formats (PDF or TXT)
4. Upgrade plan for better performance

Related Documentation

• Agent Configuration - Configure model and tools
• Creating AI Agents - Set up your first agent
• Agent Analytics - Monitor knowledge base usage
• File Management - General file organization

---

Questions about knowledge bases? Check our FAQ or contact support.