# Knowledge Bases

Knowledge bases let you upload documents (with metadata), keep them synced per environment, and query them at runtime from your agent.

## Concepts

* **Knowledge base**: A named container of documents that belongs to a specific agent.
* **Document**: A file (PDF, TXT, DOCX, etc.) plus optional metadata used for filtering.
* **Environment**: Separate datasets per environment: `development`, `staging`, `production`.

## Manage knowledge bases in the platform (UI)

### Create a knowledge base

1. Open your agent in the Minded dashboard
2. Navigate to **Knowledge Bases**
3. Click **Create knowledge base**
4. Set a **name** (and optional description) and save

### Update a knowledge base

You can update a knowledge base’s **name** and **description** from the knowledge base settings/details view.

### Delete a knowledge base

Deleting a knowledge base removes it from the agent and triggers cleanup of its documents across environments.

## Upload and manage documents (UI)

From the knowledge base view, you can upload documents and set labels and custom metadata for filtering and context enrichment.

### Document Labels

Each document supports two optional labels in `namespace:value` format:

* **label1**: Primary classification (e.g., `dept:support`, `topic:billing`)
* **label2**: Secondary classification (e.g., `lang:en`, `tier:premium`)

Labels can be used to **filter documents during retrieval** — only chunks from matching documents are returned.

### Custom Metadata

Each document also supports up to **four free-form custom metadata fields** (Custom Metadata 1–4). Unlike labels, these:

* Accept any string value (no namespace format required)
* Are limited to **500 characters** each
* Are **not filterable** — they cannot be used to restrict retrieval results
* Are **returned alongside every retrieved chunk** in the raw retrieval response

Use custom metadata to attach source identifiers, version numbers, author names, or other context you want available at retrieval time.

Typical flow:

* Upload a document (and optionally set labels and/or custom metadata)
* Wait for ingestion/sync to complete
* Use the platform “Query” / “Generate” actions to test retrieval and citations

## Manage documents via API

For programmatic document management (upload, update, metadata, delete), use the Knowledge API:

* Base URL: `https://api.minded.com/api/v1`
* Scope required: `knowledge-management`

See the full reference in [Knowledge API](/api/knowledge.md).

## Platform knowledge APIs (advanced)

These endpoints are used by the Minded dashboard. They are helpful for internal automation and debugging.

> **Note:** The dashboard APIs are not the same as the customer-facing `/api/v1/*` APIs. They require dashboard authentication and are mounted under the dashboard service.

### Knowledge base CRUD

All routes are scoped to an agent via `:agentId`.

* **List knowledge bases**
  * **GET** `/dashboard/agents/:agentId/knowledge/bases`
* **Create a knowledge base**
  * **POST** `/dashboard/agents/:agentId/knowledge/bases`
  * Body:

    ```json
    {
      "name": "Support KB",
      "description": "Policies and FAQs"
    }
    ```
* **Get a knowledge base**
  * **GET** `/dashboard/agents/:agentId/knowledge/bases/:knowledgeBaseId`
* **Update a knowledge base**
  * **PATCH** `/dashboard/agents/:agentId/knowledge/bases/:knowledgeBaseId`
  * Body:

    ```json
    {
      "name": "Support KB (v2)",
      "description": "Updated description"
    }
    ```
* **Delete a knowledge base**
  * **DELETE** `/dashboard/agents/:agentId/knowledge/bases/:knowledgeBaseId`

### Query and generate (platform testing endpoints)

These endpoints are commonly used by the dashboard UI to test retrieval and “retrieve + generate”.

* **Retrieve only**
  * **POST** `/dashboard/agents/:agentId/knowledge/:environment/kb/:knowledgeBaseId/query`
  * Body:

    ```json
    {
      "query": "What is the refund policy?",
      "numberOfResults": 5
    }
    ```
* **Retrieve and generate (with citations)**
  * **POST** `/dashboard/agents/:agentId/knowledge/:environment/kb/:knowledgeBaseId/generate`
  * Body:

```json
{
  "query": "Summarize the refund policy",
  "numberOfResults": 5,
  "modelArn": "optional-model-identifier",
  "filters": {
    "equals": { "key": "label1", "value": "dept:support" }
  }
}
```

If you want to query from agent code (recommended for runtime usage), use the SDK methods documented in [Knowledge Base RAG API](/sdk/knowledge-base-rag.md).

## Enable knowledge base usage in an agent

There are two common patterns: **automatic default retrieval** configured from the platform, and **manual retrieval** from code.

### Option A: Automatic default retrieval (platform configuration)

The platform can configure “RAG defaults” for your agent. When enabled, MindedJS will:

* Run retrieval automatically **after `TRIGGER_EVENT`**
* Retrieve from one or more configured knowledge bases
* Filter by `minScore` (if provided)
* Inject the retrieved context into the conversation as a **system message**

#### Default retrieval settings

Default retrieval is configured **per environment** (`development`, `staging`, `production`). Each environment can include:

* `enabled`: turn default retrieval on/off
* `knowledgeBases`: list of knowledge bases to query on every trigger
  * `knowledgeBaseId`: the KB ID to query
  * `environment` (optional): override which KB environment to query (defaults to the current environment)
  * `numberOfResults` (optional): how many chunks to retrieve
  * `minScore` (optional): discard results below this similarity score threshold
  * `filters` (optional): metadata filters applied to retrieval

#### Filter operators and templating

Default retrieval filters support these operators:

* `equals`
* `notEquals`
* `greaterThan`
* `lessThan`

Filter values can be either:

* A **plain string** (example: `"policy"`)
* A **memory chip pattern** in the exact form: `{state.memory.<path>}`
  * Example: `{state.memory.language}`
  * Nested values are supported with dot notation: `{state.memory.user.locale}`
  * If the memory value is missing (`null`/`undefined`), that filter entry is **skipped**

Multiple filter entries are combined with **AND** semantics.

#### Example default retrieval configuration

This is an example of the underlying shape (shown here for clarity; in practice it’s configured via the platform UI):

```json
{
  "production": {
    "enabled": true,
    "knowledgeBases": [
      {
        "knowledgeBaseId": "kb-abc123",
        "numberOfResults": 5,
        "minScore": 0.6,
        "filters": [
          { "key": "label1", "operator": "equals", "value": "dept:support" },
          { "key": "label2", "operator": "equals", "value": "{state.memory.language}" }
        ]
      }
    ]
  }
}
```

### Option B: Manual retrieval from code (e.g., in `TRIGGER_EVENT`)

If you need full control over *when* retrieval happens and *how* results are applied, you can:

Import directly from the SDK:

* `retrieveFromKnowledgeBase(...)`
* `retrieveAndGenerateFromKnowledgeBase(...)`

See:

* [Knowledge Base RAG API](/sdk/knowledge-base-rag.md)
* [Events → TRIGGER\_EVENT](/sdk/events.md#trigger_event) (includes an example of querying a knowledge base during trigger qualification)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.minded.com/platform/knowledge-bases.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.