1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132 | # Obsidian Second Brain — Set Up + Wire AI Into It
A guide to building a personal knowledge vault you own forever, on your own disk, in plain markdown — and then pointing an AI agent at it so it can read, write, and help you think.
No emojis. No hype. Just the setup.
---
## 1. Why Obsidian
[Obsidian](https://obsidian.md) stores your notes as local `.md` (markdown) files on your own computer. Not a database. Not a proprietary format. Not locked inside someone else's server.
That matters for three reasons:
- **You own it forever.** If Obsidian the company disappeared tomorrow, your notes are still plain text files sitting in a folder. Open them in any text editor, forever.
- **No lock-in.** Move the folder to a new machine, a new note app, a new AI tool — it's just files. Nothing to "export."
- **AI-readable by design.** Plain markdown is exactly the format large language models read and write best. An AI agent can `grep` your vault, read a note, edit a note, and create a new one, with zero special integration — because it's just files on disk.
This guide walks through: installing Obsidian, structuring your vault so it stays useful as it grows, syncing it across your devices honestly (including the tradeoffs), capturing content from the web, and — the part most guides skip — wiring an AI coding agent directly into your vault so it becomes a second brain that can actually write back to itself.
---
## 2. Install
Obsidian is free for personal use, available on desktop and mobile.
**Mac**
```bash
brew install --cask obsidian
```
Or download directly from [obsidian.md/download](https://obsidian.md/download).
**Windows**
Download the installer from [obsidian.md/download](https://obsidian.md/download).
**iOS / Android**
Search "Obsidian" in the [App Store](https://apps.apple.com/app/obsidian-connected-notes/id1557175442) or [Google Play](https://play.google.com/store/apps/details?id=md.obsidian). The mobile apps read and write the exact same vault folder — no separate mobile-only format.
On first launch, choose "Create new vault" and pick (or create) a folder. That folder is your vault. Everything below assumes you've done this.
---
## 3. Vault structure that works
The single biggest mistake people make with Obsidian is over-organizing early — deep folder trees, elaborate tagging systems, a taxonomy built before there's anything to organize. Two problems with that: it doesn't survive contact with real use, and it makes the vault harder for an AI agent to search (more folders to traverse, more ambiguity about where something belongs).
A flat-ish, numbered-folder layout scales better. It's an adaptation of the [PARA method](https://fortelabs.com/blog/para/) (Projects / Areas / Resources / Archive), created by Tiago Forte:
```
00-inbox/ unsorted capture — anything goes here first
01-projects/ active, time-bound efforts with a defined outcome
02-areas/ ongoing responsibilities with no end date (health, finances, a role)
03-resources/ reference material and topics of interest, not tied to a project
07-archive/ anything from projects/areas that's done or inactive
```
Why the number gaps (00, 01, 02, 03, then jumping to 07)? Room to insert categories later — `04-people`, `05-meetings`, `06-daily` — without renumbering everything that follows.
**Daily notes**: turn on Obsidian's built-in Daily Notes core plugin (Settings → Core plugins → Daily notes) and let it create one dated note per day, e.g. `06-daily/2026-07-15.md`. This becomes your default capture point — a running log you link out from into projects and areas, rather than trying to decide the "right" permanent home for every thought the moment you have it.
**Why flat-ish beats deep nesting — especially for AI retrieval:**
- A five-levels-deep folder (`03-resources/tech/ai/llms/prompting/notes.md`) means an AI agent has to explore or guess a path before it can even read the file. A flatter structure with descriptive filenames and links between notes is faster to search and easier to reason about — for you and for the agent.
- Obsidian's real organizing power is **links between notes**, not folders. A note can live in `03-resources/` and still be tightly connected to a project in `01-projects/` via a `[[wikilink]]`. Let links carry the relationships; let folders just carry the broad category.
- Grep-based tools (including AI agents reading your vault as files) work by scanning filenames and content — a shallow tree with clear names is far faster and more accurate to search than a deep, cleverly-nested one.
---
## 4. Sync options, honestly compared
There is no free lunch here. Pick based on your actual constraints, not marketing copy.
| Option | Cost | Encryption | Multi-device | Honest tradeoff |
|---|---|---|---|---|
| [Obsidian Sync](https://obsidian.md/sync) | Paid (official add-on) | End-to-end encrypted | Easiest — official, built-in, handles conflicts well | The one you pay for so you stop thinking about it. Worth it once you're relying on the vault daily across 2+ devices. |
| iCloud Drive | Free (with Apple ID) | Apple's standard cloud encryption, not E2E by Obsidian | Apple devices only | Fine for light use. Under heavy simultaneous editing (e.g. phone and laptop both open, both writing) iCloud's sync is known to produce conflicted duplicate files that need manual merging. Not Windows/Android compatible at all. |
| Git (e.g. [git-scm.com](https://git-scm.com/), hosted on [GitHub](https://github.com)) | Free | Whatever your remote provides (private repo = provider's encryption at rest) | Any device with git installed | Full version history, diffable, scriptable, and — bonus — the same tool an AI coding agent already knows how to use. But it's manual (commit/push/pull) or needs a wrapper plugin (e.g. Obsidian Git community plugin), and merge conflicts on binary attachments are painful. Technical users only. |
Rule of thumb: single device, don't overthink it — no sync needed. Two Apple devices, light use — iCloud is fine. Multiple platforms or heavy daily use across devices — pay for Obsidian Sync. Already living in git and want full history plus AI-agent compatibility — git.
---
## 5. Web Clipper
The official [Obsidian Web Clipper](https://obsidian.md/clipper) is a browser extension (Chrome, Firefox, Safari) that saves articles, pages, and highlights directly into your vault as markdown notes — with the source URL, a template you control, and no manual copy-paste-reformat step. Install it from the extension store for your browser, point it at your vault, and it lands new clips straight into `00-inbox/` for you to file later.
---
## 6. Wire AI into the vault
This is the part that turns a note-taking app into an actual second brain: an AI agent that can read your notes, understand the structure, and write back into it.
**Point the agent at the vault directory.** If you use [Claude Code](https://claude.ai/code), the pattern is simple — `cd` into the vault and start a session:
```bash
cd ~/path/to/your-vault
claude
```
From inside the vault directory, the agent can read any note, follow links, search across the whole vault, and create or edit notes — because it's all just files. No plugin, no API, no export step.
**What a `CLAUDE.md` at the vault root should say.** Drop a `CLAUDE.md` file in the root of your vault to give the agent standing instructions every time it opens there. At minimum, cover:
- **Where new notes go** — e.g. "unsorted capture goes in `00-inbox/`, never invent a new top-level folder without asking."
- **Naming conventions** — e.g. "daily notes are `YYYY-MM-DD.md`; project notes are lowercase-kebab-case; no spaces in filenames."
- **Linking style** — e.g. "use `[[wikilinks]]` to connect related notes rather than duplicating content."
- **What not to touch** — e.g. "never delete a note, only archive it to `07-archive/`."
This is the same idea as a README for a codebase — a short, explicit contract so the agent behaves consistently instead of guessing.
**Pattern: session digests auto-archived into the vault.** A useful habit once the agent is wired in: at the end of a working session, have it write a short digest note (what was decided, what changed, open threads) into a `sessions/` or dated daily note. Over time this becomes a searchable log of your own thinking and decisions — the second brain accumulating itself.
**Advanced step: embeddings/RAG over the vault.** Once a vault gets large (thousands of notes), plain grep-and-read starts to miss things that are related in meaning but don't share keywords. The next step up is embedding every note into a vector index and doing retrieval-augmented search (RAG) over it. For a fully local, free setup, [nomic-embed-text](https://ollama.com/library/nomic-embed-text) running through [Ollama](https://ollama.com) is a solid choice — it's a free, local embedding model, so your notes never leave your machine to generate the embeddings. This is an optional, later-stage upgrade — most vaults are well served by plain file search for a long time before RAG is worth the setup complexity.
---
## 7. Safety
The vault is your data. Treat it like it.
- **Keep it out of public repos.** If you version your vault with git (see section 4) and ever push it anywhere, make sure the remote is private. Never commit a personal vault to a public GitHub repo.
- **Gitignore it in other projects.** If your vault folder happens to sit inside or near a coding project directory, add it to that project's `.gitignore` so it never gets swept into a commit by accident.
- **Back it up.** Whatever sync option you choose (or don't), keep a separate backup — a local Time Machine snapshot, an external drive copy, or a private git remote. Sync is not a backup; if you delete a note and it syncs everywhere, it's gone everywhere too unless you have real version history or a backup snapshot to fall back on.
---
## Summary
1. Install Obsidian, create a vault.
2. Structure it PARA-style, numbered and flat-ish: `00-inbox`, `01-projects`, `02-areas`, `03-resources`, `07-archive`, plus daily notes.
3. Pick a sync option that matches your actual usage, not the fanciest one.
4. Install the Web Clipper for frictionless capture.
5. Point an AI agent at the vault directory, write a `CLAUDE.md` contract, and let it start reading, writing, and (eventually) digesting sessions back into the vault.
6. Keep it private, gitignored where it needs to be, and backed up.
Local files. Your ownership. AI-readable from day one.
|