memex turns your repo’s knowledge into a map agents can search. They see the whole codebase at a glance, open only the files that matter, and leave a trail for the next one.
The name is Vannevar Bush’s, from 1945. Here’s why.
Principles
Markdown first
Knowledge lives in plain Markdown in the repo, versioned with the code. No server, database, vectors or LLM: memex reads the files live, prints and exits.
Agent-agnostic
Anything with a shell can use it, whichever agent or human is at the keyboard. Plugins only wrap the CLI.
memex reads intent, tools read code
memex indexes READMEs, headers and collections, never code bodies. For symbols, rg is already the right tool.
Conventions over configuration
READMEs and headers are found by where they are; one frontmatter line joins a collection. Nothing to set up.
Never floods the context
Every list says showing N of M and takes --limit, so an agent knows what it has not seen. Nothing is cut silently.
Logs expire; knowledge is written down
Logs are work in progress: memex prunes old ones as new ones arrive. Whatever is still true gets written into a README, a header or a case by someone who understands it.
A feature earns its place by removing friction an agent actually hit in a playtest.
Get started
Paste this into your agent, in the repo you want to index. It installs memex, looks around, asks you a few questions, and sets up what you choose.
INSTALL.md
Install memex in this repo: follow https://github.com/aswemaythink/memex/blob/main/INSTALL.md
Or install it yourself
One command in the repo. It installs the binary if needed, creates .memex/, and adds a block to AGENTS.md that tells any agent to read intent before code. It is safe to repeat.
$npx @aswemaythink/memex init
Other ways to install
Manual, one command per toolchain, then memex init, or download a binary from GitHub Releases. The last line builds the binary from a checkout of the repo. It is one codebase for Linux, macOS and Windows.
After a manual install, run memex init in the repo. To uninstall, delete .memex/ and the marked block in AGENTS.md.
Context compression
memex is authored context compression. A README compresses a folder, a header a file, a case a test, a log an agent’s run. Whoever knew the most writes it, when they knew it best, so nothing has to summarise it later.
How an agent explores your codebase
Agents use the memex CLI to walk your codebase as a tree: a README at each folder, a header at the top of each file. Here two agents take turns. One wants to understand the API: the READMEs and the headers of the api files tell it enough, and it opens no code. The other is changing the schema: it finds the two files it must touch, the model and the migration, and opens only those.
The intent layer
READMEs, headers, collections and logs are the intent layer. The table runs from the most compressed at the top to the code at the bottom. READMEs and headers are found by where they are, collections by what they are, logs by when. An agent reads down it and opens code last.
Hover or tab to a rowTap a row for an example.
READMEsWhat a module is.One README.md per folder, saying what that module is and what it does.
crates/namer/README.md
# namerNamer: turns atoms into stable classnames. The same atom gets the same
name on every run and every platform.
- `src/hash.rs`: hashes atom strings.
- Cases: NAME-001 and NAME-002.
HeadersWhat a file does.A comment at the top of the file that describes what it does.
crates/namer/src/hash.rs
//! FNV-1a over canonical atom strings.
//! Hash input is the canonical atom
//! string, never object identity.
//! Cases: NAME-001, NAME-002
use std::hash::Hasher;
CollectionsAdditional knowledge worth keeping, found by what it is.Any Markdown file joins a collection with one memex: line in its frontmatter. See Patterns for ways to use them.
tests/cases/NAME-001/CASE.md
---memex: cases
id: NAME-001
---Class names are stable across runs.
Evidence: `tests/namer.test.ts`
LogsNotes agents leave for each other.Findings, hand-offs and messages, in .memex/logs/, out of git. Pruned as new ones arrive.
CodeThe source itself.Agents usually scan it wholesale, with grep, rg and the like. memex reads only the comment at the top of each file.
crates/namer/src/hash.rs
//! FNV-1a over canonical atom strings.
pub fn hash(atom: &str) -> u64 {
let mut h: u64 = 0xcbf29ce484222325;
for b in atom.bytes() {
h ^= b as u64;
h = h.wrapping_mul(0x100000001b3);
}
h
}
The bigger picture
In a large codebase, reading the code to see the whole picture costs more context than any agent has. memex gives agents a compressed version to traverse instead: what each part does, conceptually. They still read code. They find the code worth reading faster, and make better decisions once they are there.
Trailblazing
Compression gets an agent to the right code. Trails let the next agent start where the last one stopped. Bush’s memex was built around them: a reader linked what they found into a path someone else could follow later. memex gives agents two kinds: logs for work in progress, and collections for what stays true.
Logs
Logs are how an orchestrator and its worker agents talk to each other.
A worker logs what it did and what it found, and hands back a single line, the log’s ref; the orchestrator opens the full log only when it needs the detail. Reports, hand-offs and messages all travel this way, so logs fit whatever orchestration pattern your agents run. Logs are like chats: useful in the moment, stale soon after. memex prunes old ones as new ones arrive. Whatever is still true gets written into a README, a header or a collection; the rest can go.
Collections
A collection is a set of records on one topic that agents keep and search.
Each record is small and does one job: one attempt, one decision, one test. Any Markdown file joins a collection with one frontmatter line, so records live next to the work they describe.
Take performance work on an app. Every optimisation an agent tries gets a record: what it changed, what it measured, kept or cut. The next agent searches the collection before it starts. It sees what was tried, skips what failed, and goes straight to what is still worth trying.
Audit
Code moves on and the intent layer can fall behind it. memex audit checks for the drift: files with no header, folders with no README, files grown too long, one-liners that run long, references that resolve to nothing, duplicate ids. Agents run it on the paths they changed and fix what it lists in the same change, or log the rest to drift.
$memex audit srcaudit src · 148 files · 12 folders · 2 findings
headers(showing 1 of 1; files with no header)src/a.rs(no header): add a comment block atop the file; its first sentence states the file's purposecites(showing 1 of 1; unresolved)src/z.rs → NAME-404
(cites): fix the reference or remove it
Good work was being lost, not because it was wrong, but because nobody could get back to it.
1945
Vannevar Bush ran American science through the Second World War. When it ended, what kept him up at night wasn’t weapons. It was the record. Science was producing findings faster than anyone could find them again.
In July 1945 he published “As We May Think” in The Atlantic. In it he imagined a desk: two slanted translucent screens, a keyboard, levers, and inside, on microfilm, every book, letter and note you owned. He called it the memex.
The memex, sketched: two documents side by side, tied together.
Storage wasn’t the point. The point was trails. Libraries index by alphabet and category; the human mind, Bush wrote, “operates by association.” On the memex you would put two documents side by side, press a button, and tie them together. Do it again and again, add your own notes, and you’ve laid a trail through the material: your reasoning, kept, so you or anyone you handed it to could walk it later.
The process of tying two items together is the important thing.
Bush predicted a new profession: trail blazers, people who take delight in making useful paths through the common record.
The memex was never built. But Douglas Engelbart read the essay in 1945 as a young radar technician and spent his life on it. That became the 1968 demo that gave us the mouse and hypertext. Ted Nelson named hypertext with Bush in mind. From there, the web. Every link you’ve ever clicked descends from that desk.
The camera and the trail
The same essay has a second machine in it. Bush pictures a scientist with a camera the size of a walnut strapped to his forehead, taking a picture of everything he sees. Nothing is chosen at the moment of capture. You record it all, and sort it out later.
So the essay holds two answers to the same flood. The camera says: keep everything, and hope to find it again. The trail says: when you understand something, tie it to what it belongs with, so the next reader can follow. Those links are made on purpose, by someone who understood the material, at the moment they understood it.
The trail is the idea that changed the world. It became hypertext, then the web. The camera is the one we keep coming back to.
Now
Eighty years later, the flood is back, and this time agents produce it. Every run writes logs, reports, notes and hand-offs into folders nobody will open again.
And we are still building cameras. Hooks that record every step, servers that store it, vector databases that index it, models that summarise the pile after the fact. Smaller cameras, more film, the same hope: capture everything now, and something will make sense of it later. But a recording knows what happened, not what it meant. Whoever understood the work was there at the time, and nobody asked them to write it down.
memex takes Bush’s other idea.
memex
memex is authored context compression: trails of intent, for humans and agents.
Code records what a system does. The intent layer records what it’s for: a README says why a folder exists, a header says what a file is for, a case says what’s claimed and how it’s proven, and a log says what an agent was trying and what it found. Whoever understood it best compresses it, at the moment they understood it. Citations become trails, and memex walks them both ways (the intent layer, above).
Developers and agents are the trail blazers. An agent that finishes a job compresses what it learned and cites what it touched; the next agent walks that trail instead of starting from zero. Logs are the camera’s film: kept while the work is live, then thrown away. What’s still true gets authored into the layer.
No server, no database, no model in the loop. Markdown files and a CLI. Because the compression was already done, by whoever understood it.
Why this matters to us
When the story came together, the reaction was goosebumps. It wasn’t the history alone. It was recognising that the thing we’d been designing for practical reasons (READMEs everywhere, headers, case ids cited in prose, logs that expire, no automated capture) was Bush’s idea all along, and that it had been the right idea for eighty years.
The camera has always been tempting. The trail has always been what mattered.
