Skip to content
The world does revolve around you.

Obsidian and Ostler#

Ostler indexes your life into a folder of markdown files with YAML frontmatter. Obsidian is the best-known viewer for exactly that shape of data. Pointing one at the other takes about five minutes and gives you a graph view, a plugin ecosystem, and a familiar reading surface over everything Ostler knows about you.

This page walks through why the combination works, how to set it up, what you get out of the box, and where the sharp edges are.

Why this combination works#

Ostler has a two-zone file architecture. The engine zone, ~/.ostler/, holds private internal state – databases, indexes, secrets, caches – and you should never touch it. The visible zone, ~/Documents/Ostler/, is the customer-facing side: pure markdown with YAML frontmatter, organised into human-readable folders, backed up by Time Machine, indexed by Spotlight, and linked together with [[wiki-link]] syntax wherever one record references another.

That visible zone was designed from day one to be an Obsidian vault. Same markdown bodies, same frontmatter, same wiki-link relationships, same folder hierarchy. Obsidian sees no exotic format because there is no exotic format. It is the format Obsidian itself uses.

So this is not an integration project. It is two tools that already share a substrate – Ostler writes, Obsidian reads – and you get to keep both.

Setup (five minutes)#

  1. Install Obsidian from obsidian.md if you have not already. The free desktop app is what you want; no account, no signup.
  2. Open Obsidian.
  3. On the start screen, choose Open folder as vault.
  4. Navigate to ~/Documents/Ostler/ and select it.
  5. When Obsidian asks whether to trust the author of this vault, say yes. The "author" here is you and Ostler running on your Mac.

That is the whole setup. Obsidian will index the folder in the background – a fresh Ostler install indexes in seconds; an instance with a year of life in it can take a few minutes the first time.

The resulting vault has roughly this shape:

~/Documents/Ostler/
├── Conversations/      # iMessage, WhatsApp, email, voice notes (L0–L2)
│   └── 2026-05-21/
│       └── coffee-with-alice-a1b2c3/
│           ├── summary.md
│           ├── todos.md
│           ├── transcript.md
│           └── metadata.md
├── AI Conversations/   # Claude Code, ChatGPT sessions (default L3, often empty)
├── People/             # One markdown file per person you know
├── Topics/             # Topics that recur across your life
├── Meetings/           # Meeting notes from CalDAV-attached events
├── Places/             # Places, organisations, projects
├── Daily/              # Morning briefs and evening wraps
└── Notes/              # Reserved for your own notes (Ostler never writes here)

The exact folders depend on which connectors you have enabled; the shape is consistent.

What you get out of the box#

Without installing a single plugin, you immediately get:

A graph view across your life. Obsidian's built-in graph renders every person, conversation, topic, and meeting as a node, with edges wherever Ostler wrote a [[wiki-link]] between them. Open the global graph, filter by folder, and you can see how the people, places, and themes in your life actually connect. This is the same data the personal wiki renders, viewed through a different lens.

Backlinks for free. Open a person's file and the right-hand panel lists every conversation, meeting, and topic that references them. Because Ostler writes wiki-links consistently when it sees a name it recognises, "who did I talk to about this?" answers itself.

Full-text search. Cmd-O for the file switcher; Cmd-Shift-F for content search. Obsidian's search supports operators (tag:, path:, phrase quoting, regex) and is fast enough on tens of thousands of files.

Tag navigation. Ostler writes structured tags in frontmatter (type: person, level: L1, source platform, etc.). The Tags pane groups by tag and the search bar treats #person and tag:person as first-class.

Reading mode. Markdown-rendered transcripts and summaries look like the documents they are, not like raw files. Live-preview mode is the default in current Obsidian builds and reads cleanly.

Plugins worth pairing#

Obsidian's community plugin browser is the right place to discover what suits you. Three popular ones are worth singling out because they map well onto Ostler's data shape:

Dataview. Queries your vault as if it were a database. Because Ostler writes consistent frontmatter, you can ask things like "every conversation in the last 30 days that includes a given person" or "everyone I have not spoken to in three months". Dataview runs entirely locally inside Obsidian; the Dataview docs are the canonical reference for query syntax.

Calendar. Adds a small monthly calendar to the sidebar that double-clicks straight to the daily file. Pairs well with Ostler's Daily/ folder, which already contains one file per day.

Tasks. If you live in checkboxes, the Tasks plugin gives you a richer task syntax (due dates, recurrence, filters) on top of plain markdown. Ostler writes todo lists into the conversation todos.md files; you can keep those untouched and layer your own task list in ~/Documents/Ostler/Notes/ alongside.

There are hundreds of other plugins. Pick what you need. Stay alert to which ones have outbound network access – the plugin browser flags this clearly, and Obsidian itself runs without an account.

Mobile#

Obsidian has a free mobile app on iOS and Android. The supported sync routes between your desktop vault and the mobile app are:

  • Obsidian Sync, the official paid sync service from the Obsidian team. End-to-end encrypted with a key only you hold. The simplest route if you do not already have one set up.
  • iCloud Drive, by placing the vault inside your iCloud Drive folder. The Obsidian mobile app on iOS can open vaults from iCloud Drive natively.
  • A third-party sync layer (Git, Working Copy, Syncthing). These work but are more setup.

Because ~/Documents/ is what iCloud Drive syncs by default on macOS – assuming you have Desktop and Documents syncing turned on in System Settings > iCloud – an Ostler vault lands in iCloud Drive automatically. Open Obsidian on your iPhone, point it at the iCloud Drive vault, and the same files appear.

First sync on a busy vault

After Ostler has been running on your Hub for a few months, the visible zone can grow to several gigabytes of markdown. The first iCloud Drive sync after enabling mobile can take a while on a slow connection. Subsequent syncs are incremental.

Mobile is read-mostly

Treat the mobile vault as a window onto your Hub-managed data, not a writing target. If you want to capture something new from your phone, prefer the iOS Companion – it routes through Ostler's structured ingestion. Free-text notes in Notes/ written from mobile are fine and Ostler will leave them alone.

Privacy#

Nothing leaves your Mac unless you install a plugin or sync option that explicitly sends it somewhere. Obsidian itself runs offline; the desktop app does not require an account.

A few specifics worth pinning down:

  • The vault Obsidian sees is exactly ~/Documents/Ostler/. Anything Ostler keeps inside the engine zone, including secrets and the database files, is not in this folder and Obsidian cannot see it.
  • Conversations marked L3 (private) never land in the visible zone at all. Ostler's writer short-circuits L3 records at the source, so they are absent from the vault rather than present and filtered out. The privacy model covers this.
  • If you install an Obsidian plugin that talks to the network, that plugin can read anything in the vault, just as a browser extension can read any web page. Vet plugins the same way you would any other app you install. Obsidian's plugin browser shows you which plugins request which permissions.
  • Obsidian Sync, when enabled, uploads your vault to Obsidian's servers in end-to-end encrypted form. That is a deliberate choice you make; it is not on by default.

Limits and warnings#

A few things to keep in mind once you have the pairing running.

Do not hand-edit Ostler-managed files. Files in Conversations/, People/, Topics/, Meetings/, Places/, Daily/, and AI Conversations/ are written by the Ostler pipelines and may be overwritten the next time those pipelines run. If you want to annotate a conversation or person, do it in a separate file in Notes/ and [[wiki-link]] back to the canonical file – Obsidian's backlinks will pick it up.

Notes/ is yours. This folder is reserved for you. Ostler will never write into it. Use it for your own observations, project notes, journal entries, meeting prep, whatever you like. It still lives inside the vault and still gets graph view, backlinks, and search.

Frontmatter is the source of truth. If you find a markdown file where the body and the frontmatter disagree about something, treat the frontmatter as canonical. The body is generated for a human to read; the frontmatter is what the Ostler pipelines query.

Plugin updates are not Ostler's concern. When a plugin you have installed receives an update, that is between you and the plugin author. Ostler does not vet or manage Obsidian plugins.

Wiki vs vault. Ostler also produces a read-only personal wiki served on localhost. The wiki and the vault share the underlying data but are different artefacts: the wiki is curated for browsing, the vault is the raw markdown layer. Use whichever fits the question.

If you previously set WIKI_OBSIDIAN_DIR at install time (see installation), that mirrors the personal wiki into a separate vault folder you chose. The approach on this page – pointing Obsidian directly at ~/Documents/Ostler/ – is the recommended path going forward.