# Knowledge

Use Knowledge tools to find and read Redbelt content, organize folders, bring files into a task workspace, upload results, and update Markdown safely.

## Before you start

Open **Customize → Plugins** and select this plugin. Choose **Add** if it is available and not installed; **Uninstall** means it is already installed. Availability depends on the deployment and administrator policy. Enable the plugin for the selected agent or task using [agent setup](/agents/create/).

This package does not require a separate external app account for its own Redbelt tools. Its work can still depend on configured services, sandbox availability, selected files, or a separate authorized connection. Adding the package does not grant access to additional data. Review the installed tool controls and handle any requested [action approval](/threads/approvals/).

![Use Knowledge plugin in Redbelt](/screenshots/current/plugin-knowledge.png)

Plugin details under **Customize → Plugins**. The button shows the current installation state.

## Assemble a launch brief from sources

1. List the relevant Knowledge folder or search for material about your project.
2. Read selected paths and preserve the source references for each finding.
3. Ask Redbelt to draft a brief that separates confirmed milestones from unresolved questions.
4. Create a destination folder only if the existing structure does not already contain one.
5. Upload the reviewed result into the chosen folder, then read or list the saved item to verify it.

> Read the project planning files I select from Knowledge and draft a brief with milestone owners and open questions. Cite the sources and mark missing information. Show me the brief and ask which folder to use before uploading it.

## Choose the right file operation

Listing explores a location; search finds candidates; reading supplies content. Follow cursors for paginated listings rather than treating the first page as the whole folder. Reads are bounded, so split large source sets into deliberate batches.

Downloading copies selected Knowledge items or supported file references into the sandbox for processing. Uploading saves a task file into a Knowledge folder named by path, such as `/Clients/Acme/2026`, or by folder ID. The path can name any folder you can edit, even outside the folders selected for the thread, and missing folders along it are created where you may create them. A successful local file write alone is not a Knowledge upload.

New content becomes a new file; if the folder already holds that name, the new file gets a numbered name such as `report (1).docx`. When you ask Redbelt to update or fix a file it just made or you referenced, it replaces that file in place as a new revision, keeping its name, folder, and sharing; this works for any file type and needs edit access to the file. When it is unclear whether you want the existing file replaced or a new copy, Redbelt asks first.

Markdown updating replaces the body at an existing path and requires its **expected revision**. Read the current body and revision first, preserve unrelated content, and submit the complete replacement. A revision conflict means another edit happened: reread and reconcile rather than overwriting it blindly.

## Tool Reference

Thread and workflow availability are listed separately. A tool must also be enabled for your task and allowed by its account and administrator policy. [Configure workflow app actions](/workflows/apps/) using only actions offered by the current picker.

### Available Tools

| Tool                        | Required Fields                        | Thread | Workflow |
| --------------------------- | -------------------------------------- | ------ | -------- |
| `knowledge.download`        | `items`                                | Yes    | No       |
| `knowledge.list`            | No mandatory top-level fields          | Yes    | No       |
| `knowledge.markdown.update` | `path`, `content`, `expected_revision` | Yes    | No       |
| `knowledge.mkdir`           | No mandatory top-level fields          | Yes    | No       |
| `knowledge.move`            | No mandatory top-level fields          | Yes    | No       |
| `knowledge.read`            | `paths`                                | Yes    | No       |
| `knowledge.search`          | `query`                                | Yes    | No       |
| `knowledge.upload`          | `source`                               | Yes    | No       |

Required fields above are the schema minimum. The target, selected operation, or account can impose additional requirements.

**`knowledge.download`** — Copy Knowledge files into the task's workspace so other tools can use them.
Optional fields: `overwrite`.

**`knowledge.list`** — List files and folders.
Optional fields: `cursor`, `filters`, `limit`, `path`, `recursive`, `sort`.

**`knowledge.markdown.update`** — Replace one authorized Markdown file using optimistic revision control.

**`knowledge.mkdir`** — Create a Knowledge folder by name (optionally inside parent_folder_id), or a whole path such as /Clients/Acme/2026 with missing parents created.
Optional fields: `description`, `instructions`, `name`, `parent_folder_id`, `path`.

**`knowledge.move`** — Move files (upload_ids) and folders (folder_ids) into another Knowledge folder, named by destination_path or destination_folder_id.
Optional fields: `destination_folder_id`, `destination_path`, `folder_ids`, `upload_ids`.

**`knowledge.read`** — Read Knowledge files, or files the task created, as text or images.
Optional fields: `chunk_ranges`, `source`.

**`knowledge.search`** — Search the person's Knowledge files and return the most relevant passages, each with a link to its file.
Optional fields: `folder_ids`, `paths`, `upload_ids`.

**`knowledge.upload`** — Save files the task created into any Knowledge folder you can edit, by path or id, or replace an existing file in place.
Optional fields: `destination_name`, `folder_id`, `folder_path`, `if_exists`, `recursive`, `replace_upload_id`.

## Troubleshoot

If a path is missing, refresh the folder listing and use its canonical path or identifier. For revision conflicts, compare the current Markdown with the intended edit. Check upload processing before treating the content as searchable.
