<!-- BusyBot node reference — https://busybot.net/tools/knowledge-base/ -->

> Node: Knowledge Base (`knowledge_base`) · Action (binary) · v1
> Category: Data & Storage · Credentials: none
> Updated: 2026-08-16

# Knowledge Base

> Create knowledge bases and manage their documents

## Overview

Manages BusyBot knowledge bases from a workflow: create/delete a knowledge base, add a document (from binary data or text — extracted, summarized and indexed by the standard ingestion pipeline), replace an existing document in place, remove documents, and list knowledge bases or their documents.

**Category:** Data & Storage  
**Tool Name:** `knowledge_base`  
**Version:** 1

**Appearance:** Icon: `lucide-BookOpen` | Color: `#8B5CF6`

## Node Type

**Action (Binary)** — handles file/binary data operations

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | `Input` |
| Output | `Output`, `Error` |

## Credentials

This tool does not require any credentials.

### Operations

| Operation | Value | Description |
|-----------|-------|-------------|
| Add Document | `addDocument` | Extract, summarize and index a new document |
| Update Document | `updateDocument` | Replace an existing document's content, keeping its ID |
| Remove Document | `removeDocument` | Delete a document by ID or file name |
| Create Knowledge Base | `createKnowledgeBase` | Create a new (empty) knowledge base |
| Delete Knowledge Base | `deleteKnowledgeBase` | Permanently delete a knowledge base and its content |
| List Knowledge Bases | `listKnowledgeBases` | List this user's knowledge bases |
| List Documents | `listDocuments` | List the documents in a knowledge base |

### Parameters

`List Knowledge Bases` takes no parameters of its own — see All Operations.

#### Add Document (`addDocument`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Knowledge Base | `string` | Yes | — | The knowledge base ID or its exact name. Supports expressions like {{ $json.kbId }}. |
| Content Source | `options` | No | `binary` | Where the document content comes from. |
| | | | | Options: `binary` (a file from an upstream node — download, read file, S3, …), `text` (text or markdown built from the item) |
| Binary Property | `string` | No | `data` | Name of the binary property holding the file. _(shown when Content Source is `binary`)_ |
| Text | `string` | No | — | The document content. Supports expressions like {{ $json.body }}. _(shown when Content Source is `text`)_ |
| File Name (`fileName`) | `string` | No | `document-{{ $index }}.md` | File name stored with the document. The EXTENSION selects the extractor (.md, .txt, .pdf, .docx, .xlsx, .csv, .html, images, audio, video). On Update Document, leave empty to keep the current name. |
| Regenerate Knowledge Base Summary | `boolean` | No | `true` | Regenerate the knowledge-base-level summary once after the batch. Off is cheaper but leaves the summary stale, which searches will report. |
| Busy Wait (Seconds) | `number` | No | `120` | How long to wait for another writer (a KB manager upload or another node) to release this knowledge base. |

#### Update Document (`updateDocument`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Knowledge Base | `string` | Yes | — | The knowledge base ID or its exact name. Supports expressions like {{ $json.kbId }}. |
| Content Source | `options` | No | `binary` | Where the document content comes from. |
| | | | | Options: `binary` (a file from an upstream node — download, read file, S3, …), `text` (text or markdown built from the item) |
| Binary Property | `string` | No | `data` | Name of the binary property holding the file. _(shown when Content Source is `binary`)_ |
| Text | `string` | No | — | The document content. Supports expressions like {{ $json.body }}. _(shown when Content Source is `text`)_ |
| File Name (`fileName`) | `string` | No | `document-{{ $index }}.md` | File name stored with the document. The EXTENSION selects the extractor (.md, .txt, .pdf, .docx, .xlsx, .csv, .html, images, audio, video). On Update Document, leave empty to keep the current name. |
| Document ID (`docId`) | `string` | No | — | ID of the document to replace. Supports expressions. |
| Regenerate Knowledge Base Summary | `boolean` | No | `true` | Regenerate the knowledge-base-level summary once after the batch. Off is cheaper but leaves the summary stale, which searches will report. |
| Busy Wait (Seconds) | `number` | No | `120` | How long to wait for another writer (a KB manager upload or another node) to release this knowledge base. |

#### Remove Document (`removeDocument`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Knowledge Base | `string` | Yes | — | The knowledge base ID or its exact name. Supports expressions like {{ $json.kbId }}. |
| Remove By | `options` | No | `docId` | How to identify the document(s) to remove. |
| | | | | Options: `docId`, `fileName` (removes every document with this exact name) |
| Document ID (`removeDocId`) | `string` | No | — | ID of the document to remove. Supports expressions. _(shown when Remove By is `docId`)_ |
| File Name (`docFileName`) | `string` | No | — | Exact file name of the document(s) to remove. Supports expressions. _(shown when Remove By is `fileName`)_ |
| Fail If Not Found | `boolean` | No | `true` | Error when no document matches. Turn off to report notFound and continue. |
| Regenerate Knowledge Base Summary | `boolean` | No | `true` | Regenerate the knowledge-base-level summary once after the batch. Off is cheaper but leaves the summary stale, which searches will report. |
| Busy Wait (Seconds) | `number` | No | `120` | How long to wait for another writer (a KB manager upload or another node) to release this knowledge base. |

#### Create Knowledge Base (`createKnowledgeBase`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Name | `string` | Yes | — | Name of the new knowledge base. Supports expressions. |
| Description | `string` | No | — | Optional description. It is given to the search agent as context. |
| If It Already Exists | `options` | No | `getExisting` | What to do when a knowledge base with this name already exists. |
| | | | | Options: `getExisting` (return the existing one), `create` (create another), `fail` |

#### Delete Knowledge Base (`deleteKnowledgeBase`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Knowledge Base | `string` | Yes | — | The knowledge base ID or its exact name. Supports expressions like {{ $json.kbId }}. |
| Confirm Deletion | `boolean` | No | `false` | Required. Deleting a knowledge base removes every document and its stored content permanently. |
| Unlink From Agents | `boolean` | No | `true` | Also remove this knowledge base from any agent that references it. |

#### List Documents (`listDocuments`)

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Knowledge Base | `string` | Yes | — | The knowledge base ID or its exact name. Supports expressions like {{ $json.kbId }}. |
| Include Summaries | `boolean` | No | `false` | Include each document's generated summary in the listing. |

#### All Operations

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Max Concurrency | `number` | No | `5` | Items prepared concurrently. Writes to a knowledge base are always serialized. |

## Output Data

One output item per input item. The result is written to `knowledgeBase` on the output item; the rest of the item JSON passes through unchanged, and binary data is forwarded.

Every result carries `operation`, `kbId` and `kbName`, plus `kbSummaryRegenerated` when the knowledge base summary was rebuilt during that run. The remaining fields depend on the operation:

| Operation | Fields on `knowledgeBase` |
|-----------|--------------------------|
| `addDocument` | `docId`, `fileName`, `tokenCount`, `pages`, `summary`, `condensedSummary` — or `skipped: true` with `reason: "unchanged"` and the existing `docId` when the content is already in the knowledge base |
| `updateDocument` | `docId` (unchanged), `fileName`, `tokenCount`, `pages`, `summary`, `condensedSummary`, `replaced: true`, `previousFileName` |
| `removeDocument` | `removed: [{ docId, fileName }]` — or `removed: []` with `notFound: true` and a `message` when nothing matched and Fail If Not Found is off |
| `createKnowledgeBase` | `kbId`, `name`, `description`, `status`, `documentCount`, `totalTokens`, `created` (`false` when an existing knowledge base was returned) |
| `deleteKnowledgeBase` | `kbId`, `name`, `unlinkedAgents` (the agent IDs the knowledge base was removed from), and `alreadyDeleted: true` if the same knowledge base was targeted more than once in the run |
| `listKnowledgeBases` | `knowledgeBases[]` (`kbId`, `name`, `description`, `status`, `documentCount`, `totalTokens`, `kbSummary`, `updatedAt`, `health`) and `count` |
| `listDocuments` | `documents[]` (`docId`, `fileName`, `fileType`, `tokenCount`, `pages`, `status`, plus `summary` and `condensedSummary` when Include Summaries is on) and `count` |

Reference the result downstream by expression, e.g. `{{ $json.knowledgeBase.docId }}`.

## Usage Examples

- add this PDF to the Product Manuals knowledge base
- store the scraped article as a document in my knowledge base
- create a knowledge base for support tickets if it does not exist
- remove the outdated document from the knowledge base
- list the documents in a knowledge base

## Example Configuration

Add a downloaded PDF to a knowledge base:

```json
{
  "type": "knowledge_base",
  "parameters": {
    "operation": "addDocument",
    "knowledgeBase": "Product Manuals",
    "contentSource": "binary",
    "binaryPropertyName": "data",
    "fileName": "{{ $json.title }}.pdf"
  }
}
```

Store scraped text as a markdown document:

```json
{
  "type": "knowledge_base",
  "parameters": {
    "operation": "addDocument",
    "knowledgeBase": "kb_1765432100000_ab12cd34",
    "contentSource": "text",
    "text": "# {{ $json.title }}\n\n{{ $json.body }}",
    "fileName": "{{ $json.slug }}.md",
    "regenerateSummary": true
  }
}
```

Create the knowledge base only if it does not exist yet:

```json
{
  "type": "knowledge_base",
  "parameters": {
    "operation": "createKnowledgeBase",
    "name": "Support Tickets {{ $json.year }}",
    "description": "Resolved tickets, one document per ticket",
    "ifExists": "getExisting"
  }
}
```

Remove superseded documents by file name:

```json
{
  "type": "knowledge_base",
  "parameters": {
    "operation": "removeDocument",
    "knowledgeBase": "Product Manuals",
    "removeBy": "fileName",
    "docFileName": "{{ $json.oldFile }}",
    "failIfMissing": false
  }
}
```

### Error Handling

| Mode | Behavior |
|------|----------|
| **stop** | Halts workflow on first error |
| **continue** | Skips failed items, passes successful ones through |
| **errorPort** | Routes failed items to Error output port |

## Tips

Manages knowledge bases and their documents from a workflow. Creates or deletes a knowledge base, adds a document from binary data or text (the file is extracted to markdown, summarized and indexed exactly like a KB manager upload), replaces an existing document in place keeping its docId, removes documents by id or file name, and lists knowledge bases or documents. Use it to keep a knowledge base fed by a pipeline — scrape or download content, then add it — and pair it with Search Knowledge Base to read the results back. Adding and updating cost LLM tokens (summarization); documents whose content is unchanged are skipped automatically.

### Behavior notes

- **Batching.** All items targeting the same knowledge base are applied in ONE pass: one content-bundle rebuild and one KB-summary regeneration per KB per node run, not per document.
- **Duplicate content is skipped.** Identity is the sha256 of the file bytes, never the file name. Re-adding unchanged content returns `skipped: true, reason: "unchanged"` and costs no tokens.
- **`updateDocument` keeps the docId**, so existing citations stay valid.
- **Lists return an array on one item** — use a Split Out node on `knowledgeBase.knowledgeBases` or `knowledgeBase.documents` to fan out.
- **Cost.** Adding/updating runs extraction (OCR/vision/transcription for images, audio and video) plus a multi-pass summarizer; these tokens are metered to the workflow owner. Removing and listing cost nothing unless the KB summary is regenerated.