Est.

Graph Subscriptions as the Mechanism That Keeps Agents and Developers on the Same Structural Fact

Live graph updates keep developers and agents from trusting stale code structure.

Sponsored by Graphide

The Architecture Graph Editors
· 8 min read
Cover illustration for “Graph Subscriptions as the Mechanism That Keeps Agents and Developers on the Same Structural Fact”
Codebase Architecture · November 19, 2026 · 8 min read · 1,807 words

An interactive codebase graph for AI agent steering needs a subscription. A graph subscription synchronizes the structural facts that developers and agents use, turning code changes into updates to calls, imports, and dependencies. Its purpose is to keep navigation, agent context, and structural checks aligned with the code being changed.

Why a codebase is already a graph before any agent touches it

A function belongs to a file, calls other functions, and depends on definitions elsewhere in the codebase. Those relationships are there before any tool records them. Modules, files, functions, classes, objects, and variables form the nodes, while calls, imports, and dependencies form the edges. The file is a container for some of that structure. Reading its contents reveals what it defines, but not necessarily everything that depends on those definitions.

For example, changing a function takes an understanding of its callers as well as knowing where to find its declaration. A refactor can preserve the apparent coherence of the edited file while breaking a dependency elsewhere. A diff shows the altered text, but it does not automatically expose the downstream entities affected by that alteration. Developers and agents therefore need access to the same traversable structure beneath the text, because the consequences of an edit follow edges across file boundaries.

Why grep and vector search fail to answer structural questions at scale

Grep finds strings, which are not the same as resolved symbols. A common name can match comments, tests, and unrelated methods, so the agent has to read each result and work out which relationship it shows. That consumes context before the actual edit begins. When the next session repeats the search, the agent reconstructs a map that previous work had already established. The retrieval architecture contributes to this difficulty alongside the model’s ability to understand code.

Vector search changes how candidates are selected, but similarity does not establish a dependency. Naive line-based chunking can also split a function mid-body, separating the retrieved text from the context needed to interpret it. Function-level or syntax-aware chunking keeps the function from being split that way. It still does not turn semantic resemblance into an answer to “who calls this?” or “what breaks if this changes?”

An agent tracing a deep dependency chain through file reads spends its context budget on discovery, with no guarantee that it has found every relevant edge. Caller lists, blast radius, and boundary violations are all things that structural queries can answer. A graph can answer them through a tool call, while a flat search index leaves the agent to assemble the answer from scattered evidence.

What a persistent, queryable codebase graph changes for agents

A persistent graph lets an agent ask directly which functions call a target, which modules import a dependency, or which files are reachable from an entry point. The answer supplies relationships instead of search candidates. That changes context selection from an exploratory reading task into a query over known structure. The agent can receive the relevant subgraph without first reading every file that might contain a clue.

Blitzy uses Neo4j and Cypher queries to scope the context its agents receive. Query strictness provides a useful safeguard against malformed requests. When Cypher is malformed, Neo4j raises an error instead of giving an answer that looks right for a query that is invalid. That safeguard has a defined limit, because a logically incorrect query can still execute successfully. A graph makes relationships queryable, but it does not remove the need to ask the right question.

With that structural context available, agents can take on whole projects rather than only narrow slices whose boundaries a human has already worked out. Dependency direction and call paths no longer have to be rediscovered through unrestricted exploration. The benefit remains dependent on the task. Deep dependency chains create more discovery work to replace, while a small codebase may already be quick to navigate. Keeping the graph saves the work of building it again, but it can be trusted only if the stored structure still matches the code.

Why a static graph is a shared lie between agent and developer

A live graph is better than a stale one. The sharper conclusion is that a stale graph can be actively dangerous, because it presents obsolete relationships in the form of authoritative answers. An agent searching blindly at least faces an obvious discovery problem. An agent receiving an outdated caller list may instead treat an incomplete answer as ground truth and proceed with unwarranted confidence.

A point-in-time index’s commit horizon is the code state reflected in its last rebuild. The edit horizon is different. Developers and agents may be changing dependencies in an unfinished refactor while the index continues to describe the structure that preceded it. This is precisely when accurate relationships are needed to guide the next edit. A scheduled rebuild leaves a period in which the map and the work have diverged.

That discrepancy can remain difficult to see in a diff. The graph may retain old architectural decisions or inferred edges that were once plausible, while the changed text gives no direct indication that the index is wrong. Sharing that graph gives both participants the same false premise. The design requirement is therefore continuous change propagation, with an explicit uncertainty signal while affected structure is being updated, rather than silent reliance on the last completed rebuild.

How continuous graph subscriptions work mechanically

A graph subscription processes a stream of changes rather than treating each change as a reason to rebuild everything. In one implementation pattern, Tree-Sitter parses source into a concrete syntax tree, from which a structural representation and knowledge graph can be derived. The graph is kept in a local store such as SQLite. Codebase-Memory uses Tree-Sitter and SQLite for this combination of parsing and persistence. The stored object is the derived knowledge graph.

File-watching links that representation to edits as they happen. When a file changes, content hashes distinguish actual content changes, and only the modified file needs to be parsed again. The update replaces only affected nodes and edges. This is the subscription’s essential unit of work. It propagates a structural delta tied to the changed source.

There is still a brief interval between an edit and completion of its graph update. A system designed to handle this marks affected queries as pending during that time. Freshness is therefore a query contract. Unaffected structure remains usable while uncertainty about the changed portion is explicit.

Blitzy integrates graph updates with source control, updating its graph when code is merged. That covers the repository’s merged state. Refreshing on commits to the default branch does not cover uncommitted edits or an in-progress refactor on a feature branch. A subscription intended to guide active coding needs both horizons, following live edits as well as commits.

What graph subscriptions make possible that periodic indexing cannot

When developers and agents query the same updated graph, a changed dependency becomes a shared relational update. Each participant no longer has to infer its meaning independently from the diff. For example, the billing module affected by an auth service refactor belongs in the impact subgraph even if no billing file appears in the proposed change. The graph exposes the dependency connecting them. With live updates, that blast radius can be computed before a pull request is opened.

The code-review-graph GitHub Action illustrates the review consequence. Its pull request comment presents risk-scored functions, affected execution flows, and test gaps, and updates in place on every push. The associated finding of three dependency issues missed by full-context review highlights the distinction between supplying more text and supplying relationships. Full context does not guarantee structural coverage. The useful contribution is the dependency evidence that changes what the reviewer examines.

A pull-request update still differs from a live-edit subscription. It shows how structural context can support review, while the subscription makes that context available during the work itself. Multiple agents can then limit their queries to the subgraphs they need without each keeping its own map of what it has found. A locally coherent change that conflicts with the wider dependency structure becomes detectable in shared state. That is a synchronization capability, whether the developer encounters it through a visual graph, an agent query, or a structural check.

Why architectural drift is the specific failure mode graph subscriptions prevent

Architectural drift develops when locally reasonable edits accumulate into violations of the wider design. The defect lies in the relationships between changes and the boundaries they cross, so a review focused on individual diffs can miss it. Agents can repeat this pattern quickly when their context does not include the architecture their edits are altering.

Visibility alone does not prevent that drift. CodeSai describes architecture tests as deterministic gates that stop the build from passing when a rule is broken. This is a different control from asking an agent reviewer to notice a problem. Agentic review is non-deterministic and can overlook a boundary violation when the primary logic appears sound. An encoded constraint instead supplies a binary condition for acceptance.

A subscription supports that enforcement by keeping its structural input current. A command such as gr check can reliably exit non-zero for a constraint violation only when the graph describes the code actually being checked. Otherwise, the gate tests an earlier architecture. A stale graph can therefore undermine enforcement even when the rule itself is correct.

The graph must live in the repository, version with the code, and serve as input to CI enforcement. This makes the structural model part of the development contract. The subscription does not substitute for architectural rules, and the rules do not substitute for fresh relationships. Together, they make violations detectable against the current code and prevent those violations from passing the build.

How the shared graph changes who carries the burden of structural verification

Agent-generated code adds to the number of changes that developers are expected to check. Human review cannot keep up with that growth. Reading a large diff may establish that the changed code looks plausible, but structural verification requires evidence about callers, dependencies, and boundaries beyond that diff. Asking the reviewer to reconstruct all of those relationships turns attention into the limiting resource.

A live shared graph moves that reconstruction into the system. Structural verification becomes a query whose result can feed automated checks and CI gates, rather than a reading task repeated by every reviewer. The developer still evaluates the intended behavior and the architectural constraints. The system supplies the current relationships and enforces the rules encoded against them.

For the developer, the practical difference appears in the clean-looking agent change that would otherwise break something two modules away. The relevant dependency is available while the change is being made, and an encoded violation can block acceptance before that failure escapes review. Trust then rests on a current structural model and enforced constraints.

Sources

  1. Codebase-Memory: Tree-Sitter-Based Knowledge Graphsfor LLM Code Exploration via MCP
  2. The Spec Growth Engine: Spec-Anchored, Code-Coupled, Drift-Enforced Architecture for AI-Assisted Software Development

More in Codebase Architecture