/Brain
Navigation

Obsidian as the Foundation

A /Brain needs a home. Obsidian turns a folder of markdown files into a living knowledge graph — synced, searchable, and readable by both humans and AI agents.

Why Obsidian

A /Brain is a folder of markdown files. You can edit them in anything. But if you want the system to actually work — to compound, to stay alive across devices, to surface connections you didn't plan — you need more than a text editor.

Obsidian does three things that matter:

  1. Local-first storage. Your files live on your machine, not in someone else's cloud. You own them. You can read them, back them up, move them, hand them to an AI agent.
  2. A graph that mirrors your thinking. Wiki-links between notes create a structure that reflects how ideas actually connect — not how a folder hierarchy forces them to connect.
  3. An editing environment that stays out of the way. Markdown in, markdown out. No proprietary format, no lock-in, no conversion needed.

The vault is not a note-taking app. It is the filesystem layer of your personal operating system.

The vault as single source of truth

The most important rule: one vault, one truth.

Everything that matters lives in the vault. Your identity files, your current context, your durable memory, your frameworks, your decisions, your raw captures. If it is not in the vault, it does not exist for your system.

This sounds obvious until you watch people scatter their context across Notion, Google Docs, Apple Notes, random markdown files on the desktop, and three different chat threads. Then they wonder why every AI session starts from zero.

One vault. Everything in it. That is the deal.

What goes in

  • me/WORKING_WITH_ME.md — how you think, decide, and want to be worked with
  • context/now.md — what matters right now
  • MEMORY.md — durable truths that survive beyond this week
  • frameworks/ — mental models you reuse
  • decisions/ — what you decided and why
  • _inbox/ — raw captures before they are sorted
  • essays/, projects/, research/ — deeper work

What stays out

  • Credentials and API keys (use .env files or a secrets manager)
  • Large binary files (images are fine; datasets are not)
  • Anything you would not want synced to another device

Syncing between machines

A /Brain only works if it is where you are. If you use two machines — a laptop for deep work and a home server for your AI agent — the vault needs to exist on both, and stay in sync.

Obsidian Sync

Obsidian Sync is end-to-end encrypted and handles conflicts well. It syncs the vault contents and Obsidian settings across devices automatically.

The practical setup:

  1. Install Obsidian on both machines
  2. Open the same vault on each
  3. Enable Obsidian Sync and connect both to the same remote vault
  4. Set sync to include all file types (markdown, attachments, settings)

Within seconds of saving a file on one machine, it appears on the other. No git commits, no manual push/pull, no merge conflicts.

Why not git?

Git works for code. It is clumsy for a personal knowledge system. It requires manual commits and pushes, merge conflicts in prose files are painful, it adds friction to a system that needs to be frictionless, and vault settings (.obsidian/) conflict constantly between machines.

Git is excellent for backing up a vault snapshot. It is not the right sync mechanism for daily use.

Why not iCloud / Dropbox / Google Drive?

Cloud sync services work until they don't. File conflicts are silent and destructive, sync delays can lose recent edits, .obsidian/ settings cause constant churn, and you are trusting a third party with your entire knowledge base.

Obsidian Sync exists specifically because generic cloud sync was unreliable enough that the team built their own.

How an AI agent uses the vault

This is where the vault stops being a note-taking system and becomes infrastructure.

An AI agent — running on your machine or connected to your files — can read the vault directly. The markdown files are the native format language models understand best. No parsing, no conversion, no extraction pipeline. The vault IS the context.

The agent boot sequence

When a session starts, the agent reads files in a deliberate order:

  1. Identity — me/WORKING_WITH_ME.md (or SOUL.md, USER.md in agent-specific setups). Who you are, how you work, what matters.
  2. Current context — context/now.md. What is happening right now, what the priorities are, what changed recently.
  3. Durable memory — MEMORY.md. Lessons, decisions, preferences that persist across weeks and months.
  4. Deeper files only when needed — frameworks, project docs, research. Pulled in on demand, not loaded at startup.

This boot sequence means the agent starts every session knowing who you are, what you care about, and what you have already decided. No re-explaining. No lost context.

What the agent writes back

A well-configured agent does not just read the vault — it writes to it:

  • Daily memory files (memory/YYYY-MM-DD.md) — logs of what happened, what was discussed, what was decided. Raw context that feeds future consolidation.
  • Captures to _inbox/ — ideas, voice memo transcriptions, things worth keeping but not yet sorted.
  • Updates to MEMORY.md — when something durable emerges from a session, the agent promotes it to long-term memory.

The vault grows richer over time because both you and the agent contribute to it. You write the strategic layer — beliefs, frameworks, identity. The agent handles the operational layer — daily logs, status updates, routine captures.

What the agent must not do

  • Modify identity files without asking. Your WORKING_WITH_ME.md is yours. The agent can suggest changes but should not unilaterally rewrite who you are.
  • Dump raw data into startup files. The whole point of the vault structure is separation. Raw input goes to _inbox/ or daily logs. Startup files stay compact.
  • Treat the vault as a database. The vault is a knowledge graph, not a data store. Large datasets, API responses, and transactional records belong elsewhere.

Sync makes the agent always current

Because Obsidian Sync runs continuously, the agent's copy of the vault is always up to date. If you edit context/now.md on your laptop at a café, your home server agent has those changes within seconds.

This means you can update priorities on the go and the agent picks them up immediately, the agent's daily logs sync back to your laptop automatically, and there is no manual step between changing something and the agent knowing about it.

The vault becomes a shared workspace between you and your agent, kept in sync by Obsidian without either of you thinking about it.

A real example

Here is what a working vault looks like after a few months of active use:

Brain/
├── MEMORY.md                    # durable truths, updated weekly
├── context/
│   ├── now.md                   # current priorities and focus
│   ├── constraints.md           # what limits decision-making
│   └── projects.md              # active project status
├── me/
│   └── WORKING_WITH_ME.md       # operational identity
├── frameworks/                  # reusable mental models
│   ├── learning_through_building.md
│   └── leverage_and_agency_gaps.md
├── decisions/                   # what was decided and why
├── essays/                      # long-form thinking
├── _inbox/                      # unsorted captures
├── voice-memos/                 # transcribed audio captures
├── agents/
│   └── buddy/
│       ├── SOUL.md              # agent identity
│       └── learnings.md         # accumulated agent context
└── logs/                        # daily and weekly records

27 knowledge units. Not 2,700 scattered notes. Everything has a role. Startup files stay small. The graph grows through use, not through hoarding.

Getting started with Obsidian

  1. Download Obsidian (free for personal use)
  2. Create a new vault — this is your /Brain
  3. Create the four starter files: MEMORY.md, context/now.md, me/WORKING_WITH_ME.md, and _inbox/
  4. If you use multiple machines: subscribe to Obsidian Sync and connect both devices
  5. Start writing. The vault gets better the more you use it.

The first week will feel sparse. That is correct. A /Brain earns its structure through use, not through pre-planning.

Common mistakes

  • Creating complex folder hierarchies before you have real content to organize
  • Using Obsidian's plugin ecosystem as a distraction from actual writing
  • Syncing via iCloud and losing files to silent conflicts
  • Treating the vault as private-only — the best vaults have sections designed to be read by agents
  • Assuming the graph view is the point. The graph is a side effect of good linking, not the goal.

Next steps

  • Read Core Files to sharpen your startup files
  • Read Capture to build a low-friction input habit
  • Read Maintenance to keep the system honest over time