Persistent Context with Obsidian

Every Claude Code session starts with amnesia. The context window is empty. The decisions you made yesterday, the preferences you refined last week, the project architecture you debated for three sessions — gone. CLAUDE.md partially solves this by injecting project-level context at session start, but it has a hard constraint: every word in CLAUDE.md is loaded every session, consuming context window budget whether the current task needs it or not. The "second brain" pattern solves both problems — persistence and selectivity — by connecting Claude Code to an Obsidian vault through the Obsidian CLI. Obsidian stores your knowledge as structured markdown files with bidirectional links between them, creating a navigable graph of related concepts. Claude Code reads from this vault on demand, pulling only the files relevant to the current task. The result is a personal knowledge base that survives across sessions, scales without consuming fixed context budget, and grows more useful with every note you add. This is not memory in the ChatGPT sense — opaque, uncontrollable, managed by the model. This is memory you own, you structure, and you version. Every fact is a file you can read, edit, or delete.

The architecture has two layers. Layer one: the Obsidian vault itself — a folder of markdown files organized by project, domain, and decision type. Project context files describe what you are building, the current phase, key constraints, and decisions already made. Domain files capture institutional knowledge: terminology, standards, workflows, vendor preferences. Decision logs record what was decided, when, and why, using the ADR format from Lesson 2. Layer two: the Obsidian CLI, which exposes the vault to Claude Code as a set of readable files with their link relationships intact. When Claude Code accesses the vault, it does not just read flat files — it can see that your "API Design Standards" note links to your "Authentication Architecture" note, which links to your "Q1 Security Audit" note. This graph structure lets Claude traverse related context without you manually assembling it. The critical distinction from CLAUDE.md is the loading model: CLAUDE.md is always-on context, consumed at session start regardless of relevance. Obsidian notes are on-demand context, fetched only when the task requires them. This maps directly to the context layering strategy from Lesson 1 — high-frequency, universal context belongs in CLAUDE.md; project-specific, domain-specific, and historical context belongs in the vault.

1. 1. Install Obsidian and Create Your Vault Download Obsidian (free, open source) and create a new vault. A vault is a folder of markdown files — nothing proprietary, nothing locked in. Create top-level folders for: projects (one subfolder per active project), domains (institutional knowledge, standards, glossaries), decisions (ADR-format decision logs), and meetings (transcripts, notes, action items).
2. 2. Install the Obsidian CLI for Claude Code Install the Obsidian CLI tool, which creates an MCP server that Claude Code can access. This gives Claude Code the ability to read vault files and — critically — to see the bidirectional link relationships between them. Configure your Claude Code settings to connect to the MCP server. Verify access by asking Claude Code to list your vault structure.
3. 3. Structure Notes for Agent Consumption Write each note with a clear title, a one-sentence summary at the top, and backlinks to related notes using [[double-bracket]] syntax. Use consistent heading structures so Claude can parse them predictably. Tag notes by type: #project, #decision, #standard, #meeting. The more consistently you structure notes, the more reliably Claude can find and interpret them.
4. 4. Build Context-Loading Commands Create Claude Code slash commands that load specific vault sections before a work session. A /context command reads your project files, recent daily notes, and active decision logs. A /project command loads everything related to a specific project by following its backlinks. These commands replace the manual context assembly that wastes the first ten minutes of every session.
5. 5. Maintain the Vault as Ongoing Practice Write daily notes capturing decisions, blockers, and open questions. Update project context files at phase transitions. Log every significant decision with rationale. The vault compounds — each note you add increases the context available to every future session. A stale vault produces stale output, same as stale context documents from Lesson 6.

For teams, the Obsidian vault becomes a shared persistent layer. A shared vault — synced via Git, Obsidian Sync, or a shared drive — gives every team member's Claude Code sessions access to the same institutional knowledge. The glossary is canonical. The decision logs are complete. The project context is current. When a new team member starts a Claude Code session and loads the shared vault, they inherit months of accumulated context without a single onboarding meeting. This connects directly to the knowledge base design from Lesson 2, but with a structural advantage: Obsidian's bidirectional links create a navigable graph rather than a flat document library. Claude can follow links from a project file to its related decisions, from a decision to the meeting where it was made, from the meeting to the people involved. The graph structure mirrors how institutional knowledge actually works — interconnected, not siloed. One governance rule is non-negotiable: define who writes to the vault and who only reads. If agents write freely into a shared vault, you lose the ability to distinguish human decisions from generated content. The vault must remain a human-authored source of truth that agents consume, not a space where human and machine-generated content blend without attribution.