> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/settings/managing-knowledge-base.md).

# Managing Knowledge Base

{% hint style="info" %}
**Path:** `/settings/knowledge-base`
{% endhint %}

### Managing Knowledge Base Sources

The Knowledge Base stores articles that AI agents use to answer questions and provide support. Sources can be uploaded manually or connected from third-party tools. Configure at **Settings** → **Knowledge Base**.

Personal preferences (theme, Enter key, desk visibility) are configured in [Profile & Preferences](https://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md).

#### Understanding the Knowledge Base

The Knowledge Base enhances AI agent responses with your organization's documentation. Articles from sources are indexed and made available to agents. You can toggle **Enhance with general AI knowledge** to control whether agents use only KB content or can also use general knowledge. This toggle is located in the page header, alongside the "Knowledge base" title, making it easy to find at a glance.

#### Understanding KB Sources

Sources provide articles to the Knowledge Base:

* **Manual upload** - PDF files you upload directly
* **Third-party** - Confluence, Notion, Freshservice, SharePoint (requires integration)

Each source can have multiple articles. Articles sync periodically; status (Completed, Pending, Failed) is shown per article.

#### Adding Knowledge Base Sources

1. Go to **Settings** → **Knowledge Base**.
2. Click **Add source** (or Add knowledge source).
3. Choose:
   * **Upload file** - For manual PDF uploads
   * **Third-party** - Confluence, Notion, Freshservice, or SharePoint (when the integration is configured)

![Add source dropdown (Upload file, third-party)](/files/1X1ur332nIDZr6VW6kXX)

#### Uploading Files Manually

1. Choose **Upload file** from the Add source dropdown.
2. Drag and drop PDF files or click to browse.
3. **Supported file types** - PDF only.
4. **File size limit** - 50 MB per file.
5. Save. Articles are created and synced.

AI tagging applies automatically to manually uploaded PDFs, just as it does for integration-sourced content. Any PDFs you uploaded before this feature was introduced have been retroactively tagged, so your entire knowledge base benefits from consistent AI-driven categorization regardless of how content was added.

#### Connecting Third-Party Sources

**Prerequisites:** The integration (Confluence, Notion, Freshservice, SharePoint) must be connected in **Settings** → **Integrations**. If not configured, the add-source flow links to integrations.

**Steps:**

1. Choose the third-party source from the Add source dropdown.
2. A selection dialog opens with a tree view of available content (spaces, pages, etc.).
3. Search or browse to find articles.
4. Select the items to add.
5. Click **Save & sync** to add them and start syncing.

![Selection dialog with tree of spaces/pages](/files/axTR0R6WEIvgFSBuQtOT)

#### Understanding KB Sync Status

Each article has a sync status:

| Status        | Description                                |
| ------------- | ------------------------------------------ |
| **Completed** | Article synced successfully.               |
| **Pending**   | Sync in progress or queued.                |
| **Failed**    | Sync failed. Hover for the failure reason. |

#### Monitoring KB Sync Progress

The Knowledge Base table shows sync status per article. Use the status filter to see Pending or Failed items. For Failed items, hover the status badge to view the failure reason (e.g., permission error, invalid source).

![Knowledge Base table with articles and sync status](/files/c7ULq78IZjGBgP3vOkW6)

#### Understanding Sync Failures

When sync fails, the status badge shows **Failed**. A tooltip displays the `failure_reason`. Common causes: permission changes in the source, deleted content, or integration issues. Fix the underlying issue and re-sync (or re-add the source).

#### Controlling Private Information Detection

Harmony automatically detects and excludes documents containing sensitive or private data during knowledge base ingestion. This helps ensure that confidential information is not indexed and cannot be surfaced in AI-generated responses to your customers.

***

### Organizing KB Articles

#### Searching Knowledge Base Articles

Use the search box in the Knowledge Base table. It filters articles by the query string (e.g., title, content).

#### Filtering KB Articles by Status

Use the status filter: **Completed**, **Pending**, or **Failed**. Combine with other filters as needed.

#### Filtering KB Articles by Source

Filter by source type: Manual, Confluence, Notion, Freshservice, SharePoint.

#### Filtering KB Articles by AI Insights

When AI Insights is enabled, a dedicated set of filter options appears in the filter panel. You can narrow down articles across multiple AI-analyzed dimensions:

* **Knowledge type** - filter by the type of knowledge an article represents (also shown as a subtitle under each article title for quick scanning)
* **Category** - filter articles by their AI-assigned top-level category
* **Sub-category** - narrow results further within a category
* **Solution method** - filter by how the underlying issue is typically resolved

#### Sorting KB Articles

Sort by:

* **Title**
* **Status**
* **Owner**
* **File size**
* **Last synced**

Default sort is by last synced (newest first). Toggle ascending/descending.

#### Understanding Article Metadata

| Field              | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| **Article owner**  | Employee who owns or is associated with the article (avatar). |
| **File size**      | Formatted size (B, KB, MB, GB).                               |
| **Last sync date** | When the article was last synced, or "-" if never.            |

***

### AI Insights and Tagging

#### Understanding AI-Generated Tags

During each KB sync, Harmony automatically classifies articles across two tag dimensions:

* **Content tags** - visible in the KB table; describe what an article covers, including:
  * **Knowledge Type:** Troubleshooting, Setup, Policy, Information, or FAQ
  * **Category / Subcategory:** Matches your ticket tag taxonomy (e.g., Software > Productivity)
* **Usage tags** - used by the AI Service Agent and Copilot to improve recommendations

AI tagging applies to all articles regardless of source, including manually uploaded PDFs.

#### Viewing AI Insights on Articles

A dedicated **AI Insights** column in the Knowledge Base table displays tag pills for each article, giving you a quick at-a-glance summary of how Harmony has classified your content. Each article shows up to three tags inline, with a **+N** indicator when there are more. Hovering over the tags opens a detail card that breaks down the AI insights into structured sections:

* **Knowledge Type** - the broad classification of the article's content
* **Category** and **Sub Category** - hierarchical topic groupings
* **Solution** - the resolution method associated with the article

***

### AI-Generated KB Recommendations

#### Understanding KB Recommendations

Harmony's insights engine analyzes your resolved support tickets and support conversations to automatically surface Knowledge Base article recommendations. The system clusters related topics and identifies gaps or drift in your existing content, helping you keep your knowledge base aligned with what customers are actually asking about.

Recommendations appear in the **Recommendations** tab within the Knowledge Base page. The tab is only shown when there are pending recommendations - when none exist, the page displays a clean **Sources** header above your data table instead of an empty tabbed layout. When recommendations are present, the familiar **Sources** and **Recommendations** tabs appear as normal, and all table functionality including filters, pagination, and sorting continues to work in both views.

Recommendations can include:

* **New article drafts** - for topics with no existing KB coverage
* **Update drafts** - for articles where resolution steps have drifted from current practice
* **Rewrite drafts** - for articles with low success rates or high ticket reopens

Each recommendation includes evidence from real ticket resolutions so you can trace exactly what drove the suggestion.

#### Reviewing and Approving Article Updates

When Harmony's drift detection identifies that an existing KB article needs updating, it surfaces an update recommendation in the Recommendations tab alongside new article suggestions - so everything is in one place.

Update recommendations are visually distinguished from new article suggestions:

* An **"Update available"** badge clearly identifies update-type recommendations at a glance
* An **"Update article"** button replaces the standard "Create new article" call-to-action on update-type cards
* A notice on the detail page shows which existing article the update applies to

#### How Harmony Avoids Duplicate Insights

The system identifies whether a new insight relates to an existing one by comparing the support conversations that drove each insight. If enough conversations overlap, it is recognized as the same problem and handled accordingly:

* **No change detected** - if an insight already exists and its recommended resolution steps have not changed, it is left as-is
* **Updated insight** - if the resolution steps have evolved, the existing insight is refined rather than duplicated

This means the same underlying issue is improved over time rather than regenerated as a separate entry.

#### Understanding Resolution Steps in Recommendations

Resolution steps are displayed in a clear, structured format with explicit actor and action labels. Each role is represented by a distinct color-coded badge so you can immediately understand who is responsible for each action:

| Badge              | Color                           |
| ------------------ | ------------------------------- |
| **IT Agent**       | Violet                          |
| **Employee**       | Sky blue                        |
| **IT Operator**    | Grey                            |
| **Approver**       | Green                           |
| **Unknown actors** | Outlined (auto-formatted label) |

Conditional step instructions (for example, "if ..." clauses) are displayed separately beneath the relevant step.

#### Approved Insights Articles and AI Responses

When you approve an article generated from your support insights, it is instantly published and indexed so the AI can draw on that knowledge when responding to customers. If an article is later dismissed, it is automatically removed from the AI's knowledge base, keeping responses accurate and up to date. This creates a continuous feedback loop where your team's curation directly improves the quality of AI-powered support.

#### Filtering and Sorting Knowledge Sources by Conversation Count

In the Insights engine you can filter and sort your knowledge sources by conversation count, making it easier to identify which sources are driving the most (or least) support conversations:

* **Sort by conversation count** - order sources ascending or descending
* **Filter by minimum conversation count** - focus only on sources with meaningful volume
* **Filter by maximum conversation count** - narrow in on lower-traffic sources

***

### Managing KB Permissions

#### Understanding KB Permissions

KB permissions determine who can access articles. Permissions come from the source system (e.g., Confluence space permissions). Harmony displays them but does not let you change them in the Knowledge Base; update permissions in the source.

#### Viewing Authorized Groups

In the permissions view (or article detail), **Authorized groups** shows groups that have access. Each group appears as a badge. Groups are synced from the source.

![KB permissions dialog with Authorized groups](/files/Q4eXY5l895ujAYGRMHwf)

#### Viewing Authorized Users

**Authorized users** shows individuals with direct access. Displayed as avatars or email badges.

#### Understanding Unsynced Groups

When some groups from the source are not synced to Harmony (e.g., IdP sync gap), an amber badge appears with "Some groups are not synced." Resolve by syncing groups in User Management or the IdP.

#### Viewing Permission Warnings

For Confluence (and similar) sources, a **Permissions** warning button (lock or alert icon) may appear when there are permission issues. Click to view details. Fix permissions in the source system.

***

### Maintaining KB Content

#### Bulk Deleting KB Articles

1. In the Knowledge Base table, select one or more articles (checkboxes).
2. Click **Delete** in the toolbar.
3. Confirm in the dialog. Selected articles are removed from the Knowledge Base.

![Knowledge Base table with selection and Delete button](/files/PqR2oQrPzwtWwTgajEP6)

#### Single Delete

Click the delete (trash) button on an article row to remove it individually. Confirm when prompted.

#### Removing Knowledge Sources

There is no separate "remove source" action in the Knowledge Base. To stop syncing from a third-party source, disconnect the integration in **Settings** → **Integrations**. Individual articles can be deleted from the table.

#### Understanding KB Storage Limits

* **Per-file limit** - 50 MB per uploaded file.
* **Total storage** - No total storage or usage display in the UI. Storage is managed by your tenant limits.

#### Controlling AI Agent Knowledge Scope

You can configure whether the AI agent for Service Desk answers questions exclusively from your Knowledge Base, or also draws on its general trained knowledge. This setting is available in **Settings** → **Knowledge Base** via the **Enhance with general AI knowledge** toggle in the page header.

* **Knowledge Base only mode** - The AI agent returns answers sourced only from your KB. If no relevant answer is found, the agent escalates the ticket to a human agent rather than generating a response from general training data.
* **Knowledge Base + trained data mode** (default) - The AI agent uses your KB content first and supplements with its general trained knowledge when needed.

***

### Related Resources

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Profile &#x26; Preferences</strong></td><td>Theme, Enter key, desk visibility</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-your-profile-and-preferences/README.md</a></td></tr><tr><td><strong>Understanding Integrations</strong></td><td>Connect Confluence, Notion, and other KB sources</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/understanding-integrations/README.md</a></td></tr><tr><td><strong>User Management</strong></td><td>Notification destinations</td><td><a href="https://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md">https://github.com/harmonyso/public-docs/tree/main/guides/managing-user-management/README.md</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://docs.harmony.io/settings/managing-knowledge-base.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.