Knowledge Bases

Knowledge bases are collections of content sources that power AI agents with contextual information. They index content, generate vector embeddings, and provide intelligent retrieval capabilities.

What are Knowledge Bases?

A knowledge base is an organized collection of content sources that provides:

• Interactive Chat — Ask questions and have conversations with your indexed content using built-in RAG
• Vector Embeddings — AI-powered content representations for similarity matching
• Agent Context — Provide agents with relevant information automatically
• Content Triggers — Automatically run agents when content changes
• Multi-Source Indexing — Combine multiple sources into one searchable collection

Knowledge bases act as the "memory" for your AI agents, allowing them to access and reason about your content intelligently.

Creating a Knowledge Base

1. Navigate to the Knowledge Bases page
2. Click Create Knowledge Base
3. Give it a name and optional description
4. Select one or more content sources to include
5. Configure retrieval settings (or keep the defaults)

You can add or remove sources at any time after creation.

Retrieval Settings

Each knowledge base carries retrieval settings. They are not all the same kind of setting, and the difference decides whether changing one affects agents you have already built:

Reranker Model is inherited on every run. A retrieval step that leaves its own reranker unset uses whatever the knowledge base is set to, so changing it here changes how existing agents retrieve.

Building a knowledge base over the API instead? GET /models/rerankers and the list_reranker_models MCP tool list the available rerankers with their per-action credit cost and which one is the default. To turn reranking off, send "none" as reranker_model — that is not a value from the list.

Top N, Top K and Score Threshold are starting values, not live settings. When you pick this knowledge base on a new retrieval step, the editor fills these in for you — and from then on the step owns them. Changing them here never alters an agent you have already built, and never overwrites a value you set on a step yourself. Edit the step to change what a built agent retrieves.

Score Threshold filters on rerank scores only. It becomes the step's Minimum Rerank Score, which drops matches the reranker scored below it. It does nothing when reranking is off, and it never filters on similarity score — so it is not a general relevance cutoff. Matches a reranker cannot score, such as natively embedded images, are always kept.

A reranker is a text model — it scores your query text against each match's chunk text. Chunks indexed natively as images, audio or video carry no text, so a reranker has nothing to score for them — Seclai skips reranking automatically when a search turns up nothing it could score, and a retrieval step can override the knowledge base either way. A knowledge base is created with Reranker Model: None by default only when every one of its sources uses an embedding model that cannot handle text at all; a multi-modal model (the default) can index both, so it keeps the reranker for the text it holds. See Reranking and media knowledge bases.

Turning the reranker off over the API or MCP: send "none". reranker_model is three-valued on an update, and the three are easy to confuse. Omitting the field — or sending null — leaves the current reranker exactly as it is; it does not turn it off. Send the string "none" to turn reranking off, and a model id to switch to that model. The empty string is still accepted as a synonym for "none", but prefer "none": an empty string does not reliably survive every client's serialization, so it can arrive as nothing at all — which reads as "leave it unchanged".

Media Indexing

By default a content source indexes text only. You can also have a source extract media from the pages it indexes and embed it as multi-modal chunks, so the knowledge base can retrieve images (and video) by content — not just the surrounding text.

Choose it per source when you create the source — it is on the last step, above the retention options — or turn it on later from the source's Edit dialog under Media indexing:

Vector-drawn PDF pages are indexed as page images. Assembly instructions, schematics, exploded parts diagrams and CAD exports are drawn as vector art rather than embedded photographs, so there is no image inside them to pull out. For any page that contains no embedded image of its own, Seclai renders the page and indexes it as an image — so "index the images in this PDF" returns the pictures rather than nothing. Four things follow from that:

• It works page by page, not document by document. A manual whose cover page carries a bitmap logo still gets its illustration pages rendered; the cover contributes its logo, the rest contribute their pages.
• A page that already has an embedded image is not also rendered, so the same picture is never indexed — or billed — twice.
• Text-only pages are skipped. A page has to actually draw something to be rendered; pages that are just prose are left to the text index, so you are not billed for an embedding of a picture of text.
• Rendered pages are named after the page (page_7.png, versus page_7_image_0.png for an image the PDF genuinely contained) and carry their page number like any other PDF image match.

There is no page limit. A 400-page manual has all 400 of its illustrated pages indexed; extraction continues across as many passes as it takes, and you are billed for what it indexes, in the same way a long document is chunked into as many text chunks as it needs.

The count describes the content, not your source. Two sources that ingest the same document share one indexed copy, and media indexing is applied if any of them asked for it. So a source with media indexing off can still show a media count for a document another source also ingested — those chunks belong to that other source's knowledge bases, not yours.

Checking what was indexed. Open the content item and look at the media count next to the word count: it reads "12 media indexed", or "No media indexed" when the file was opened for media and nothing indexable was found. If the count is missing entirely, media indexing did not apply to that content at all. The same value is on GET /contents/{id} as extracted_media_count and on the get_source_content_text MCP tool.

Requires a multi-modal embedder. Media is only retrievable if the knowledge base's embedding model can index that modality. Most multi-modal embedders support images; video requires a video-capable embedder (e.g. Nova Multimodal). The Edit dialog only offers the media kinds your embedder can index (others are hidden), and any unsupported kind is dropped at index time — so enabling Video on a text/image-only KB is a no-op rather than an error. Audio and linked documents are not offered here because this setting is about pulling media out of a page — there are no pictures inside an MP3, and a PDF's pictures are already covered by Images.

Uploaded files are embedded whole, separately from this setting. On a multi-modal embedder, an uploaded image, video, audio file or PDF also gets one embedding of the file itself, alongside the text extracted from it — which is what makes a photograph findable by a photo, and an audio file findable by a sound. That happens for any source whose embedder can read the type, with no toggle, and each such embedding is billed at the embedder's rate for that modality. See searching with a photo.

Extracted media is fetched through an SSRF guard; an individual asset that fails to download or is unusually large (over 10 MB for an image, 25 MB for video) is skipped, leaving the rest of the document and the text index intact. Each embedded media chunk is billed at the embedder's standard rate.

There is no limit on how much media one document contributes. A 200-page catalogue indexes 200 figures, the same way a long text document is split into as many chunks as it takes. Usage scales with what you index, so a media-heavy source costs proportionally more — the content list shows how many images and videos each item contributed.

Media is extracted in the background, alongside the text, and a document with a lot of it can take several passes. It stays Indexing until both are finished, so an item that shows as indexed has all of its media indexed too. Interrupting a pass is safe: it resumes where it left off rather than starting the document again.

Web pages are the exception, and only for remote media. Images embedded directly in a page cost nothing extra, but a page that links out to hundreds of separate image, video, or document files would mean hundreds of downloads from someone else's server, so one pass will only fetch so much — 100 downloads, two minutes of fetching, and 250 MB in total.

An item cut short — a page that ran out of that download budget, or a file too damaged to read to the end — is marked media capped in the content lists, and opening it shows how many assets were indexed. That marker matters: media search will not match anything past the cut, and without it a partly-indexed item looks identical to a fully-indexed one. To index the rest, re-upload the file or re-fetch the page once it has changed — that produces a new version, which is extracted again from the start.

Where a media match came from. Each extracted image is indexed as its own chunk, so a match points at that individual image rather than the document containing it. Results carry the locators the source format actually provides:

These fields appear in the retrieval step output and in the search_knowledge_base MCP tool result, and citations name the image itself (e.g. [image: page_7_image_0.png (page 7)]) rather than repeating the document title for every hit. Content indexed before this was added keeps its old chunks until the source is re-indexed.

What a media match returns as its text. An extracted image has no text of its own, so the content field of a match carries the image's label — the alt text of an <img>, the title or aria-label of a <video>, or the wording of the link a document was fetched from. Three things to know about it:

• It is capped at 512 characters, and a longer one is cut with a trailing … rather than dropped. The label comes from the page being indexed, not from you, so it is bounded before it is stored — otherwise a single image could take up more of an agent's prompt than every real match around it. A genuine alt attribute is well under this; accessibility guidance recommends staying below about 125 characters.
• Line breaks in it are flattened to spaces. A label is a caption, not a document, and retrieval results are read by a model — one that could introduce new lines could dress itself up as a second match.
• It does not always affect what matches. Whether the label is part of what the image is searchable by depends on the knowledge base's embedding model: some multi-modal embedders can only embed the picture or the words, not both, and index the picture. The label is always stored and always returned; treat it as a caption you will see on a hit, not as a reliable way to make an image findable by keyword. To search images by wording you control, put the wording in the surrounding page text, which is indexed normally.

An extracted asset with no label at all — or one that is only whitespace or invisible characters — is cited by name instead: content carries the citation itself, [image: page_7_image_0.png (match 3)], so a match is never a blank body. That applies to any kind of asset, not just images: a <video> with no title or aria-label, or a linked document whose anchor had no text, is cited the same way. Images extracted from a PDF are the common case, since a PDF figure has no alt attribute to take. Square brackets inside a label are rewritten to parentheses, so a label can never be mistaken for one of those citations.

Chat

Every knowledge base has a built-in chat interface that lets you have interactive conversations with your indexed content. The chat uses RAG under the hood — each message triggers a retrieval against the knowledge base, then feeds the relevant content to an LLM to generate a grounded response.

Starting a conversation

Open a knowledge base and switch to the Chat tab. Type a question and press Enter. A new conversation is created automatically, and the response streams back in real time.

Key capabilities:

• Ask with a file — Attach an image, audio file, video or PDF to your message and the knowledge base is searched with the file itself, not just your words: photograph a page and ask which document it came from. Requires the knowledge base to be indexed with an embedder that reads that kind of file; a file it cannot read is set aside and your question is searched on its own. A message is still required, so a file always accompanies a question rather than replacing it. See searching with a photo for the full rules, including which embedders read which kinds.
• Multiple conversations — Create as many conversations as you need. Each one maintains its own message history and can be renamed, archived, or deleted.
• Model selection — Choose between Fast (Nova Lite), Balanced (Claude Sonnet), and Thorough (Claude Opus) tiers per message. You can also select a specific model from the full model catalogue.
• Streaming responses — Responses stream token-by-token so you see results immediately.
• Conversation management — Rename conversations for easy reference, archive old ones to keep the sidebar clean, or bulk-delete conversations you no longer need.
• Regenerate responses — If a response isn't satisfactory, regenerate it to get a fresh answer.
• Copy and feedback — Copy any message to your clipboard, and use the thumbs-up/down feedback buttons to rate response quality.

How it works

When you send a message, Seclai:

1. Retrieves relevant content chunks from the knowledge base using the configured retrieval settings (Top N, Top K, reranker, score threshold)
2. Constructs a RAG prompt with the retrieved context and your conversation history
3. Sends the prompt to the selected model and streams the response back

Conversations persist across sessions — come back any time to continue where you left off.

API Access

Knowledge bases can be managed programmatically via the Public API using your API key:

# List knowledge bases
curl "https://api.seclai.com/knowledge_bases?page=1&limit=20" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Create a knowledge base
curl -X POST https://api.seclai.com/knowledge_bases \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech News KB",
    "description": "Aggregated tech news sources",
    "source_ids": ["source-id-1", "source-id-2"]
  }'

# Get a knowledge base
curl "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY"

# Update a knowledge base. Only the fields you send are changed;
# the rest are left exactly as they were.
curl -X PUT "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Renamed KB", "default_top_k": 10}'

# Turn reranking off. Send the string "none" — omitting the field, or
# sending null, leaves the current reranker in place.
curl -X PUT "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reranker_model": "none"}'

# Delete a knowledge base
curl -X DELETE "https://api.seclai.com/knowledge_bases/$KNOWLEDGE_BASE_ID" \
  -H "X-API-Key: $SECLAI_API_KEY"

Field names in the request body must match exactly — unrecognised keys are ignored, not rejected, so a misspelled field silently does nothing. The retrieval settings are reranker_model, default_top_n, default_top_k and default_score_threshold.

source_ids replaces the whole list, so send every source you want to keep, not just the new ones. Omit the field to leave the sources untouched. An empty list is rejected — a knowledge base must keep at least one source; to stop using one entirely, delete it.

To see which reranker model ids you can pass, and what each costs:

curl "https://api.seclai.com/models/rerankers" \
  -H "X-API-Key: $SECLAI_API_KEY"

Each entry carries the model_type to pass as reranker_model, its credits_per_action, and whether it is the platform default (is_default — what you get when you omit reranker_model on create).

Turning reranking off is not a model, so it does not appear in that list: pass the literal string "none" as reranker_model.

See API Examples for more examples in multiple languages.

MCP Tools

Knowledge base operations are available as MCP tools for AI coding assistants:

See MCP Server → Knowledge Base Tools for setup instructions.

Exporting

Export a knowledge base's full content — sources, metadata, and indexed items — as a downloadable JSON file.

• UI: Open the knowledge base detail page and click the Export button. You'll see an estimate of the export size before confirming.
• API: POST /authenticated/resource-exports with resource_type: "knowledge_base" and the knowledge base ID.
• MCP: Use the create_resource_export tool with resource_type: "knowledge_base".

See Export Formats → Knowledge Base for the full file schema and available filter options.

Next Steps

• Content Sources — Learn about content sources
• Contents — Inspect, replace, and delete indexed content items
• Agents — Build agents that use knowledge bases
• API Examples — Code samples for the API
• API Reference — Complete API documentation
• MCP Server — Use knowledge base tools from AI coding assistants