> ## Documentation Index
> Fetch the complete documentation index at: https://hellotars.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure a retriever

> Create, test, and promote a retriever on a knowledge base.

export const Browser = ({url, children}) => <div className="tars-browser">
    <div className="tars-browser-bar">
      <span className="tars-browser-dots">
        <i />
        <i />
        <i />
      </span>
      {url ? <span className="tars-browser-url">{url}</span> : null}
    </div>
    <div className="tars-browser-view">{children}</div>
  </div>;

export const img = {
  activity: {
    activityTimeline: "/docs/guides/activity/images/activity-timeline.png",
    capturedVariablesPanel: "/docs/guides/activity/images/captured-variables-panel.png",
    dataViewCards: "/docs/guides/activity/images/data-view-cards.png",
    exportDataDialog: "/docs/guides/activity/images/export-data-dialog.png",
    tasksPanelExportReady: "/docs/guides/activity/images/tasks-panel-export-ready.png"
  },
  analytics: {
    analyticsOverview: "/docs/guides/analytics/images/analytics-overview.png",
    exploreGallery: "/docs/guides/analytics/images/explore-gallery.png",
    exploreTab: "/docs/guides/analytics/images/explore-tab.png",
    goalForm: "/docs/guides/analytics/images/goal-form.png",
    goalsTab: "/docs/guides/analytics/images/goals-tab.png",
    improveDiagnostics: "/docs/guides/analytics/images/improve-diagnostics.png",
    improveTab: "/docs/guides/analytics/images/improve-tab.png",
    teamTab: "/docs/guides/analytics/images/team-tab.png"
  },
  billing: {
    billingOverview: "/docs/guides/billing/images/billing-overview.png",
    buyConversationsDialog: "/docs/guides/billing/images/buy-conversations-dialog.png",
    buySeatsDialog: "/docs/guides/billing/images/buy-seats-dialog.png",
    livechatSeatsTab: "/docs/guides/billing/images/livechat-seats-tab.png",
    organizationDeletionLifecycle: "/docs/guides/billing/images/organization-deletion-lifecycle.svg",
    organizationSwitcher: "/docs/guides/billing/images/organization-switcher.png",
    rolesAndAccessMatrix: "/docs/guides/billing/images/roles-and-access-matrix.png"
  },
  building: {
    agentBehaviorGuardrails: "/docs/guides/building/images/agent-behavior-guardrails.png",
    agentCardMenu: "/docs/guides/building/images/agent-card-menu.png",
    agentConfigure: "/docs/guides/building/images/agent-configure.png",
    agentExitRoutesDialog: "/docs/guides/building/images/agent-exit-routes-dialog.png",
    agentLibrary: "/docs/guides/building/images/agent-library.png",
    agentModelParameters: "/docs/guides/building/images/agent-model-parameters.png",
    aiAgentGambitLoop: "/docs/guides/building/images/ai-agent-gambit-loop.svg",
    builderBasics: "/docs/guides/building/images/builder-basics.png",
    builderConnectHandlePanel: "/docs/guides/building/images/builder-connect-handle-panel.png",
    builtInToolsDialog: "/docs/guides/building/images/built-in-tools-dialog.png",
    configureDebugTab: "/docs/guides/building/images/configure-debug-tab.png",
    configureLanguage: "/docs/guides/building/images/configure-language.png",
    configureNotifications: "/docs/guides/building/images/configure-notifications.png",
    createAgentDialog: "/docs/guides/building/images/create-agent-dialog.png",
    draftPublishRollbackPinning: "/docs/guides/building/images/draft-publish-rollback-pinning.svg",
    draftSwitcherChip: "/docs/guides/building/images/draft-switcher-chip.png",
    duplicateAgentDialog: "/docs/guides/building/images/duplicate-agent-dialog.png",
    flowConditions: "/docs/guides/building/images/flow-conditions.png",
    gambitPalette: "/docs/guides/building/images/gambit-palette.png",
    gambits: {
      gambitAiAgent: "/docs/guides/building/gambits/images/gambit-ai-agent.png",
      gambitApiCall: "/docs/guides/building/gambits/images/gambit-api-call.png",
      gambitAutoSuggestion: "/docs/guides/building/gambits/images/gambit-auto-suggestion.png",
      gambitButton: "/docs/guides/building/gambits/images/gambit-button.png",
      gambitCard: "/docs/guides/building/gambits/images/gambit-card.png",
      gambitChannel: "/docs/guides/building/gambits/images/gambit-channel.png",
      gambitCustomCode: "/docs/guides/building/gambits/images/gambit-custom-code.png",
      gambitDateTime: "/docs/guides/building/gambits/images/gambit-date-time.png",
      gambitGeoLocation: "/docs/guides/building/gambits/images/gambit-geo-location.png",
      gambitLanguage: "/docs/guides/building/gambits/images/gambit-language.png",
      gambitLiveChat: "/docs/guides/building/gambits/images/gambit-live-chat.png",
      gambitMediaUpload: "/docs/guides/building/gambits/images/gambit-media-upload.png",
      gambitNoInput: "/docs/guides/building/gambits/images/gambit-no-input.png",
      gambitRedirect: "/docs/guides/building/gambits/images/gambit-redirect.png",
      gambitStarRating: "/docs/guides/building/gambits/images/gambit-star-rating.png",
      gambitStartAndEnd: "/docs/guides/building/gambits/images/gambit-start-and-end.png",
      gambitText: "/docs/guides/building/gambits/images/gambit-text.png",
      gambitTrigger: "/docs/guides/building/gambits/images/gambit-trigger.png"
    },
    languagesTranslateGambit: "/docs/guides/building/images/languages-translate-gambit.png",
    languageSystemMessages: "/docs/guides/building/images/language-system-messages.png",
    newDraftDialog: "/docs/guides/building/images/new-draft-dialog.png",
    outputComponentsGrid: "/docs/guides/building/images/output-components-grid.png",
    publishDialog: "/docs/guides/building/images/publish-dialog.png",
    systemPromptDialog: "/docs/guides/building/images/system-prompt-dialog.png",
    testModeEventLog: "/docs/guides/building/images/test-mode-event-log.png",
    testModePanel: "/docs/guides/building/images/test-mode-panel.png",
    validationProblemsPanel: "/docs/guides/building/images/validation-problems-panel.png",
    variablePickerPanel: "/docs/guides/building/images/variable-picker-panel.png",
    variablePillInserted: "/docs/guides/building/images/variable-pill-inserted.png",
    versionsDraftsPanel: "/docs/guides/building/images/versions-drafts-panel.png"
  },
  campaigns: {
    campaignFlavorsTriggers: "/docs/guides/campaigns/images/campaign-flavors-triggers.svg",
    campaignReplyRouting: "/docs/guides/campaigns/images/campaign-reply-routing.svg",
    campaignSendAnatomy: "/docs/guides/campaigns/images/campaign-send-anatomy.svg",
    createACampaign: "/docs/guides/campaigns/images/create-a-campaign.png",
    walletReserveSettleRefund: "/docs/guides/campaigns/images/wallet-reserve-settle-refund.svg",
    webhookCampaignContractLocking: "/docs/guides/campaigns/images/webhook-campaign-contract-locking.svg",
    webhookCampaignLifecycleStates: "/docs/guides/campaigns/images/webhook-campaign-lifecycle-states.svg",
    webhookCampaignOneCallOneDelivery: "/docs/guides/campaigns/images/webhook-campaign-one-call-one-delivery.svg"
  },
  channels: {
    distributeWhatsappConnect: "/docs/guides/channels/images/distribute-whatsapp-connect.png",
    whatsappConnectDialogWaiting: "/docs/guides/channels/images/whatsapp-connect-dialog-waiting.png",
    whatsappEmptyState: "/docs/guides/channels/images/whatsapp-empty-state.png"
  },
  deploy: {
    bridgeEventGambitSection: "/docs/guides/deploy/images/bridge-event-gambit-section.png",
    deploymentSurfacesAndChannels: "/docs/guides/deploy/images/deployment-surfaces-and-channels.svg",
    designAgentTab: "/docs/guides/deploy/images/design-agent-tab.png",
    designLauncherTab: "/docs/guides/deploy/images/design-launcher-tab.png",
    embedIframeTab: "/docs/guides/deploy/images/embed-iframe-tab.png",
    embedTheWidget: "/docs/guides/deploy/images/embed-the-widget.png",
    mobileAppIntegration: "/docs/guides/deploy/images/mobile-app-integration.png",
    onYourDomain: "/docs/guides/deploy/images/on-your-domain.png",
    shareYourAgentLink: "/docs/guides/deploy/images/share-your-agent-link.png"
  },
  developer: {
    api: {
      channelSendTemplateVsMessage: "/docs/developer/api/images/channel-send-template-vs-message.svg",
      endUsers: {
        endUsersListCursorPagination: "/docs/developer/api/end-users/images/end-users-list-cursor-pagination.svg"
      },
      triggerCallConversationLifecycle: "/docs/developer/api/images/trigger-call-conversation-lifecycle.svg"
    },
    developerSurfacesMap: "/docs/developer/images/developer-surfaces-map.svg",
    embed: {
      embedConfigToWidgetContext: "/docs/developer/embed/images/embed-config-to-widget-context.svg",
      hostPageBridgeFlow: "/docs/developer/embed/images/host-page-bridge-flow.svg",
      identitySigningFlow: "/docs/developer/embed/images/identity-signing-flow.svg",
      scriptVsIframeEmbed: "/docs/developer/embed/images/script-vs-iframe-embed.svg"
    },
    mobile: {
      bridgeMessageProtocol: "/docs/developer/mobile/images/bridge-message-protocol.svg",
      webviewBridgeArchitecture: "/docs/developer/mobile/images/webview-bridge-architecture.svg"
    }
  },
  endUsers: {
    anonymousToIdentifiedProfile: "/docs/guides/end-users/images/anonymous-to-identified-profile.svg",
    bulkActionBar: "/docs/guides/end-users/images/bulk-action-bar.png",
    campaignConsentGate: "/docs/guides/end-users/images/campaign-consent-gate.svg",
    consentPerChannelStates: "/docs/guides/end-users/images/consent-per-channel-states.svg",
    dynamicVsStaticSegments: "/docs/guides/end-users/images/dynamic-vs-static-segments.svg",
    endUserDirectory: "/docs/guides/end-users/images/end-user-directory.png",
    endUserProfileAcrossChannels: "/docs/guides/end-users/images/end-user-profile-across-channels.svg",
    endUserProfilePanes: "/docs/guides/end-users/images/end-user-profile-panes.png",
    profileMergeAndTakeoverProtection: "/docs/guides/end-users/images/profile-merge-and-takeover-protection.svg",
    segmentBuilder: "/docs/guides/end-users/images/segment-builder.png",
    segmentsPage: "/docs/guides/end-users/images/segments-page.png"
  },
  getStarted: {
    agentStates: "/docs/get-started/images/agent-states.svg",
    buildToLivePath: "/docs/get-started/images/build-to-live-path.svg",
    dashboardSidebarMap: "/docs/get-started/images/dashboard-sidebar-map.png",
    organizationOwnershipAndRoles: "/docs/get-started/images/organization-ownership-and-roles.svg",
    quickstart: {
      step1CreateYourAccount: "/docs/get-started/images/quickstart/step-1-create-your-account.png",
      step3ConnectTheAiAgent: "/docs/get-started/images/quickstart/step-3-connect-the-ai-agent.png",
      step4TestMode: "/docs/get-started/images/quickstart/step-4-test-mode.png"
    },
    quickstartCanvas: "/docs/get-started/images/quickstart-canvas.png"
  },
  knowledge: {
    addASource: "/docs/guides/knowledge/images/add-a-source.png",
    addRetrieverPicker: "/docs/guides/knowledge/images/add-retriever-picker.png",
    attachKnowledgeGambit: "/docs/guides/knowledge/images/attach-knowledge-gambit.png",
    configureARetriever: "/docs/guides/knowledge/images/configure-a-retriever.png",
    createKnowledgeBaseDialog: "/docs/guides/knowledge/images/create-knowledge-base-dialog.png",
    customRetrieverDialog: "/docs/guides/knowledge/images/custom-retriever-dialog.png",
    datasetTab: "/docs/guides/knowledge/images/dataset-tab.png",
    documentChangeReindexLifecycle: "/docs/guides/knowledge/images/document-change-reindex-lifecycle.svg",
    documentsTabPreview: "/docs/guides/knowledge/images/documents-tab-preview.png",
    importAWebsite: "/docs/guides/knowledge/images/import-a-website.png",
    kbList: "/docs/guides/knowledge/images/kb-list.png",
    retrieverIndexStates: "/docs/guides/knowledge/images/retriever-index-states.svg",
    retrieverQueryPipeline: "/docs/guides/knowledge/images/retriever-query-pipeline.svg",
    standardVsParentChildChunking: "/docs/guides/knowledge/images/standard-vs-parent-child-chunking.svg",
    syncManagement: "/docs/guides/knowledge/images/sync-management.png",
    testRetriever: "/docs/guides/knowledge/images/test-retriever.png"
  },
  liveChat: {
    agentWorkspace: "/docs/guides/live-chat/images/agent-workspace.png",
    assignedAgentPicker: "/docs/guides/live-chat/images/assigned-agent-picker.png",
    automaticAssignmentRouting: "/docs/guides/live-chat/images/automatic-assignment-routing.svg",
    availabilityDropdown: "/docs/guides/live-chat/images/availability-dropdown.png",
    cannedResponses: "/docs/guides/live-chat/images/canned-responses.png",
    composerPreferences: "/docs/guides/live-chat/images/composer-preferences.png",
    copilotPanel: "/docs/guides/live-chat/images/copilot-panel.png",
    filterConversationsDialog: "/docs/guides/live-chat/images/filter-conversations-dialog.png",
    inboxAnalyticsTab: "/docs/guides/live-chat/images/inbox-analytics-tab.png",
    inboxAvailabilityTab: "/docs/guides/live-chat/images/inbox-availability-tab.png",
    inboxesSettings: "/docs/guides/live-chat/images/inboxes-settings.png",
    inboxRoutingTab: "/docs/guides/live-chat/images/inbox-routing-tab.png",
    labelsSettings: "/docs/guides/live-chat/images/labels-settings.png",
    newAttributeDialog: "/docs/guides/live-chat/images/new-attribute-dialog.png",
    newCannedResponseDialog: "/docs/guides/live-chat/images/new-canned-response-dialog.png",
    notificationPreferences: "/docs/guides/live-chat/images/notification-preferences.png",
    notificationsPage: "/docs/guides/live-chat/images/notifications-page.png",
    pickupTargetCard: "/docs/guides/live-chat/images/pickup-target-card.png",
    resolveMenu: "/docs/guides/live-chat/images/resolve-menu.png",
    searchDialog: "/docs/guides/live-chat/images/search-dialog.png",
    seatGateConversation: "/docs/guides/live-chat/images/seat-gate-conversation.png",
    seatsSettings: "/docs/guides/live-chat/images/seats-settings.png",
    workTheInbox: "/docs/guides/live-chat/images/work-the-inbox.png"
  },
  security: {
    addOpenRouterKeyDialog: "/docs/guides/security/images/add-open-router-key-dialog.png",
    auditChainVerified: "/docs/guides/security/images/audit-chain-verified.png",
    auditEventDrawer: "/docs/guides/security/images/audit-event-drawer.png",
    auditExportDialog: "/docs/guides/security/images/audit-export-dialog.png",
    auditLogViewer: "/docs/guides/security/images/audit-log-viewer.png",
    auditRecordLifecycle: "/docs/guides/security/images/audit-record-lifecycle.svg",
    logPrivacyRedactionEnabled: "/docs/guides/security/images/log-privacy-redaction-enabled.png",
    modelProviderEmptyState: "/docs/guides/security/images/model-provider-empty-state.png",
    privacySettings: "/docs/guides/security/images/privacy-settings.png",
    siemConnectWizard: "/docs/guides/security/images/siem-connect-wizard.png",
    supportActorMasking: "/docs/guides/security/images/support-actor-masking.svg"
  },
  tools: {
    addToolModal: "/docs/guides/tools/images/add-tool-modal.png",
    addToolsPanel: "/docs/guides/tools/images/add-tools-panel.png",
    codekitActionEditor: "/docs/guides/tools/images/codekit-action-editor.png",
    codekitConnectToolkitsDialog: "/docs/guides/tools/images/codekit-connect-toolkits-dialog.png",
    codekitSchemaDialog: "/docs/guides/tools/images/codekit-schema-dialog.png",
    codekitToolkit: "/docs/guides/tools/images/codekit-toolkit.png",
    codekitToolkitAnatomy: "/docs/guides/tools/images/codekit-toolkit-anatomy.svg",
    createActionDialog: "/docs/guides/tools/images/create-action-dialog.png",
    createCodekitDialog: "/docs/guides/tools/images/create-codekit-dialog.png",
    responseFilteringDialog: "/docs/guides/tools/images/response-filtering-dialog.png",
    toolGambitEditorAgentMode: "/docs/guides/tools/images/tool-gambit-editor-agent-mode.png",
    toolGambitEditorWorkflowMode: "/docs/guides/tools/images/tool-gambit-editor-workflow-mode.png",
    toolkitDetail: "/docs/guides/tools/images/toolkit-detail.png",
    toolsConnected: "/docs/guides/tools/images/tools-connected.png",
    toolsDirectory: "/docs/guides/tools/images/tools-directory.png",
    viewActionsModal: "/docs/guides/tools/images/view-actions-modal.png",
    workflowModeResponse: "/docs/guides/tools/images/workflow-mode-response.png"
  }
};

export const urls = {
  app: "https://dashboard.hellotars.com",
  site: "https://hellotars.com",
  support: "mailto:support@hellotars.com",
  status: "https://status.hellotars.com"
};

At the end of this page, you have a tested retriever on your knowledge base, promoted as the live default.

<Browser url={urls.app}>
  <img src={img.knowledge.configureARetriever} alt="Retriever tab with the three setup steps above a Vector search retriever marked Default" />
</Browser>

## Before you start

Before you start, sign in to <a href={urls.app}>the dashboard</a> and select the organization you want to work in.

* You need a role that can manage resources to add, edit, or index retrievers.
* You need a knowledge base with at least one processed source. See [Create a knowledge base](/docs/guides/knowledge/create-a-knowledge-base).

## Configure and test

<Steps>
  <Step title="Open your knowledge base and select the Retriever tab">
    The tab lists existing retrievers and marks the live default **Default**.
  </Step>

  <Step title="Select Add retriever and pick a preset">
    Select **Add** on **Vector search** for most agents. Select **Customize** on **Custom retriever** for advanced options.
  </Step>

  <Step title="Select + Index on the new card">
    A toast confirms **Indexing started**. Wait for the progress bar to finish.
  </Step>

  <Step title="Open the Actions menu and select Test retriever">
    Enter a question an end user would ask, then select **Search**.
  </Step>

  <Step title="Review the Top results">
    Check that the top chunks contain the answer. Try several real questions.
  </Step>

  <Step title="Select Make default from the Actions menu">
    A toast confirms **Set as default retriever**. The card now shows the **Default** badge.
  </Step>
</Steps>

## The Test retriever dialog

The dialog is titled **Test retriever** and searches only the retriever you opened it from. Type a question into the **Enter a question…** field and press Enter or select **Search**.

<Browser url={urls.app}>
  <img src={img.knowledge.testRetriever} alt="Test retriever dialog with a query and scored Top results listing ranked chunks with their sources" />
</Browser>

Results appear under a **Top results** header. Each chunk shows its source document title, the rendered content, a rank marker such as **#1**, and a **Score** badge. For what the score means, see [Retrievers explained](/docs/guides/knowledge/retrievers-explained).

A line above the results tells you when the answering index was built. If the retriever needs a reindex, the line notes that later changes are not in the index yet and offers **Reindex**. Results clear on their own when the index changes.

| Message                                                      | When it appears                                                     |
| ------------------------------------------------------------ | ------------------------------------------------------------------- |
| **No results. Try a different question.**                    | The search ran but nothing matched.                                 |
| **Search failed. Check the retriever status and try again.** | The search itself failed, often because the retriever is not ready. |
| **Untitled document**                                        | The matched chunk's source has no title.                            |

## Verify

Run a test query against the promoted retriever. The **Top results** show the chunks your agent receives when it searches this knowledge base. The card carries the **Default** badge and no status badge.

## Reference

### The Retriever tab

Open a knowledge base and select the **Retriever** tab. The retriever marked **Default** answers live for your agent. A guide strip below the tab bar tracks three steps: **Add a retriever**, **Add test questions**, and **Run experiments**.

| State                            | What you see                                                                                                                                    |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| No retrievers                    | Title **How your agent finds answers** with an **Add a retriever** button. The preset picker opens once on its own if you can manage resources. |
| Retrievers exist                 | Heading **How your agent searches**, an **Add retriever** button, and one card per retriever.                                                   |
| No retriever indexed or indexing | A blue notice titled **Index a retriever to use it**. An unindexed retriever stays out of the agent's Knowledge tool and cannot be tested.      |
| Stale retrievers                 | An amber alert, for example **1 retriever needs reindexing**, with a **Reindex all** button and a confirmation dialog.                          |
| Deleted retrievers exist         | A **Recently deleted (N)** button that opens the restore dialog. A deleted retriever keeps its index for 30 days.                               |

### The Add a retriever picker

**Add retriever** opens a dialog titled **Add a retriever**. An info strip recommends starting with Vector Search. Four cards are available:

| Card                       | Description shown                                          | Badge                                                                                 |
| -------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Vector search**          | "Solid all-round semantic search."                         | Strategy badge **Vector**.                                                            |
| **Keyword + vector blend** | "Mixes exact terms with meaning."                          | Strategy badge **Hybrid**.                                                            |
| **Keyword / exact terms**  | "Best for codes, names, and exact phrases."                | Strategy badge **Keyword**.                                                           |
| **Custom retriever**       | "Configure search, embedding model and chunking yourself." | Badge **advanced**. Its **Customize** button opens the **Build from scratch** dialog. |

<Frame>
  <img src={img.knowledge.addRetrieverPicker} alt="The Add a retriever dialog with the four cards and their strategy badges" />
</Frame>

Each strategy badge carries a tooltip explaining the search style. An **Add** button on a preset card creates the retriever at once. The button reads **Added** and is disabled when a retriever with that strategy already exists. **Done** closes the dialog.

If the configuration already exists, no new retriever is created, and a toast names the existing one.

### The Build from scratch dialog

The dialog holds a **Name** field of up to 40 characters, then two sections. An info icon beside most fields explains what it controls.

For a new retriever, the **Name** field fills itself from the **Search** strategy and the **Embedding model**, for example `Vector · OpenAI · 3-small`. The strategy shows as `Vector`, `Hybrid`, or `Keyword`, and the model drops its `(default)` suffix.

The name follows those fields until you type your own name, which then stays. If the name is already used on this knowledge base, a suffix such as `(2)` is added. If you clear the field, the retriever gets the generated name.

| Section                   | Fields                                                                 |
| ------------------------- | ---------------------------------------------------------------------- |
| **1 · How it's indexed**  | **Index**, **Chunk size**, **Chunk overlap**, and **Embedding model**. |
| **2 · How it's searched** | **Query**, **Search**, **Refinement**, and **Results to retrieve**.    |

<Frame>
  <img src={img.knowledge.customRetrieverDialog} alt="The Build from scratch dialog with Name filled in as Vector · OpenAI · 3-small, above the Index, Chunk size, Embedding model, Query, Search, and Refinement fields" />
</Frame>

Under the **Parent-child** index, the chunk fields read **Child chunk size** and **Child overlap**. An **Advanced chunking (parent size/overlap)** section then holds **Parent chunk size** and **Parent overlap**.

When **Refinement** is **Re-rank top results**, the first count field reads **Passages to re-rank**. A second field, **Results to retrieve**, sets how many re-ranked passages the agent gets.

Number fields accept whole numbers only. A value out of range shows its allowed range under the field, and **Add** stays disabled until you fix it.

| Field                                              | Allowed values                                                     |
| -------------------------------------------------- | ------------------------------------------------------------------ |
| **Chunk size** and **Child chunk size**            | 200 to 4000, or to the embedding model's limit when that is lower. |
| **Parent chunk size**                              | 200 to 4000. It cannot be smaller than the child chunk size.       |
| **Chunk overlap** and **Parent overlap**           | 0 up to a maximum that depends on the chunk size.                  |
| **Passages to re-rank** or **Results to retrieve** | 1 to 100.                                                          |
| **Results to retrieve** after re-ranking           | 1 up to the number of passages to re-rank.                         |

### The retriever card

Each retriever renders as a card with its name, a summary line, and a footer.

| Element                     | Meaning                                                                                                                                                       |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Default** badge           | This retriever is the live default for the knowledge base.                                                                                                    |
| Summary line                | The strategy in short form, for example "Vector", "Hybrid · Re-rank", or "Keyword · Parent-child".                                                            |
| Status badge                | **Needs indexing** before the first build, or **Needs reindex** when documents changed. A ready retriever shows no status badge.                              |
| **Index A** badge           | Shown when the knowledge base has several retrievers. Retrievers with the same letter share one index, and reindexing any of them rebuilds it for all.        |
| **Auto** / **Manual** badge | The reindex mode. **Auto** reindexes after a scheduled crawl, though your own edits still need a manual reindex. **Manual** reindexes only when you start it. |
| **+ Index** button          | Starts the first build, or a retry after an error.                                                                                                            |
| **Reindex** button          | Shown when the retriever is stale. Opens the **Apply pending changes** approval dialog.                                                                       |

While a build runs, the card shows **Indexing** or **Replacing** with a percentage and a progress bar. A failed build shows a red **Indexing failed** alert with a **Details** popover and a **Retry** button.

When single documents fail to index, an amber alert reads **Repairing N documents**. They are temporarily unavailable. **Details** lists each document and its retry attempts. Tars retries on its own, and **Retry now** schedules another attempt at once. See [Manage documents](/docs/guides/knowledge/manage-documents) for the reindex flow.

### The card Actions menu

The menu on a card offers:

| Action             | What it does                                                                                                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **View config**    | Opens a read-only view of the configuration, grouped into **1 · How it's indexed**, **2 · How it searches**, and **Updates**.             |
| **Edit config**    | Opens the **Edit retriever** dialog. Hidden while the retriever is indexing or reindexing.                                                |
| **Test retriever** | Opens the **Test retriever** dialog. Shown only when the retriever can serve queries.                                                     |
| **Make default**   | Promotes this retriever to the live default. Shown when it is ready or stale and not already the default.                                 |
| **Delete**         | Moves the retriever to **Recently deleted** for 30 days. Shown to organization admins only. The last indexed retriever cannot be deleted. |

When a change in **Edit config** requires a rebuild, the footer warns that saving reindexes the retriever. A retriever with settings the form cannot show can only be renamed there.

## Related pages

* [Retrievers explained](/docs/guides/knowledge/retrievers-explained)
* [Create a knowledge base](/docs/guides/knowledge/create-a-knowledge-base)
* [Manage documents](/docs/guides/knowledge/manage-documents)
* [Attach knowledge to an agent](/docs/guides/knowledge/attach-knowledge-to-an-agent)
