.md is all you need

What I've wanted to build for a while is a personal AI assistant that actually knows me. Not a chatbot you reset every conversation. Not a search engine you query. Something more like the best personal assistant imaginable. One that remembers everything, connects dots you didn't notice, and gets sharper the longer you work together.

Many tools promise to be your "second brain." Each one I tried eventually became a system I was maintaining instead of using.

But the problem wasn't the tools. It was my mental model of what I was trying to build.

Context is the product

When you imagine a world-class personal assistant - not software, a human one - what makes them irreplaceable isn't that they do tasks faster. It's that they walk into every meeting already knowing what matters. They remember what you said three months ago and connect it to what you're dealing with today. They don't need to be briefed. They have the right context.

That's the thing I was actually trying to build. A context machine.

And when I started thinking about it that way, the entire problem simplified.

Don't automate the task

The obvious move is to go fully agentic: connect AI to your email, calendar, and files, and get out of the way. But there's a structural problem: it removes you from the loop. And for a system that's supposed to be an extension of your thinking, that's fatal.

The value of a second brain isn't that it acts autonomously. It's that it helps you think better. The moment the system is doing things without your judgment in the mix, it stops being an extension of your brain and starts being a separate agent with its own agenda. And fully automated systems fail in non-obvious ways. They act on incomplete context, misinterpret intent, and do it confidently. For routine tasks, that's fine. For knowledge work, where nuance is everything, it's not.

My omfg-moment

Here's what I actually needed: a sufficiently smart LLM and a well-designed filing system.

That's it. Two things.

Any capable LLM today can read files, write files, create folders, and follow instructions. That's table stakes. The model isn't the hard part.

The filing system is where everything happens. And here's what makes it different from a simple folder of notes: the rules of the system live inside the system itself. Every folder contains a plain text file explaining what it is, what belongs there, and how it connects to everything else. The model reads those files as it navigates. It doesn't need to be configured separately or re-briefed every session, the filing system does the briefing.

The result is a context layer that is persistent, cumulative, and self-enforcing. Not because the model is constrained by it, but because the filing system makes the model capable.

And because the model can write to the system, every session makes it smarter. Notes get filed. Ideas get cross-referenced. Reminders get set. The system improves itself, one conversation at a time.

One rule for every folder

One main folder. Everything organized in subfolders. And one rule, applied without exception:

Every folder - including every subfolder - contains an _instructions.md file that explains what the folder is and why it exists.

That's it. No database. No proprietary format. No app to maintain.

The top-level _instructions.md is the most important file in the system. It explains the whole architecture, describes what lives where, and contains context that is always relevant. It's the briefing document your personal assistant reads before walking into the room.

Everything else follows naturally. A work/ folder with its own instructions. A knowledge_base/ with subfolders for ideas, research, and learning — each self-documenting. A reminders.md at the root that gets surfaced at the start of every session.

Claude/
├── _instructions.md        ← always read first; explains the whole system
├── reminders.md
├── work/
│   ├── _instructions.md
│   ├── deals/
│   │   └── _instructions.md
│   └── notes/
│       └── _instructions.md
└── knowledge_base/
    ├── _instructions.md
    ├── ideas/
    │   └── _instructions.md
    └── research/
        └── _instructions.md

The model reads the instruction files as it navigates. It knows what each folder is for. It knows where to file things. It knows what context is relevant to what conversation. Because you told it — once, in plain text, in the folder itself.

Good preparation takes too long

Here's the insight that reframed everything for me.

I used to think that if I could just move faster through my task list, I'd be ahead. But that's not where time goes. Time goes into preparation. Into gathering enough context to actually do a task or make a decision well.

Before writing an email to an important contact, I'd spend twenty minutes finding the thread, remembering what was said, recalling the strategic context, and reminding myself what I was trying to achieve. The email itself took five minutes.

Now I don't do that preparation. The system does it. Everything relevant is already in the knowledge base, cross-referenced, surfaced on request. I have a personal archivist and librarian for semantic information, fully transparent by default since I can read all the files. Cherry on top: it can live locally or in your preferred cloud and you're not tied to any one backend.

Better orientation is the real unlock.

A better foundation for agents

Autonomous AI agents are getting impressive — but they still fail the same way: not enough of the right context to make good decisions. This filing system solves that problem. Not just for me interacting with a model, but eventually for agents I connect to it. When an agent needs to prioritize an email or figure out what a meeting is worth, it has the deal history, the relationship notes, the strategic priorities — all structured, searchable, and current.

The context layer I'm building now is what will make agentic systems actually useful later.

Stop looking for the right app

There probably isn't one.

What you actually need is a filing system you'll stick to, a format any tool can read, and a model capable enough to make it intelligent. Markdown checks the second box by default. The models are there. The filing system is the only thing you have to design — and it only needs to be coherent, not clever.

The intelligence emerges over time through the structure you create and the language you use to describe it.

Plain text has been here the whole time. But now it has a reader worthy of it.

I built this system on top of Claude with filesystem access to iCloud Drive. Happy to share more detail on the folder structure and instruction file convention.

Originally published on X