Knowledge
A Knowledge note is a short piece of operational text — markdown or plain prose — that an AI Assistant retrieves while it is investigating, when the note is relevant to the question. Knowledge is how your team feeds the assistant the narrative facts that telemetry alone cannot supply: ownership boundaries, maintenance windows, architecture decisions, history.
Knowledge differs from Rules in important ways. Rules tell the assistant how to interpret findings. Knowledge gives the assistant facts to consider. A Rule says “treat this as background”; a Knowledge note says “the payments team owns this service and is on PTO until Monday”.
Why Knowledge exists
There is a class of information that is essential for good investigation but cannot be discovered from telemetry:
- Ownership — which team owns which service, who is on call, where to escalate.
- Architecture decisions — “we deliberately run two replicas in dev to keep cost down.”
- Recent history — “we migrated this service last sprint; the previous URL is gone on purpose.”
- Constraints — “this cluster shares storage with cluster B; quota changes need both teams.”
- Conventions — “namespaces prefixed
lab-are sandboxes and may be unstable.”
Without these facts an assistant has to either guess or omit context, both of which produce shallow answers. With Knowledge, the same investigation can read “the checkout service is owned by @payments (per ownership note); on-call is paged via #pay-oncall.”
How retrieval works (conceptually)
When you save a Knowledge note, the platform indexes it for semantic retrieval. During an investigation, the assistant considers the user’s question and the resources involved, and pulls the notes most likely to help.
Two practical implications:
- Authors don’t paste note IDs into prompts. Retrieval happens automatically — your job is to write notes that are findable and correct.
- Indexing takes a moment after save. A freshly created note may not be retrieved instantly; the platform surfaces indexing status so you know when a note is fully available.
Scope: who a note is relevant to
Knowledge notes can be:
- Workspace-wide — applies any time the assistant might benefit. Use for facts that are true everywhere in this workspace.
- Resource-scoped — pinned to one or more resource paths (a namespace, a cluster, an SLX). The note is more strongly retrieved during investigations that touch those resources.
Resource scope is a retrieval signal, not a hard filter — a workspace-wide note about on-call procedure can still surface during a namespace investigation if it is the most relevant note. Use scope to promote, not to hide.
Status: active vs deprecated
A note can be active (eligible for retrieval) or deprecated (kept for audit but not retrieved). Deprecation is the right move when a fact becomes stale but you want to preserve the historical record — preferred over deletion.
What makes a good Knowledge note
A useful note is short, operational, and specific:
- Short: one or two paragraphs, not a wiki page. The assistant retrieves whole notes; long notes dilute relevance.
- Operational: written for someone investigating a problem, not as documentation for documentation’s sake. Lead with the decision or fact.
- Specific: name the team, the resource, the timeline, the constraint. Vague notes (“services may have issues during deploys”) do not improve answers.
A counter-example: a 4,000-word architecture overview pasted from Confluence is not a good note. It will dilute retrieval and rarely answer a specific question. Break it into focused notes about ownership, deploy procedure, and known constraints.
Where Knowledge sits in operational context
Knowledge is the third of three operational-context levers, alongside Rules and Commands. The Building Operational Context guide shows how teams layer all three over time.
A useful framing:
| If your assistant is… | Reach for… |
|---|---|
| …flagging too much noise as critical | A Rule that sets interpretation. |
| …missing standard checks engineers always do | A Command that encodes the procedure. |
| …giving generic answers that ignore who and why | A Knowledge note that supplies the missing fact. |
Anti-patterns
- Pasting raw logs or telemetry as a Knowledge note. Telemetry is collected by tasks; Knowledge is for facts that telemetry cannot show.
- One enormous note per service. Several focused notes retrieve more reliably.
- Letting notes drift. When ownership changes or a constraint goes away, mark the note deprecated rather than leaving stale guidance in retrieval.
Where to use this in the UI
For the in-product workflow — creating, scoping, and reviewing notes — see Use → Workspace Studio → Knowledge.