How it works

An agent that has been here before shouldn't start from nothing.

coldstart is codebase memory: what an agent worked out about your code, written down at the moment it worked it out, and checked against the code again every time it's read. Underneath it sits an exact index, so an agent can still find the file no one has left a note on.

← back to the overview

Two layers, and only one of them is memory.

The index is a fact about the repository as it exists right now. The notebook is a fact about what someone learned here that reading the file wouldn't tell you. They're built differently because they expire differently.

The notebook

Memory of this codebase

Notes written by the agent that did the reading — anchored to a file, often a symbol, and stamped against the exact bytes it verified.

written during the task, not after
addressed to a file and symbol
re-surfaced when the next agent needs it
re-checked on every read
says [fresh] or flags itself stale
How the notebook works
The navigation layer

An exact map, no embeddings

Paths, symbol names, imports and calls, parsed and kept current in the background. Queried with two lookups, answered without a model call.

find — which files match these terms
gs — one file's shape and its callers
ranked on checkable evidence
no embeddings, no API key
useful from the first lookup
How navigation works
Why they can't share a design. The index can be rebuilt from the repository at any moment, so it is never wrong for long — a wrong entry is a bug. A note can't be rebuilt from anything; the reasoning that produced it is gone the moment the session ends. So a note that goes wrong stays wrong, silently, and gets acted on as fact. That asymmetry is the whole reason the notebook carries freshness machinery and the index doesn't need any.

The index is how the memory gets found.

They aren't alternatives you pick between. Notes are addressed to files, so the index is what retrieves them — one lookup returns the ranked files and whatever is already known about those same files, together.

On the code

The ranking comes first

Filenames, path segments, exported symbols and a repo-wide reference scan — find ranks each file by how many of your terms it covers, and shows the evidence for the ranking. This runs whether or not a single note exists.

Same result

The note rides along

Any ranked file that has one carries a Summary: line against the result itself, right where you're deciding whether to open it. Marked [fresh], the file is byte-identical to when it was verified.

Your call

The next move is yours

Open the file with gs if the note made it interesting. Open the note itself for per-symbol detail and the flows through it. Or go straight to the code — most files have no note, and the ranking alone was enough.

Which is why the memory has to be addressed to code. A note anchored to a file is reachable by the same lookup that finds the file. A note filed under a topic or a similarity score is something you'd have to go and search for separately — and an agent mid-task won't.
Read the docs coldstart vs vector RAG → Engineering blog →