Relationships
The Context Graph has two kinds of edge:
- A relation connects two entities, for example the service
checkoutowned by the teampayments. The source entity's blueprint defines it. - A label association connects an Autoheal resource to an entity, for example the skill
release-checksto the servicecheckout. A label on the resource creates it.
Solid edges are relations. Dashed edges are label associations. The graph view draws them the same way.
Relations
A blueprint defines the relations its entities can have. Each relation has a key, a target blueprint, and rules:
relations:
owner:
title: Owner Team
target: team
many: false # one target
required: false
contributors:
title: Contributors
target: person
many: true # a list of targets
schema: # properties stored on each edge
properties:
role:
type: string
title: Role
| Rule | Behavior |
|---|---|
| Direction | A relation belongs to its source entity and points to its target. You can traverse it from either end: a team's page lists the services it owns. |
One target (many: false) | Setting a new target replaces the old one. |
Many targets (many: true) | Each target is its own edge. Adding a target that is already there changes nothing. |
| Required | An entity cannot be created or updated without a target for this relation. |
| Target blueprint | Each target must be an entity of the target blueprint. A target of another blueprint is refused. |
| Relation properties | Values stored on the edge itself, such as a contributor's role. They are checked against the relation's schema. |
The system blueprints define these relations:
Custom blueprints can define relations to any blueprint, and system blueprints can be targets. See Custom blueprints.
Where a relation comes from
Each relation records its origin. A sync replaces only the relations its own source wrote. A relation you set by hand stays when the integration syncs again.
| Origin | Examples | Written by |
|---|---|---|
| Integration | A PagerDuty service's escalation team, a GitHub team's members, a ServiceNow CI's owner group | The sync for that integration, through the resolver |
| Identity rule | A repository is part_of a service because its service property names that service | The resolver |
| Declared | An owner set in the UI, a relation sent through the API or the push API, a depends_on list in a repository's .autoheal/context-graph.yaml | People and their automation |
| Agent | A dependency an agent found in traces, an owner it inferred from commit history | Agents, through context_graph_write |
When two origins disagree about a one-target relation, the field precedence rules pick the winner, the same as for a property.
Unresolved relations
A relation names its target by the target's canonical name. If no entity of the target blueprint has that name yet, the relation is kept as unresolved:
- It is stored on the source entity, and the entity response carries the warning
SOFT_LINK_UNRESOLVED. - It is not drawn as an edge.
- When an entity with that name appears, the resolver links the relation. You do not need to write it again.
This lets syncs and pushes arrive in any order. A service can name its owner team before the team sync runs.
List unresolved relations with GET /api/v1/context-graph/soft-links. A long-lived unresolved relation usually means a name differs between two tools, for example payments in one and payments-team in the other. Fix it by setting the team's identity, or by changing the name in the source.
Delete an entity that others refer to
When you delete an entity that other entities refer to, Autoheal lists those entities and asks you to confirm. If you confirm, the relations that pointed to it become unresolved. They resolve again if an entity with the same name returns.
Label associations
A label connects an Autoheal resource to an entity when:
- The label's key is the name of a blueprint in the project, such as
service,team, or a custom blueprint such asenvironment. - The label's value is the canonical name of an entity of that blueprint, such as
checkout.
The edge points from the resource to the entity and carries its evidence: the label key and value.
| Resource | Where its labels live |
|---|---|
| Skill | labels: in its SKILL.md front matter |
| Agent | The top-level labels: in its agent.yaml |
| Memory | Autoheal, edited on the memory's page |
| Artifact | Autoheal, edited on the artifact's page |
| Integration connection | Autoheal, edited on the integration's page |
In files, write each label as one - key: value item. Repeat a key for each value:
labels:
- team: payments
- service: checkout
- service: ledger
- environment: prod-us
Matching rules:
- Exact match on the canonical name. The match is case-sensitive. Autoheal stores label keys and values in lowercase, so give an entity a lowercase name if labels must match it.
service: checkoutmatches the servicecheckout.service: checkout-apidoes not. Titles are never matched. - Label format. A key starts with a lowercase letter and has up to 64 characters: letters, digits,
_,-,.and/. A value has 1 to 256 characters. - A key that names no blueprint is an ordinary label.
priority: highdescribes the resource and creates no edge. - A value that names no entity is a diagnostic. The graph shows it on the resource, and no node is invented. Label editors suggest valid values first.
- Computed when read. A new entity or blueprint activates existing labels on the next read. Deleting an entity removes the edge but keeps the label.
- Descriptive only. A label association does not grant access and does not change what an agent runs.
- Labels on entities do not create edges. Use a relation to connect two entities.
A skill or agent's labels are read from the branch you are viewing, at its latest published commit. A label in a draft does not show until it is published.
The resolver
The resolver is the reconciliation engine of the Context Graph. It runs each time a source record changes: after a sync, an event, a push, a declared edit, or an agent write. A daily pass checks every link again.
For each source record, it does three things:
Identity rules
Each blueprint has an ordered list of identity rules. The resolver tries them in order and stops at the first strong match.
| Blueprint | Identity rules, in order |
|---|---|
| person | 1. Verified email address. 2. Single sign-on identity. 3. A link you make by hand. |
| team | 1. A link you make by hand. 2. Normalized name: Payments Team, payments-team and payments match. 3. Similar names become a suggestion. |
| service | 1. A declared service name (UI, API, push, or repository file). 2. The service tag or OpenTelemetry service.name that a monitoring tool reports. 3. A repository's service custom property. 4. Similar names become a suggestion. |
| repository | Provider, host and repository ID. Never the name, so a renamed repository keeps its identity. |
| Custom blueprints | The entity's canonical name. |
When a service is renamed, the resolver keeps the old name as an alias. Records that still use the old name keep linking to the same entity.
Integration blueprints without a system counterpart, such as slack_channel and servicenow_cmdb_ci, are their own canonical entities. Each source object is one entity.
Relations inside an integration become graph relations
Integrations describe relations between their own objects. When both ends are linked to canonical entities, the resolver writes the same relation between those entities:
| Integration relation | Becomes |
|---|---|
pagerduty_service owner → pagerduty_team | service owner → team |
pagerduty_team members → pagerduty_person | team members → person |
github_team members → github_person | team members → person |
github_repository owner → github_team | repository owner → team |
github_service contributors → github_person | service contributors → person |
datadog_service owner → datadog_team | service owner → team |
servicenow_service owner → servicenow_team | service owner → team |
servicenow_team members → servicenow_person | team members → person |
slack_team members → slack_person | team members → person |
jira_service lead → jira_person | service contributors → person, with role lead |
Field precedence
When several sources supply the same field, the resolver keeps the value from the source with the highest rank for that field:
- Declared values: the UI, the API, the push API and repository files.
- Integrations, in a default order for each field.
- Agents.
Default order between integrations for common fields:
| Field | Order |
|---|---|
service.owner | PagerDuty (escalation team) → GitHub (CODEOWNERS team for the repository root) → Datadog (team tag) → ServiceNow (owner group) |
service.tier | PagerDuty → Datadog → ServiceNow |
service.description | GitHub → Datadog → PagerDuty → ServiceNow → Jira |
person.display_name, person.email | Your organization's users → Slack → PagerDuty → GitHub → Jira → ServiceNow |
team.members | All integrations. Members are combined, not ranked. |
Rules:
- A declared value stays until someone clears it. Syncs and agents never overwrite it.
- When the top source stops reporting a value, or its record becomes stale, the next source in the order takes over.
- A
manyrelation, such asmembersordepends_on, combines the targets from every source. Removing a target in one source removes only that source's edge. - The entity's Sources tab shows each field's value from every source, and which one won.
The review queue
The resolver does not guess. When a decision is uncertain, it creates a suggestion and leaves the graph as it is until a person decides.
| Suggestion | Example | Accept does |
|---|---|---|
| Link | PagerDuty's Checkout API and the service checkout look like the same service: similar name, same owner team, no shared key. | Links the record to the entity. The two become one entity. |
| Field | An agent found the owner of checkout is platform, but PagerDuty says payments. | Sets the agent's value as declared. |
| Relation | An agent found that checkout calls fraud-score in 92% of traces. | Adds the relation as declared. |
Open Context Graph → Review to see pending suggestions. You need permission to edit entities to accept or reject one. A rejected suggestion is not raised again for the same records.
You can also list and answer suggestions through the API.