# Why AI coding agents need context graphs Something quietly identical is happening at engineering organizations that otherwise have nothing in common. Every one of them is building a knowledge graph. Not always by that name. At one company it's a service catalog. At another it's an API registry, or an ownership map, or a dependency graph, or an internal developer platform, or a "single pane of glass" project the platform team has been threading through the roadmap for the last two quarters. Different labels, same shape underneath. A set of typed entities that describe what exists in the company, and a set of typed relationships that describe how those entities connect. The reason so many teams landed here at the same time isn't a coincidence. AI coding agents changed the economics. An agent working inside a solo weekend project doesn't behave anything like one dropped into a real codebase, and the difference isn't the model. It's how much of the team's context the agent can reach. Whether the codebase is a startup with a dozen services or an enterprise with five hundred, the useful information is scattered across other repos, other teammates, earlier service contracts, internal APIs nobody has cataloged, deprecated endpoints, a policy doc that hasn't been touched in six months, and a Slack thread that answers half the question. An agent without a graph is guessing. I've spent time watching agents try to fix a ticket in a codebase they've never seen. They read the immediate file. They grep for a function name. They guess at the shape of a response body. Then they write a plausible-looking change that references an endpoint that was retired last quarter, or that duplicates a service another teammate already built, or that fails a contract check the moment it hits CI. The agent is not incompetent. It's operating without the graph of context the humans on the team have quietly built in their heads over months or years. The first response most companies tried was a bigger context window. That helps at the edges. It doesn't fix the underlying problem, and there's a growing body of research to say so. Chroma's [2025 context rot study](https://research.trychroma.com/context-rot) tested 18 frontier models and found every one of them degrading well before its window filled. Stanford's earlier ["lost in the middle" work](https://arxiv.org/abs/2307.03172) showed accuracy dropping by 30% or more for information placed in the middle of long prompts. Longer prompts are not the same as better retrieval. The second response, the one that's actually working, is to build the graph externally and let the agent query it. Ownership, service contracts, deprecations, governance rules, incident history. Not stuffed into a prompt, but sitting in a queryable system an agent can reach. That's what all the catalog-shaped projects converging in the last year have in common. Code graphs, API graphs, ownership graphs, governance graphs. Not a document store. A graph. ## What a context graph actually is At its simplest, a context graph is a set of typed entities and typed relationships between them. If you've read the [W3C RDF 1.2 concepts spec](https://www.w3.org/TR/rdf12-concepts/), you know the underlying idea: subject, predicate, object. In plain terms, each fact is a small three-part statement. `Service X` `exposes` `Endpoint Y`. `Endpoint Y` `is owned by` `Team Z`. `Team Z` `uses` `Auth Scheme A`. For any real codebase, the entities that matter for an AI coding agent are roughly: - Repositories, packages, modules, and functions - Services, endpoints, and their OpenAPI specifications - Teams and their code ownership - Environments, deployments, runtime dependencies, and feature flags - Governance rules, deprecation flags, and approval status - Prior incidents and postmortems tied to any of the above An entity in that graph might look like this: ``` { "id": "svc.payments.charges", "type": "service.endpoint", "method": "POST", "path": "/v2/charges", "spec_ref": "specs/payments/openapi.yaml#/paths/~1v2~1charges", "owner_team": "team.payments-core", "status": "active", "deprecates": "svc.payments.charges.v1", "auth": "oauth2:payments.write", "consumers": ["svc.checkout", "svc.subscriptions"], "last_incident": "INC-4821" } ``` Given that record, an agent can answer questions a raw grep cannot: is there already an endpoint that does this? Who has to approve a change? What is likely to break if the response shape shifts? Which team should get the pull request? Those questions are the ones that separate a change that ships from a change that gets bounced back with a comment that starts with "Actually..." ## Why bigger models aren't the fix The failure mode I keep seeing in the wild isn't a reasoning failure. It's a retrieval and grounding failure. The agent doesn't know that a payments endpoint already exists, so it invents a new one. The agent doesn't know that a team has migrated off a library, so it writes code against the earlier API. The agent doesn't know that a proposed change touches an endpoint listed in an incident from three months ago. [VentureBeat's coverage of production AI coding agents](https://venturebeat.com/ai/why-ai-coding-agents-arent-production-ready-brittle-context-windows-broken/) put it well: agents "lose context across large codebases, generate unstable refactors, and lack operational awareness." Operational awareness is the graph problem. It isn't solvable by adding tokens. Two research directions are worth reading if you want the deeper argument. [Microsoft's GraphRAG project](https://www.microsoft.com/en-us/research/project/graphrag/) shows that graph traversal supports the kind of cross-entity reasoning that vector search misses. And [CodexGraph (NAACL 2025)](https://aclanthology.org/2025.naacl-long.7/) shows that having an LLM query a graph database of the repo produces better navigation and generation results than retrieval alone. Neither one is a silver bullet. Together they point at the same conclusion: the model is the wrong place to put the missing knowledge. ## The API layer is a graph you already have If you work on APIs for a living, the good news is you've already been building parts of this graph without calling it one. An OpenAPI spec is a set of typed entities (paths, operations, schemas) with typed relationships (references, security schemes, tags). A Postman workspace with Postman Collections, Environments, and monitors is a set of runtime facts about how those APIs behave. Add ownership, add approval state, add governance policy, and you have something an agent can query. Postman treats this as first-class infrastructure. The [Private API Network](https://learning.postman.com/docs/collaborating-in-postman/private-api-network/overview/) is where an organization publishes the APIs it wants people (and agents) to discover. [Postman API Governance](https://learning.postman.com/docs/api-governance/api-governance-overview/) attaches rules to those APIs so an agent can tell whether a change breaks a policy before it opens a pull request. Ownership, tags, folders, versions, and deprecation status are already part of the model. The [Postman API](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a) exposes it so an agent can walk the graph programmatically. The graph doesn't stop at your own APIs. Every team that ships software runs on a mesh of third-party services: Stripe for payments, Okta for identity, Twilio for messaging, Salesforce for CRM data, plus a long tail of narrower vendors that end up in someone's critical path. Those integrations produce the same failure modes as internal ones. An agent that doesn't know your app calls a vendor's v2 endpoint (not the deprecated v1) will happily generate code for the wrong version, and the wrong assumption doesn't surface until you're rate-limited or billed for it. That same graph extends to the vendor APIs your app depends on. The public [Postman API Network](https://www.postman.com/explore) publishes tens of thousands of vendor APIs with real specs and working collections. Your Private API Network can pin the specific vendor APIs your organization actually uses, alongside ownership metadata for each integration and the environment that holds the credentials. [Postman Flows](https://www.postman.com/product/flows/) takes this further with **Connector** blocks, which represent specific external services as typed nodes an agent can wire into a flow without having to memorize the shape of each SDK. Here's a small example of the kind of question an agent can ask before writing a single line of code: ``` curl -H "X-Api-Key: $POSTMAN_API_KEY" \ "https://api.getpostman.com/apis?workspace=$WORKSPACE_ID" \ | jq '.apis[] | {name, id, summary}' ``` That returns the list of APIs published in the workspace. Not raw code. Not filenames. The set of contracts your organization has already agreed on. If the agent's next move is "write a new POST /charges endpoint," the answer to this call tells it whether one already exists. ## Query the graph, don't just search the code The problem with letting an agent grep a monorepo is that grep returns matches, not meaning. What you want is for the agent to reach a graph over a well-typed interface and get back structured entities. That's what the [Model Context Protocol](https://modelcontextprotocol.io/) is for. MCP is the open protocol for exposing tools and data sources to AI agents in a way they can query. The [Postman MCP Server](https://learning.postman.com/docs/postman-ai/mcp-servers/overview/) publishes the Postman graph as MCP tools: search APIs, inspect collections, look up environments, check governance rules. An agent running in an IDE can call those tools directly. A pre-request script that stashes the current workspace ID for later tools looks like this: ``` const workspaceId = pm.environment.get("workspace_id"); if (!workspaceId) { throw new Error("Set workspace_id in the Environment before running."); } pm.variables.set("workspace_id", workspaceId); ``` And the test script that validates the shape of an API search response before the agent acts on it: ``` pm.test("Response returns a list of APIs", () => { const body = pm.response.json(); pm.response.to.have.status(200); pm.expect(body).to.have.property("apis"); pm.expect(body.apis).to.be.an("array"); }); pm.test("Every API has a stable identifier", () => { const body = pm.response.json(); body.apis.forEach(api => { pm.expect(api).to.have.property("id"); pm.expect(api).to.have.property("name"); }); }); ``` The point is not the specific script. The point is that the agent now has a typed answer to "what exists," not a string match. Broader industry momentum is moving in the same direction. Google recently published the [Agentic Resource Discovery specification](https://developers.googleblog.com/en/announcing-the-agentic-resource-discovery-specification/), which is exactly the "publish a graph of machine-usable capabilities so agents can find them" pattern applied at internet scale. The internal version of that for your team is the graph you already own. ## Gotchas I've hit A few things to watch for once you start treating the graph as infrastructure. The graph goes stale fast. If nobody updates ownership when a team reorgs, agents will page the wrong people. Wire the graph updates into the same review workflows that already merge code changes, not a separate quarterly cleanup ritual. Governance without teeth is worse than no governance. If the graph knows an endpoint is deprecated and the agent still ships against it, either the agent doesn't have access to that fact or the enforcement path is broken. Both are fixable. The second is more painful because it usually means fixing CI. Cardinality bites you. A team of 8 with 20 services is easy to model. A company with 500 services, 40 teams, and a decade of history has entities that look like duplicates and aren't, and duplicates that look distinct and aren't. Start narrow (public APIs, active services, current owners) and grow from there. Discovery is only half the loop. An agent that can find the right endpoint but can't test it is still stuck. Publishing collections and environments alongside the specs is what turns a graph of contracts into something an agent can actually run against. ## Where to start If you want to move on this without a six-month platform program, three concrete steps are cheap to try this week: 1. Publish the APIs your organization already runs into the [Private API Network](https://learning.postman.com/docs/collaborating-in-postman/private-api-network/overview/) with real ownership metadata. Even a partial graph beats a Slack thread. 2. Turn on [API Governance](https://learning.postman.com/docs/api-governance/api-governance-overview/) rules for at least deprecation and required-auth. Agents will pick up violations at review time instead of after a customer does. 3. Connect an agent (Claude Code, an internal Copilot-style assistant, whatever you're using) to the [Postman MCP Server](https://learning.postman.com/docs/postman-ai/mcp-servers/overview/) so it can query the graph instead of guessing. None of these is a research project. They're the plumbing that makes the agents you already have more useful. ## Resources - [Chroma: context rot in frontier models](https://research.trychroma.com/context-rot) - ["Lost in the middle" (Stanford, 2023)](https://arxiv.org/abs/2307.03172) - [Microsoft GraphRAG](https://www.microsoft.com/en-us/research/project/graphrag/) - [CodexGraph (NAACL 2025)](https://aclanthology.org/2025.naacl-long.7/) - [W3C RDF 1.2 concepts](https://www.w3.org/TR/rdf12-concepts/) - [Model Context Protocol](https://modelcontextprotocol.io/) - [Google Agentic Resource Discovery spec](https://developers.googleblog.com/en/announcing-the-agentic-resource-discovery-specification/) - [Postman Private API Network](https://learning.postman.com/docs/collaborating-in-postman/private-api-network/overview/) - [Postman API Governance](https://learning.postman.com/docs/api-governance/api-governance-overview/) - [Postman MCP Server](https://learning.postman.com/docs/postman-ai/mcp-servers/overview/) - [Postman API documentation](https://www.postman.com/postman/workspace/postman-public-workspace/documentation/12959542-c8142d51-e97c-46b6-bd77-52bb66712c9a) - [Postman AI Agent Builder](https://www.postman.com/product/postman-ai-agent-builder/)