MD vs MCP
Markdown is a CSV. Your agents need a database.
Markdown in the repo was the first generation of agent context: the first way most teams gave coding agents something to read. CLAUDE.md, AGENTS.md and spec kits made spec-driven development real. They proved that agents build better from written intent than from a chat message.
We owe them a lot. But a folder of files was made for people, who read top to bottom. Agents read differently, and as the team and the codebase grow, three problems show up.
Three problems with markdown
Non-deterministic reads
Your rules files load in every session. Your specs and design docs do not. An agent finds those with search tools such as grep, so what lands in its context window depends on what it happened to search for.
Pick a different word and it reads a different file, or none at all. Developers have little control over what was read, and little visibility of it afterwards.
Silent drift
A spec in markdown is true on the day it is merged. Then the code moves on. Nothing ties the file to the code it describes, so the two drift apart and nobody notices it happened.
The next agent reads the old spec and builds on it with confidence.
The wrong amount at the wrong time
An agent needs very specific information at specific moments. A rules file that loads in every session grows with every lesson learned. Large documents either clog the context window or bury the one line that mattered.
Thoughtworks put agent instruction bloat in Caution on its Technology Radar in November 2026, and progressive context disclosure in Adopt. We agree with both calls.
Files versus records
A CSV is a fine way to start keeping records. Nobody runs a business on one. Markdown is the same: a fine start for one developer, and Memex exports to markdown whenever you want a file.
Once a team and its agents share the work, the record needs search, structure and writes. That is a database.
| Markdown in the repo | Memex over MCP | |
|---|---|---|
| Who writes it | Whoever has the repo open | Agents draft it; each discipline reviews its lens |
| How information is found | Rules files load whole; specs are found by grep | Semantic and full-text search over every record |
| Control over what is read | Whatever the agent happened to search for | The records the task asks for, by facet and by search |
| Context cost | The whole file, every time | The clauses for the work in hand |
| Decisions | Lost in chat | Recorded, with the reason and who agreed |
| Drift | Unnoticed until something breaks | Registered when found, and sent to a person |
| Writes back | Only when someone edits and commits the file | Agents record decisions, drift, progress and tasks |
| Team-shared | One copy per branch and per clone | One live record for every person and agent |
| Proof | Someone says it is done | Every criterion proven by a test |
How the MCP approach works
Memex is a database your agents reach over MCP. It holds every Spec, decision and Standard your team has made, with semantic and full-text search across all of it.
Search, not guesswork
An agent asks a question and gets back the decisions that answer it, matched by meaning as well as by words. It does not depend on which file it opened first.
Facets: the right clauses at the right moment
Facets are the aspects of engineering in play at a given moment, such as user interface, security, data or testing. When an agent starts work on the user interface, it gets the clauses that govern user interface work.
Those clauses may come from many Standards. The agent gets them together, not one long skill document it has to read end to end.
Agents read and write
Agents do not only read. They draft Specs and raise decisions for your team to settle. They register drift when they find it, record progress as they work, and keep tasks and planning current.
Your team works with that knowledge live, in the browser, while the agents work with it over MCP. It is a way of working, not a static file.
- agent · task: show one calm status when a payment fails
- facets · user interface, security
- std-87 · Status messages follow the payment patterns
- std-81 · No card data in logs or job payloads
- search decisions "failed payment message"
- dec-4 · Three silent retries, then one re-authentication step · resolved
- record progress
- spec-942 · status banner built, 3 of 4 criteria passing
- new question
- dec-5 · raised for architecture to decide
Works with the tools you already use
Memex does not replace your agent or your files. It sits alongside them.
Claude artifacts in a Spec
Link a Claude artifact from a Spec, such as a design mock or a working prototype, and every agent and reviewer opens the same thing. It works brilliantly.
Other MCP servers
Your agent can use Memex and other MCP servers in the same session. Memex holds what your team decided; the others do their own jobs.
Any agent that speaks MCP
Memex is a standard MCP server, so any MCP-capable coding agent can read from it and write to it.
Markdown when you want it
Memex exports to markdown. Keep CLAUDE.md for local habits, such as how you like tests run on your machine.
Give your agents a database.
Sign up free and connect your agent. It drafts your first Spec from your real codebase, ready for your team to review in the browser.
Sign up freeSee Memex build itself