Skip to main content

​
Overview

Anam’s Knowledge Base lets your AI personas search and retrieve information from your documents using Retrieval-Augmented Generation (RAG). Instead of relying solely on the LLM’s training data, your personas can access up-to-date, organization-specific information from your uploaded documents.
Beta Feature: Knowledge Base is currently in beta. You may encounter some issues as we continue to improve the feature. Please report any feedback or issues to help us make it better.
With this feature, personas can:
  • Answer questions from your documentation
  • Provide information about your products, policies, or procedures
  • Stay current with your latest content updates
  • Ground responses in verified sources

​
How It Works

Knowledge tools let your AI persona search your documents to answer questions.
1

Upload

You upload a file using a three-step signed upload process.
async function uploadDocument(file, folderId, apiKey) {
  try {
    // Step 1: Get an upload URL from Anam
    const response = await fetch(
      `/v1/knowledge/groups/${folderId}/documents/presigned-upload`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          filename: file.name,
          contentType: file.type,
          fileSize: file.size
        })
      }
    );

    if (!response.ok) {
      throw new Error('Failed to get upload URL');
    }

    const { uploadUrl, documentId } = await response.json();

    // Step 2: Upload your file directly to the URL
    const uploadResponse = await fetch(uploadUrl, {
      method: 'PUT',
      body: file
    });

    if (!uploadResponse.ok) {
      throw new Error('Failed to upload file to storage');
    }

    // Step 3: Confirm the upload with Anam
    const confirmResponse = await fetch(
      `/v1/knowledge/documents/${documentId}/confirm-upload`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ fileSize: file.size })
      }
    );

    if (!confirmResponse.ok) {
      throw new Error('Failed to confirm upload');
    }

    return await confirmResponse.json();
  } catch (error) {
    console.error('Upload failed:', error.message);
    throw error;
  }
}
This process stores the document and begins the processing pipeline.
2

Processing

A background job processes the document to make it searchable. This typically takes ~30 seconds.Status changes to PROCESSING.
3

Ready

Once processing completes (typically ~30 seconds), the document status changes to READY and becomes searchable.
You can now attach this folder to knowledge tools and start searching.
Documents must be in READY status to be searchable. If a document fails processing, its status will be set to FAILED with an error message.

​
Document Processing

The system processes different file types appropriately:
File TypeHow It’s Processed
PDF, TXT, MD, DOCXSplit into paragraphs for precise search results
CSVEach row is searchable independently
JSONEntire file kept intact
LOGEach line is searchable independently

​
Optimizing Document Structure

For best search results, structure your documents with: Clear headings and sections: 
# Installation Guide

## Prerequisites

Before installing, ensure you have...

## Step 1: Download the software

Navigate to our downloads page...

## Step 2: Run the installer

Double-click the downloaded file...
Self-contained paragraphs: Each paragraph should make sense independently, as it may be retrieved without surrounding context. Descriptive filenames:
  • product-installation-guide.pdf
  • billing-faq-2024.md
Avoid generic names like document1.pdf or untitled.txt.

​
Storage Limits and Quotas

​
Upload Limits

Document uploads are subject to file size and monthly storage limits based on your plan.
Need higher limits? Contact us about Enterprise plans with custom upload limits tailored to your needs.
File uploads:
  • Maximum file size per document varies by plan
  • Batch uploads supported (multiple files at once)
  • Storage quotas count only non-deleted documents
Deleting documents frees up quota for new uploads.

​
Checking Your Usage

You can view your current usage in the Anam Lab UI at /knowledge or via API: 
const response = await fetch("/v1/knowledge/usage", {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

const usage = await response.json();
console.log(`Used: ${usage.totalBytes} / ${usage.quotaBytes}`);

​
Search Performance

​
How Search Works

When your AI searches documents, it finds the most relevant information to answer the user’s question. The system ranks results by relevance and provides the best matches to the LLM.

​
Improving Search Results

Use descriptive folder names and document titles: Metadata helps the system understand context. Keep documents focused on specific topics: Instead of one 500-page manual, upload focused documents on individual topics. Update documents regularly: Delete outdated documents and upload current versions. Organize by knowledge domain: Create separate folders for different areas:
  • Product documentation
  • FAQs
  • Policies
  • Troubleshooting guides

​
Using Knowledge Tools

Once your documents are uploaded and processed, create knowledge tools to enable search: 
{
  type: 'server',
  subtype: 'knowledge',
  name: 'search_product_docs',
  description: 'Search product documentation when users ask technical questions about features, installation, or usage',
  documentFolderIds: ['550e8400-e29b-41d4-a716-446655440000', '6ba7b810-9dad-11d1-80b4-00c04fd430c8']
}
Attach the tool to a persona, and the LLM will invoke it when relevant: User: “How do I configure SSL?” LLM internal process:
  1. Recognizes this is a technical question
  2. Invokes search_product_docs with query “SSL configuration”
  3. Receives relevant chunks from documentation
  4. Generates response: “To configure SSL, you’ll need to…”
Learn more about creating and using knowledge tools in the Tools documentation.

​
Security and Privacy

​
Organization Isolation

All knowledge base data is organization-scoped:
  • Users can only access their organization’s folders and documents
  • API requests are filtered by organization ID at the database level
  • Even with knowledge of folder IDs, users cannot access other organizations’ data
Always use HTTPS for API requests. Never commit API keys to version control or expose them client-side.

​
Troubleshooting

​
No Search Results

Possible causes:
  • Documents still in PROCESSING status (wait ~30 seconds)
  • Query semantically unrelated to document content
  • Folder contains no READY documents
  • Documents in wrong folder (check folder assignments)
Solutions:
  1. Check document status in the UI or via API
  2. Test query using debug modal (Ctrl+Shift+K)
  3. Try rephrasing query with more specific terms
  4. Verify folder contains relevant documents

​
Upload Failures

File too large (>50MB):
  • Split document into smaller files
  • Remove images in PDFs
  • Remove unnecessary pages
Processing failed:
  • Check file isn’t corrupted
  • Verify file format is supported
  • Try re-uploading the file

​
Slow Processing

Normal processing time: 30 seconds for typical documents Longer processing times may occur with:
  • Very large files (40-50MB)
  • Complex PDFs with many images
  • High system load
You can upload multiple documents simultaneously. The system processes up to 4 documents concurrently.

​
Next Steps

Cookbook: RAG Knowledge Base

Tutorial for adding a RAG knowledge base to your avatar agent

Knowledge Base Setup

Step-by-step guide to creating folders and uploading documents

Uploading Documents

Detailed guide on the upload process and batch uploads

Tools Overview

Learn about all available tool types including knowledge tools