ghostbrain/docs/vault structure

vault structure

ghostbrain doesn't own its database — the obsidian vault is the database. every captured item is one markdown file with frontmatter, sitting in a predictable folder, with wiki-links to every other item it touches. obsidian's graph view and backlinks panel work because we wrote everything obsidian would expect.

top-level folders

vault/
├── inbox/            # queries you piped here, today's catch
├── people/           # one note per known person
├── projects/         # inferred projects, one folder each
├── meetings/         # calendar events, by date
├── threads/          # gmail + slack threads
├── docs/             # notion pages, google docs, drive files
├── code/             # github prs, issues, mentions
└── .ghostbrain/      # indexer state — see below

only .ghostbrain/ is reserved. you can rearrange anything in the other folders and ghostbrain will follow your edits — the indexer treats your version as authoritative and won't overwrite it.

note

by default ghostbrain writes into a sibling vault called ghostbrain-vault. point it at an existing vault in settings → ghostbrain → vault path if you'd rather share one with your own notes.

file types

people note

one per resolved person. lives at vault/people/<display-name>.md. ghostbrain merges multiple identities (gmail address, slack id, github handle) into a single note.

---
name: marie chen
aliases: [marie, m.chen, marie c]
emails: [[email protected], [email protected]]
slack: U07ABC123
github: marie-c
role: head of marketing
last_seen: 2026-05-07
sources: [gmail, slack, calendar]
---

# marie chen

works with you on the q3 launch. tends to ship copy late but always nails
the headline.

## recent
- [[2026-05-07]] · slack #launch — locked launch date jun 11
- [[re-q3-launch-marketing]] · gmail thread, 14 replies
- [[2026-05-05 mon weekly]] · 30m, calendar

## links
[[people/sam okafor]] · [[projects/q3-launch]]

thread note

one per gmail thread or slack thread/channel-day. file name is the (cleaned) subject for email, #channel/yyyy-mm-dd.md for slack.

meeting note

one per calendar event, named yyyy-mm-dd <title>.md. recurring events still get one file per occurrence so the timeline reads correctly.

project

folder, not a file. ghostbrain infers projects from co-occurring tags and people and creates vault/projects/<slug>/ with an index README.md plus child notes for milestones, decisions, and meeting recaps.

frontmatter conventions

every ghostbrain-written file starts with yaml frontmatter. the shared keys:

key	meaning
id	stable identifier. don't edit.
source	connector that emitted it. one of `gmail · slack · notion · linear · github · calendar · drive`.
source_url	deep link back to the original item.
captured_at	iso timestamp of when ghostbrain wrote the file.
occurred_at	iso timestamp of the underlying event (message sent, meeting started, pr opened).
people	array of `[[people/...]]` wiki-links involved.
tags	flat list. ghostbrain infers a few; you can add your own.

tip

you can add any keys you want. ghostbrain never deletes frontmatter fields it doesn't recognise — those are yours. it only adjusts the keys above.

wiki-links and entities

ghostbrain writes [[wiki-links]] the way obsidian expects. every person, project, thread, and meeting gets a link; entity resolution makes sure "marie", "marie c", and "[email protected]" all point at the same file.

links are relative to the vault root:

[[people/marie chen]]
[[meetings/2026-05-07 q3 launch sync]]
[[threads/re-q3-launch-marketing]]

this matches obsidian's default link style and means the graph view "just works."

.ghostbrain/ — indexer state

everything ghostbrain needs to reconstruct your index, isolated to one folder:

vault/.ghostbrain/
├── manifest.json     # schema version, vault config
├── connectors/       # per-connector cursors + last-sync
├── index/            # lexical + vector index files
├── people.json       # resolved entity table
└── logs/             # rolling indexer log, 7 days

safe to delete: index/ and logs/. ghostbrain will rebuild them on next launch. do not delete connectors/ while a connector is authorised — you'll lose the cursors and the next sync will be a full backfill.

what happens when you edit a file

ghostbrain checksums every file it writes. when it next visits one, it does one of three things:

unchanged — overwrite normally with the latest source data.
edited by you — keep your version, append new source data below a ## added by ghostbrain heading, never overwrite your text.
renamed/moved — follow the rename via the obsidian metadata cache, keep updating the new path.

warning

if you delete a ghostbrain-written file, the next sync will rewrite it. to permanently remove items from the vault, use ghostbrain purge with a glob — see cli reference.

← previous

query syntax

api & cli