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

  1. 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.

  2. 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.

  3. 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 and Memex over MCP compared
Markdown in the repoMemex over MCP
Who writes itWhoever has the repo openAgents draft it; each discipline reviews its lens
How information is foundRules files load whole; specs are found by grepSemantic and full-text search over every record
Control over what is readWhatever the agent happened to search forThe records the task asks for, by facet and by search
Context costThe whole file, every timeThe clauses for the work in hand
DecisionsLost in chatRecorded, with the reason and who agreed
DriftUnnoticed until something breaksRegistered when found, and sent to a person
Writes backOnly when someone edits and commits the fileAgents record decisions, drift, progress and tasks
Team-sharedOne copy per branch and per cloneOne live record for every person and agent
ProofSomeone says it is doneEvery 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.

  1. agent · task: show one calm status when a payment fails
  2. facets · user interface, security
    • std-87 · Status messages follow the payment patterns
    • std-81 · No card data in logs or job payloads
  3. search decisions "failed payment message"
    • dec-4 · Three silent retries, then one re-authentication step · resolved
  4. record progress
    • spec-942 · status banner built, 3 of 4 criteria passing
  5. 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