Overview
Knowledge is the operational knowledge you hand to AI SRE: aDUTY.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 opens other files as needed — bringing your team’s incident-handling experience, naming conventions, and system topology into every diagnosis.
Console entry: AI SRE → Customize → Context → Knowledge. Memory, in the same group, is a separate page and is managed separately.
An account has at most one Shared knowledge, and each team has at most one team knowledge:
- Shared (account-level) knowledge is visible to all agents within the account.
- Team-level knowledge is loaded only in sessions of that team.
Knowledge 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 whole knowledge and is loaded automatically in every session. The agent reads DUTY.md in full, then fetches other files on demand through @filename references. The agent can also find knowledge files that DUTY.md doesn’t reference.
If a scope has no DUTY.md yet, the system doesn’t skip it silently. The agent is told that the scope has no guide, and it looks through that scope’s files and reads the relevant ones before doing substantive work.
References use the @<path> style, where the path points to another file within the same knowledge. Subdirectories are supported (for example, @runbooks/api-5xx.md):
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.
File constraints (enforced at create and edit time):
Maintain it in the console
Go to AI SRE → Customize → Context → Knowledge. Each row of the list is one knowledge, labeled by scope (“Shared” or the team name), with its file count,DUTY.md status, and last edit time. The DUTY.md status is one of Not created, Up to date, or Needs refresh · N changes since (other files changed after DUTY.md was written). Click Create to add knowledge for the Shared scope or for a team you belong to. When the account and every team available to you already have one, the button is disabled.
If no knowledge exists yet, the page shows a starter with two options. Set up AI-SRE opens a new chat that runs /init, and Upload existing docs opens a new chat with the attachment picker open.
Click a row to open that knowledge:
- The file tree is on the left.
DUTY.mdis pinned at the top with an Auto-loaded tag; the other files are listed under “Other files · Read on demand”. Without aDUTY.md, this spot shows “Not created” and a Let AI generate it button. Above the tree are the usage (used / 5 MB and the file count) and the New file and Upload entries. - The file body is on the right. Click Edit to change the open file, switch between Preview and Source, and click Save to write it.
- Upload: any UTF-8 text file goes straight in, a whole folder can be uploaded at once, and you are asked before a file with the same name is overwritten. PDF, Word, HTML, and similar documents cannot go in directly. Click Analyze in chat and the AI reads the document, turns it into Markdown files, and saves them after you confirm.
@reference can name a file that is not in the knowledge, and the save still completes.
Ask AI to change it
Type what to change in the input box below the body (for example, “add an OOM troubleshooting runbook”) and send it. The console opens a new chat with a reference to this knowledge and your request (switching to the team for team knowledge). The AI first explains which files it will change and how, and saves only after you agree. Let AI generate it and Let AI update it (below) follow the same flow: they move to a new chat with the request already written.When DUTY.md needs a refresh
If other files change afterDUTY.md was written, a notice above the file tree says it may need updating. With edit permission, you can:
- Let AI update it: moves to a new chat and has the AI update the
DUTY.mdindex against the current files; the change is confirmed with you first. - Still accurate: confirms
DUTY.mdis still correct. The notice disappears until the next file change.
The assistant can also maintain the knowledge for the current session’s scope, for example “add a runbook” or “update services.md”. It reads, edits, and saves after you confirm.
How the Agent uses knowledge
Knowledge is not all loaded at once — it follows a catalog-first, expand-on-demand pattern:1
Session start: load the catalog
When a session starts, the current scope’s
DUTY.md is loaded. 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.2
Follow references to read files
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.3
Mount another team's knowledge on demand
In a personal session not bound to a team, the agent can read the knowledge of teams the session creator belongs to. After that read, the team’s knowledge, Skills, and MCP stay available for the rest of the session. A session bound to a team cannot read other teams’ knowledge.
Scope & visibility
Knowledge follows the rules in Scope and permissions. What is specific to knowledge:- Promoting existing knowledge to Shared scope (Set to Shared) is limited to the Account Owner or admins. A regular member can’t do it, even for their own team’s knowledge.
- A session bound to a team can use only the Shared knowledge and that team’s knowledge. Reading another team’s knowledge is refused, for Account Owners and admins as well.
- Reading a team the creator does not belong to returns the same error as “file not found”. For cross-team troubleshooting, ask the other team to make the relevant knowledge Shared, or do the combined analysis in a personal session.
Best practices
Use DUTY.md as a catalog, not as body content
Use DUTY.md as a catalog, not as body content
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.One topic per file
One topic per file
Focus each runbook on one incident type or one service (for example,
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 (for example, runbooks/, configs/).Use structured file types
Use structured file types
Service catalogs, cluster topologies, and threshold configs are well-suited to
.yaml / .json (for example, services.md, cluster.yaml), so the agent can both read and parse them directly. Script snippets can use .sh.Keep references consistent
Keep references consistent
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.Let the agent help maintain it
Let the agent help maintain it
When troubleshooting surfaces new handling experience, ask the agent to “add a runbook” or “record this incident pattern.” It reads, edits, and saves within the current scope and writes the experience back into the knowledge. This builds a continuous learning loop.
Related pages
Skills
Encapsulate reusable diagnostic workflows as Skills, sharing the same scope model as Knowledge.
MCP (External Tools)
Connect external systems through MCP so the agent can call your tools and data.
Learn about Memory
Preferences, procedures, facts, and lessons the AI notes in conversations, managed separately from knowledge.
Console Chat
Learn how sessions bind to teams and how knowledge is read and mounted during a session.