Skip to main content

Engineering Context Graph

The Engineering Context Graph (ECG) is what your agents know about your engineering organization before they start work. It answers the questions a new engineer asks in their first week:

  • Which services exist, and which team owns each one?
  • Which repository builds this service, and what depends on it?
  • Who should review a change to it, and where does that team talk?
  • What has the team learned about changing it safely?

The ECG is Autoheal's context plane. Every agent reads it before it acts, and the Evaluator and Healer improve it. It is one graph:

  • Entities are the things in your organization: services, teams, people, repositories, infrastructure, and any entity type you define. Skills and memories are entities too, the ones that hold the text agents read for each task.
  • Relationships connect entities. An entity declares a relationship directly, such as a service's owner team. A label also makes one: a skill labeled service: checkout is related to the checkout service. Skills, memories, agents, artifacts and recent agent runs link to entities and to each other this way.

Integrations keep the graph current, people correct it, and agents add what they learn.

Sources
Integrations
GitHub, PagerDuty, Slack, ServiceNow and more
People
UI, API and repository files
Agents
Facts they learn during runs
Engineering Context Graph
Entities
Services, teams, people, repositories, infrastructure
Skills and memories
Related to entities by their labels
read before each step
Agent runs
Reviews, fixes, migrations, releases
Runs add what they learn

Integrations give capabilities, the ECG gives context​

An agent combines two things:

Integrations (MCP tools)

Live access to your tools: GitHub, Datadog, Grafana, Sentry and more. Agents read code, query metrics, search logs and check deploy history.

Engineering Context Graph (native tools)

What exists, who owns it, how it connects, and the procedures your teams follow. This tells an agent where to look and how to use its tools.

Without the ECG, a PR review agent can read a diff but does not know that checkout-api builds the tier-1 checkout service, that the payments team owns it, or that web and mobile-bff call it. With the ECG, it finds all of that in one graph read, and it loads the release-checks skill labeled with that service.

What goes where​

What it holdsWhere it comes from
EntitiesServices, teams, people, repositories and your own entity types, defined by blueprints and connected by relationshipsSynced from integrations, declared by people, and written by agents
SkillsArchitecture overviews, procedures and tool conventionsAuthored or imported by you, or proposed by the Healer for your approval
MemoriesLearnings from finished runs: what worked, what failed, what to check next timeCaptured automatically from agent runs

Use the split when you decide where to put something. A fact about what exists, such as a service, its owner or its dependencies, belongs in the Context Graph. It may already be there. A judgment about what to do, such as how to roll out a schema change or which dashboard to check first, is a skill.

How the Context Graph stays current​

The graph has three kinds of source, and a reconciliation engine that merges them:

  1. Integrations sync on connect, on events from the tool, on a daily schedule, and when you select Sync now. You choose which entity types each integration brings and filter what comes in. See Sync integrations.
  2. People declare facts in the UI, through the API, or in a repository's .autoheal/context-graph.yaml. A declared value outranks every integration.
  3. Agents write what they learn during runs. Their writes fill gaps. A conflict with another source goes to the review queue.

The resolver links what each source says about the same thing to one entity, picks each field from the most trusted source, and records where every value came from. See How the Context Graph works.

How context improves over time​

Each run can leave the ECG better than it found it:

  • An agent asks a question. The answer is a candidate for a skill.
  • An agent finds a fact the graph lacks, such as a dependency in a trace. It writes it to the graph.
  • An agent cannot resolve an owner. Add the missing relationship, or fix the integration that should supply it.
  • A run finishes. Autoheal captures a memory of what happened and recalls it the next time a similar task comes up. Durable procedures are worth promoting to a skill.
  1. A run starts

    The agent reads the graph around what it is working on, and loads the skills and memories labeled with those entities.

  2. It finds gaps

    It asks questions, makes assumptions, or discovers facts the graph does not have.

  3. It writes back

    It records new facts in the graph, and Autoheal captures a memory of the run.

  4. You review

    You accept or reject suggestions in the review queue, approve memories, and turn repeated procedures into skills.

  5. The next run starts further ahead

    The next agent starts from a better graph and better skills.

Get started​