obsidian-vault-architect

name

obsidian-vault-architect

description

Architects durable, scalable, LLM-queryable Obsidian (and any wikilink-markdown) vaults; the design layer above tactical tools. Two modes: greenfield design (note granularity, frontmatter schema, plugins vs external vector RAG, dual-layer memory, scale guardrails, MOC cartography, persona/voice fidelity) and remediation of an existing vault (the 8-dimension graph-health rubric plus an ordered lever stack to reach Grade-A without data loss). Encodes hard-won scale, pipeline, and persona anti-patterns. Use when designing, restructuring, or auditing an Obsidian vault or second brain, making it LLM-queryable / building RAG over notes, choosing note or frontmatter structure, deciding plugins-vs-external-retrieval, fixing a vault that won't scale, grading graph health, or reducing orphans/over-siloing. Mechanical execution belongs to the tactical obsidian-graph-auditor, obsidian-brain-eval, obsidian-orphan-killer, and obsidian-bases/obsidian-markdown skills.

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