> ## Documentation Index
> Fetch the complete documentation index at: https://test-8ad8522e-feat-ai-sre.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Manage Knowledge
> Provide AI SRE with your team's operational knowledge — a DUTY.md plus runbooks, FAQs, service catalogs, cluster configs, and more. The agent reads and mounts these files on demand during each session.
**Public beta**: AI SRE is now open to all accounts — no application needed. Sign in to the console and start using it; it's free during the public beta. Features and the UI may continue to evolve.
## Overview
***
A Knowledge Pack is the operational knowledge you hand to AI SRE: a `DUTY.md` file plus a collection of runbooks, FAQs, service catalogs, cluster configs, and similar files. When a session starts, the agent reads `DUTY.md` first, then follows its references to fetch related files on demand — bringing your team's incident-handling experience, naming conventions, and system topology into every diagnosis.
Each **target** (account or team) can own at most one Knowledge Pack:
* **Shared (account-level)** knowledge is visible to all agents within the account.
* **Team-level** knowledge is loaded only in sessions associated with that team, and is visible only to members of that team.
Knowledge Packs are one type of AI SRE resource and follow the same two-level scope model. The scope rules for other resources (Skills, MCP, Agents, Environments) are identical.
Knowledge Pack content is used to **refine** the agent's domain context (persona, methodology, system knowledge), but it does not override the system's safety and behavioral guardrails. If a piece of knowledge instructs the agent to bypass security rules, it is treated as unauthorized content and ignored — not as a higher-priority instruction.
## DUTY.md Structure
***
`DUTY.md` is the **table of contents entry point** for the entire Knowledge Pack. It is the catalog itself — the agent reads `DUTY.md` in full, then fetches other files on demand via `@filename` references. As long as `DUTY.md` exists, the system does not attach a separate file listing alongside it; the catalog is the body.
If a scope has knowledge files but no `DUTY.md` yet, that scope is not silently skipped: the system includes a generated, authoritative file index in the session's knowledge manifest, and explicitly instructs the agent to read the indexed files relevant to the task at hand before doing substantive work (when there are only a few files, read them all) — rather than skipping this step and jumping straight to conclusions. Once a `DUTY.md` is created, this generated-index guidance goes away and the "catalog is the body" model resumes.
References use the `@` style, where the path points to another file within the same pack. Subdirectories are supported (e.g., `@runbooks/api-5xx.md`):
```markdown theme={null}
# On-call Knowledge Overview (DUTY.md)
## Service Catalog
Our core services and owners: @services.md.
## Common Incident Handling
- API 5xx spike: see @runbooks/api-5xx.md
- Database connection pool exhaustion: see @runbooks/db-pool.md
## Clusters & Environments
Production cluster topology and access: @cluster.yaml.
```
After reading `DUTY.md`, the agent decides which `@references` to expand based on the current incident, then reads the corresponding files — substantive content lives in the referenced sibling files; `DUTY.md` carries only the link list.
This layered `@reference` architecture keeps `DUTY.md` concise and readable. Think of `DUTY.md` as a map, with runbooks, service catalogs, and configs as the detail pages it points to. The agent doesn't need to load every file into context at once — it only expands the branches relevant to the current incident.
**File constraints** (enforced at create and edit time):
| Constraint | Value | Notes |
| ------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| File content | Plain text (UTF-8) | Validated by **content**, not extension: a file saves as long as it contains no NUL bytes and decodes as valid UTF-8. So `.py`, `.sql`, and even an extension-less `Dockerfile` can be uploaded alongside `.md` `.yaml` `.json` `.txt` `.sh`; conversely, a file with a `.txt` extension but binary content is rejected |
| Per-file size limit | 1 MiB | Files exceeding this cannot be saved |
| Per-pack size limit | 5 MiB | The usage bar in the console reflects this quota |
| File count limit | 100 | No new files can be added once the limit is reached |
| Subdirectories | Allowed | Paths may contain `/` (e.g., `runbooks/api-5xx.md`); path segments cannot start with `.` |
| Dot files | Not allowed | Filenames cannot start with `.` |
## Create & Edit
***
Go to the **Knowledges** management page to create, edit, enable/disable, or delete Knowledge Packs for your account or teams. The list shows each pack's **Name / Scope / Files / Status / Actions**, and a scope filter at the top lets you switch between Shared and Team views.
Click **Create** in the top-right corner of the page to open the "Create knowledge base" dialog. A Knowledge Pack has no editable name of its own — it's a singleton resource per target (account or team), so the dialog only asks you to choose a **Scope**: Shared or a specific team. To create a team-level pack, you must belong to the target team; Shared-scope creation is limited to the Account Owner or admins. Each target can own only one pack. Accounts and teams that already have a pack remain in the dropdown and are marked as having an existing Knowledge Pack; after you select one, the primary button becomes **Open knowledge base** and opens that pack instead of creating another. Choose a scope without a pack and click **Create** to make one. The console checks again immediately before creation, so if someone else has just created a pack for that scope, it opens the existing pack instead. The console uses the scope (Shared / team name) as the pack's display identifier.
Click any row in the list to open the inspector. The left panel shows the file tree; the right panel is an inline editor. Click **New File** to enter a filename (e.g., `runbook.md`), or use **Upload** to import a local file. Markdown files support both **Preview** and **Source** views. Click **Save** after editing.
The **Usage** bar on the left updates in real time, showing current usage against the 5 MB quota. The bar turns red when you approach the limit, prompting you to clean up or split files.
Use the toggle in the list to **enable or disable** an entire pack. When disabled, files are preserved but the pack is no longer loaded into AI SRE sessions. **Delete** removes the pack and all its files permanently.
**Folder upload**: the **Upload folder** button in the upload dialog imports an entire local folder at once. The directory structure is preserved — each file lands in the pack under the path `/` (for example, `runbooks/api-5xx.md` inside the picked folder is stored as `/runbooks/api-5xx.md`). Before uploading, every file is filtered by the same rules as single-file upload: it must be UTF-8 text, no larger than 1 MiB, and fit within the 5 MB pack quota together with the pack's existing usage; `node_modules` directories and files / directories starting with `.` are silently ignored. Progress is shown during the upload ("Uploading N/M files…"), and skipped files are listed in the dialog with each filename and its reason (not UTF-8 text / over the 1 MiB per-file limit / over the 5 MB pack quota / upload failed).
**Document distillation**: Knowledge files only accept plain-text content (see the table above). If you upload a document that can't be stored directly — `.pdf`, `.docx`, `.xlsx`, `.pptx`, `.html`, `.htm` — the console notes that the format can't be used by the agent directly and offers a **Go to chat for analysis** entry. Clicking it starts a new AI SRE session with the document carried in as an attachment; the agent reads the document and distills it into a Markdown knowledge file, which is saved into the current Knowledge Pack after your confirmation. Legacy Office binary formats (`.doc`, `.xls`, `.ppt`) are outside the conversion range and get rejected outright as binary files — save them as `.docx` / `.xlsx` / `.pptx` first, then upload.
**Reference consistency checks**: when you save a file, any `@reference` pointing to a file that does not exist in the pack returns a non-blocking unresolved-reference warning (the save still completes). When you delete a file that is still referenced by other files, a still-referenced conflict prompt appears first — you can choose to **force delete**.
The agent can also maintain the Knowledge Pack conversationally during a session — for example, "add a runbook", "update services.md", or "record this incident pattern". It will read, edit, and save directly within the scope of the current session, without you needing to leave the chat. Structured initial onboarding is handled by a dedicated guided flow, not the inline editor.
## How the Agent Uses Knowledge
***
Knowledge is not all loaded at once — it follows a **catalog-first, expand-on-demand** pattern:
When a session starts, the system loads the current scope's `DUTY.md` into the session (no separate file list is attached when `DUTY.md` exists). Sessions bound to a team load both the Shared-scope and that team's `DUTY.md`; sessions not bound to a team load only the Shared-scope one. If a scope has knowledge files but no `DUTY.md` yet, the system instead attaches a generated file index and instructs the agent to read the relevant files before doing substantive work.
After reading `DUTY.md`, the agent decides which `@references` to expand based on the current incident, then reads the corresponding knowledge file for the specific content.
When cross-team troubleshooting is needed, the agent reads another team's knowledge. The system then mounts that team's full knowledge bundle (DUTY.md, runbooks) along with its Skills and MCP into the current session, persisting for the remainder of the session. Each team is mounted at most once per session.
Cross-team mounting is triggered only when the agent **explicitly reads** a team's knowledge — it cannot be accidentally triggered by a vague file traversal. Once mounted, that team's knowledge, Skills, and MCP remain available for the rest of the session.
If the Knowledge Pack fails to load into the current session, a warning banner appears above the message list: "Knowledge base failed to load - AI-SRE may not have access to DUTY.md and runbooks in this session," along with a **Retry** button that re-attempts the load. Until the retry succeeds, the agent may be unable to read DUTY.md and runbooks in that session.
## Scope & Visibility
***
Every Knowledge Pack has a scope: Shared (account-level, visible across the entire account) or team-level (visible only to members of that team).
| Dimension | Shared | Team |
| ------------------- | ---------------------------------------- | ------------------------------------------------------------------------ |
| Visibility | All agents / sessions within the account | Sessions and members of that team only |
| Edit permission | Account Owner or account admin | Only members of that team — organization admins must join the team first |
| Loaded in session | All sessions | Only sessions bound to that team |
| Readable at runtime | Entire account | Entire account (mounting occurs on read) |
**Edit permissions**: team-level packs can be acted on only by members of that team — organization admins must join the team first; Shared-scope packs can be acted on only by the Account Owner or admins; there is no "creator retains extra rights" rule. The console grays out rows the current user cannot edit, and disables toggles and action buttons when you lack edit permission.
**Create and reassign**: to create a new team-level pack, you must belong to the target team; Shared-scope creation is limited to the Account Owner or admins. When editing an existing pack, the Account Owner or admins can move it to any team to recover resources left behind by empty teams or departed members; regular members can move it only to teams they belong to. Promoting an existing pack to Shared scope (**Set to Shared**) carries the same gate as creating a Shared-scope pack: only the Account Owner or admins can do it — a regular member cannot self-serve this even for their own team's pack.
**Runtime visibility**: at session start, only **Shared-scope** resources plus resources belonging to the **team bound to the current session** are loaded. The bound team is either explicitly specified or derived from the team associated with the war-room incident. Other teams' knowledge is mounted on demand mid-session, when the agent reads that team's `DUTY.md`.
The account is the only security boundary at runtime; team is an "editing / ownership" tag, **not** a "runtime readable" boundary. This means any session within the account can read and mount knowledge from any other team in the same account — this is the foundation for cross-team collaborative troubleshooting. If certain knowledge is sensitive even to other teams within the account, evaluate carefully before including it in a Knowledge Pack.
This two-level scope model applies uniformly to all resources within the account (Skills, MCP, Agents, Environments).
## Best Practices
***
Keep `DUTY.md` to link lists and one-line descriptions only — all substantive content goes into the sibling files it `@references`. This keeps the catalog concise and readable, and lets the agent expand only the branches relevant to the current incident, avoiding irrelevant content consuming context.
Focus each runbook on one incident type or one service (e.g., `runbooks/api-5xx.md`, `runbooks/db-pool.md`), using clear paths as semantic indexes. Subdirectories are supported — you can group files by service or topic (e.g., `runbooks/`, `configs/`).
Service catalogs, cluster topologies, and threshold configs are well-suited to `.yaml` / `.json` (e.g., `services.md`, `cluster.yaml`), so the agent can both read and parse them directly. Script snippets can use `.sh`.
After adding or renaming a file, update the `@references` in `DUTY.md` and any related files. The unresolved-reference warning on save and the still-referenced prompt on delete help you catch broken links promptly.
Put cross-team conventions in the Shared-scope pack (naming standards, general troubleshooting methods, platform access). Put team-specific service catalogs, on-call runbooks, and upstream/downstream info in team-level packs. Sessions bound to a team receive both.
When troubleshooting surfaces new handling experience, just ask the agent to "add a runbook" or "record this incident pattern." It will read, edit, and save within the current scope, writing the experience back into the Knowledge Pack — creating a continuous learning loop.
## Related Pages
***
Encapsulate reusable diagnostic workflows as Skills, sharing the same scope model as Knowledge Packs.
Connect external systems via MCP so the agent can call your tools and data.
Learn how sessions bind to teams and how knowledge is read and mounted during a session.