Knowledge Base - Cloosphere Guide

When you ask the AI a question and it replies “I don’t know” or gives an off-topic answer, that’s where the Knowledge Base comes in. By converting your internal documents into a form the AI can reference directly, the Knowledge Base enables accurate, document-grounded answers.

Example

“What is our company’s annual leave policy?”

State	Behavior	Result
No Knowledge Base	Answers from general AI knowledge	Inaccurate or “I don’t know”
Knowledge Base connected	Searches `hr-policy.pdf` for related content, then answers	Accurate policy + citation

Each Knowledge Base can use a different Document Processing Profile with its own extraction method and chunking strategy. See Document Processing Profile Selection below for details.

Collections and Libraries

The Knowledge Base list mixes two kinds of card, told apart by the badge at the card’s top left (Library in blue, Collection in green). Create each with + New Knowledge · New Library at the top right of the list.

	Collection	Library
Structure	A flat bundle of documents, no folders	A container with a folder tree
Shown on the card	File count · last updated	Folder count · file count
Best for	Gathering documents on one topic in one place	Moving an already-foldered pile of documents structure and all

Working with a Library

Open a library and you get the folder tree on the left, and the selected folder’s file list on the right.

Control	Where	What it does
Search folders and files	Search box above the tree	Searches every folder of the library at once
Import folder · structure + files	Below the tree	Pulls a folder from your PC in with its subfolder structure intact
+ New collection	Below the tree	Creates a new folder inside the library
Process all · N pending	Below the tree (only when files are unprocessed)	Embeds every unprocessed file in the library in one go

Each folder behaves like an independent Knowledge Base. A new folder inherits its parent’s filter schema, extraction mode, extraction model, search settings, and access control at creation, and you can change each of them per folder afterwards.Tool description is the one exception — it is not inherited. “When to search this folder” has to differ per folder, so it starts empty.

Inside a library folder, the AI button next to the tool description fills the whole subtree, not just that folder. Leaf folders are drafted from a sample of their filenames and parent folders from a summary of their children, bottom-up — so one click at the root folder fills the entire library. Folders that already have a description are skipped, and a “Generated descriptions for N folders” toast confirms the result.

Agents can connect an entire library. The knowledge picker on the agent edit screen has Library / Collection / Document filters so you can narrow by type.

Deleting a library or a folder deletes the whole subtree, files and vectors included. It is not a “detach from the group” action — it removes the structure itself, and it cannot be undone. A confirmation dialog appears first.

Naming rules differ too. A collection name must be unique across the workspace, but folder names inside a library only need to be unique among siblings — so every department’s library can have its own “Contracts” folder.

If the folder names themselves are your classification axis (e.g. project-number/doc-type/file), pair this with a filter’s Folder mapping. Upload a folder and the folder names fill the metadata values directly, with no LLM extraction needed. See the Dynamic Filters Deep-Dive for details.

RAG Pipeline

Uploaded documents go through this pipeline before becoming searchable.

Stage	Description
Apply Profile	Applies the extraction/chunking strategy from the KB’s document processing profile
Extract Text	Extracts text from documents (default, OCR, LLM Vision, etc., depending on profile)
Chunking	Splits long documents into search-friendly sizes (fixed-size or semantic)
Preserve Tables	Keeps tables intact in adjacent chunks instead of splitting (per profile)
Preserve Context	Adds an LLM-generated summary of the document context to each chunk (per profile)
Embedding	Converts text to high-dimensional vectors
Similarity Search	Finds chunks most similar to the question
LLM Response Generation	Generates an answer using the retrieved documents as context

Creating a Knowledge Base

Enter basic information

In Workspace > Knowledge Base, click + New Knowledge at the top-right to open the create form. Enter a name and description, then set the permission.

Knowledge Base creation form — Enter name and description, and set access permissions

Field	Description	Example
Name	KB name (required)	“HR Policy 2024”
Description	Purpose and content (required)	“HR team policies and guidelines”
Permission	Public / Private. If private, pick targets in the Groups card below	Private + “Sales”

Upload documents

Add documents to the new Knowledge Base. Click the Add Content (+) button to choose an upload method.

Knowledge Base detail — Use Add Content (+) to choose file upload, text input, or cloud sources

Upload methods:

Method	Description
Drag and Drop	Drag files onto the upload area
Upload Files	Select “Upload Files” from the “Add Content” menu
Upload Directory	Select “Upload Directory” — bulk-upload all files in a folder
Cloud Storage	Google Drive, OneDrive, SharePoint (visible when admin has configured)
Add Text	Write text directly to add as content

Wait for processing

Uploaded documents go through text extraction → chunking → embedding → indexing automatically. A real-time notification appears when processing completes.

Files that take more than 30 minutes to process are auto-failed. Delete and re-upload the file in that case.

Bulk uploads:

5+ files or directory uploads switch to batch mode
A progress bar shows steps (upload → processing) at the top, with failures shown in red
3 files are processed in parallel
Progress state persists across page refreshes

Verify and validate

Click a document to view extracted text and connect it to an agent to validate retrieval quality. Toggle Summary in the file list to see the AI-generated document summary.

Supported File Formats

The default extraction engine recognizes text in the following formats. Switching the extraction engine widens this coverage (see Content Extraction Engine below).

Category	Supported Formats
Documents	PDF, DOCX, RST, EPUB, MSG (Outlook mail)
Spreadsheets	XLSX, XLS, CSV
Presentations	PPTX, PPT
Web / Markup	HTML, HTM, XML, MD
Text / Source code	TXT, PY, JS, TS, JSON, SQL, JAVA, GO, C, C++, CS, RB, RS, PHP, SH, and ~50 more

Extensions not listed can still be uploaded — they are read as plain text. However, binary files such as ZIP or executables may be ingested as garbled content, so we recommend uploading the formats above. An admin can configure an allowed-extension whitelist to restrict uploads to specific formats only.

Max Size / Count

Item	Default	Where to change
Max file size	No limit	Admin Panel > Settings > Documents > Files (unit: MB)
Max file count	No limit	Admin Panel > Settings > Documents > Files

Both values are unlimited by default. Leaving an admin field empty means no limit; entering a number rejects any file exceeding that threshold at upload time.

Dynamic Filters

Dynamic filters let you classify documents in a KB by metadata and automatically narrow the search scope.

For internal mechanics of dynamic filters — Manual vs. AI comparison, 5-step search flow, and more — see the Dynamic Filters Deep-Dive.

Defining the Filter Schema

Click “Add Filter” in Knowledge Base settings to define filter fields.

Filter schema definition — Define filter fields to classify documents by metadata

Setting	Description	Example
Field Name	Filter field name	”Department”, “Year”
Type	Data type	Single Select, Multi Select, Glossary, Date, Number
Mark as required	Warns files that leave this field empty when it’s set as required	Required ON/OFF toggle
Folder mapping	On folder upload, stores the folder name at this depth as the value	None / Folder level 1–3
Filter Options	List of allowed values (Single Select / Multi Select types)	“Finance, HR, Engineering”
Agent Description	Description so the AI understands the filter	”Filter by the document’s department”

Filter Types

Type	Description
Single Select	Single selection from predefined options
Multi Select	Multiple selections from predefined options
Glossary	Define a filter by selecting a glossary
Date	Date range filter
Number	Integer filter

Per-File Metadata Settings

After defining the filter schema, set metadata values per file. A filled fields / total filters badge at the far right of each file row shows the state at a glance.

File metadata input — Per-file metadata state is shown as a fill badge

Badge color	Meaning
Green	All filter fields have values
Blue	Required fields are filled; some optional fields are empty
Orange	A required field is empty
Gray	Nothing filled and no filter marked required

While AI extraction runs, an “Extracting” badge replaces the count; with no filters defined, the badge doesn’t appear at all. Color is decided by whether required fields are satisfied, not by how many are filled.

When metadata changes, the vector index is updated automatically. Existing vectors are kept — no re-embedding required.

AI Auto-Extraction

When you set an extraction prompt on the filter schema, the LLM analyzes document content and filename at upload time and auto-extracts metadata.

Set extraction mode

Click the Manual / AI toggle in the filter schema and switch to AI mode.

Write the extraction prompt

Write an extraction prompt for each filter. Example: “Extract the country name from the filename”

Pick an AI model

Select the LLM model for extraction.

Run extraction

Runs automatically on upload, or run single/all extraction manually.

Method	Description
Auto-extraction	Runs automatically right after upload (AI mode + an extraction hint present)
AI Extract	Re-extract just that file from the Metadata panel that opens when you click it
Extract (N)	Bulk-extract the checked files from the toolbar above the file list

You can use “filename” as a condition in the extraction prompt. Example: “If the filename starts with [XX] (country code), extract that country code”

Filter Use During Search

When a connected KB has dynamic filters, the AI auto-infers filter conditions from the user’s question to narrow search scope.

Q: Show me the Finance team's 2024 policies
→ Filters auto-applied: department=Finance, year=2024
→ Searches only matching documents

Tool Description

Tool Description, at the top of the Knowledge Base detail screen, is the AI-only description that tells the agent when and in what situations to search this Knowledge Base. The screen itself reads “Describe when the agent should search this knowledge base.”

Example of a good tool description

Use when there are questions about company HR policies and internal guidelines.
Reference for HR-related questions like leave, benefits, and travel policies.

If the tool description is empty, the KB’s general description is used instead. We recommend writing a specific one so the AI can pick the right Knowledge Base among many. AI auto-generation: Click the AI button next to the tool description — it drafts the text from the KB name, description, file list, and filter info. The dropdown beside it picks the model used for generation.

Connect a Knowledge Base with an empty tool description to an agent and a “Tool description is missing” warning appears above the knowledge list, naming the items involved. It still saves, but the agent has a harder time deciding when to use that Knowledge Base.

The filter edit form has its own field also called Agent Description. That one describes a single filter; the tool description here describes the whole Knowledge Base. The Dynamic Filters Deep-Dive lays out the difference.

Knowledge Base Management

Document Management

Action	Method
Add document	Add Content (+) button or drag-and-drop
Delete document	Select a document and click delete
View content	Click a document to preview the extracted text
Search	Search by filename (server-side, fast even on large KBs)
Sort	Newest (default) / Oldest / By name
Review changes	Activity History button at the top

The file list uses infinite scroll to load 50 entries at a time. File state badges:

Badge	Meaning
Failed (red)	Processing failed — click Retry next to it
Processing (orange)	Processing in progress
Summary (toggle)	Processed + summary available — click to view inline summary
N/M (fill badge)	Metadata fill state, shown only when filters exist

Re-uploading a file with the same name shows a duplicate confirmation dialog.

Option	Behavior
Overwrite	Delete the existing file and replace
Skip	Skip the duplicate, keep the existing file
Cancel	Cancel upload

Reindexing

To rebuild the vector index for the entire KB, run reindex from Admin Panel > Settings > Documents. This is admin-only and processes all KBs at once. When you edit and save an individual file’s content, only that file is automatically re-processed.

Using in Chat

@ Command
Agent Connection

Reference directly during chat with @kb-name.

@hr-policy What is the leave application process?

Click citation numbers in the AI response to view the source content.

Document Processing Profile Selection

New feature — Apply different document processing strategies (extraction engine, chunking method, table preservation) per Knowledge Base.

Choose one of the profiles defined by the admin in Admin Panel > Settings > Documents. If you don’t pick one, the default profile applies.

Profile Use Cases

Knowledge Base	Recommended Profile	Reason
HR policy (text PDF)	Default Extraction	Plain text, no extra cost
Financial report (many tables)	Table Preservation enabled	Improves table data search accuracy
Scanned documents (image PDF)	LLM Vision	Accurately extracts text inside images
Technical docs (long reports)	Semantic Chunking + Context Preservation	Topic-based separation + preserved opening context

Only admins can create profiles. If a needed profile is missing, ask your admin. See Admin Panel > Settings > Documents for profile setup.

Advanced Settings

Adjust document processing and search parameters in admin settings.

These settings are global defaults for KBs without a Document Processing Profile. KBs with a profile use the profile settings instead.

Content Extraction Engine

Choose the engine for extracting text from documents in admin settings.

Engine	Strengths	Best For
Default (PyPDF/Langchain)	No setup needed	Plain-text PDF, DOCX
Tika	Server required, supports many formats	Mixed file formats
Docling	Server required	Complex layout documents
Azure Document Intelligence	Azure subscription required, high-precision OCR	Scanned documents, table-heavy PDFs
Mistral OCR	Mistral API required	PDF OCR
Google Cloud Document AI	GCP subscription required	Documents with embedded images
LLM Vision	Vision LLM-based, high precision	Complex layouts, charts

Image files (PNG, JPG, etc.) are not text-indexed by default — they are stored but their contents are not searchable. To search text inside images, set the knowledge base’s document processing profile to Google Cloud Document AI or LLM Vision. (Azure Document Intelligence and Mistral OCR handle PDF and Office documents but do not support standalone image files.)

Document Processing Profile Options

Setting	Description	Default
Name	Enter the document processing profile name	-
Default Engine	Engine used for files whose extension has no engine mapping	built-in engine
Extension → Engine Mapping	Use the selected engine for specific registered extensions	-
Text Splitter	Choose how to split text (default, token, semantic)	Default (character)
Preserve Tables	Keep tables attached to the preceding text chunk instead of splitting them during chunking	Enabled
Contextual Chunking	Add a per-chunk context summary to improve search accuracy	See the note below

Contextual chunking only takes effect when a Context Model is also selected. On a new profile the switch appears on, but the model is empty so nothing is applied. Pick a model and save to use it. It also does not apply to files attached ad hoc in chat — only to documents loaded into a knowledge base.

Text Splitter options:

Setting	Description	Default	Applies To
Chunk Size	Document split unit (characters)	1,000	Default (character), Token
Chunk Overlap	Overlapping characters between chunks	100	Default (character), Token, Semantic
Min Tokens per Chunk	Minimum characters to form a chunk	-	Default (character), Token, Semantic
Max Tokens per Chunk	Maximum characters to form a chunk	-	Default (character), Token, Semantic
Threshold Type	Type of similarity criterion for splitting chunks	Percentile (recommended)	Semantic
Threshold	Split-decision threshold per threshold type	-	Semantic

Embedding Engine

Engine	Strengths
Default (SentenceTransformers)	No external transmission, strong security
Ollama	Local server, custom models
OpenAI	High quality, API costs
Azure OpenAI	Optimized for enterprise
Gemini	Google embedding model, GCP integration
Vertex AI	GCP managed embedding service

Search Settings

Search settings have two layers — global (admin) and per-KB.

Setting	Default	Description
Top K	Global setting	Chunks to retrieve via vector search
Reranker Top K	Global setting	Final chunks after reranking
Reranker Threshold	Global setting	Minimum reranker score (lower = more pass through)

Override search settings per Knowledge Base. Click the Search Settings icon on the KB edit screen. All three fall back to the global setting when left empty — the greyed-out number in each field is the global value currently in effect. Review or change it under Admin › Settings › Search Engine.

Per-KB Document Summary Settings

Control document summary generation per KB. Configure under the “File Summary” section in the search settings modal.

Setting	Description	Default
Enable File Summary	Auto-generate AI summary on file processing completion	On
Summary Model	LLM model for summarization	Uses Task Model

For files with summaries, click the “Summary” toggle in the list to view inline.

Question Generation (Multi-Vector Search)

When question generation is enabled, the LLM pre-generates “questions a user might ask to find this content” for each chunk and stores them as separate vectors.

State	Search Method	Effect
Disabled	Content vectors only	Standard search
Enabled	Weighted sum of content + question vectors	Improved accuracy with user-question-style phrasing

Enabling question generation adds LLM calls during document processing. Processing time and cost may increase.

Configure question generation per KB independently of the global setting. Use the “Question Generation” section in the search settings modal to enable/disable and select the LLM model.

Best Practices

Document Preparation

Clean format: Distinguish titles and subheadings clearly with consistent styling
Keep current: Update documents regularly and remove old ones
Right size: Split large documents by topic and group related content together

Knowledge Base Composition

Separate by topic: Create separate KBs for “HR Policy”, “IT Guide”, “Product Manual”, etc.
Granular access: Manage sensitive info separately and restrict access by department
Write tool descriptions: A specific tool description helps agents auto-pick the right KB

Use Cases

New Employee Onboarding

Build Knowledge Bases of HR policy, work manuals, and IT guides so new hires can adapt quickly by asking the AI.

Knowledge Bases: “HR Policy”, “Work Manual”, “IT Usage Guide”
Connect 3 KBs to the agent
Differentiate KB purposes via tool descriptions

Customer Support Automation

Build Knowledge Bases of product manuals, FAQs, and technical docs to provide accurate answers to customer inquiries.

Dynamic filters: filter by product name, version
Agent: customer-support system prompt + Knowledge Base connection
Use citation display to ensure trust

Per-Department Policy Management

Classify per-department documents with dynamic filters and search the right policies by department.

Dynamic filters: department, year, document type
AI auto-extraction for metadata
Access control to protect sensitive documents

FAQ

Are there KB capacity limits?

By default, there’s no limit on file count or capacity. Admins can set limits via environment variables.

What happens if I re-upload the same file?

When a file with the same name is detected, a duplicate confirmation dialog appears with Overwrite, Skip, or Cancel options.

Is text inside PDF images recognized?

The default extraction engine extracts text from images embedded in PDFs to a limited degree, but for scanned documents or image-heavy PDFs, Azure Document Intelligence, Google Cloud Document AI, or LLM Vision engines are much more accurate. To upload a standalone image file (PNG/JPG) and search its text, a Google Cloud Document AI or LLM Vision profile is required. Check the extraction engine setting with your admin.

Does changing dynamic filter metadata require re-embedding?

No. Metadata changes only update the vector index’s filter fields; existing vectors stay intact. Processed quickly without re-embedding.

What happens to search settings when multiple KBs are connected to one agent?

When multiple KBs are connected, search settings merge as follows:

Top K, Reranker Top K: Use the largest value across KBs
Reranker Threshold: Use the lowest value across KBs (more results pass)

Does changing the Document Processing Profile affect existing documents?

Existing documents’ vectors are not auto-reprocessed when the profile changes. To apply the new profile to existing documents, delete and re-upload them, or run a full reindex from admin settings.

What's the cost of LLM Vision or Context Preservation?

LLM Vision: page count × 1 LLM call + 1 heading-level normalization call
Context Preservation: chunk count × 1 LLM call

For a 10-page PDF + 20 chunks: LLM Vision (11 calls) + Context Preservation (20 calls) ≈ 31 LLM calls. Bulk uploading large documents can cost a lot, so use selectively for important docs.

Dynamic Filters Deep-Dive

Filter internals, Manual vs AI, the 5-step search flow

Knowledge Graph

Connect Knowledge Bases + glossaries + DBs into one graph

Agents

Connect a Knowledge Base to an agent

Glossary

Improve AI understanding by defining domain terms

​Example

​Collections and Libraries

​Working with a Library

​RAG Pipeline

​Creating a Knowledge Base

​Supported File Formats

​Max Size / Count

​Dynamic Filters

​Defining the Filter Schema

​Filter Types

​Per-File Metadata Settings

​AI Auto-Extraction

​Filter Use During Search

​Tool Description

​Knowledge Base Management

​Document Management

​Reindexing

​Using in Chat

​Document Processing Profile Selection

​Profile Use Cases

​Advanced Settings

​Content Extraction Engine

​Document Processing Profile Options

​Embedding Engine

​Search Settings

​Per-KB Document Summary Settings

​Question Generation (Multi-Vector Search)

​Best Practices

​Document Preparation

​Knowledge Base Composition

​Use Cases

​FAQ

​Related Pages

Dynamic Filters Deep-Dive

Knowledge Graph

Agents

Glossary

Example

Collections and Libraries

Working with a Library

RAG Pipeline

Creating a Knowledge Base

Supported File Formats

Max Size / Count

Dynamic Filters

Defining the Filter Schema

Filter Types

Per-File Metadata Settings

AI Auto-Extraction

Filter Use During Search

Tool Description

Knowledge Base Management

Document Management

Reindexing

Using in Chat

Document Processing Profile Selection

Profile Use Cases

Advanced Settings

Content Extraction Engine

Document Processing Profile Options

Embedding Engine

Search Settings

Per-KB Document Summary Settings

Question Generation (Multi-Vector Search)

Best Practices

Document Preparation

Knowledge Base Composition

Use Cases

FAQ

Related Pages