Step 1: Plain files in a repo

The decision everything else rests on is the substrate: plain markdown files in a git repo. Not because apps are bad, but because every capability you’ll want later (agent access, search, history, sync, tooling) falls out of files for free, and falls awkwardly out of apps forever.

You’ve met this before. Plain-text productivity is a decades-old lineage (todo.txt, org-mode, Zettelkasten), and “files over apps” is its modern slogan. The agent renews the argument decisively: an agent reads, greps, moves, and refactors files natively, while a notes app’s database needs an export, an API, or a prayer.

Why files win

Agent-native. Read, write, grep, move: the agent’s entire tool vocabulary works on day one. No integration exists to break.
Git underneath. Every note versioned, every reorganization reversible, sync by push. The vault inherits the whole git guide for free.
Greppable beats organized. Perfect hierarchy is a trap; full-text search over plain files, by you or the agent, does most retrieval work.
Portable forever. Markdown from 2010 opens today. Whatever editor, whatever agent, whatever comes next.

The conventions (minimal on purpose)

kebab-case filenames, lowercase, no spaces. Predictable names are what let an agent link and move files without asking.
Frontmatter only when it earns its place: title, created, tags, status. An empty template on every note is friction that kills capture.
A file can graduate to a folder (some-idea.md → some-idea/index.md) when it accumulates assets. Structure grows from content, not ahead of it.

Try it

TRY IT App or files

you

I want to finally start a real knowledge base: notes, projects, ideas, all of it. Should I get one of those notes apps?

agent

The substrate decision comes first, and it's the one that's expensive to reverse: an app's database, or plain files.

Pick the agent's next move, then see where it leads:

ASetting you up with the leading notes app: great editor, sync included, and it has an API I can integrate with for automation.

you

Can you go through my project notes and update the stale ones?

agent

That needs an API token, three paginated endpoints, and their rate limit. And their API doesn't expose the backlink data at all. What would be grep-and-edit on files is an integration project here. Also worth saying now rather than later: everything you write is accumulating inside their format.

the baseline

The app optimizes the human editor and walls off everyone else, including your agent. Every future automation pays the API tax, and the notes themselves live in someone else's schema.

BPlain markdown files in a git repo. One folder to start, kebab-case names, frontmatter only where it earns its place. Every tool I have works on it natively, and git gives you history and sync for free.

you

Go through my project notes and update the stale ones.

agent

Done directly: grepped for last-touched dates, read the four stale ones, proposed edits, committed with a message saying what changed. No integration existed because none was needed: read, grep, move, and version are the native operations on files.

correct

Files made the agent a first-class citizen on day one: the entire tool vocabulary just works, git rides underneath, and the notes will open unchanged in whatever editor or agent exists in ten years.

CLet's design it properly first: I'll draft a folder taxonomy (areas, resources, projects, archives, each with subcategories) so every future note has a correct home before we write anything.

you

Two weeks later: I've written three notes. Each time I spent five minutes deciding which of the fourteen folders it belonged in.

agent

The taxonomy was designed for notes that didn't exist, and now it charges an admission fee on every thought. Three notes can't tell us the right structure. Thirty could have.

plausible but wrong

Taxonomy-first is structure ahead of content: a filing decision taxed onto every capture, calibrated on zero data. Two notes that want a home create the home. Structure grows from what accumulates.

Do it by hand

Make the folder, git init, write one note about something you’re actually working on. Resist the urge to design the taxonomy first. Step 2 gives you the only four directories you need to start.

Or paste this into Claude

I'm starting a plain-file vault. Create the folder (ask me where),
git init it, and write a first note: interview me briefly about one
current project and file it as a markdown note with kebab-case
naming and minimal frontmatter (title, created). Then commit. Don't
create any directory structure yet beyond the root. Structure comes
next step.

Watch out

Taxonomy-first paralysis: designing folders for notes that don’t exist yet. Two notes that want a home create the home.
App-shaped exports: importing 2,000 notes from an old app on day one buries the new vault in someone else’s structure. Start empty; import selectively when a note is actually needed.