Coldstart has not been released. The behavior on this page runs in the development build; there is no release you can install today.
The export work produced facts that outlive it: the approved column list, the rejected background job, the queued historical IDs. The project record is where a fact goes when it has to survive 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 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.
The ordinary alternative
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 fail the same way. One long document accumulates until nobody reads it; a folder of free-form notes accumulates until nobody can tell which note is current. Neither lets you ask where a fact lives, so neither lets you know whether you have found all of it.
A plain design document carries the same facts and is often enough. The stricter record earns its cost when fresh sessions repeatedly need to find facts starting from the feature or file they affect.
Where the export facts land
| Fact | Home | Why there |
|---|---|---|
| The approved export columns | Decision | It constrains what may leave the app |
| The rejected background job | With that decision, or its owning plan | It is the same choice, not a second summary |
| The historical-ID exclusion | A later owner | It is open work, not a settled fact |
| An observed serializer edge case | Gotcha | It will surprise the next person the same way |
These are authored facts: a person or agent writes them deliberately, and the file stays their authority. Filing makes location and shape checkable. It does not make the content true.
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.
| Required part | What it is | Why it is refused without it |
|---|---|---|
| A topic | The item is named by what it is about, not by a number or date | A list of items should read as a list of subjects |
| A one-line subject | One sentence directly under the topic | The generated map lists items by that line; no subject means a blank row later |
| A location key | A tag naming the feature, file or section this explains | Without it the item is findable only by browsing, never from the thing it is about |
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.
| Kind | What it holds |
|---|---|
| Plan | Intended work for an area |
| Decision | A settled choice and the constraint it imposes |
| Gotcha | Something that surprised you and will surprise the next person |
| Reference | A pointer to something useful that lives outside the project |
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. Closed is not the same as permanent: these four are what the reviewed build carries, and the list changes by a deliberate decision rather than by someone needing a fifth compartment tonight.
Kinds matter beyond tidiness. What happens to an item when the thing it describes is deleted depends on its kind — a plan for finished work is disposable in a way a decision never is — and 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 agent's own memory is a different surface with the same rule: a small index plus one typed fact per file, the two 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, so 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 | Do not file |
|---|---|
| A decision whose reasoning would be expensive to reconstruct and whose outcome constrains future work | What the code already says — a second source of truth about the code is the one that goes stale |
| A gotcha that surprised you and will surprise the next person | A conversation; if the narrative matters, write down the decision it produced |
| A reference when the useful thing lives outside the project and finding it again is the cost | Anything filed to be thorough; every item is currency a future reader must evaluate |
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: that items parse, that kinds come from the list, that homes are well-formed, 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 the human 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.