Skip to main content

Setting Up a Knowledge Base

This guide creates a knowledge base, fills it from each kind of source, checks that search finds the right material, and attaches it to an agent. For how knowledge bases work, see Knowledge Bases.

Before you start​

  • You need write access to the project. Ingesting from Git and re-embedding also need the Editor role.
  • Your organisation needs a default embedding model, or you need the ID of an embedding model that returns 1536-dimension vectors. Without one, search falls back to keyword matching only.
  • Have the agent you want to use the knowledge base ready. Its Memory setting must be on.

Step 1: Create the knowledge base​

  1. Go to Resources → Knowledge.
  2. Choose the Add knowledge base button above the list (or Create Knowledge Base if the project has none yet).
  3. Enter a Name and a Description. The description is what you will see when attaching it to an agent.
  4. Leave Agent ID (optional) empty. You will attach the agent from the agent's own page in Step 4.
  5. Leave Embedding LLM Config ID (optional) empty to use your organisation's default embedding model. If you set it, use the numeric ID of an embedding model under Resources → Models that produces 1536-dimension embeddings.
  6. Leave Embedding Dimensions at 1536. Any other value is rejected.
  7. Choose Create.

The knowledge base opens with two tabs: Documents and Search.

Step 2: Add content​

All the ingest buttons are on the Documents tab.

Paste text​

  1. Choose Ingest Text.
  2. Enter a Title (optional) and the Content.
  3. Choose Ingest.

Text is processed straight away. Give it a title: untitled text appears in the list as one row per chunk rather than as a single document.

A web page​

  1. Choose Ingest URL, enter the URL and choose Ingest.
  2. The page is queued. The platform fetches it and extracts the main body text, so navigation and boilerplate are mostly left out.

Pages behind a login, or that build their content with JavaScript, may extract little or nothing. If the text cannot be extracted, nothing is stored.

A file​

  1. Choose Upload File and pick a file: PDF, DOCX, PPTX, XLSX, HTML, Markdown (.md), plain text or CSV.
  2. The file is uploaded and queued for processing.

The default upload limit is 50 MB. Scanned PDFs without a text layer produce little usable text.

A Git repository​

  1. Choose Ingest Git.

  2. Fill in the form:

    FieldWhat to enter
    Repository URLhttps://… or git@… address of the repository
    BranchDefaults to main
    Subfolder (optional)Restrict ingestion to one folder, for example docs/guides
    Path filter (glob)Which files to ingest. Defaults to **/*.md
    Integration (optional)For a private repository, an integration holding an access token. Choose None (public repository) for a public one

  3. Choose Ingest.

Each matching file becomes its own document, titled with its path. The integration must hold a secret named one of GITHUB_PERSONAL_ACCESS_TOKEN, GITHUB_TOKEN, access_token, git_token or token (matched without regard to case); these are the same names the GitHub MCP server uses, so one secret can serve both. Repositories on private or internal network addresses are refused.

Default limits per ingest: 2,000 matching files, 10 MB per file, 25 MB in total, and folders up to 16 levels deep. Symbolic links are skipped.

Confluence​

  1. Choose Ingest Confluence.
  2. Enter the Confluence Base URL, for example https://yourorg.atlassian.net.
  3. Choose Whole Space and enter the Space Key, or choose Parent Page and enter the Parent Page ID to ingest that page and all its descendants.
  4. Choose an Integration (optional) holding your Confluence credentials, or choose None (enter credentials below) and enter Username (email) and API Token.
  5. Choose Ingest.

An integration is searched for these secret names: a base URL (CONFLUENCE_URL, CONFLUENCE_BASE_URL, confluence_base_url, base_url, url), a username (CONFLUENCE_USERNAME, confluence_username, username, CONFLUENCE_EMAIL, email) and an API token (CONFLUENCE_API_TOKEN, confluence_api_token, api_token, ATLASSIAN_API_TOKEN, token). If a required secret is missing, the error names the secrets the integration does have.

All pages from one Confluence ingest are grouped as a single row in the documents list.

A manifest​

  1. Choose Add Manifest, pick a Manifest from the project and choose Add.

The manifest's fields are written out as text and ingested immediately. Ingest a manifest when you want its content to be searchable alongside your prose. An agent that needs the exact values should read the manifest itself; see Manifests.

Background ingests​

URL, file, Git and Confluence ingests run in the background, so they do not appear in the list immediately. Select the knowledge base again after a short wait to refresh the list. If a background ingest fails, nothing is added; through the API, each of these calls returns a job_id you can poll at GET /knowledge-documents/ingest-jobs/{job_id} (tool get_ingest_job) for its status and error.

Step 3: Check what search returns​

  1. Open the Search tab.
  2. Type a question the way a user would ask it, not just a keyword, and choose Search.
  3. Review the ten results and their scores.

If the right passage is not found:

  • Try a paraphrase. If only exact wording works, some or all chunks have no embedding. Check the knowledge base's readiness and re-embed it; see Knowledge Bases.
  • Check the source text. Open the source and confirm the answer is actually in it, in extractable text.
  • Check for stale duplicates. If you re-ingested an edited document without deleting the old one, both versions are searchable.

Step 4: Attach it to an agent​

  1. Go to Build → Agents and open the agent.
  2. Make sure the Memory checkbox is ticked and saved. Knowledge-base content is only given to agents with memory on.
  3. Open the agent's Memory tab.
  4. Under Attached Knowledge Bases, choose Attach KB.
  5. Choose Attach next to your knowledge base.

The dialog lists only knowledge bases that are not already attached to an agent. A knowledge base belongs to one agent at a time; to move it, remove the chip from the first agent's Attached Knowledge Bases list, then attach it to the second. An agent searches at most three attached knowledge bases.

Step 5: Test the agent​

Start a new chat with the agent and ask something only your content can answer. Knowledge-base content is gathered when the agent is initialised for the session, so test in a new chat after attaching.

If the agent answers generically, check that memory is on, that the knowledge base is listed on its Memory tab, and that the Search tab finds the passage.

Keeping it current​

  • To update a document, delete its row on the Documents tab, then ingest the new version.
  • Re-running a Git or Confluence ingest adds only chunks whose text has changed; unchanged chunks are skipped. Old versions of changed chunks remain until you delete them.
  • To automate ingestion, call the knowledge-document endpoints from a workflow or script, or use the platform tools through the platform MCP server.