Skip to main content

Cluster Memory

Cluster Memory holds facts shared with everyone working on a specific cluster. It's the right place for things like:

  • Ownership ("Team B owns all pay-* services")
  • Deployment rules ("We never deploy on Fridays after 3 PM")
  • Known quirks ("The legacy-api deployment requires manual scaling — no HPA")
  • Historical context ("This cluster ran the v1 migration last quarter")

Cluster memory is the unit of organizational memory most teams use. It captures the tribal knowledge that usually lives in one engineer's head and makes it available to investigations and chat for the whole team.

Scope​

Scoped toVisible toLoaded by AI for
A single clusterAnyone with access to the clusterInvestigations and chat on that cluster

Cluster memory entries are facts only — there are no shared preferences. (Preferences are personal — see My Memory.)

Creating Cluster Memory​

  1. Open AI Memory → Cluster Memory
  2. Choose the target cluster from the selector
  3. Click Create
  4. Enter the fact and save

Anyone with access to the cluster can create cluster memory entries. Decide as a team how you want to manage this — some teams designate a few "memory curators", others leave it open to everyone.

What Belongs in Cluster Memory​

Good cluster memory entries are:

  • Short — one to three sentences
  • Stable — facts that change rarely (monthly, not daily)
  • Operational — useful when reasoning about alerts, configurations, or changes
  • Specific — tied to this cluster, not generic Kubernetes advice

Good examples​

  • "All pay-* services have a 30-second startup probe. Don't treat early restart loops as abnormal — wait 60s minimum before assuming a crashloop."
  • "This cluster runs on EKS 1.29 in us-east-1. The node groups are general, gpu, and memory-optimized."
  • "The monitoring namespace is managed by the platform team via ArgoCD. Don't suggest direct kubectl edits there."
  • "ConfigMap changes in payments require a Job-based migration to refresh cached values."

Avoid​

  • ❌ Long-form documentation — use Knowledge Sources
  • ❌ Live status ("Right now we're seeing latency issues") — that's not durable
  • ❌ Generic Kubernetes advice not specific to this cluster
  • ❌ Sensitive information (credentials, secrets, customer data)

How OpsWorker Uses Cluster Memory​

When an investigation triggers for a resource in this cluster, OpsWorker loads relevant cluster memory entries as background context. The investigation agents (Kubernetes Agent, Observability Agent, Git Agent) factor this context into their reasoning.

Example: if a cluster memory entry says "All pay-* services have a 30-second startup probe", and an alert fires for pay-checkout restarting twice in 15 seconds, the AI is more likely to interpret this as "still within expected startup behavior, monitor for 60s more" rather than "CrashLoopBackOff — needs intervention".

In chat sessions on this cluster, the same entries are loaded and the AI can answer questions like "who owns this service?" by referencing cluster memory directly.

Promoting to Organization​

When a cluster memory entry turns out to apply across every cluster — for example, a company-wide deployment policy — promote it to Organization Memory:

  1. Open the entry in Cluster Memory
  2. Click Promote to Organisation
  3. Confirm

The cluster copy is kept as-is; an organization-scoped copy is created. See Promotion.

Editing and Deleting​

Cluster memory entries can be edited or deleted by any user with access to the cluster:

  • Edit replaces the entry (the underlying entry ID changes — this is delete-then-create on the backend).
  • Delete removes it immediately. There is no soft-delete; once deleted, the entry must be re-created if needed.

Consider documenting which team members own cluster memory curation if your team is large enough to risk conflicting edits.

Next Steps​