The gist
Every session with Claude starts from scratch: unless memory or a rules file is turned on, it remembers nothing about you. You spend time explaining, and it spends tokens figuring out the context. Obsidian solves this: you build a knowledge base in markdown files, Claude reads it directly and gets to work with the context already in place.
Key concepts
- Local-first: files live on your computer, not in the cloud; your data stays under your control
- Markdown = the language of AI: Claude reads
.mddirectly, no conversion needed - Link graph: connections between notes through
[[Title]]form a neural network of knowledge - Hot Cache pattern: frequently needed data in a separate folder, so Claude loads only that
- MCP filesystem: the bridge between Claude Code and your vault
- Smart Connections: semantic search across the whole vault, not just by keywords
- Daily Note: a developer's daily log with tasks, decisions and the cost of AI sessions
Theory
Why you need a "second brain" at all
Here's a typical situation: three weeks ago you researched the real estate market in Ecuador. You wrote a report and remembered the details. Today a client asks a related question. You start explaining the context to Claude, spending 15 minutes and 2,000 tokens on something you've already researched.
With a knowledge base in Obsidian: you open Claude, give it the path to the note through MCP, and ask your question. Claude already has the context. 30 seconds instead of 15 minutes.
This multiplies across the number of projects, the number of clients, the months of work. A knowledge base is an asset that grows in value over time.
Why Obsidian and not Notion or Google Docs
Three reasons Obsidian wins for an AI builder:
Reason 1: Local-first
Your files live on your computer, in a folder on disk. No subscription that could get shut down (Obsidian itself is free, including for work). No API that could go down. No questions about who owns the data. MCP filesystem reads these files directly: no exports, no conversions, no OAuth.
Notion stores data on Notion's servers. For Claude to read a note from Notion, you need a connection (a connector or an MCP server) with authorization. Those are extra steps, and if the service is down, you're cut off from your data. More on Notion: Notion AI as a team knowledge base.
Reason 2: Markdown = AI's native language
Every .md file is just text with simple markup. Claude reads it like plain text. No parsing, no lost formatting, no encoding problems.
When an agent writes research results straight into an Obsidian note, it writes markdown. When Claude reads that note through MCP, it reads the same markdown. One format everywhere.
Reason 3: The knowledge graph
In Obsidian, notes connect through links: [[Cuenca market]], [[Client — Smith]], [[Project — Downtown Apartments]]. Obsidian builds a visual graph of these connections. You can see how concepts relate to each other, like a neural network.
A folder structure for an AI builder
We use the PARA system (Projects, Areas, Resources, Archive), a proven structure that scales:
vault/
├── 00-hot-cache/ ← the most needed files (Claude loads these first)
├── 01-inbox/ ← raw ideas, unprocessed voice memos, quick notes
├── 02-projects/ ← active projects (one folder = one project)
│ ├── acme-realty/
│ │ ├── CLIENT-BRIEF.md
│ │ ├── market-research.md
│ │ └── meeting-notes/
│ └── academy-course/
├── 03-areas/ ← ongoing areas of life and business
│ ├── finances.md
│ ├── health.md
│ └── ai-stack.md ← which tools you use, API keys (not the keys themselves)
├── 04-resources/ ← reference material, research, terms
│ ├── ecuador-real-estate/
│ ├── ai-tools/
│ └── code-snippets/
├── 05-archive/ ← finished projects, things no longer relevant
└── templates/ ← note templates
├── daily-note.md
├── project.md
├── meeting.md
└── research.mdWhy this folder order?
The number at the start of the name sets the sort order. 00-hot-cache is always at the top. It's the folder Claude reads first. Put in it whatever you need in almost every session: the current context of your projects, key decisions, active tasks.
The Hot Cache pattern: saving tokens
This is one of the most practical patterns for working with Claude.
The problem: a vault grows over time. 300 notes, 500, 1,000. If you hand Claude the whole vault, that's thousands of tokens spent on navigating and reading things it doesn't need. Expensive and slow.
The fix: a 00-hot-cache/ folder with the files you need in 90% of sessions.
What to keep there:
00-hot-cache/
├── CONTEXT.md ← who you are, which projects are active, current status
├── active-projects.md ← 3-5 active projects in one file
├── decisions-log.md ← the last 10 key decisions
├── ai-costs-this-month.md ← how much you've spent on AI, your limit
└── weekly-goals.md ← this week's goalsThe instruction for Claude in your project's CLAUDE.md:
## My Obsidian vault Path: ~/vault/ At the start of a session, read these first: - ~/vault/00-hot-cache/CONTEXT.md - ~/vault/00-hot-cache/active-projects.md These two files give you 80% of the context you need. Ask for anything else as needed.
The savings: instead of loading the whole vault (thousands of tokens), two files (300-500 tokens). That's a 90% saving on context tokens.
Plugins for an AI builder
Obsidian supports plugins through its built-in marketplace (Settings → Community Plugins). A list for our use case:
Smart Connections: semantic search across your vault (check in the plugin directory that the plugin is maintained and compatible with your Obsidian version)
Regular search looks for keywords. Smart Connections understands meaning. Ask "what do I know about competitors?" and it finds every related note, even if the word "competitors" doesn't appear in them.
On top of that, you can ask questions about your notes right inside Obsidian through a built-in AI chat. Smart Connections plugs into Obsidian and answers questions using your files as context. That's RAG (Retrieval-Augmented Generation) right in the interface, with no setup.
Copilot: Claude or GPT right inside Obsidian
A community plugin (not to be confused with GitHub Copilot) that adds a side panel with an AI chat. You can ask a question using the current note as context. Handy when you're working in Obsidian and want to quickly expand or rewrite a note with AI without switching to Claude Code.
QuickAdd: add notes from a template, fast
Press a hotkey, pick a template (meeting/idea/research), fill in two fields, and the note is created in the right folder with the right structure. Without QuickAdd, every time you have to think about where to put the note and what to call it.
Dataview: SQL-like queries over your notes
It's a full database on top of markdown files. If you add metadata (frontmatter) to your notes, Dataview can query it:
```dataview TABLE cost_usd, agent, status FROM "02-projects/acme-realty" WHERE status = "complete" SORT cost_usd DESC ```
The result: a table of all completed AI tasks for the project with their cost. Right inside an Obsidian note.
A note as of October 2026: Obsidian has a built-in core plugin called Bases that does similar table views by note properties through the interface, no code needed. For simple tables, start with that. Dataview is still useful for complex logic, but it hasn't had a release in a long time, so don't build anything critical on it.
Templater: dynamic templates
Templater makes templates with logic. For example, a daily note template automatically inserts today's date, the day of the week, and a link to yesterday's note. No need to fill it in by hand every time.
---
date: <% tp.date.now("YYYY-MM-DD") %>
week: <% tp.date.now("WW") %>
---
# <% tp.date.now("dddd, DD MMMM YYYY") %>
## Today's tasks
- [ ]
## AI sessions today
| Task | Agent | Cost |
|--------|-------|-----------|
| | | |
## Decisions and notes
## Ideas for the inbox
[[<% tp.date.now("YYYY-MM-DD", -1) %>]] ← yesterdayCalendar: navigating your log
Adds a calendar to the side panel. Click a date to open that day's daily note. An easy way to find what you were doing a week ago.
Claude + Obsidian: practical patterns
Pattern 1: Asking your own knowledge base
The simplest pattern. You start Claude Code in your vault folder (or add it with the /add-dir command); for a chat app with no file access, you connect the filesystem MCP. Tell Claude where the vault is and ask your question:
Read my notes in /vault/04-resources/ecuador-real-estate/ and answer: what do I know about the typical mistakes buyers make in Cuenca?
Claude reads every file in the folder and builds an answer from your own notes. Not the internet, not general knowledge: your own observations from your own knowledge base.
Pattern 2: An agent writes to the vault
A research agent gets a task → does it → writes the result straight into the vault:
## Task for the agent Research current rental prices in Cuenca. Save the result to /vault/04-resources/ecuador-real-estate/rent-prices-2026-10.md Use the template at /vault/templates/research.md
The next time you need this analysis, it's already in the vault. The agent reads it instead of redoing the work.
Pattern 3: Voice → Note
A workflow for ideas that come to you on the go:
Record a voice memo on your phone →
Whisper (or a dictation app such as Superwhisper, MacWhisper or Wispr Flow) → transcribes it into text →
The text lands in /vault/01-inbox/ →
Claude processes the inbox and files the notes into foldersThis solves the "brilliant idea in the shower, forgot it by the time I got to my computer" problem.
Pattern 4: An automatic note after a meeting
## Instructions for Claude after a client meeting
The user gives you a transcript or notes.
You create a file meeting-{date}.md in /vault/02-projects/{project}/
Structure: attendees, key decisions, next steps, deadlines.
Link it with [[]] to existing notes for the project.MCP for working with an Obsidian vault
An important clarification first: Claude Code already reads and writes files in the folder where it's launched, and you can add extra folders with the /add-dir command or the --add-dir flag. So for Claude Code, the simplest route is to open a terminal in your vault folder and run claude. MCP is needed where the assistant has no direct file access (in a chat app, for example) or when you need capabilities that plain file operations don't have.
There are two ways to connect through MCP.
Option 1: Filesystem MCP (official)
Gives Claude read and write access to the vault folder through MCP.
# Add the filesystem MCP for the vault
claude mcp add filesystem -- \
npx -y @modelcontextprotocol/server-filesystem \
~/vault
# Check that it was added
claude mcp listOnce connected, Claude can read and write files in the vault directly. Replace ~/vault with the real path to your vault.
Option 2: Obsidian MCP (community, extended)
Adds extra capabilities: searching the vault, managing tags, the link graph. There are several of these servers and plugins (for example, plugins that run an MCP server right inside Obsidian). The command to connect depends on the project you pick; see its README for the format. Before installing, check that the project is maintained and doesn't ask for suspicious permissions: an MCP server gets access to your notes.
This kind of MCP understands Obsidian's structure: frontmatter, [[]] wiki links, # tags. Filesystem MCP just sees text files.
Which to choose:
| Filesystem MCP | Obsidian MCP | |
|---|---|---|
| Setup | Easier | Harder |
| Reliability | Official | Community |
| Search | By file contents | Depends on the server you pick |
| Understands structure | No | Yes (tags, links) |
| Writes files | Yes | Yes |
Start with the simplest option: Claude Code in your vault folder, and the filesystem MCP if you need it. It's official and works right away.
Daily Note: an AI builder's log
A daily note is a note you create every day. It's not a feelings journal, it's an operations log.
What to record:
---
date: 2026-10-09
week: 41
---
# Friday, October 09, 2026
## Tasks
- [x] Write a lesson for the Academy
- [ ] Connect the filesystem MCP to the vault
- [ ] Code review for client X
## AI sessions
| Task | Agent | Model | Cost |
|--------|-------|--------|-----------|
| Lesson for the Academy | writer | Sonnet | $0.12 |
| Market research | researcher | Sonnet | $0.08 |
**Total today: $0.20**
## Decisions
- Picked filesystem MCP over Obsidian MCP: official, simpler
- Standard PARA structure for the vault
## Ideas
- Could automate creating the daily note with a session-start hook
## Blockers
- Need to test Superwhisper on M1 for voice → text
[[2026-10-08]] ← yesterday | tomorrow → [[2026-10-10]]The links to the past and future at the bottom are for navigating in the Calendar plugin.
Why record the cost of AI sessions:
A month from now you'll look at the numbers and see how much researcher costs per month and how much writer costs (the amounts in the tables above are made up, for the example). Where the money really goes shows up in the data, not in your gut feeling. That lets you optimize your budget.
A PROJECT note template
Every project in 02-projects/ starts with this file:
--- project: Acme Realty status: active client: internal started: 2026-10-01 tags: [real-estate, ecuador, content] --- # Project: Acme Realty ## What it is A content project about real estate in Ecuador for an English-speaking audience. ## Current status Phase 1: building the content strategy. ## Key decisions - [[2026-10-07]] Picked an email newsletter as the main channel - [[2026-10-08]] Defined the brand voice: an observer, not an expert ## Active tasks - [ ] Write 5 launch posts - [ ] Set up Obsidian MCP for automatic reports ## Related notes - [[Cuenca real estate market]] - [[Audience — Americans in Latin America]] - [[Competitors — real estate newsletters]] ## AI session history | Date | Task | Cost | |------|--------|-----------| | 2026-10-08 | Market research | $0.08 | | 2026-10-09 | Content plan | $0.05 |
Dataview can query by status: active and show all active projects on one page.
Practice
Step 1: Install Obsidian and create a vault
# Download Obsidian: obsidian.md (free, including for work)
# Install with brew:
brew install --cask obsidianLaunch it and create a new vault somewhere convenient (for example, ~/vault or ~/Documents/vault). Not in iCloud if you don't want syncing: the files will be in Git anyway.
Step 2: Create the folder structure
# Replace ~/vault with the real path to your vault
VAULT=~/vault
mkdir -p $VAULT/00-hot-cache
mkdir -p $VAULT/01-inbox
mkdir -p $VAULT/02-projects
mkdir -p $VAULT/03-areas
mkdir -p $VAULT/04-resources
mkdir -p $VAULT/05-archive
mkdir -p $VAULT/templatesStep 3: Create your first CONTEXT.md in the hot cache
cat > $VAULT/00-hot-cache/CONTEXT.md << 'EOF'
# Context: who I am and what I'm working on
## About me
AI builder, creating automations with Claude Code.
Active projects: [list them]
## Active projects
- **Project 1**: [short description, current status]
- **Project 2**: [short description, current status]
## My AI stack
- Claude Code (I pick the model for the task)
- Obsidian vault for knowledge
- Ollama for local models (private data)
## Current goals (this week)
- [ ] Connect the filesystem MCP
- [ ] Set up the daily note template
EOFStep 4: Connect the filesystem MCP to Claude Code
# Add the MCP (replace the path with your real one)
claude mcp add filesystem -- \
npx -y @modelcontextprotocol/server-filesystem \
~/vault
# Check it
claude mcp listThen, in a new Claude Code session, type:
Read the file ~/vault/00-hot-cache/CONTEXT.md and tell me what you learned about my current context
Claude should read the file and answer based on what's in it.
Step 5: Install plugins
In Obsidian: Settings (Ctrl+, or Cmd+, on Mac) → Community Plugins → Turn on → Browse.
Install them in this order:
- Templater: templates with logic
- Calendar: navigating daily notes
- Dataview: queries over your notes
- QuickAdd: quick note capture
- Smart Connections: semantic search (optional; see the plugin's documentation for model settings)
For simple tables over your notes, try the built-in Bases first (Settings → Core plugins).
Step 6: Set up the daily note template
Create a file templates/daily-note.md with the basic structure from the theory section. In the Daily Notes settings (Settings → Core Plugins → Daily Notes), set the folder for daily notes and the template.
With Templater, build a more advanced version with an automatic date and links to the neighboring days.
Step 7: First real use
Take any task you're currently doing for a client or project. Create a note from the project template. Connect Claude through MCP and ask a question about what's in the note.
Make sure it works: Claude reads the file and answers using your own data.
Tools and resources
- obsidian.md: download Obsidian (free, including for work)
- Obsidian Community Plugins: the directory of all plugins
- Smart Connections: semantic search
- Templater: the plugin's documentation
- Dataview: full query documentation
- @modelcontextprotocol/server-filesystem: the official filesystem MCP
- Obsidian MCP: look for community servers and plugins in the Obsidian plugin directory and in MCP directories; pick projects that are maintained
- Superwhisper: voice → text on Mac (for the voice → inbox pattern); similar tools are in the Academy's directory: Tools
- PARA Method: the original methodology behind the vault structure
Key takeaways
TL;DR: Obsidian + filesystem MCP = long-term memory for Claude. You build the knowledge base once, and it works for you in every future session.
The Hot Cache pattern: 2 files in
00-hot-cache/cover 80% of your context needs with a minimum of tokens.
Local-first wins: markdown files on disk that Claude Code reads directly, with no API and no OAuth.
Daily Note = an operations log: tasks + AI sessions + decisions. A month in, you'll see patterns in your work that would otherwise stay invisible.
Start minimal: a vault + the filesystem MCP + one CONTEXT.md. Add complexity when you feel you need it.
What's next
→ Notion AI as a team knowledge base: when the knowledge needs to serve not just you but your team
The mark stays in this browser only and is never sent anywhere. My progress