D780 — graph_context is named where agents choose their tools, not fused into search¶
Decision. The first generated "Operational instructions" bullet, the line
that tells an agent which tools to consult a KB with, also names
graph_context, for answers that span several linked pages. Its tool
description says when to use it, one call instead of chaining search,
concept_read and graph_neighbors, in place of listing its response fields.
The search ranking is unchanged.
Why. graph_context (D242) was called 0 times in 124 agent sessions of one
installation since it shipped, while search was called 198 times and 24% of
concept_read calls opened a page linked from one read earlier in the session,
which is the walk graph_context replaces. Nothing an agent reads at session
start named it: the generated bullet listed search, atlas_overview and
concept_read, and the only sentence saying when to prefer it lived in
docs/control-plane.md. A structural index earns its gain inside the tool the
agent already calls (Bhola et al., Code Isn't Memory: A Structural Codebase
Index Inside a Coding Agent, arXiv:2606.22417, 2026); naming the tool where
agents pick their tools is the cheapest test of whether adoption, not ranking,
is the gap. It costs 136 bytes per KB in every steering file.
Alternatives rejected.
- Fusing the graph into search's ranking (reciprocal rank fusion of the
search and graph_context lists): on 99 real searches replayed against
the same server, with the concepts the agent then read as the relevant set,
the first relevant hit at rank 1 fell from 51% to 24% and in the top 5 from
82% to 61%, because graph_context leaves its seeds out of its results.
- A related block appended to every search response: the share of
later-read concepts the response covers rose from 73% to 80% (9 of the 27
searches whose reader went past the top 10 were recovered), for about 1 KB
more per search, roughly what the reads it saves cost. Kept as
#781, to decide on
measured usage after this change; taken as
D781, which amends this
decision.
- A pointer in search's description: the agent-profile tools/list budget
(D285) had under 80 bytes left, and the steering line reaches the agent before
any tool list does.
Consequences. A KB whose instructions.md opts out of the generated bullets
(preamble: none) does not get the line; its curated text decides which tools
it names. Whether this was enough is read from the client transcripts, not
from the server: a later change to how structure reaches agents starts from
that count.