| name | dftracer-context-economy |
| description | Context/token economy for every dftracer agent. Use the graph tools (graph_query / graph_ensure) to LOCATE code and compute change blast-radius instead of reading whole files into context. Load this before any tool call, annotation, optimization, or pipeline step that would otherwise open source files.
|
| priority | critical |
Context economy — locate, don't read
The dominant token cost in this pipeline is input: source an agent reads to
orient itself. graphify (dependency graphifyy) builds a tree-sitter graph
over C/C++/Fortran/Python plus markdown headings, so skills and agent
definitions are queryable too.
Measured on this repo:
| Approach | ~tokens |
|---|
| Read the 3 relevant source files whole | 29,456 |
graph_query(question=..., budget=1200) | 986 (3.3%) |
graph_query(mode="explain", symbol=...) | 208 |
graph_query(mode="affected", symbol=...) | 212 |
Use the MCP tools, not the CLI
Two tools, deliberately (graphify's own MCP server registers ~25 schemas; this
project already exposes 137). They guarantee freshness before answering:
graph_query(question="python annotation cost gate", budget=1200) # locate
graph_query(mode="explain", symbol="_python_annotate_file_impl") # defn + callers
graph_query(mode="affected", symbol="recommend", depth=2) # blast radius
graph_ensure(force=True) # manual refresh
For the target application in a session, pass run_id:
graph_ensure(run_id=RUN_ID) # build the app's graph once
graph_query(question="checkpoint save", run_id=RUN_ID)
The CLI (graphify query|explain|affected) still works and is a fine fallback,
but it does not check freshness — the MCP tools do.
Rules
- Locate before you read. Never
grep/Read a tree to find where something
lives. Ask the graph, then open only the file:line it names. Paths returned
are absolute and openable.
- Before editing any shared function, run
mode="affected" and state the
blast radius. It is how you learn that changing recommend() also moves
_estimate_file_impl -> _validate_python -> _plan. Skipping it is how a
"local" fix silently breaks a caller.
- Freshness is automatic. The graph rebuilds only when the skills/agents/code
content hash changes, or a writer marked it dirty (~5 s). An unchanged graph
costs ~0.1 s to validate. Self-learning skill edits therefore do invalidate it.
- Budget queries (
budget=1200). BFS depth 2 pulls in generic nodes (_ok,
json); ignore them rather than widening.
Honest limits
- The graph is structural. It finds where code is and how it connects; it
does not read semantics. For "what does this do", open the
file:line.
- Symbols are class-qualified. A method appears as
.save_checkpoint(), so
mode="affected" on a bare method name can report "No unique node match". Use
mode="query" with a phrase, or the qualified name.
graphify honours .gitignore, does not follow symlinked dirs, and needs code
files present for markdown to be extracted. The graph tool works around all
three; do not hand-run graphify update on a gitignored path and expect nodes.- Upstream advertises 70x; what we actually measured here is ~30x on a realistic
locate-then-read query.
