Help & Guides

Knowledge is the foundation of intelligence in Alkimi. It allows you to transform your agents from generic assistants into specialized experts grounded in your proprietary data. By organizing documents, websites, and text into structured Collections, you provide the definitive source of truth that your agents use to answer questions, reason through problems, and automate tasks.

The Knowledge section is your central hub for managing these assets. Here, you can ingest diverse data sources (from PDF manuals and research papers to live documentation websites) and organize them into secure, permission-controlled libraries. Once a Collection is connected to an agent, it acts as a private, long-term memory that the agent can query instantly, ensuring every response is accurate, relevant, and strictly based on the information you've verified.

Collection List

The Knowledge Collections page is your central hub for viewing, managing, and creating knowledge bases within your workspace. It displays all collections you have access to in either a grid (cards) or list (table) layout.

• Collection Cards: Each card shows the collection's name, item count, last updated date, and a content breakdown bar showing the proportion of files (blue), text (purple), and websites (green). Hover the bar segments to see counts.
• Search: Filter collections by name.
• Org-wide: By default, you only see collections in your current workspace. Organization Admins can toggle "Org-wide" to see collections across all workspaces, including ones they don't belong to. The toggle is shown to workspace members holding both Create Collections and Manage Settings, but the request succeeds only for org Admins; external members cannot use it.
• Grid / List Toggle: Switch between visual cards and a compact table view with sortable columns (Collection, Content, Items, Blocks, Updated).
• Right-Click Menu: Right-click any collection for quick actions: Settings or Delete. Collections imported from cloud storage or Canvas also offer Resync to pull in changes from the source.
• + New Collection: The dropdown button offers multiple creation paths: Blank Collection, From Canvas Module, From Google Drive Folder, From OneDrive Folder, From Dropbox Folder, or From Box Folder.

Creating a Collection

To get started, you'll need to create a collection. This acts as a container for your documents. You can have multiple collections for different topics or projects.

Content Management

Content within a collection is organized in a hierarchical structure, similar to a file system. The Content Explorer is the primary interface for browsing, adding, and managing your knowledge items. You can view content in either a table (detailed list with columns for type, blocks, status, and last updated) or grid (visual cards) layout.

Item Status

The status column follows each item through ingestion. Agents can only search an item once it is Active; everything before that is in-flight work you can leave running while you navigate elsewhere.

• Uploading / Waiting: The file is still leaving your browser (large uploads queue behind each other).
• Queued: Received and waiting for a processing worker.
• Crawling n/m pages: Websites only: pages fetched so far out of the crawl limit.
• Reading n pages, Describing n figures, Indexing: The processing stages: text extraction (OCR for scanned pages and images), figure descriptions, then embedding the blocks so they become searchable. A progress fill on the row tracks each stage.
• Active / Inactive: Ready to search. Deactivating an item keeps it in the collection but hides it from agents.
• Failed: Processing stopped; hover the status for the reason. The item's menu offers Retry (for transient errors) and Delete; fix the source first when the cause is the content itself (for example an unreadable file or a website that blocks crawlers).

It's important to note that the folder hierarchy has no bearing on agent responses. It is purely an organizational tool to help you manage permissions and activate or deactivate content in bulk.

Explorer Controls

The Content Explorer supports rich file-management interactions:

• Drag & Drop: Drag items onto folders to move them, or drop external files directly into the explorer to upload them.
• Right-Click Context Menu: Right-click any item to access actions like Open, Rename, Cut, Download, and Delete. Selected items download together as a zip.
• Multi-Select: Use checkboxes, Ctrl+Click for multiple items, or Shift+Click for range selection. Ctrl+A selects all.
• Keyboard Shortcuts: Cut (Ctrl+X), Paste (Ctrl+V), Rename (F2), Delete (Del), Deselect (Esc).
• Search: Filter items by name within the current view.
• Breadcrumb Navigation: Click folder names in the breadcrumb bar to jump back up the hierarchy.

Naming & Structure

To maintain a clean and functional structure, the following naming rules apply:

• Item names cannot contain a forward slash (/).
• Folder names cannot exceed 64 characters.
• The names for files, text, and website items cannot exceed 150 characters.

While the system supports nesting folders up to 32 levels deep, we recommend keeping your folder structure relatively shallow (2-3 levels deep) to ensure easy navigation and management.

Content Types

You can add content to your collections in several ways:

Cloud Storage Imports

If your organization has cloud storage integrations enabled (see Account Integrations), you can import files directly from connected services like Google Drive, OneDrive, Dropbox, or Box. This allows you to keep your knowledge base in sync with your existing document repositories.

Activating & Deactivating Content

Each item in your collection, including folders, can be individually activated or deactivated. Deactivating an item temporarily removes it from the knowledge base available to agents without permanently deleting it. This is useful for temporarily excluding certain documents or entire folders from agent responses.

Viewing an Item

Opening an item shows the original document next to the blocks extracted from it. PDFs and converted Office documents render page by page with each block outlined in place; spreadsheets open as a worksheet; Markdown, LaTeX, JSON and source code open as line-numbered text. The Blocks tab lists every retrievable block with its role (paragraph, table, figure, code symbol), page or line range, nearest heading and OCR confidence, and the Table of Contents tab is built from the document's own headings. Selecting a block or heading scrolls the document to it. Blocks are read-only: they are regenerated whenever the item's content is replaced, so there is nothing to edit, split or merge by hand.

How Retrieval Works

When you add a document, it is broken into blocks: paragraphs, tables, code symbols, or spreadsheet rows, each tagged with its position and the heading it sits under. When a user asks a question, the agent searches every active collection for the blocks that best match the question. There is nothing to configure per collection; every collection uses the same retrieval.

Matched blocks do not arrive alone. Each block records the other blocks it structurally depends on, and retrieval follows those links automatically:

• Strong links pull in content the match cannot be understood without: the header row for a spreadsheet slice, the class a method belongs to, or the definition of a symbol the code calls.
• Weak links add the neighboring paragraphs within the same section so the agent sees the surrounding argument, without crossing into unrelated sections.

Everything retrieved is then fitted to the agent's context budget. Loosely linked neighbors are dropped first and the direct matches last, so the most relevant material always survives. This is a best-effort process rather than a guarantee: very large questions or very small budgets can still leave context out.

Profile

Each Knowledge Collection has a profile page where you can manage its name and description. This page also shows you which agents currently have access to the collection, allowing you to track its usage across your organization.

Danger Zone

The profile page contains the "Danger Zone," where you can permanently delete the entire collection and all the files within it. This action cannot be undone.

Permissions

Control who can use and manage this collection. Similar to agents, you can set a default access role for all members of the workspace and grant explicit, overriding permissions to specific members. The Public Access card lets you enable Public Guest Access, which allows public agents to use the collection for visitors who are not logged in; a default workspace role must be set first.

Collection Roles

Collection roles are fixed and global — they cannot be customized or extended. Each member is assigned exactly one role per collection. This is different from organization and workspace roles, which are fully customizable.

Statistics

Gain insights into how your knowledge collection is growing, being used, and performing. The statistics dashboard provides real-time metrics to help you optimize your content.

Overview Metrics

The top row provides a quick snapshot of your collection's health and usage:

• Content Overview: Tracks the total number of items (files, websites, text) and individual blocks (the paragraphs, headings, list items, tables and figures the retrieval system searches) in your collection. It also shows the breakdown of active vs. inactive content.
• Usage: Displays the total number of times blocks have been retrieved from this collection and how many messages have utilized it. It also tracks "unused blocks" to help you identify content that might not be relevant.
• Storage: Shows the total disk space used by your collection and the average size of your items.

Charts & Trends

Visualize your collection's activity over the last 7, 30 or 90 days, or a custom date range:

• Content Growth: Visualizes how your collection has grown over time, broken down by content type (Files, Websites, Text).
• Usage Over Time: Tracks the daily volume of messages that have successfully retrieved information from this collection.

Block Usage Heatmap

This visual tool helps you understand exactly which parts of your documents are being used.

• Each cell represents a 5% segment of a document.
• Darker blue indicates that specific section is frequently retrieved by agents.
• This is powerful for identifying the "hot spots" in your knowledge base—the specific paragraphs or sections that contain the answers your users are looking for.

Top Retrieved Content

A ranked list of the documents that are most frequently accessed by your agents. You can sort this list by:

• Total Retrievals: The raw number of times the document was used.
• Avg. Retrievals/Block: A normalized metric that helps you identify highly efficient documents (short documents that are used often).

Agent Usage Breakdown

See which agents are relying most heavily on this collection. This helps you understand the downstream impact of your knowledge base and which agents are driving knowledge consumption.

Activity

The Activity page provides a detailed audit log of all changes made to a knowledge collection. This ensures transparency in how your organization's data is being managed.

• Content Ingestion: When new files, websites, or text items are added to the collection.
• Content Deletion: When items or folders are removed from the knowledge base.
• Settings Updates: Changes to the collection's name, description, or access defaults.
• Activation Toggles: When items are activated or deactivated for use by agents.
• Permission Updates: Changes to the explicit access roles granted to organization members.