Adding documents · AI Brain

The knowledge base is a collection of documents you upload that the AI uses as its reference library. When the AI gets a question — either from you or from a customer — it searches the knowledge base for relevant information and uses it to answer accurately.

How it works

When you upload a document:

The text is split into chunks of approximately 500–1,000 characters each
Each chunk is converted into a vector embedding (a numerical representation of its meaning)
Chunks and embeddings are stored in the database
When a question arrives, the question is also embedded and the most similar chunks are retrieved
Those chunks are injected into the AI's context as reference material

This technique is called Retrieval-Augmented Generation (RAG) — the AI retrieves facts rather than hallucinating them.

Supported file types

Type	Description
`txt`	Plain text file
`md`	Markdown file
`csv`	Comma-separated values (treated as text)
`pdf`	PDF document (text extracted)
`docx`	Word document (text extracted)
`url`	(planned) Fetch and index a web page
`manual`	Directly paste text content

Uploading a document

In the dashboard → AI Brain → Knowledge Base → Add document.

Choose your file type, upload or paste content, give it a descriptive filename, and click Add. The status starts as Processing and changes to Ready when indexing is complete.

Via the API:

POST /brain/knowledge
Content-Type: application/json
 
{
  "filename": "FAQ - Delivery & Shipping",
  "file_type": "manual",
  "content": "**Do you deliver internationally?** Yes, we ship to 50+ countries via DHL and FedEx. Standard delivery takes 7–14 business days...\n\n**What is your return policy?** We accept returns within 30 days of delivery..."
}

Response:

{
  "docId": "doc_01j...",
  "status": "ready",
  "chunksCreated": 4,
  "filename": "FAQ - Delivery & Shipping"
}

Document size limits

Limit	Value
Maximum document size	500 KB (text content)
Minimum document size	10 characters
Chunk size	~500–1,000 characters per chunk
Credit cost	Per chunk created (see Billing)

NOTE

PDF and DOCX files must be parseable text — scanned images (PDF without OCR) will produce low-quality or empty chunks.

Viewing your documents

AI Brain → Knowledge Base shows all uploaded documents with their status and chunk count.

Click a document to see a preview of the first 20 chunks. This helps you verify the chunking quality — if the AI is giving wrong answers, the chunk preview can show why.

GET /brain/knowledge

{
  "docs": [
    {
      "id": "doc_01j...",
      "filename": "FAQ - Delivery & Shipping",
      "file_type": "manual",
      "status": "ready",
      "chunk_count": 4,
      "created_at": "2026-06-15T10:00:00Z"
    }
  ],
  "total": 1
}

Deleting a document

Deleting a document removes it and all its chunks (including embeddings). The AI will no longer reference that content.

DELETE /brain/knowledge/:docId

Requires brain:memory.delete permission.

Tips for good knowledge base performance

Write for questions, not just facts. Instead of listing features, write in Q&A format. The AI retrieves chunks based on similarity to the question — chunks that are already written as answers to common questions match better.

Keep chunks focused. Long paragraphs that mix multiple topics produce lower-quality matches. Break content into short, focused sections.

Use descriptive filenames. The filename is shown to you in the document list but is not used by the AI during retrieval — it's for your reference only.

Update outdated documents. Delete the old version and upload a fresh one. There's no in-place update for documents.

Test with the copilot. After uploading, ask the copilot a question that should trigger the new document. If the answer is wrong or vague, check the chunk preview.