Knowledge bases

​

Overview

Use knowledge bases to let agents search and reference external, read-only data sources, such as documents, repositories, and other systems. Each knowledge base is indexed independently, and you must explicitly assign it to agents.

​

When to use a knowledge base

Use a knowledge base when you want agents to:

• Search large or shared document collections
• Reference organizational or team knowledge
• Access documentation or source code that changes infrequently
• Keep reference data out of the local codebase

Do not use a knowledge base for:

• Frequently changing or transactional data
• Binary assets like images, videos, or executables
• Data that requires write access
• Actions, tool invocation, or API calls (use an MCP server instead)

​

Source types

Each knowledge base connects to a single external data source and is indexed independently. Poolside supports the following knowledge base source types:

• Git repositories, with optional file filtering
• Amazon S3–compatible object storage, with optional prefix filtering

​

Supported content and limits

​

Supported content

• Text-based files that standard MIME type detection recognizes as plain text
• Source code, configuration files, and documentation

​

Unsupported content

• Binary files, such as images, videos, or executables
• Symbolic links
• Files that cannot be interpreted as text

​

Size limits

• Maximum file size is 2 MB per file

​

Access and security

Role-based permissions and agent configuration determine who can access a knowledge base and how agents can use it.

​

Role-based permissions

Role permissions determine whether a user can create, use, or manage knowledge bases. A user must have the Use Knowledge Bases permission to allow an agent to search and retrieve content from a knowledge base. For a complete list of permissions, see Permissions reference.

​

Agent access

Agents require explicit access to each knowledge base.

• Enable each knowledge base for the agents that need it
• Agents get read-only access

An agent can search a knowledge base only if:

• The agent has that knowledge base enabled, and
• The user running the agent has permission to use that knowledge base

Enabling a knowledge base for an agent does not give users permission to use it.

​

How agents use knowledge bases

When you enable a knowledge base for an agent, the agent can:

• Search indexed content for relevant information
• Retrieve relevant documents or excerpts
• Use retrieved content to answer questions or help with coding tasks

Knowledge base searches run alongside local context gathering and other enabled tools, depending on the task and agent configuration.

​

Create a knowledge base

Prerequisites

• You have the Create Knowledge Bases permission.
• You have the connection details for the data source you want to add, such as a Git repository URL or an S3 bucket path.

Steps

1. In the Poolside Console, navigate to Tools > Knowledge Bases.
2. Click New Knowledge Base.
3. Enter a Name.
4. Optional: Enter a Description.
5. For Type, select Git Repository or Amazon S3.
6. Configure the source based on the selected type.
   • Git Repository
   • Amazon S3

   If you selected Git Repository, provide the following:

   • Repository URL: The HTTPS Git URL of the repository.
   • Branch: The branch to index. Defaults to main.
   • Username: Required for private repositories.
   • Password / Token: A Git password or personal access token.
   • File patterns (optional): Glob patterns to control which files to index, one pattern per line. Leave empty to include all files. Examples:
     • docs/**
     • **/*.py
     • src/{lib,utils}/**

   If you selected Amazon S3, provide the following:

   • S3 URI: The bucket and optional path to index. Example: s3://bucket-name/path/
   • Path prefixes (optional): One prefix per line to filter which objects to include. Leave empty to include all objects. Examples:
     • documents/
     • data/exports/
7. Click Create Knowledge Base.

After creation, the knowledge base begins indexing. Content is not available to agents until indexing completes. Next steps After creating a knowledge base:

1. Assign the knowledge base to one or more agents. Knowledge bases are not available to agents by default. For more information, see Agents.
2. Verify indexing status before relying on it in agent workflows.
3. Test retrieval by invoking an agent that has access to the knowledge base.
4. Refine scope by adjusting file patterns or prefixes if needed.

​

Delete a knowledge base

Deleting a knowledge base removes it from all agents that reference it. Agents configured to use the deleted knowledge base can no longer retrieve external content from it. If one or more agents currently use a knowledge base, Poolside may prompt you to confirm the deletion. Steps

1. In the Poolside Console, navigate to Tools > Knowledge Bases.
2. Select the knowledge base you want to delete.
3. Click Delete.