Coldstart is in final cutover and has not been released. The behavior on this page runs in the development build; there is no release you can install today.
The project record is where a fact goes when it has to outlive the session that discovered it. It is not one document. It is a set of small items, each about one topic, each filed in a named home, each carrying a key back to the part of the project it explains.
The shape is deliberately strict, and the strictness is the point: an item the product cannot parse is refused rather than filed loosely, because a record that quietly accepts anything is a record nobody can trust to be complete.
[Visual 3.1 — The upper shelf from the section opener, enlarged into one room drawn as an open-fronted shelf with four labelled compartments running along it: "plan", "decisions", "gotchas", "reference". A small padlock sits on the shelf edge, labelled "closed list — an invented compartment is a defect, not a new category". Inside one compartment a single card is drawn large, showing its three required marks stacked: a topic line at the top, a one-line subject directly under it, and at the foot a tag reading "location: the thing this explains". To the right of the card, three small rejected cards are drawn greyed and struck through, each with one mark missing and one label: "no topic", "no subject", "no location". Below the shelf, a separate small frame shows the agent's own memory as an index column whose every row has exactly one arrow to exactly one fact file; two rows pointing at the same file are drawn crossed out with the caption "one fact, one owner".]
The problem it solves
Project knowledge does not disappear all at once. It leaks. A constraint gets agreed in a conversation, half of it lands in a commit message, the rest stays in someone's head, and six weeks later the only surviving copy is a comment that no longer matches the code.
The usual repairs make it worse. One long document accumulates until nobody reads it. A folder of free-form notes accumulates until nobody can tell which note is current. Both fail the same way: there is no way to ask where a fact lives, so there is no way to know whether you have found all of it.
Giving every durable fact a typed home and exactly one owner turns "do we have this written down" into a question with an answer.
What one item looks like
Each item is a small file about a single topic, and three things about it are required rather than encouraged.
A topic. The item is named by what it is about, not by a number or a date. The name is the heading, so a list of items reads as a list of subjects.
A one-line subject. One sentence directly under the topic saying what this is about. It exists because the generated map lists items by that line: an item with no subject is an item the map has nothing to display, so it is refused at the point of filing rather than rendered blank later.
A location key. A tag naming the feature, file or section this item explains. Without it the item can only be found by browsing, which means it will not be found from the thing it is about, which is the only direction anyone actually searches from.
An item missing any of the three is reported as a defect with its own path named. Nothing is half-filed and nothing is silently skipped.
Typed homes and the closed list
Items live in named rooms — one per area of the project — and inside each room they sit in a compartment named for the kind of thing they are: a plan, a decision, a gotcha, or a reference.
That list is closed. A compartment invented on the spot is refused, and the refusal is the feature. An open vocabulary drifts within weeks: the same kind of fact starts arriving under three different names, and the record turns into a folder of free-form notes with extra ceremony.
Kinds matter beyond tidiness. What should happen to an item when the thing it describes is deleted depends on what kind of item it is. A plan for finished work is disposable in a way a decision never is. A fixed vocabulary is what lets that be a rule rather than a judgment call each time.
The structure is also deliberately shallow. Compartments do not nest, and a room holds compartments rather than loose files. Growth happens sideways, by adding rooms, because a deep tree is a tree where the same fact has several defensible homes.
One fact, one owner
The record and the agent's own memory are different surfaces with the same rule.
The agent's memory is a small index plus one typed fact per file, and the index and the files are a bijection: every row points at exactly one fact, and every fact is reachable from exactly one row. Facts carry a type from a short fixed list, and a file that does not parse into that shape is reported rather than absorbed.
Duplication is caught mechanically. A fact's body is hashed, and two facts with identical bodies are an exact duplicate pair by definition, whatever their filenames and however differently they were saved. When the index grows past its budget, a consolidation pass runs, and its safeguards are the interesting part:
- It can only merge, remove, or flag a disagreement. There is no operation that rewrites the prose inside a fact it is keeping.
- A merge appends the source text unchanged. The pass moves facts between files; it does not compose new sentences and present them as your record.
- One file gets one fate. Nothing can be both removed and written by the same pass.
- Facts marked as protected cannot be dropped, and an attempt to drop one refuses the whole pass rather than applying the rest.
- By default the proposal is shown to you and applied only after approval, and the whole thing refuses to run unless the prior state is recoverable through version control first.
The narrow point of all that machinery: an automated pass that edits your memory is only acceptable if the things it can do are a short closed list and every one of them is reversible.
When to file, and when not
File a decision when the reasoning would be expensive to reconstruct and the outcome constrains future work. File a gotcha when something surprised you and will surprise the next person. File a reference when the useful thing lives outside the project and finding it again is the cost.
Do not file what the code already says. A record of what the code does is a second source of truth about the code, and it will be the one that goes stale.
Do not file a conversation. The record holds facts with owners, not a narrative of how they were reached. If the narrative matters, the decision it produced is the thing to write down.
Do not file to be thorough. Every item is something a future reader has to evaluate for currency, so an item that will never change anyone's action is a small permanent tax.
Limits
Filing does not make a fact true, and it does not keep it true. A decision item records what was decided, and nothing in the structure notices when the project quietly stops obeying it.
The checks here are structural. They establish that items parse, that kinds come from the list, that homes are well-formed and that no two facts are byte-identical. None of that is evidence that a decision was right, that a gotcha is still real, or that the set is complete. A well-formed record of stale facts passes every check on this page.
Duplicate detection is exact-match only. Two items saying the same thing in different words are two items, and no automatic step will notice. Recognising that pair is human work, and it is the work the sweep verb exists to prompt rather than to do.
Existing projects are the honest gap. The structure is built for facts filed into it as they are discovered; migrating a large body of existing notes into it has no verified path today, and nothing here should be read as claiming otherwise.
Next
The record is written by hand. What lists it is not: generated maps.
How current this page is
Checked on 10 August 2026 against the product's current record structure, its memory consolidation safeguards and its recorded release state. Four compartment kinds and four memory fact types are counts of what exists today; both lists are deliberately changeable by decision. To ask whether a claim here still holds, or to report one that does not, write to [email protected].