Custom Knowledge Base

Custom Knowledge Base: Trieve & Bring-Your-Own Server

Overview

The Knowledge Base and Query Tool Setup pages cover the general concept and the fastest dashboard- and API-driven paths to giving an assistant a knowledge base. This page is specifically about the two provider-level integration approaches underneath those: connecting or creating a Trieve vector store, and building a fully custom knowledge base server of your own. Use this page when you need retrieval-tuning control (chunking, search heuristics) or when neither built-in provider fits and you want to bring your own retrieval backend entirely.

Approach A: Trieve Vector Store Integration

Trieve is a vector store provider you can connect to a knowledge base in one of two ways:

Connect an existing Trieve vector store — if you already manage a Trieve dataset, reference it directly with vectorStoreProviderId.
Create a new Trieve vector store from uploaded files — upload files through the Files API first, then create the knowledge base with those file IDs, and a new Trieve-backed vector store is provisioned for you automatically.

Chunking & Ingestion Options

When a new vector store is created from files, you can tune how documents are split into retrievable chunks:

Field	Purpose
`splitDelimiters`	Custom characters or strings used to split source documents into chunks, instead of relying on default sentence/paragraph boundaries
`targetSplitsPerChunk`	The target number of delimiter-separated splits grouped into a single chunk, controlling how large or small each retrievable chunk is
`rebalanceChunks`	Rebalances chunk sizes after initial splitting so no single chunk ends up disproportionately larger or smaller than its neighbors

Search Heuristics

Field	Purpose
`scoreThreshold`	Minimum relevance score a chunk must meet to be returned as a search result — raising it reduces false positives at the cost of occasionally missing borderline-relevant matches
`removeStopWords`	Strips common stop words ("the", "a", "is", etc.) from the query before searching, which can improve match quality on short, keyword-style queries

Approach B: Fully Custom Knowledge Base Server

For complete control over retrieval — a proprietary vector database, a hybrid search system, or logic that doesn't fit a standard vector store at all — you can implement your own knowledge base server and register it as a custom-knowledge-base provider.

Step 1: Register Your Server

curl --location 'https://api.sulus.ai/knowledge-base' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "provider": "custom-knowledge-base",
    "server": {
        "url": "https://your-domain.com/kb/search",
        "secret": "your-webhook-secret"
    }
}'

Step 2: Attach via knowledgeBaseId

A custom knowledge base can only be attached to an assistant through the API, not the dashboard, and it's attached at the model level via knowledgeBaseId:

curl --location --request PATCH 'https://api.sulus.ai/assistant/YOUR_ASSISTANT_ID' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--data '{
    "model": {
        "model": "gpt-4o",
        "provider": "openai",
        "messages": [
            { "role": "system", "content": "Your existing system prompt..." }
        ],
        "knowledgeBaseId": "YOUR_KNOWLEDGE_BASE_ID"
    }
}'

Important: this PATCH request replaces the entire model object. Include every existing field you want to keep, not just knowledgeBaseId, or the rest of the model configuration will be overwritten.

Step 3: Handle the Request Your Server Receives

Whenever the assistant needs to retrieve information, your endpoint receives a POST request shaped like this:

{
  "message": {
    "type": "knowledge-base-request",
    "messages": [
      { "role": "user", "content": "What is your return policy?" }
    ]
  }
}

Step 4: Respond in One of Two Formats

Option 1 — return documents for the assistant's model to reason over and incorporate into its own response:

{
  "documents": [
    {
      "content": "Relevant text chunk...",
      "similarity": 0.92,
      "uuid": "chunk-id-123"
    }
  ]
}

Option 2 — return a direct, pre-formed message that the assistant speaks verbatim instead of generating its own reply:

{
  "message": {
    "role": "assistant",
    "content": "Based on our knowledge base, here is the answer..."
  }
}

Response Time

Your endpoint should respond in roughly 50 milliseconds ideally, with a hard maximum of 10 seconds. Slower responses noticeably degrade conversational flow, since the assistant is waiting mid-call for your server before it can reply to the caller. Always fail gracefully (for example, returning an empty documents array) rather than letting a request time out or error.

Trieve vs. Custom Knowledge Base: Comparison

	Trieve Vector Store	Custom Knowledge Base Server
Setup effort	Low — upload files or connect an existing store	Higher — you build and host a server endpoint
Retrieval logic	Managed by Trieve, tunable via chunking & search heuristic fields	Fully under your control — any backend, any ranking logic
Dashboard support	Available via dashboard or API	API only
Response format flexibility	Documents only	Documents, or a direct pre-formed message
Best for	Most standard document/FAQ retrieval use cases	Proprietary data stores, hybrid search, or logic that doesn't fit a standard vector store

In summary: use the Trieve integration when you want managed vector search with tunable chunking and relevance heuristics and minimal setup; use a fully custom knowledge base server when you need complete control over the retrieval backend and response shape. For the general knowledge base concept and the dashboard-first path, see Knowledge Base; for the type: "query" tool object and file-management detail, see Query Tool Setup.

On this page