The intent layer

What the code leaves out

A reader can work out what a system does by reading its code. The code rarely says why a folder exists, what a file is for or what a test is meant to prove. The intent layer says those things, next to the code it describes.

Four parts, in reading order

The layer has four parts. An agent reads them from the most compressed down, and opens the code last.

1. READMEs, one per folder. The first paragraph says what the folder is and why it exists. Found by where they are.
2. Headers, the comment block atop each file. Its first sentence says what the file is for. Found by where they are.
3. Collections, any Markdown file with a memex: line in its frontmatter, such as a CASES.md that lists test ids and what each one proves. Found by what they are.
4. Logs, what one agent run did and found. They are scaffolding, and they expire. Found by when they were written.

Code comes last: an agent opens it only when the layer cannot answer.

What memex reads, and what it leaves to rg

memex never indexes code bodies, only the comment block at the top of a file. To find a symbol in the code, use rg: memex finds meaning, cases and findings.

The parts link to each other through citations. Write an id, a path or a ref into a README, header or doc rather than copying the text. memex builds the links both ways, and they are the trails.

See the intent layer on the intro page.