Step 1: Plain files in a repo

Start with plain Markdown files in a Git repository. This gives you and the agent the same material to read, search, move, edit, and version. A notes app can still be a useful editor, but the files remain the source of truth instead of depending on an export or a private database.

You’ve met this before. Plain-text productivity is a decades-old lineage (todo.txt, org-mode, Zettelkasten). Coding agents strengthen the case: they already know how to work with files and Git. A private app database needs an export or integration before the agent can do the same work.

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.

Try it with your agent

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.