Skip to main content

How the Context Graph works

The Context Graph is a typed graph of what exists in your engineering organization: services, teams, people, repositories, and any entity type you define. Agents read it to answer questions such as "which service does this pull request change, who owns it, and what depends on it?"

Three kinds of source write to the graph:

  • Integrations sync what your tools already know: repositories from GitHub, services and teams from PagerDuty, people from Slack.
  • People declare facts: an owner team set in the UI, a service tier pushed through the API, a service declared in a repository file.
  • Agents record what they learn during runs: a dependency found in a trace, a repository that builds a service.

These sources often describe the same thing. GitHub, PagerDuty and Datadog can each know a service called checkout. A reconciliation engine, the resolver, links what each source says to one entity, picks each field from the most trusted source, and records where every field and relationship came from.

The pipeline​

Sources that sync
Integrations
GitHub, PagerDuty, Slack, ServiceNow and more
Your systems
Push API and repository files
connect, events, schedule, Sync now, push
Source records
One record per object per connection, in an integration blueprint
github_repositorypagerduty_serviceslack_person
People
UI edits and the API
Resolver
Identity rules and field precedence
Agents
Facts found during runs
Engineering Context Graph
Entities
Services, teams, people, repositories and your own types, one per real thing
Skills and memories
Entities that hold the text agents read
Relationships
Declared by an entity, or made by a label. Each records its origin.
read by
Context Graph UI
REST API
Agent tools

Three layers​

The graph keeps what each source said apart from the merged result. This is what lets a sync run again without erasing your edits.

LayerWhat it holdsWho writes itBlueprint
Source recordsOne record per object per integration connection, for example one PagerDuty service. The original API payload is kept with it.The sync for that integration. Each sync replaces only its own records.An integration blueprint, such as pagerduty_service
Canonical entitiesOne entity per real thing, for example the checkout service. Each field remembers which source supplied it.The resolver, from source records, people's edits and agent writesA system blueprint or a custom blueprint
RelationshipsTyped, directed edges between canonical entities, for example checkout owned by payments. Each edge records its origin.The resolver, people and agentsDefined by the source entity's blueprint

A fourth kind of edge, the label association, connects Autoheal resources (skills, agents, memories, artifacts and integrations) to entities. Autoheal computes these edges when the graph is read. See Relationships.

Agents and the UI read canonical entities. You can open the source records behind any entity on its Sources tab.

Follow one service through the graph​

A PR Risk Review agent needs to know who owns the code a pull request changes. Here is how that fact reaches the graph.

The PagerDuty record does not create a second checkout service. The resolver matches it to the entity that GitHub created, and adds the owner that only PagerDuty knows.

Every fact has a source​

Each value in the graph carries its source. When two sources disagree, the resolver keeps the value from the source with the higher rank for that field.

SourceExamplesDefault rank
DeclaredA field you set in the UI, a value sent through the API or the push API, a repository's .autoheal/context-graph.yaml file1 (highest)
IntegrationA sync from GitHub, PagerDuty, ServiceNow and others. The order between integrations is set per field.2
Identity ruleAn edge the resolver adds when two records share a key, for example a repository whose service property names a service2
AgentA value or edge an agent writes during a run3 (lowest)

A declared value stays until someone clears it. A sync never overwrites it. When the top source for a field stops reporting a value, the next source in the order takes over that field. See Field precedence.

Agents keep the graph current​

Agents read the graph before they act, and they write back what they learn. A Deploy Verification agent that finds checkout calling ledger in its traces records that dependency. A PR Risk Review agent that sees one team make most commits to a repository records the likely owner.

  • An agent write fills a field or edge that no higher-ranked source has set. It takes effect at once.
  • An agent write that conflicts with a value from a higher-ranked source does not overwrite it. It becomes a suggestion in the review queue.
  • An agent can write only to the blueprints its agent.yaml allows. See Agent tools.

Every agent write records the run that made it. The entity's Sources tab shows which run wrote each value.

When the graph changes​

Each integration updates the graph in four ways. All four use the same path: read from the integration, update the source records, then let the resolver re-link what changed.

TriggerWhen it runsWhat it reads
ConnectOnce, when you connect an integration or change its settingsEvery object the integration can see (a backfill)
EventsWithin minutes of a change, for integrations that send webhooksThe changed object, read again by ID
ScheduleDaily, as a full reconcileEvery object. Objects that are missing become stale.
Sync nowWhen you select Sync now for an integration or for an entity typeEvery object for that integration or entity type

See Sync integrations for each integration's schedule, events, and settings.

One graph per project​

Each project has its own Context Graph. An entity belongs to one project. An integration connection writes to the project it is connected to, or to the target project set in its sync settings. Labels resolve only to entities in the same project. Every API call and agent read names its project.

Where the graph is read​

ReaderHowLimits
PeopleContext Graph → Graph and Table, and each entity's pageA project overview loads up to 2,000 entities and 6,000 relationships
Scripts and toolsThe Context Graph APILists are paginated. A neighborhood read returns up to 500 nodes and 1,500 edges; the overview up to 2,000 nodes and 6,000 edges.
AgentsThe Context Graph toolsLimited to the blueprints in the agent's scope and the permissions of the user it runs for

A read never grants access. Each kind of resource in the graph keeps its own permissions. A user who cannot read memories does not see memory nodes in the graph.