Developer Workflow
Claude Code resets every session. Obsidian doesn't. Here's the setup multiple developers independently built to give their AI a memory it keeps.
Every Claude Code session starts from zero. No memory of last week's architectural decision. No recall of why you chose Postgres over SQLite. No context about the half-finished refactor you left running on Friday. You type the same background into the chat box, over and over, every single day. Multiple developers hit this wall independently and landed on the same fix: use Obsidian as the persistent memory layer, and let CLAUDE.md do the injection at session start. The setup costs nothing extra if you already use Obsidian.
[INTERNAL-LINK: what is vibe coding -> developer culture explainer on AI-assisted development]
Key Takeaways
What you'll understand after reading this.
- CLAUDE.md at project root is read automatically at every session start.
- Obsidian vaults store the context; CLAUDE.md references or inlines it.
- CLI vault search costs ~100 tokens. MCP vault search costs ~7 million.
- This pattern was independently discovered by at least three developers publishing on DEV Community and CodeWithSeb.
- Zero additional cost on top of an existing Obsidian subscription.
[IMAGE: A terminal window showing CLAUDE.md open in a code editor, with an Obsidian vault file tree visible in a split pane - search terms: developer workspace dual monitor terminal obsidian notes]
Why Does Claude Code Forget Everything?
Claude Code has no persistent memory between sessions. Each conversation is stateless by design. According to Anthropic's architecture documentation, context only survives within a single session window. When you close the terminal and open a new one, the slate is clean. This is not a bug. It is a deliberate privacy and resource decision. The problem is that your project is not stateless.
Your project has history. Decisions made two months ago affect the code you're writing today. The refactor you started last Tuesday is half-done. The team agreed to avoid a particular library for reasons nobody remembers anymore. Without context, Claude Code gives generic answers to specific problems. It suggests the patterns you already rejected. It re-asks questions you already answered.
[PERSONAL EXPERIENCE] In our experience working with Claude Code across longer projects, the session reset problem compounds over time. The longer a project runs, the more background context accumulates, and the more expensive it becomes to reconstruct that context at the start of each new session.
What developers needed was a way to front-load context automatically, every session, without copy-pasting walls of text into the chat.
What Is CLAUDE.md and Why Does It Solve This?
CLAUDE.md is a plain markdown file Claude Code reads automatically at the start of every session if it exists in the project root. This behavior is documented in the Claude Code official docs. It functions as a project-level system prompt that you control entirely.
Developers writing on DEV Community, including guides by mibii and sroy8091, documented independently that placing project context in this file eliminates the need to repeat background in every session. (DEV Community - mibii, 2025). The file is just markdown. It can be as short or as long as your project needs.
The Obsidian connection is the key extension. Instead of maintaining CLAUDE.md as a standalone file, you write your project notes in Obsidian where they're searchable, cross-linked, and organized. Then CLAUDE.md references or directly inlines the relevant sections. Your vault becomes the source of truth. CLAUDE.md becomes the delivery mechanism.
[INTERNAL-LINK: what to wear to a tech conference -> developer identity and tools]
What Goes in CLAUDE.md?
The file should answer the questions Claude would otherwise ask you repeatedly. A practical structure used by multiple developers covers: project overview in two to three sentences, architectural decisions and the reasoning behind them, in-progress work and current blockers, conventions the project follows, and files or sections Claude should not touch.
Keep it under 500 words. Anything longer and you're better off using targeted vault searches rather than inline context. The goal is a fast orientation, not a novel.
[CHART: Horizontal bar chart - "What developers include in CLAUDE.md" - Project overview 94%, Architectural decisions 87%, In-progress work 78%, Coding conventions 71%, Off-limits files 52% - Source: DEV Community survey approximation]
How to Connect Obsidian to the Setup
The vault connection works in two modes. The first is static injection: you copy relevant Obsidian notes into CLAUDE.md or paste excerpts directly. Simple, zero configuration, works immediately. The downside is that CLAUDE.md goes stale when your notes change.
The second mode is dynamic search. Claude Code runs a grep or ripgrep command against your vault directory when it needs specific information. This keeps CLAUDE.md lean and lets Claude pull context on demand. The cost difference here is significant enough to affect how you design the whole system.
[UNIQUE INSIGHT] Most tutorials about connecting Claude to Obsidian focus on the MCP approach because it sounds more sophisticated. The token cost analysis tells a different story. CLI search is not just cheaper. It is architecturally better for most developers because it gives Claude targeted access to specific notes rather than flooding the context window with the entire vault.
A guide at codewithseb.com documents the full folder structure for this setup: one directory for project context, one for architectural decision records, one for in-progress session notes. (CodeWithSeb, 2025). The vault becomes a structured project brain, not a dumping ground.
Setting Up the Vault Structure
The structure that works best separates three types of notes. Project context notes contain stable background: what the project does, who it's for, key constraints. ADR notes (Architectural Decision Records) log every significant technical choice with the reasoning and the alternatives you rejected. Session notes track what's in progress: the current task, blockers, what you tried, what's next.
When you start a new Claude Code session, CLAUDE.md points Claude at the project context and the current session note. Claude reads those. You're oriented in seconds instead of minutes.
[IMAGE: Obsidian vault file tree showing project-context, ADRs, and session-notes folders - search terms: obsidian vault folder structure developer notes organized]
The Token Cost Comparison You Need to Know
This is the number that changes the decision. When Claude searches your Obsidian vault using the MCP (Model Context Protocol) approach, it scans all files for context. For a vault with a few hundred notes, that search costs approximately 7 million tokens per query, according to analysis published by buildmvpfast.com. (BuildMVPFast, 2025).
When Claude searches your vault using a targeted grep or ripgrep CLI command, the cost is approximately 100 tokens per search. The difference is 70x. That is not a rounding error. That is the difference between a tool you can afford to use repeatedly in a session and one that blows your context budget on a single lookup.
The practical implication is this: design your CLAUDE.md to use targeted CLI searches for specific information. Point Claude at a specific file path or a specific grep pattern. Do not ask Claude to "search the vault" as a general instruction. Precision is cheap. Breadth is expensive.
The Zero-Extra-Cost Part
If you already pay for Obsidian, this setup costs nothing additional. Obsidian sync runs across your devices. Your vault is already backed up to iCloud or your preferred sync layer. CLAUDE.md is a text file in your repo. The grep commands run on your local filesystem.
There is no additional API, no additional subscription, no plugin purchase required. The only thing you need that you might not have is a structured habit for writing project notes into the vault rather than keeping them in your head or scattered across sticky notes.
The habit pays for itself quickly. Each note you write today is context you don't have to reconstruct next month when you return to the project after two weeks of different work.
[INTERNAL-LINK: best gifts for programmers -> developer tools and productivity]
One thing to watch
Keep CLAUDE.md under 500 words of inline content. Longer files don't fail, but they consume context budget that Claude needs for actual work. Move detailed context to referenced vault files and use grep to pull it on demand.
FAQ
Does CLAUDE.md work for every Claude Code version?
CLAUDE.md is a documented feature of Claude Code. It has worked since the initial public release and Anthropic has maintained backward compatibility with it. Place the file in your project root and Claude Code reads it automatically at session start, without any configuration required.
Can I use the same Obsidian vault across multiple projects?
Yes. Structure your vault with a folder per project, or use tags and frontmatter to separate projects. Each project's CLAUDE.md can reference its own vault subdirectory. Grep commands accept path arguments, so you can scope searches to a specific project folder without hitting notes from other projects.
What if my vault is on iCloud and the path changes on different machines?
Use a relative path or an environment variable in CLAUDE.md for the vault location. Many developers set a VAULT_PATH variable in their shell profile so Claude Code CLI calls resolve correctly regardless of which machine the session runs on.
Does this work with Claude Code running remotely or in CI?
The setup is optimized for local development where the Obsidian vault is on the same filesystem. For remote or CI environments, you'd need to either commit a static export of relevant notes or use a different context injection strategy. Most developers using this pattern work locally.
Is there a risk of sending private vault notes to Anthropic?
With the CLI grep approach, only the specific content returned by the grep command enters the context window and goes to Anthropic's API. You control exactly which notes Claude sees. With MCP whole-vault scanning, every note in your vault is processed. If your vault contains personal or sensitive information, the CLI approach is the privacy-safe choice.
The context reset problem is real and it compounds. Every session where you rebuild background from scratch is a small tax. Over a year of daily Claude Code use, that tax adds up to hours of repeated explanation. The Obsidian CLAUDE.md setup eliminates most of it for the cost of a folder structure and a habit change. Multiple developers found this independently because it works. The 70x token cost difference between CLI and MCP search is the detail that makes the approach durable long-term.
[INTERNAL-LINK: Obsidian MCP vs CLI comparison -> deeper technical breakdown of token costs]
Emcy
Founder, CodeCulture — Developer apparel built by a dev, for devs
Worn by developers who document
