# Obsidian + Claude Code Complete Guide

Huashu's April 2026 guide documents how to run a personal knowledge base where Claude Code acts as full-time librarian. The core thesis: store knowledge in a format AI can read (local Markdown), and let AI handle organizing, connecting, and maintaining it. You record and think; AI indexes and links.

The guide validates the [[llm-wiki-pattern]] with practical implementation details. Huashu manages 2,000+ files across 9 workspaces using a hierarchy of CLAUDE.md files — a root-level router dispatches tasks to subdirectory-specific rulesets. He wrote 55 custom Skills before discovering that Obsidian's native features (bidirectional links, graph view, fuzzy search) already solve problems he'd been reimplementing.

## Convergent Evolution

Three billion-dollar projects independently chose the same memory format:
- **Manus** (acquired by Meta for $2B): stores agent memory in task_plan.md and notes.md
- **OpenClaw** (355k GitHub stars): MEMORY.md for knowledge, SOUL.md for personality
- **Claude Code**: CLAUDE.md for project context, memory/ directory for long-term storage

All landed on plain Markdown files. The reasoning: near-zero latency, $0 cost, any text editor works, native Git support, no vendor lock-in. For personal knowledge bases under 400K characters (~200K words), direct file reading beats vector databases on every dimension.

## Three-Layer Architecture

The guide proposes a raw → wiki → output flow:

**raw/** holds immutable source material — articles, meeting notes, reading annotations, chat screenshots. Append only, never modify. This is the source of truth.

**wiki/** holds AI-written structured articles organized by type: concepts/, entities/, topics/. Each article follows a SCHEMA.md specification that defines naming conventions, frontmatter template, tag taxonomy, wikilink rules, and article structure. The AI creates and maintains these; humans can correct.

**output/** holds query products — reports, analyses, comparisons generated from wiki knowledge. Good outputs feed back into wiki as new entries.

SCHEMA.md turns a general-purpose LLM into a consistent wiki curator. Without it, AI might use #ai-tools today and #AI-Tools tomorrow. With it, formatting stays predictable.

## Six Design Principles

1. **Markdown only** — convert everything to .md before it enters the vault; keep originals outside
2. **Consistent terminology** — pick one form (RAG vs Retrieval-Augmented Generation) and stick to it; put the glossary in CLAUDE.md
3. **Flat first** — no more than 3 folder levels; use tags and links for categorization, folders for lifecycle (active/archive)
4. **Every note needs a summary** — one frontmatter sentence so AI can skip the full read when scanning
5. **Five frontmatter fields** — title, tags, created, type (fleeting/literature/permanent), summary
6. **Separate human from AI output** — different folders or filename prefixes; different trust levels, different modification rules

The type field borrows from Zettelkasten: fleeting notes (jotted thoughts), literature notes (reading summaries), permanent notes (refined opinions). AI can skip fleeting notes and prioritize permanent ones.

## Workflows

Seven practical workflows, each requiring minimal human effort:

- **Daily Notes + Weekly Review**: write 3-5 lines daily, have AI generate weekly summaries
- **Reading Notes**: dump highlights into raw/, AI generates structured literature notes with cross-references to existing vault content
- **Research Accumulation**: save raw research, AI compiles into wiki articles, future research on the same topic starts with context
- **Writing from Notes**: describe topic in one sentence, AI searches vault and drafts from your existing material
- **Project Management**: one folder per project with index.md, completed projects move to archive/
- **Auto-Organizing Old Notes**: batch-process unsorted files, AI adds frontmatter and links
- **Automatic Backlinks**: AI scans daily notes, identifies entities, replaces plain text with `[[wikilinks]]`, creates stub pages for missing entities

The last workflow — "Agentic Note-Taking" — is the most ambitious. Stefan Imhoff used to spend 10-15 minutes daily adding links by hand. With Claude Code, it takes seconds.

## Tooling

**obsidian-skills** (by kepano, Obsidian's CEO) teaches Claude Code to handle Obsidian-specific syntax: `[[wikilinks]]`, callout blocks, .canvas files, frontmatter YAML. Install with `claude install kepano/obsidian-skills`.

**Claudian** embeds Claude Code's chat interface directly in Obsidian's sidebar — no terminal switching.

**Smart Connections** builds a semantic index using AI embeddings. For vaults over 400K characters, this supplements direct reading.

**MCP** is unnecessary for most users. Claude Code already reads/writes local files directly — MCP adds a middle layer with no benefit unless you need Claude Desktop (not Claude Code) to access the vault, or you need to invoke Obsidian plugin features like Dataview queries.

## Scale Thresholds

| Size | Approach | Vector DB? |
|------|----------|------------|
| Under 100K chars | wiki/ + INDEX.md + direct reading | No |
| 100K-400K chars | Same, wiki split by topic | No |
| 400K-1M chars | Add Smart Connections | Optional |
| Over 1M chars | Full RAG | Yes |

Claude's 200K-token context holds ~500K-800K Markdown characters. For most personal knowledge bases, that's enough to never need vector retrieval.

## Relation to Existing Setup

This vault already implements Template C (Karpathy Wiki) from the guide:
- sources/ ≈ raw/
- wiki/ ≈ wiki/
- CLAUDE.md defines schema inline rather than in a separate SCHEMA.md

The guide suggests improvements worth considering:
- A glossary section in CLAUDE.md to enforce terminology
- The `type: fleeting | literature | permanent` distinction for wiki pages
- Auto-linking workflows for daily notes
- Separating AI output into its own directory or prefix

The core insight: "AI isn't your search engine — it's your knowledge compiler." RAG re-derives every answer from scratch. The wiki approach compiles raw material into persistent articles that accumulate and cross-reference over time.