AboutThe useful boundary
The file is the durable part.
A folder is a good place to keep notes. It is easy to inspect, back up, move, and version. It is less good at answering questions that involve the whole collection.
Markdow adds the missing context without replacing the folder. It extracts frontmatter, resolves wiki links, records backlinks, and builds full-text search. The derived data can be discarded and rebuilt from the files.
The separation becomes useful when the same notes need to appear in more than one place. An editor can work directly with the vault while an application or agent uses Markdow. Both are looking at the same underlying material.
--- title: Architecture tags: [markdow, engineering] --- # Architecture Markdown files are the content source of truth. PostgreSQL carries the index. See [[Project plan]].
How it worksThree kinds of state
There is very little machinery.
The storage driver reads and writes note bodies. PostgreSQL holds the note index, extracted relationships, and access records. The REST API and MCP server expose the same note operations to clients.
| Layer | What it holds | What happens without it |
|---|---|---|
| Markdown vault | Note bodies and assets | The notes remain ordinary files. |
| PostgreSQL | Search, tags, links, graph, and access records | The note index can be rebuilt; access must be established again. |
| Client | The editing or reading interface | Choose another client without converting the notes. |
OperationsOne shared contract
Work with notes from any client.
It creates users and their vaults, then creates, reads, updates, deletes, imports, and lists the notes inside each vault. The same vault-scoped index supports these higher-level operations:
- search_notes
- Search titles and bodies and return a relevant excerpt.
- list_backlinks
- Find notes that link to a given note, including the surrounding sentence.
- get_note_graph
- Traverse linked notes to a requested depth.
- rebuild_index
- Read the vault again and reconstruct its derived state.
- embed_text
- Create an embedding with a vault owner's encrypted provider credential.
Get startedChoose your prompt
Copy the right one into your agent.
New to Markdow
Sign me up for Markdow using https://markdow.org/auth.md. Ask me for anything you need, then create my first vault through its Model Context Protocol server.
Already use Markdow
Connect me to my existing Markdow account using https://markdow.org/auth.md. Ask me for anything you need, then list my vaults through its Model Context Protocol server.
ContributingCode and design
Markdow is small enough to change.
An Elixir service, a PostgreSQL index, and a folder of Markdown files. There is little machinery between an idea and a working patch.
Code is welcome. A storage driver, a note operation, better indexing, or a client for the editor you already use. When an operation changes, its web route, its OpenAPI description, and its Model Context Protocol tool are updated and tested together, so a contribution stays consistent across every interface.
Design is welcome on the same terms. These pages, the documentation, and the social preview images read from one set of design tokens, so a considered change to the palette, the type scale, or a layout reaches all of them at once. A proposal is as useful as a patch.