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:

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

Store scraped text as a markdown document:

{
  "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:

{
  "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:

{
  "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.