Notes on agents, codebases, and the work before the work.
Problem-first engineering writing about why agents keep starting cold, why notes are different from documentation, and why some context should be captured only after real work.
Codebase memory is not agent memory
Two different problems get called memory in agent tooling right now. Conflating them gets you the wrong tool for the job you actually have.
How your own benchmark lies to you first
Before a token-savings number can lie to a reader, it usually lied to whoever built it. Four concrete ways that happens, and the checks that catch each one before the number ships.
What a graph cannot see
A real call graph, built by parsing syntax, still misses the couplings that live outside syntax entirely. A story from three hook scripts that shared no import and broke each other repeatedly.
Why coldstart makes zero LLM calls
coldstart is two parts: a notebook of AI-written notes, and a navigation layer that decides which files are relevant to a query. The obvious way to build that second part is embeddings and similarity search. Here's why it uses declared identity and a real grep pass instead.
Why most token savings tools lie
Most published token-savings percentages measure a compressed call, not a smaller bill. What it actually takes to measure a whole session, and the two real numbers that came out of doing it that way.
Why an index of your code cannot answer the same question twice
A code graph makes each step of a search cheaper. It does not reduce the number of steps, and it never makes the second occurrence of a question cheaper than the first. Why that gap needs a different kind of record.
From four tools to two
An origin story told through deletions: the two traversal tools that were really missing fields, the architectural role labels, and the server that served nothing. What survived was two operations.
Notes about code should be written by whoever read the code
Why codebase notes for AI coding agents should be written by the agent that did the work, not reconstructed later from a transcript.
The tool the agent does not call
You can ship a tool, document it, and inject an instruction telling the agent to prefer it, and the agent will still reach for grep. Why availability is not adoption, why the detector I built to catch it caught nothing, and the rule that survived: surface, don't steer.
Where the tokens go in an agent session
Most of what an agent session costs is not the answer it produced. It is the same context, re-sent on every turn. How to decompose your own transcript and find the one lever that matters.