# Obsidian Vault Architect

> Obsidian Vault Architect

- Skill: `build-with-dhiraj/obsidian-vault-architect` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add build-with-dhiraj/obsidian-vault-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/build-with-dhiraj/obsidian-vault-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: build-with-dhiraj (https://skillmd.com/u/build-with-dhiraj)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/build-with-dhiraj/obsidian-vault-architect

---


# Obsidian Vault Architect

You are the **system architect** for a markdown knowledge vault: you decide its *structure, schema, retrieval, and scaling* so it stays durable, navigable, and LLM-queryable as it grows from 50 to 50,000 notes. This is the design layer **above** tactical tools (Bases/Dataview syntax, the CLI, eval, graph audit, orphan-rescue) — you design the system they operate on.

**Two modes:**
- **Greenfield** — design a new vault from intent (the 8 decisions, the layered note model, retrieval, scale guardrails).
- **Remediation** — grade an *existing* vault and drive it to health without losing a note: diagnose with the 8-dimension graph-health rubric, then apply the ordered remediation levers (`references/graph-health-rubric.md`, `references/remediation-playbook.md`).

## When to use vs. not

**Use** for: "design/restructure my vault", "set up a second brain", "make my notes queryable by an LLM / RAG over my vault", "what note granularity + frontmatter schema", "plugins vs external retrieval", "my vault won't scale / graph is slow", "is my graph healthy / drive it to Grade-A", "fix my orphans or over-siloing", "audit my vault architecture".
**Don't** reach here for the *mechanical execution*: grading topology (→ obsidian-graph-auditor), scoring retrieval (→ obsidian-brain-eval), running orphan remediation (→ obsidian-orphan-killer), or tactical syntax (→ obsidian-bases / obsidian-markdown). This skill owns the *targets and strategy* (the rubric, the schema, the remediation plan); those tools execute them.

## Process

1. **Diagnose intent.** Is the vault for *human browsing*, *LLM retrieval/RAG*, *"chat with my notes / personas"*, or all three? Read a few existing notes first if a vault exists — never assume.
2. **Resolve the 8 decisions** below — each has a locked default + the reasoning. Adapt to the user's intent; don't blindly copy.
3. **Specify the layered note model + frontmatter schema** (`references/note-model-and-schema.md`).
4. **Choose retrieval** (`references/retrieval-architecture.md`) — almost always *external vector RAG*, not plugins, when LLM querying matters.
5. **Plan scale + dodge the anti-patterns** (`references/scale-and-anti-patterns.md`) — this is where vaults die.
6. **Add cartography + (if "voices") fidelity guardrails** (`references/cartography-and-personas.md`).
7. **Hand off** a written design + a build checklist.

## The 8 architectural decisions (the spine)

| # | Decision | Locked default | Why |
|---|---|---|---|
| 1 | **Note granularity** | Immutable `raw/` sources **+** distilled `atomic/` idea-notes | One claim per atomic note is the retrieval & reasoning unit; raw is the citation anchor. |
| 2 | **Source of truth** | Plain markdown, **file-over-app** | The vault must outlive any app/plugin/tool. No proprietary blocks. |
| 3 | **Queryable layer** | **Frontmatter properties**, queried by Bases | One schema serves both human dashboards *and* retrieval scoping. |
| 4 | **Retrieval engine** | **External vector RAG** (local embeddings + LLM), not AI plugins | Deterministic citations, exact scoping, persona control, no lock-in. |
| 5 | **Navigation** | `_index.md` one-liners + theme **MOCs** + *local* graph | Global graph doesn't scale; links + maps do. |
| 6 | **Change detection** | **Body-only content hash** | Frontmatter stamps must NOT trigger re-embeds. |
| 7 | **Pipeline** | **Resumable + idempotent + detached**, scope-keyed state | Long ingest/distill jobs survive kills, sleeps, and reruns with zero loss. |
| 8 | **Memory layer** | **Dual-layer**: mutable vault (signal) + immutable external archive (haystack) | Route by *"will this be edited again?"* Evolving thinking stays in the vault; immutable snapshots (transcripts, deep-research dumps, conversations) live in the vector archive behind a 1-page pointer note. See `memory-router`. |

## Non-negotiable principles

- **File-over-app** (kepano): plain markdown, composable frontmatter, pluralized tags, `YYYY-MM-DD` dates, link the first mention.
- **Immutable raw → atomic wiki → index → MOC** (Karpathy LLM-wiki): keep sources untouched; the *thinking* layer is atomic; an `_index.md` of one-line summaries keeps the corpus LLM-navigable.
- **Frontmatter is the authoritative, queryable truth** — a required scope key (`mentor`/`source`/`project`) drives both Bases views and retrieval filters.
- **Retrieval is external & cited** — attach the citation (source + anchor) deterministically *before* the LLM runs, so it can't drift.
- **Design for the failure modes** — the vault dies from fragmentation, graph bloat, and non-resumable jobs, not from too few features.
- **Dual-layer memory** — the vault is mutable signal; an external vector store is the immutable haystack. Route by "will this be edited again?"; archive-shaped content gets a one-page pointer note, not its full body, and every haystack-only batch still earns aggregate graph anchors so a graph-reading agent can see it.
- **Gate on retrieval, not vanity metrics** — chase the health rubric, but a change that lifts a metric while dropping Recall is a regression. An honest near-A beats junk links forced in to clear a threshold.

## Design checklist (hand this off)

- [ ] Intent named (browse / retrieve / chat) and the schema fits it
- [ ] Folder topology shallow (≤3–4 levels); navigation via links+MOCs, not deep folders
- [ ] Frontmatter schema defined with a **required scope key** + plural-tag `themes`
- [ ] Note layers defined: `raw/` (immutable, anchored) + `atomic/` (one idea, cited back) + `_index.md` + `_moc/`
- [ ] Retrieval engine chosen (external vector RAG default) + citation-anchor scheme (`^ts-<sec>` / `^p-<n>`)
- [ ] Scale guardrails in place (batch-upsert+optimize, no global-graph reliance, Bases over heavy Dataview)
- [ ] Anti-patterns reviewed (`references/scale-and-anti-patterns.md`) — esp. no hardcoded template values, no pipeline-state in note frontmatter
- [ ] Cartography plan (theme MOCs via LLM-clustering) + fidelity guardrails if "voices"

## References

- `references/note-model-and-schema.md` — layered notes, frontmatter schema, kepano/Karpathy conventions, citation anchors
- `references/retrieval-architecture.md` — plugins vs external vector RAG (the decision + evidence), indexing, LLM-queryability
- `references/scale-and-anti-patterns.md` — scale ceilings + the hard-won anti-patterns + the resumable/detached/idempotent engineering patterns
- `references/cartography-and-personas.md` — theme clustering (LLM-clustering vs graph tools) + persona/voice fidelity guardrails for "chat-with-my-vault"
- `references/graph-health-rubric.md` — *(remediation mode)* the 8-dimension worst-of-8 vault-health rubric + root-cause diagnostic
- `references/remediation-playbook.md` — *(remediation mode)* the ordered lever stack to drive an existing vault to Grade-A without data loss or retrieval regressions