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
github_repositorypagerduty_serviceslack_personThree 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.
| Layer | What it holds | Who writes it | Blueprint |
|---|---|---|---|
| Source records | One 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 entities | One 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 writes | A system blueprint or a custom blueprint |
| Relationships | Typed, directed edges between canonical entities, for example checkout owned by payments. Each edge records its origin. | The resolver, people and agents | Defined 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.
| Source | Examples | Default rank |
|---|---|---|
| Declared | A field you set in the UI, a value sent through the API or the push API, a repository's .autoheal/context-graph.yaml file | 1 (highest) |
| Integration | A sync from GitHub, PagerDuty, ServiceNow and others. The order between integrations is set per field. | 2 |
| Identity rule | An edge the resolver adds when two records share a key, for example a repository whose service property names a service | 2 |
| Agent | A value or edge an agent writes during a run | 3 (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.yamlallows. 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.
| Trigger | When it runs | What it reads |
|---|---|---|
| Connect | Once, when you connect an integration or change its settings | Every object the integration can see (a backfill) |
| Events | Within minutes of a change, for integrations that send webhooks | The changed object, read again by ID |
| Schedule | Daily, as a full reconcile | Every object. Objects that are missing become stale. |
| Sync now | When you select Sync now for an integration or for an entity type | Every 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
| Reader | How | Limits |
|---|---|---|
| People | Context Graph → Graph and Table, and each entity's page | A project overview loads up to 2,000 entities and 6,000 relationships |
| Scripts and tools | The Context Graph API | Lists 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. |
| Agents | The Context Graph tools | Limited 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.
System, integration and custom entity types, and the schema that defines them.
Direct relations, label associations, identity rules and field precedence.
Connect, events, schedules, Sync now, and how to choose what gets synced.
How agents read the graph and write what they learn.