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 metadata for filtering.

Typical flow:

• Upload a document (and optionally add 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.

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:

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

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

    {
      "query": "What is the refund policy?",
      "numberOfResults": 5
    }

• Retrieve and generate (with citations)

  • POST /dashboard/agents/:agentId/knowledge/:environment/kb/:knowledgeBaseId/generate

  • Body:

    {
      "query": "Summarize the refund policy",
      "numberOfResults": 5,
      "modelArn": "optional-model-identifier",
      "filters": {
        "equals": { "key": "category", "value": "policy" }
      }
    }

If you want to query from agent code (recommended for runtime usage), use the SDK methods documented in Knowledge Base RAG API.

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):

{
  "production": {
    "enabled": true,
    "knowledgeBases": [
      {
        "knowledgeBaseId": "kb-abc123",
        "numberOfResults": 5,
        "minScore": 0.6,
        "filters": [
          { "key": "category", "operator": "equals", "value": "policy" },
          { "key": "language", "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

• Events → TRIGGER_EVENT (includes an example of querying a knowledge base during trigger qualification)