Trails

Citations go both ways

An id, a path or a ref written into a doc links the two. NAME-001 in a README links that README to the case with that id. A path such as crates/namer/src/hash.rs links a README to the file it names.

memex reads every link both ways. memex show lists what a doc cites, each with its one-liner, and what cites it, so a reader can follow a trail back as easily as forward.

Logs are immutable: memex has no verb to edit one. A correction is a new entry that cites the old one, and the old entry then shows the correction under cited by.

Logs are work in progress

A log records one run: what an agent tried, and what it learned that the code does not say, such as a verdict, a dead end or a gotcha.

A worker logs its full report and hands back one line, the log’s ref. The orchestrator opens the full log only when it needs the detail.

Logs are like chats: useful in the moment, stale soon after. memex prunes the oldest as new ones arrive, within the limits set in configuration.

Collections keep what stays true

A collection is a set of records on one topic that agents keep and search. Any Markdown file joins one with a memex: line in its frontmatter.

The usual first one is a CASES.md with memex: cases, where each entry is a test id and the claim it proves. Collections are authored, not pruned: they stay until someone changes them.

Promoting a finding

When a log holds something still true, write it down once, in your own words, where the next reader will look: a README, a header or a doc in a collection. Cite the ids, and let the log expire.

Never copy the log into the repo, or give it a memex: line. That turns one run’s record into permanent noise.

The steps are on the promote findings pattern page. See Trailblazing on the intro page, and the story for where the word comes from.