Two graphs for coding agents: fewer tokens, and lessons that last

A coding agent spends much of its token budget on finding code: it searches, opens files, and reads them to learn who calls what. This article shows two graphs that change that. A code graph answers where the code is in one call. A work graph remembers why and what was proved, so the agent gets better from one session to the next without retraining.

Who it is for: developers who build LLM apps and coding-agent setups, and teams that pay for the tokens their agents use.

What this covers

1. The token problem
2. Inside a code graph
3. How the agent talks to it: MCP
4. Wiring it into Claude Code, Codex, Copilot and Gemini
5. What the context hook costs
6. Measure the tool, not the promise
7. Traps
8. The second graph: a work graph
9. How an agent improves between sessions
10. Keep the two graphs apart

 question: "who calls X?"
      │
      ├─► CODE GRAPH (where)            SQLite: symbols + links, built from source
      │      one MCP call ─► source + callers + impact ─► open only those files
      │
      ├─► edit ─► the graph's file watcher re-indexes on save
      │
      └─► WORK GRAPH (why, what was proved)
             task ─► acceptance criteria ─► evidence ─► check ─► lesson
                                                                  │
             next session reads the lesson before it starts ◄─────┘

1. The token problem

Search returns lines; the agent must still open files to find which function each line sits in. A code graph returns the calling functions themselves.

The graph's answer is 36–84% shorter, and it is already the answer, not a list of places to look.

Two other things already cut token cost, so measure the graph's saving on top of them: prompt caching, which makes repeated context cheap, and a hook that summarises long search output before the model reads it.

• What to do: time one real "who calls X" lookup with grep and with the graph, in your own repository, before you decide.

2. Inside a code graph

The examples use CodeGraph, an open-source (MIT) code graph. It parses source with tree-sitter and stores the result in one SQLite file, .codegraph/codegraph.db. Two tables do the work: every function, class or route is a row in nodes, and every relation between two of them is a row in edges.

CREATE TABLE nodes (id TEXT PRIMARY KEY, kind TEXT, name TEXT, file_path TEXT,
                    start_line INTEGER, end_line INTEGER, signature TEXT /* … */);
CREATE TABLE edges (source TEXT REFERENCES nodes(id), target TEXT REFERENCES nodes(id),
                    kind TEXT /* contains, calls, references, imports … */, line INTEGER);

"Who calls X" is one join. Run against TabBridge:

SELECT s.name AS caller, s.kind, e.line, s.file_path
FROM edges e JOIN nodes t ON t.id = e.target JOIN nodes s ON s.id = e.source
WHERE e.kind = 'calls' AND t.name = 'Button';

caller        kind      line  file_path
ApprovalCard  function  33    extension/src/pane/ApprovalCard.tsx
Actions       function  130   extension/src/pane/shared.tsx
Pane          function  11    extension/src/popup.tsx

The tool reports 6 dependents, not 3: it counts the 3 functions that call Button and the 3 files that import it. Know what your tool counts before you compare numbers.

• What to do: open the database with sqlite3 "file:.codegraph/codegraph.db?immutable=1". It runs in WAL mode, so a plain read-only open fails while an agent uses it.

3. How the agent talks to it: MCP

The agent starts codegraph serve --mcp as a child process and talks JSON-RPC over stdin and stdout (Model Context Protocol). In version 1.6.2 the server offers one tool, codegraph_explore. Its answer holds the source of the relevant symbols, the call path between them and a list of what depends on them.

→ {"method":"initialize", …}
← {"serverInfo":{"name":"codegraph","version":"1.6.2"},
   "instructions":"# Codegraph — available (per-project; pass projectPath) …"}
→ {"method":"tools/call","params":{"name":"codegraph_explore",
   "arguments":{"query":"Button ApprovalCard"}}}
← "- ApprovalCard → Button   [dynamic: renders <Button>] … Found 25 symbols …"

The instructions string matters. Claude Code puts each server's instructions into the model's context, so the model reads "ask the graph before you read files" before its first tool call.

• What to do: read your MCP server's instructions text. It steers the model as much as the tool does.

4. Wiring it into Claude Code, Codex, Copilot and Gemini

One command connects the agents it supports. Turn telemetry off first: indexing before that queues anonymous usage data.

npm i -g @colbymchenry/codegraph@1.6.2
codegraph telemetry off
codegraph init -y .                                   # in the repository root
codegraph install -y --target claude,copilot-cli,codex
agy mcp add codegraph -- codegraph serve --mcp         # Gemini through Antigravity CLI

For Claude Code, the installer writes three things: the server in ~/.claude.json, a permission mcp__codegraph__* in ~/.claude/settings.json, and a UserPromptSubmit hook, codegraph prompt-hook.

Agents that run in a fresh clone need more. A CI job or a cloud runner has no index, and Claude Code started with --strict-mcp-config uses only the MCP servers passed with --mcp-config, never the global ones. Such a runner must build the index in the clone and pass the server itself.

• What to do: pin the version, turn telemetry off before the first index, and check each agent lists the server (claude mcp list, agy mcp list).

5. What the context hook costs

The hook reads each prompt before the model does. For a question about code structure it adds a <codegraph_context> block with source and callers. It saves a tool call, but it is not free.

The hook matches words, not intent. On a small repository its context can cost more than the search it replaces.

• What to do: turn the hook on, then compare a day of token use with and without it. Keep it only if the number goes down.

6. Measure the tool, not the promise

Version 0.6.8 of the same tool answered "No callers found" for the access check with 60 callers. Version 1.6.2 finds all of them.

An agent trusts what the graph says. A wrong "no callers" invites it to delete live code.

• What to do: before you rely on a code graph, check three lookups you know the answer to.

7. Traps

• What to do: put these five lines in your repository's AGENTS.md, so every agent on the team follows them.

8. The second graph: a work graph

A code graph knows where code is. It cannot know why it was written, what "done" meant, or what went wrong last time. A work graph holds that. Ours is called Graph-Engineering: a small SQLite graph per project with four kinds of node.

The completion check passes only when every criterion links to real evidence. A passing build is not evidence that a user flow works.

• What to do: before an agent starts a task, have it write the acceptance criteria as observable results, each with the check that will prove it.

9. How an agent improves between sessions

A model does not learn from your sessions. Its weights stay the same. What can change is what it reads at the start of the next session. That is the whole mechanism, so build it on purpose:

failure or owner correction ─► lesson (trigger · cause · action · evidence)
        ─► next task reads matching lessons first ─► applies the action
        ─► evidence shows it worked ─► lesson marked effective
                                  └─► it failed ─► revise or retire the lesson

• Adoption is not effectiveness. A written lesson stays pending until a later task checks it.

• Stale lessons cost tokens and mislead. Retire them as readily as you add them.

• Retrieval beats volume. The agent reads the lessons that match the task, not all of them.

• What to do: add a lesson only when a failure or a correction teaches something reusable, and record the evidence with it.

10. Keep the two graphs apart

Merging them would put your records in a cache that the next upgrade rebuilds. Link them thinly instead: a lesson names the symbol it is about, and evidence can hold an impact report from the code graph.

Checklist

• Measure one real lookup with grep and with the graph before you adopt it.
• Pin the code graph's version, and check three lookups you know the answer to.
• Turn telemetry off before the first index.
• Never commit the index; build it per machine, and per worktree.
• In fresh clones and CI, build the index there and pass the MCP server explicitly.
• Measure the context hook's token use before you keep it.
• Search once before you delete code the graph says nobody calls.
• Write acceptance criteria as observable results, and link real evidence to each.
• Add lessons only from failures and corrections; retire the ones that stop helping.
• Keep the code graph and the work graph separate.

Where this fits

iKanban ships both ideas to its subscribers. A setup skill in the developer kit installs and connects the code graph for each agent. On the laptop runner, a Use CodeGraph setting, on by default, indexes each run's fresh clone.

Limits

• The measurements come from three repositories on one Mac, with CodeGraph 0.6.8 and 1.6.2. Your repository and version can differ.
• We did not measure the total token saving over a full working day.
• The work-graph loop records and retrieves. Whether a lesson helps is shown only by a later task's evidence.

Sources

• CodeGraph — the code graph used; commands checked with --help on version 1.6.2.
• Model Context Protocol specification — how the agent and the server talk.
• Claude Code: MCP and hooks — server configuration and the UserPromptSubmit hook.
• TabBridge — the public repository behind the examples; every TabBridge output above was run by us.