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: checkoutis related to thecheckoutservice. 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.
Integrations give capabilities, the ECG gives context
An agent combines two things:
Live access to your tools: GitHub, Datadog, Grafana, Sentry and more. Agents read code, query metrics, search logs and check deploy history.
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 holds | Where it comes from | |
|---|---|---|
| Entities | Services, teams, people, repositories and your own entity types, defined by blueprints and connected by relationships | Synced from integrations, declared by people, and written by agents |
| Skills | Architecture overviews, procedures and tool conventions | Authored or imported by you, or proposed by the Healer for your approval |
| Memories | Learnings from finished runs: what worked, what failed, what to check next time | Captured 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:
- 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.
- People declare facts in the UI, through the API, or in a repository's
.autoheal/context-graph.yaml. A declared value outranks every integration. - 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.
- A run starts
The agent reads the graph around what it is working on, and loads the skills and memories labeled with those entities.
- It finds gaps
It asks questions, makes assumptions, or discovers facts the graph does not have.
- It writes back
It records new facts in the graph, and Autoheal captures a memory of the run.
- You review
You accept or reject suggestions in the review queue, approve memories, and turn repeated procedures into skills.
- The next run starts further ahead
The next agent starts from a better graph and better skills.