Knowledge

Knowledge flows one way: files land in the Library, folders parse and embed them, sources are the parsed documents, and datasources keep folders filled from outside systems. Tags label sources along the way. Agents read it all through search_knowledge.

LibraryCopy Anchor Link

One page for everything stored: uploads, chat attachments, and agent-generated files list together, because every file is a Source with an origin (upload, chat, or agent). Three tabs — Files, Folders, Skills — each its own path.

Uploading straight into the Library stores and previews the file but never parses or embeds it: not knowledge, just a file. These uploads take most document, image, audio, video, and archive types, up to 10 MB. Knowledge starts when a file is uploaded into a folder.

FoldersCopy Anchor Link

A folder is a knowledge base: a named collection of sources with its own parsing, chunking, and indexing settings. Names are unique, and your plan caps how many folders you can have.

Folders are the exception to the platform sharing rule: absent sharing means not shared, so only people using an agent whose knowledge tool already covers the folder can attach it. Over the API, chunkStrategy takes type, chunk_size, and chunk_overlap.

Changing parsing or chunking reports how many sources went stale; reindexing is an idempotent background job, so re-running it after a partial failure picks up the remainder. Deleting a folder deletes its sources and their indexed chunks. It is refused while a datasource keeps its pages there — delete the datasource first.

Folder SettingsCopy Anchor Link

One workspace-wide setting for every folder, behind the gear on Library → Folders.

• Embedding model — turns sources into vectors. Dimensions follow the model. If nothing is saved, creating the first folder sets BAAI/bge-large-en-v1.5 at 1024 dimensions. The Free plan embeds with FastEmbed only.
• Image Reading — how text comes out of images and scanned pages. OCR (the default) reads locally at no cost. Vision model sends each image to a vision model you pick (gpt-6-luna by default, or gpt-6.1-sol, claude-sonnet-5-5, claude-opus-5-5, gemini-3.8-flash, gemini-4-argon), billed per image.

Pick the model before adding sources. Sources keep the vectors and image text they were processed with: after changing either setting, run Index on existing sources to process them again.

SourcesCopy Anchor Link

The single collection for all documents: files, pasted text, and web pages (a URL, with optional CSS selectors to keep or drop parts of the page). Each source carries its type, status, folder, tags, size, content, and sync provenance (which datasource and external version it came from). Titles are unique within a folder.

Files a folder accepts:

The largest file and the folder count depend on your plan:

A source moves through these statuses:

A source page has Preview and Chunks tabs. Chunks shows what indexing cut the source into, in document order, for indexed sources. The row menu re-runs processing: Index in an indexed folder, Extract otherwise.

The API covers the lifecycle: composable list (by folder, type, origin, or title), JSON create for text and web sources, multipart upload, a dry-run extract that parses without indexing, content streaming and byte replacement, a chunk list, and per-source get/update/delete/process. Uploads into a folder need the create permission; guest chat attachments don't.

POST /sources/search is the folder search box. It matches titles and retrieves content in one call, across every folder unless folderIds narrows it:

Results come back in raw retriever order with no reranking, which makes the box the place to compare strategies before setting one on an agent. If retrieval is down, content falls back to scanning stored text and the response says so.

Searching knowledgeCopy Anchor Link

Agents read folders through the search_knowledge tool (see Tools). One configured tool gives the model up to three tools that share its folder scope: search_knowledge, plus list_folder_sources and read_source. The tool needs at least one folder. A chat turn's attached folders or scope.folderIds (see Chat) narrow it for that turn; when none of the tool's folders is in scope, the tool is not offered.

OptionsCopy Anchor Link

Set on the tool. Out-of-range numbers clamp to the range.

Retrieval modesCopy Anchor Link

• semantic — ranks by meaning. Catches paraphrase; can miss exact identifiers.
• hybrid — meaning plus keyword ranking, fused. The best all-round recall.
• fulltext — keyword ranking only, with no semantic drift. For error codes, names, and quoted strings.
• auto — the model picks one of the three per call through the strategy input, defaulting to hybrid.

hybrid, fulltext, and auto need the keyword lane; without it they run as semantic.

Per-call inputsCopy Anchor Link

What the model sends on each call:

Calling again in the same turn skips chunks already returned, so a repeat query pages deeper. A beforeExecute hook receives { query } and may return a rewritten query; afterExecute can reshape the result.

Folders without vectorsCopy Anchor Link

Each folder is searched by what it holds:

• Indexed — vector search with the full pipeline above.
• Indexing off — keyword match over the extracted text. Hits are whole documents with a snippet.
• Parsing none — nothing to search. The tool says the documents were stored without being read and points the model at list_folder_sources.

Reading whole documentsCopy Anchor Link

Search returns fragments, which is the wrong shape for "compare these two documents". The two companion tools cover that:

• list_folder_sources — no inputs. Lists up to 200 documents with titles, sizes, folders, and whether each can be read; says when the list was cut off.
• read_source — takes a source_id from that list and returns the document's text, up to 60,000 characters. Longer documents are truncated and say so. A document stored without being read returns an error rather than empty text.

Context filtersCopy Anchor Link

contextFilters narrows results to the caller's own records. Each rule is { field, operator, value }:

• field — a chunk field such as metadata.source_id, or cf.<key> for a key in a source's metadata.
• operator — eq (one value), any (one of a list), or except.
• value — a static value, a list, or a placeholder such as ${user.id} or ${user.email}.

Filters fail closed: a placeholder that doesn't resolve, or an unsupported operator, drops the tool for the turn. With filters set, only indexed folders are searched, and list_folder_sources and read_source are not offered, since they can't apply the filters. There is no form for filters yet; set them through the API.

DatasourcesCopy Anchor Link

Connectors that fill one folder from an external system and keep it in sync on a schedule. Two kinds: Notion (OAuth consent, then page sync) and crawl (website discovery within a scope). A connector owns its folder and creates it, with indexing on, when none is given — named after the Notion workspace, or after the crawl, whose default name is the site's host. Datasource names are unique.

• Schedule is a five-field cron that runs at most every 15 minutes, in the organization's timezone. Leave it empty for manual-only sync.
• Syncs are incremental. New and changed pages are fetched; unchanged ones are skipped. A crawl spots changes by the sitemap's last-modified date or a hash of the page. Pages gone from a complete listing are removed; a listing cut short by a cap removes nothing.
• Preview runs a real discovery crawl and lists the pages it would read, with their depth and whether a cap stopped it. Sync is async (202 — follow the row's status).
• Disconnect is for Notion: it drops the credentials and stops the schedule, keeping fetched pages. A crawl has nothing to disconnect — clear its schedule or delete it.
• Delete stops the connector. Its pages stay in the folder as ordinary sources.

Crawl settings:

Robots.txt is always respected. Saving new crawl settings starts a sync; changing the selectors re-reads every stored page.

List rows carry folder, status (pending, active, syncing, error, revoked), schedule, last sync stats (scanned/created/updated/deleted/ skipped/failed), and account info — credentials never appear on the row; they live on the integration.

TagsCopy Anchor Link

Lightweight labels with an optional color, attached to sources by name at upload or edit — the tag picker can create one on the spot. Names are unique, 1–64 characters; a source takes up to 100 tags. Managed as a global list.