# 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](https://docs.minded.com/api/knowledge).

## 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](https://docs.minded.com/sdk/knowledge-base-rag).

## 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](https://docs.minded.com/sdk/knowledge-base-rag)
* [Events → TRIGGER\_EVENT](https://docs.minded.com/sdk/events#trigger_event) (includes an example of querying a knowledge base during trigger qualification)