Why Your Claude Code Setup Loses Context Every Session — And the Obsidian Architecture That Fixes It

Imagine this scenario: Monday morning. A payment reconciliation job failed overnight — 847 transactions sitting in PENDING state. You open Claude Code. The agent doesn't know your codebase. It doesn't know why you use append-only events in a Postgres JSONB column instead of EventStoreDB. It doesn't know that the OutboxRelayService polls every 500ms and that's intentional, not a bug. You spend 40 minutes re-orienting it on decisions that took four months to reach. You find the actual bug — a missed null check in the settlement saga — in six minutes.

The ratio is wrong. Forty minutes of context-loading for six minutes of work. And it happens every single session.

This isn't a Claude-specific failure. Every session starts cold. The agent that understood your architectural reasoning yesterday begins today with nothing. Except you already own a tool designed for exactly this problem — long-term, interconnected knowledge management. You've been using Obsidian for notes for two years. You just never thought to wire it into your AI workflow.

Obsidian as persistent memory layer — the OS Claude Code runs on top of.

There are at least fifteen articles on Medium right now about connecting Claude Code to Obsidian. Most show you how to install an MCP server and point it at your vault. This is not that article. The tutorials cover the connection. None cover the architecture: how the vault should be structured, what CLAUDE.md needs to contain to actually eliminate cold-start, which session data is worth persisting and which isn't, and why most setups that "work" in week one produce noise by week four.

The engineers I've seen get consistent, durable productivity from Claude Code aren't the ones who've mastered prompt engineering. They're the ones who built the knowledge infrastructure first — and with the right configuration, Obsidian is the OS that infrastructure runs on.

This article covers how to build that. I'll walk through structuring an Obsidian vault so the agent always knows where things live, designing a CLAUDE.md that eliminates cold-start by encoding your conventions once, wiring MCP servers so Claude can read and write vault notes without manual intervention, building session hooks that automatically capture what was discovered so you never re-explain the same architectural decision twice, and the five configuration mistakes that each cost me at least a week of re-training.

The Core Mental Model

The framing matters here, because it shapes every configuration decision that follows.

Obsidian is not an AI chat interface. It is the persistent memory layer. Claude Code has full filesystem read/write access to any directory you launch it from. No plugin required. No API key. No sync subscription. When you cd into your vault directory and run claude, the agent can read and write every note in your vault — which means every architectural decision, every project status, every session log you've accumulated is available as context on the next turn.

The insight that unlocks this setup: the agent's context window is temporary; the vault is permanent. Everything important that gets discovered in a session — a non-obvious dependency, a decision that ruled out three alternatives, the reason a migration runs in a specific order — should end up in the vault, not just in the terminal scroll history.

Three principles shape every configuration decision that follows.

Wikilinks are the retrieval mechanism, not folder structure. A note without links to related notes is dead weight — the agent can find it by path but can't reason about its relationships. Folders are for humans. Links are for agents.

When updating knowledge, overwrite and synthesize existing notes rather than creating new ones for each piece of information that arrives. Ten small notes about the payment module are harder for an agent to reason about than one well-maintained note that synthesizes all of them. Compile, don't accumulate.

The description frontmatter field (~150 characters) is load-bearing. It's what lets an agent assess relevance without opening the file. Without it, Claude reads entire files to decide whether they're worth reading — burning context tokens on dead ends before you've typed the first message.

Vault Architecture

The PARA structure (Projects, Areas, Resources, Archives) — Tiago Forte's actionability-first organization system — maps cleanly onto how AI agents use memory:

PARA folders mapped to AI memory tiers. Each tier has different read/write behavior.

Add one more top-level folder that PARA doesn't include: AI/. This is where the agent writes everything it generates — session summaries, scratch drafts, distilled insights. Separating agent-written content from human-written content is the single most important hygiene decision in an agentic vault.

CLAUDE.md               # Agent operating manual — auto-loaded every session
hot.md                  # ~500-word semantic snapshot — agent reads FIRST
Dashboard.md            # Human-facing entry point

00-inbox/               # Raw captures — agent routes out of here
10-projects/
  active/               # Max 3–5 active projects
  archive/YYYY/
20-areas/
30-resources/           # Read-only from agent perspective
40-archive/
50-daily/YYYY/MM/       # YYYY-MM-DD.md
AI/
  sessions/             # Agent-written session summaries
  knowledge/            # Distilled facts, patterns, preferences
  scratch/              # Ephemeral drafts — promote then delete
Templates/
.claude/
  commands/             # Custom slash commands
  agents/               # Subagent definitions

The AI/scratch/ convention matters: at session end, the agent either promotes scratch content into a proper note or deletes it. Scratch that accumulates becomes noise. A vault full of orphaned AI drafts is worse than no AI integration at all.

CLAUDE.md: The Agent Operating Manual

CLAUDE.md at vault root is auto-loaded into Claude Code's system prompt at session start. The agent does not re-read it during the session — write it as standing instructions, not as a document to consult. Keep it under 500 lines; anything longer risks partial parsing.

Seven sections cover everything the agent needs.

1. Identity and vault purpose. 2–3 sentences. Prime the persona. Prevent the agent from treating your vault as a generic project directory.

2. Skills to load. If you're using kepano/obsidian-skills (and you should be — more on this below):

Skills to load before vault work:
- obsidian:obsidian-markdown   (wikilinks, embeds, callouts, properties)
- obsidian:obsidian-cli        (vault operations via Obsidian CLI)
- obsidian:obsidian-bases      (database-style views over frontmatter)

3. Vault structure map. Explicit folder-to-purpose mapping. Agents navigate better with a named directory contract than by exploring. The table above belongs here.

4. Linking rules. This section is more important than it sounds:

Linking rules:
- Use [[wikilinks]] for ALL internal references — never [markdown links](path)
- Every new note must link to at least one existing note
- Only create [[wikilinks]] to notes you can confirm exist via search or listing
- Filenames: kebab-case only — no colons, no slashes, no spaces
- [[Note|display text]] for aliases — never rename files (use Obsidian UI)

The "only link to notes you can confirm exist" rule is critical. Claude's default behavior is to generate wikilinks to plausible-sounding notes that don't exist. This silently corrupts your graph — every broken link is noise the next agent has to ignore.

5. Frontmatter schema. Define it explicitly. Every note gets:

---
date: YYYY-MM-DD
description: "~150 chars — enables scan-without-open retrieval"
tags: [flat, list, only]
type: concept|project|daily|reference|session-log
status: active|in-progress|done|archived
---

Flat YAML only. No nested objects. Some MCP servers don't parse nested YAML, and inconsistent schemas make Dataview and Obsidian Bases queries unreliable.

6. Session protocol. The agent needs explicit start and end rituals:

Session start:
  1. Read hot.md (recent context — always first)
  2. Read Dashboard.md or the relevant project index
  3. Check 00-inbox/ for unprocessed items

Session end:
  1. Write session summary to AI/logs/YYYY-MM-DD-HH-MM-project.md
  2. Update hot.md with ~500-word snapshot of current state
  3. Promote AI/scratch/ drafts or delete them
  4. Update index files if new notes were created

7. Do Not Touch list. Without this, the agent will happily overwrite source files, rename notes and break backlinks, and modify .obsidian/ config. Be explicit:

Never:
- Modify .obsidian/ config
- Write to 30-resources/ (read-only source material)
- Delete files without explicit instruction
- Rename files (renames break backlinks — use Obsidian UI)
- Use absolute paths in wikilinks

Five inputs, one operating manual. The synthesis prompt generates the final CLAUDE.md from accumulated context.

What makes a bad CLAUDE.md

No "do not touch" list. No session protocol. Longer than 500 lines. No definition of where agent output should land — so it ends up everywhere. Missing description field in frontmatter schema. Any of these, and the agent starts each session with incomplete instructions and compensates with assumptions.

Building Your CLAUDE.md: A 5-Step Interview

The seven sections above describe the anatomy. This is the procedure that produces them. Give Claude Code these five prompts in sequence — each answer constrains the next — and have it draft the final CLAUDE.md from the accumulated context. Don't use a generic template. An agent reading a template-generated CLAUDE.md learns nothing specific about your vault.

Step 1 — Vault identity

Prompt Claude with this, filling in your answers:

I'm setting up an Obsidian vault as a persistent memory layer for Claude Code.
Help me write a CLAUDE.md. First question: what is this vault for?

My answers:
- Primary purpose: [software projects / research / writing / PKM / mixed]
- Main domains: [e.g., "NestJS backend dev, event sourcing, fintech architecture"]
- Who else reads this vault: [just me / team of N / shared with clients]
- Existing note count: [new vault / migrated from X with N notes]

Claude produces a 2–3 sentence identity paragraph and persona priming. The "who else reads this" answer is the one people skip — a shared vault needs stricter write permissions than a solo one, and Claude should know that before generating the Do Not Touch list.

Step 2 — Vault map

Second question: what is your folder structure and what does each folder mean?

[Paste output of: ls ~/path/to/vault/ | head -20]

For each folder, one line: what it contains and whether the agent should
read it, write to it, or never touch it.

Paste the real ls output, not a description from memory. Claude identifies PARA, Johnny Decimal, flat, or custom structures and writes the directory contract to match what actually exists — not an idealized version you don't maintain.

Step 3 — Write permissions

Third question: what can the agent write, and what should it never touch?

Agent-writable folders: [list them]
Agent-readable only: [list them]
Off-limits entirely: [typically .obsidian/, raw source files, anything synced
                      from external systems]

Specific files to never modify:
[e.g., "Dashboard.md is human-maintained", "Templates/ are mine"]

This step produces the Do Not Touch list. Most people skip it. Every skipped Do Not Touch list eventually becomes a corrupted source file or a broken template.

Step 4 — Frontmatter contract

Fourth question: what fields does every note need, and what note types exist?

Required fields on ALL notes: [e.g., date, description, tags, status]
Note types: [e.g., concept / project / daily / reference / session-log / decision]
Status vocabulary: [e.g., active / in-progress / done / archived]
Type-specific fields: [e.g., "decision notes also need: owner, outcome, date-decided"]

If your existing notes have inconsistent frontmatter — and they do — add this:

My existing notes have inconsistent frontmatter. Most common pattern:
[paste one real example from your vault]

Claude writes the schema to match your dominant existing pattern and flags where it deviates from the recommended structure. You want a schema your existing 847 notes already mostly satisfy, not one that makes them all wrong.

Step 5 — Session rituals

Fifth question: how should sessions start and end?

Session start — always read:
  [e.g., hot.md, the current project index]

Session start — check for:
  [e.g., unprocessed items in 00-inbox/]

Session end — write:
  [e.g., session summary to AI/logs/YYYY-MM-DD-HH-MM-project.md]

Session end — update:
  [e.g., hot.md with a ~500-word snapshot of current state]

Session end — clean up:
  [e.g., promote or delete AI/scratch/ content]

The synthesis prompt

After answering all five, send this:

Now generate my complete CLAUDE.md using all five answers above.
Structure it with these seven sections in order:
1. Identity and vault purpose (from step 1)
2. Skills to load (obsidian:obsidian-markdown, obsidian:obsidian-cli, obsidian:obsidian-bases)
3. Vault structure map (use step 2 folder list as a table with columns:
   Folder | Contents | Agent access)
4. Linking rules (always [[wikilinks]], kebab-case filenames,
   never link to non-existent notes)
5. Frontmatter schema (from step 4, flat YAML only — no nested objects)
6. Session protocol (from step 5)
7. Do Not Touch list (from step 3)

Constraints:
- Under 500 lines total
- Write as standing instructions for an agent, not documentation for a human
- Every rule in sections 4–7 must be unambiguous: "always", "never",
  "only if" — not "try to" or "prefer to"
- Section 3 must reference the actual folder names I gave you in step 2

The constraint about unambiguous rules is the most important one. "Prefer [[wikilinks]]" produces mixed output. "Use [[wikilinks]] for ALL internal references — never [markdown links](path)" doesn't.

MCP Servers: What the Agent Can Touch

CLAUDE.md tells the agent the rules. MCP servers expand what it can actually do inside the vault. MCP (Model Context Protocol) is a JSON-RPC 2.0 standard that exposes tools, resources, and prompts to the AI — in this context, tools for reading, writing, searching, and querying your vault. Four architectural approaches, with different capability/complexity tradeoffs:

A. Filesystem MCP (no plugin, Obsidian can be closed)

The simplest starting point. No dependencies, works even when Obsidian isn't running:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/path/to/your/vault"
      ]
    }
  }
}

Limitations: no Dataview queries, no Obsidian command execution, no wikilink graph traversal. You get file read/write. Sufficient for 80% of use cases, but you'll hit the ceiling when you need to query "all active projects" or "notes tagged #decision from the last 30 days".

B. REST API Bridge (surgical edits, Dataview queries)

Requires the obsidian-local-rest-api community plugin and Obsidian running. The most feature-complete option (cyanheads/obsidian-mcp-server):

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "npx",
      "args": ["obsidian-mcp-server"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-from-plugin-settings",
        "OBSIDIAN_BASE_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_VERIFY_SSL": "false",
        "OBSIDIAN_ENABLE_CACHE": "true"
      }
    }
  }
}

cyanheads/obsidian-mcp-server gives you 14 tools: read, surgical PATCH (by heading, block reference, or frontmatter key), text search, Dataview DQL queries, and tag reconciliation. The PATCH capability is the one that matters — instead of rewriting entire notes, the agent updates the specific section that changed. Notes stay coherent.

Add a global kill switch if you want to protect against runaway writes:

OBSIDIAN_READONLY=true   # Read-only mode — disables all write tools

C. Obsidian Plugin as MCP Server (wikilink graph traversal)

Semantic Notes Vault MCP (semantic-vault-mcp) runs as an Obsidian community plugin serving MCP over HTTP at localhost:3001. Install via Obsidian's Community Plugins browser — search "Semantic Notes Vault MCP". Worth it for one capability the REST API bridge doesn't have: wikilink graph traversal. The agent can follow backlinks, find related notes, and reason about how concepts connect — not just read individual files.

claude mcp add -t http obsidian-graph http://localhost:3001/mcp \
  -H "Authorization: Bearer your-token-from-plugin-settings"

D. Semantic Search (obra/knowledge-graph)

For vaults above ~500 notes, keyword search and file reads start breaking down — too much to scan, not obvious what's relevant. obra/knowledge-graph indexes your vault as a proper graph with SQLite + vector search (local embeddings using Xenova/all-MiniLM-L6-v2, no API key required):

git clone https://github.com/obra/knowledge-graph.git
cd knowledge-graph && npm install
export KG_VAULT_PATH=/path/to/vault
npx tsx src/cli/index.ts index   # Run once, then incremental on changes

Ten MCP tools including graph path traversal, community detection, and PageRank centrality. The prove-claim capability is the most useful: decompose a claim → semantic search → path traversal → read evidence → cite. Ask "what patterns have we established for event versioning?" and get an answer grounded in your actual notes, not the model's training data.

Comparison

MCP server capabilities at a glance. Start with Filesystem; add layers as you hit their limits.

For most setups: filesystem MCP as always-on baseline + semantic-vault-mcp when Obsidian is running (for graph traversal and Dataview) + obra/knowledge-graph for semantic reasoning. Start with just the filesystem MCP and add layers as you hit their limits. Don't configure all three on day one.

kepano/obsidian-skills — The Right Starting Point

Before configuring any MCP server, install kepano/obsidian-skills — published by Obsidian CEO Steph Ango (12,900+ stars). Copy the repo contents into .claude/ at your vault root. This teaches Claude Code the actual Obsidian syntax: wikilinks, embeds, callouts, Properties format, Bases schema.

Without it, Claude will write syntactically valid Markdown that looks wrong in Obsidian's reading view — broken embeds, ignored callouts, malformed frontmatter. The skills are free, take five minutes to install, and eliminate an entire category of frustration.

Session Logging with Hooks

MCP configuration isn't where the real value is. The session log is. Every session where something important gets discovered — a non-obvious dependency, a failed approach, an architectural constraint — that knowledge should automatically end up in the vault.

Claude Code's Stop hook fires when the agent finishes a session. Wire it to write a structured session log:

{
  "hooks": {
    "SessionEnd": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/path/to/your/vault/.claude/scripts/session-logger.sh"
      }]
    }]
  }
}

The session logger script captures what actually happened:

#!/bin/bash

SESSION_DATE=$(date +%Y-%m-%d)
SESSION_TIME=$(date +%H-%M)
PROJECT=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "no-git")
FILES_MODIFIED=$(git status --porcelain 2>/dev/null | awk '{print $2}' | head -10)

VAULT_PATH="${VAULT_PATH:-/path/to/your/vault}"
OUTPUT_FILE="${VAULT_PATH}/AI/logs/${SESSION_DATE}-${SESSION_TIME}-${PROJECT}.md"

cat > "$OUTPUT_FILE" << EOF
---
type: session-log
date: ${SESSION_DATE}
project: "[[${PROJECT}]]"
branch: ${PROJECT}
status: completed
---

# Session ${SESSION_DATE} ${SESSION_TIME}

## Files modified
${FILES_MODIFIED}

## Open questions
<!-- Claude fills this in at session end -->

## Key decisions
<!-- Claude fills this in at session end -->
EOF

Stop hook stdout is printed to the terminal but is NOT injected into Claude's context. The agent cannot see hook output. The hook writes to the vault; you review in Obsidian. Don't expect the hook to feed information back to the agent in the same session — that's not how it works, and designing around that assumption breaks things.

For the agent to write to the session log itself — capturing the "open questions" and "key decisions" sections with actual content — it needs to do it explicitly before stopping, not via hook. The session protocol in CLAUDE.md handles this: the end-of-session ritual instructs Claude to write the summary and update hot.md before stopping.

The Three-Tier Memory Architecture

With this setup, vault memory operates at three levels. The distinction matters because each tier has different loading behavior.

Three-tier memory architecture. The agent decides what to load — unlike RAG pipelines that retrieve for you.

AI/scratch/ is working memory — current session only, ephemeral by design. Notes here either get promoted or deleted at session end.

AI/logs/ is episodic memory — timestamped records of what happened, queryable by Dataview. Not loaded automatically. The agent queries these when asked about past decisions.

AI/knowledge/ is semantic memory — distilled facts, verified patterns, project conventions, known constraints. This is what actually gets loaded at session start to eliminate cold-start. It's the tier you're building toward.

This maps onto the three-tier hierarchy from the MemGPT paper (arXiv:2310.08560): core memory (in-context, always loaded) → recall memory (episodic, queried on demand) → archival memory (semantic, indexed for retrieval). The key differentiator from RAG: in this setup, the agent decides what to load, via the session protocol you define in CLAUDE.md. RAG pipelines retrieve for you. This retrieves for itself.

The agent adds to semantic memory via synthesis: after several sessions on the same project, it distills recurring patterns into a knowledge note that lives at AI/knowledge/project-name-patterns.md. That note gets linked from hot.md, which means it's loaded automatically next session.

Navigation Files: Eliminating Cold Start

The cold-start problem isn't just about having notes. It's about having notes the agent can assess cheaply, without reading every file.

hot.md — The Most Important File

A ~500-word semantic snapshot of the current state of your work. The agent reads this first, every session, before anything else. At session end, it updates hot.md with what's changed. This single file eliminates most of the 40-minute re-orientation problem — instead of re-explaining your architecture, the agent reads a snapshot you built together over weeks of sessions.

# Hot Cache — updated 2026-05-13

## Current focus
- [[payment-module]] — adding dispute flow, blocked on [[settlement-service]] API changes
- [[outbox-relay]] — investigating 500ms poll lag under high load

## Recent decisions
- Rejected EventStoreDB in favor of Postgres JSONB — [[event-store-decision-2026-04]]
- OutboxRelayService polls every 500ms intentionally — [[outbox-design-rationale]]

## Open loops
- Settlement service team hasn't responded on API contract change
- Performance profile on EventStore under 10K concurrent payments still pending

## What next session needs
- Settlement saga dispute state hasn't been modeled yet
- [[payment-aggregate]] throws on PENDING → PENDING transitions — expected behavior

The wikilinks in hot.md are the real value. They're bidirectional — any note that links back to hot.md gets surfaced as a backlink, and the agent can follow them to read more context on demand.

Tiered Read Hierarchy

Loading the entire vault on session start would exhaust your context window before you typed the first message. The practical hierarchy:

1. hot.md — always first, ~500 words
2. Dashboard.md / index.md — catalog scan, find what's relevant
3. Domain sub-indices — narrowed scan within a project or area
4. Individual note bodies — maximum 3–5 per session, on demand

This is 2K–4K tokens for session start, not 20K. The difference compounds across every session.

index.md Per Folder

Every folder in 10-projects/active/ and 20-areas/ gets an index.md: a one-line summary of each note in the folder, maintained by the agent whenever it writes a new note. The agent scans the index before reading individual notes. This single pattern — index first, then individual reads — is the difference between a vault that helps and a vault that slows you down.

The Five Gotchas That Break This Setup

In roughly the order you'll hit them.

1. Markdown links instead of wikilinks

Claude defaults to [text](path) format. Every time it does this, the graph stays empty, backlinks break, and Obsidian Bases can't find the note. The fix is in CLAUDE.md — make it explicit, make it a rule, and include it in the example above. I got 200 notes into a vault before I noticed, and fixing them was miserable.

2. Filename constraints

Colons and slashes in note titles fail at the OS level. A note named GDPR: Article 17 Compliance creates a file called GDPR: Article 17 Compliance.md on macOS — fine — but breaks on Linux filesystems and inside Docker. Specify in CLAUDE.md: letters, numbers, hyphens, underscores, that's it.

3. Never let Claude rename files

Renaming updates the filename on disk but leaves every [[Note Old Name]] wikilink pointing at nothing. Obsidian's UI updates backlinks on rename. Claude's mv or Edit tool doesn't. Use Obsidian for renames. This is a "do not touch" rule, not a suggestion.

4. iCloud and Git fighting over the same vault

iCloud locks files during sync. Git locks files during operations. They conflict, and the result is silent corruption — a note that looks fine in Obsidian but has a .iCloud placeholder on disk that Claude reads instead of the actual content. Keep your personal vault on iCloud (never let Claude write here) and your AI workspace vault in a Git-tracked directory (Claude reads and writes freely, no iCloud). Use obsidian-git for automatic commit-and-sync from within Obsidian; it auto-commits every 10 minutes and handles .gitignore for .obsidian/workspace.json (which changes constantly and causes merge conflicts).

5. Frontmatter corruption from some MCP servers

A few MCP implementations rewrite the entire file on update, corrupting YAML headers with special characters or multi-line values. semantic-vault-mcp handles frontmatter safely. cyanheads/obsidian-mcp-server does surgical PATCH operations specifically to avoid this. If you're using a different MCP server and your frontmatter starts looking wrong after agent writes, that's why.

What I Got Wrong (And What I'd Do Differently)

The biggest mistake in my first vault was treating the AI integration as an add-on. I built the vault structure for human note-taking, then tried to layer Claude Code on top of it. The CLAUDE.md was an afterthought, two paragraphs long, with no session protocol and no linking rules. Every session, the agent made different assumptions about how the vault worked. Sessions were productive in isolation and produced noise in aggregate.

The second mistake was not adding the description field to existing notes before connecting Claude Code. The agent had to read hundreds of full note bodies to assess relevance. Sessions routinely consumed 15K+ tokens just on orientation.

The third mistake was configuring three MCP servers simultaneously on day one. The filesystem MCP is enough to start. Add the REST API bridge when you need Dataview queries. Add semantic search when your vault crosses 500 notes. Configuring all three before you understand what problems they solve adds complexity without adding value.

In my experience, teams that get this setup right build it incrementally: vault structure first, then CLAUDE.md, then session logging, then MCP servers as specific limitations emerge. Teams that configure everything at once spend a week debugging server conflicts and never develop the habit of writing to the vault consistently.

I learned each of these the hard way. You don't have to.