The Notes Setup That Actually Works with AI

I was a Microsoft OneNote user for a long time. More than ten years. I could not even begin to count how many notes I had built up in that time — meeting notes, project research, code snippets, random ideas. A decade of thinking, captured in a proprietary format on Microsoft's servers.

As a developer, I knew there was a principle about managing data well: keep content and configuration in the same file. Keep it portable. Don't let your tools hold your data hostage. I knew this principle. I applied it in code. And then I ignored it completely for my own notes, for over a decade.

I eventually made the switch — to Markdown files, and specifically to Obsidian. What surprised me was the timing. I moved before the current AI wave hit. I wasn't chasing a trend. I was just finally acting on something I already believed.

What I didn't anticipate was how right the decision would turn out to be, and for reasons that had nothing to do with personal productivity and everything to do with how AI agents actually work.

---

The cloud productivity era made a bet that didn't pay off

Notion, Confluence, Evernote, Roam — the story of the last decade in knowledge management was about abstracting away the file system. Your notes lived in a database. You got a beautiful interface, collaboration features, and the feeling of being organized. What you gave up was ownership.

Try exporting a Notion workspace. You get a ZIP file full of HTML with embedded metadata. Try searching it with grep. Try giving an AI agent access to it without going through Notion's API. Try owning it in any meaningful sense when Notion changes its pricing.

Obsidian went the other direction. Your notes are files, in a folder, on your machine. The application is a lens, not a container. Open any note in vim, in VS Code, in any text editor that's ever existed. Grep across your entire vault in milliseconds. Pipe notes through scripts. Sync them however you want — iCloud, Syncthing, git, a USB drive. The data is yours.

This turns out to matter enormously when you want an AI agent to work with your knowledge.

---

Why Markdown is AI-native

Markdown is not just human-readable. It sits in a specific sweet spot: structured enough for machines, flexible enough for humans. Here I get to geek out a bit, but hang with me. If you do not understand all the jargon, the underlying logic is straightforward. The principles still stand. Every property that makes Markdown good for people also makes it good for AI:

Plaintext means any tool can read it. No parsing libraries, no API calls, no format negotiation. A language model can read a Markdown file the same way you do.

YAML frontmatter means machine-readable metadata lives in the same file as the content. Tags, relationships, dates, custom properties — they travel with the note. No separate database, no sync issues, no "the metadata is here but the content is somewhere else" problem. This is the golden rule I mentioned earlier: data and metadata in the same file. Markdown with frontmatter is exactly that.

Wikilinks are explicit, named relationships between documents. Not just hyperlinks — semantic connections. [[Parent Note]], [[Related Concept]]. A knowledge graph can traverse these. An AI agent can follow them. They're more than navigation; they're declared structure.

Headers as structure give AI systems natural chunking boundaries. When you build a RAG pipeline over your notes, the ## sections become coherent retrieval units. The document structure you wrote for yourself becomes the document structure the AI uses to find what's relevant.

Compare this to a Notion export (HTML soup), a Confluence page (proprietary JSON), or a Word document (XML zip file). When you want an AI agent to reason over your accumulated knowledge, Markdown wins on every dimension.

---

The ecosystem is unusually deep

Obsidian has around 1,500 community plugins. The number is less interesting than what those plugins expose.

What's notable is how deeply plugins can reach into Obsidian. A plugin isn't limited to changing the look of the app or adding a button to the toolbar. It can read and traverse all your notes and the connections between them, access and modify the metadata attached to any note, create custom links that other applications can respond to, and read and write files directly on your computer. Most applications give developers a narrow window to work with. Obsidian gives them the keys to the building. The result is that the plugin ecosystem treats Obsidian like a platform you build on, not an application you use.

And because everything is files, these plugins compose. A plugin that writes to frontmatter works with a plugin that reads frontmatter. A plugin that adds links works with a plugin that traverses links. Nothing is siloed in its own database. The file is the contract between components.

---

Local-first is the AI privacy play

When you feed your notes to an AI, you're feeding it your actual thinking. Not your polished output — your actual thinking. Uncertainties, half-formed ideas, personal projects, things you know about your employer, opinions you haven't published.

Local-first means you control what goes where. Your notes don't train OpenAI's next model by default. You can run local models against your full vault with zero data leaving your machine. An AI agent running locally has file system access without a round-trip through the cloud. You can choose, per model and per task, what context to provide.

This isn't paranoia. It's the same operational security principle that applies to any sensitive data. You make conscious decisions about what leaves your control, rather than having that decision made for you by a terms of service update.

---

The agent interface pattern

Something subtle has been happening in how AI agents structure their relationship with human context, and it's worth paying attention to.

Claude Code stores its persistent instructions in CLAUDE.md. It stores memory about the user in memory/*.md files. Reusable agent behaviors are defined in .claude/skills/*.md. None of this is a database, an API, or a proprietary format. It's all Markdown files.

This isn't arbitrary. Markdown is the right medium for this interface because it's readable by both the human and the AI, it can contain structured data alongside prose, it can be version-controlled, and it requires no infrastructure to read or write.

Your Obsidian vault is already structured this way — or can be. Notes with frontmatter properties, wikilinks declaring relationships, tags encoding categories. If you layer the right tooling on top (MCP servers, vector search, RAG), your entire knowledge base becomes queryable by any AI agent you work with. The vault becomes the context window.

---

But there is a gap

What Obsidian doesn't solve natively: reaching outside the vault.

The vault knows about your notes. It doesn't know about your project directories, your code repositories, your Downloads folder, your PDF library. Every tool that isn't a Markdown file inside the vault is invisible to it. Each time you want to connect a note to a project directory, you're solving that coordination problem manually.

This is the limitation that led me to build FolderTether — but that's the subject of the next post.

---

Supplemental: How to Organize Your Notes

This section is for readers who are new to Obsidian or want to understand the organizational approach that underpins the system described above. It's a practical starting point, not a requirement for the main post. Just a bonus!

---

The single most important shift in using Obsidian well is giving up on folders as your primary organizational tool.

Folders are how most of us learned to organize files. They feel intuitive. But in a knowledge system, they create problems: a note can only live in one folder, folders don't appear in the graph view, and a folder hierarchy becomes a decision you have to make upfront and then live with.

Obsidian gives you better tools: tags, links, and properties.

The Golden Rule

Store your data and its metadata in the same file. Use YAML frontmatter at the top of every note to capture structured information — tags, dates, relationships, source references. This is what makes your notes queryable by both you and any AI tool you use.

---
tags:
  - knowledge/ai/rag
  - goal/project/my-project
created: 2026-03-13
up: "[[Parent Note]]"
source: "[[Reference Material]]"
---

Tags over folders

Tags are more flexible than folders because a note can have multiple tags. Use hierarchical tags for structure — knowledge/ai/rag is more precise than knowledge and more flexible than a nested folder structure.

Put tags in frontmatter rather than inline in the text. This keeps your note body clean and makes tags easier to query.

Links as declared relationships

Wikilinks ([[Note Name]]) are Obsidian's most powerful feature. Use them intentionally:

• Named links in properties for strong, explicit relationships: up: "[[Parent Note]]", source: "[[Reference]]"
• Inline wikilinks for contextual connections in the body of a note
• Obsidian tracks all links and updates them automatically when notes are renamed — no broken references

The graph view becomes useful when you have real links connecting real notes. It's a map of your thinking, not just a visualization of your folder structure.

Properties for structure

Properties (frontmatter fields) let you treat your vault like a lightweight database. Beyond tags, consider:

• up — the primary upstream relationship (what this note belongs to)
• sibling — lateral relationships at the same level
• source — where the information came from
• archive: true — mark notes as inactive without deleting them

A note on PARA

PARA (Projects, Areas, Resources, Archives) is a popular organizational framework you may encounter in Obsidian content. It maps well to tags: goal/project/..., area/..., knowledge/.... Use it if it fits how you think. The key is that PARA works better as a tagging system than as a folder hierarchy.

---

The video that shaped this approach: https://www.youtube.com/watch?v=B0yAy2j-9V0