finally thinking.
Claude forgets everything between sessions. Here is how Obsidian fixes that without burning your token budget.
Every developer who has used Claude Code on a multi-week project has hit the same wall. New session, same project, and Claude asks you to re-explain something you spent three hours documenting two weeks ago. Context rot is not a bug. It is the default behavior.
The obsidian claude ai developer workflow is the pattern a growing number of developers are using to solve this. It is not complicated: Obsidian holds the persistent memory, and Claude reads from it at the start of every session via a file called CLAUDE.md. The result is a development environment that remembers what you have already decided.
This post is the practical setup guide. No theory. Just the two approaches, the real cost difference between them, and which one to use.
What is Claude Code's session amnesia problem?
Claude Code has no persistent memory between sessions. When you close a session and open a new one, you start from a blank slate. The model has no knowledge of your architecture decisions, your preferred naming conventions, your in-progress refactor, or the three-page design doc you wrote last Tuesday. Every session is day one.
For short, self-contained tasks, this is fine. For long-running projects spanning weeks, it compounds. You re-explain. Claude suggests approaches you already ruled out and documented. You spend tokens on context that should be free. The work gets slower, not faster, as the project matures.
This is the session amnesia problem. It is not unique to Claude Code. Any stateless LLM session has it. What is different here is that Claude Code has a built-in mechanism to address it, and most developers do not use it.
What is CLAUDE.md and why does it matter?
CLAUDE.md is a markdown file that Claude Code reads automatically at the start of every session in a project directory. It is the project briefing file. Whatever you put in it, Claude has at session start without you typing a word. Put your architecture decisions there. Put your naming conventions, your open questions, your in-progress work, your "do not touch" list.
The file lives at the root of your project directory. Claude Code looks for it there and loads it before the conversation starts. It is not a feature you configure. It is always on. The question is only whether you have bothered to write anything useful in it.
Most developers who use CLAUDE.md write it by hand and update it manually. That works, but it introduces a new problem: the CLAUDE.md file drifts from your actual project notes. You document something in your note-taking system and forget to update the file. The briefing gets stale.
[PERSONAL EXPERIENCE] The pattern that actually sticks is using Obsidian as the source of truth and treating CLAUDE.md as a compiled output of that source. You update your vault notes normally, and CLAUDE.md stays current because it draws from the same place you always write things down.
MCP vault search: ~7 million tokens. CLI grep search: ~100 tokens. Same result, 70x cheaper. Per buildmvpfast.com analysis.
How does Obsidian connect to Claude? MCP vs CLI
There are two real approaches for connecting an obsidian claude ai developer workflow. The difference between them is not a minor implementation detail. It is a 70x cost difference per search, and it matters at scale.
Approach 1: Obsidian MCP server
The MCP (Model Context Protocol) approach lets Claude read and write to your Obsidian vault directly through an MCP server connection. It is technically elegant. Claude can query vault contents, update notes, and create new ones without you leaving the session. The integration feels seamless.
The cost is the problem. According to buildmvpfast.com's token cost analysis, each vault search via MCP costs approximately 7 million tokens. That is not a typo. The MCP server loads vault context into the model window to perform the search, and with a moderately sized Obsidian vault, that context load is enormous. For developers on usage-based billing, this adds up fast.
The Obsidian CEO has also publicly expressed skepticism about MCP for vault access, citing concerns about third-party integrations having read/write access to personal knowledge bases. That is a reasonable concern for a tool where many developers store private notes, client information, and personal logs alongside project documentation.
Approach 2: Claude Code with CLI search
The CLI approach keeps the Obsidian vault as a flat directory of markdown files and uses grep or rg (ripgrep) to search it from Claude Code's command context. Claude reads specific files on demand rather than loading the entire vault.
The cost is approximately 100 tokens per search, per the same buildmvpfast.com analysis. That is 70 times cheaper than the MCP approach for the same query. At that cost, you can afford to search your vault frequently without watching your token budget.
The practical setup is straightforward. Your Obsidian vault needs a flat folder structure where AI-relevant notes are easy to locate with a single rg command. Claude Code can then grep the vault directly in session. The CLAUDE.md file at the project root links specific vault notes for immediate loading, and Claude can search broader vault context as needed.
[UNIQUE INSIGHT] The flat folder argument is not about preference. Deep hierarchies with nested subfolders create grep patterns that fail or return too much noise. A flat structure where project notes, decision logs, and architecture docs sit in one predictable directory makes CLI search reliable enough to use in production workflows.
How do you set up the Obsidian Claude workflow in practice?
The setup has four parts. None of them require anything beyond what you already have if you use Obsidian and Claude Code.
First, flatten the relevant section of your vault. You do not need to restructure everything. Create one directory for project-related notes that Claude might need to search: architecture decisions, conventions, open questions, meeting notes, design docs. Keep that directory flat.
Second, write a CLAUDE.md at each project root. This file should include: a one-paragraph project summary, current sprint focus, any architectural constraints Claude must know, links to the specific vault files most relevant to this project, and a list of things Claude should never do in this codebase (your "do not touch" list). The DEV Community post by mibii ("Claude Code + Obsidian: Build a Second Brain That Actually Thinks") goes into more depth on structure options.
Third, set a habit of updating vault notes before closing each session. Write what you decided, what you deferred, and what Claude should know about next session. Treat the vault as the session handoff document. This is the discipline that makes the whole system work. The CLAUDE.md is only as good as the vault notes it points to.
Fourth, test the search cost before committing to either approach. Run a Gemini CLI query against your vault (free tier, 60 requests/minute) to verify grep patterns work cleanly before wiring Claude Code to search it. Fix the structure if the results are noisy. Getting the search right first saves significant debugging later.
Is the Obsidian Claude stack worth building?
If you use Claude Code on projects that last more than one week, yes. The session amnesia problem is real and it compounds. Re-explaining context is not just annoying; it burns tokens and produces worse results because the model is working from partial information.
The setup cost is an afternoon. One flat vault directory, one CLAUDE.md per project, one session-closing habit. The ongoing maintenance is writing notes you should be writing anyway. You are not adding a new system. You are wiring two systems you already use to talk to each other.
The developers who report the best results describe the combination as finally having a development environment with a memory. Not perfect memory, but consistent memory. Claude knows what you decided last session. It does not suggest the pattern you already ruled out. It picks up where you left off.
That is not a small thing. That is the difference between a tool and a workflow.
Frequently Asked Questions
What is Claude Code's session amnesia?
Claude Code resets context at the end of every session. When you open a new session, the model has no memory of previous conversations, decisions, or code you discussed. This is the default stateless design of LLM sessions. On long-running projects, it means repeatedly re-explaining context that should persist automatically. The CLAUDE.md file is the standard workaround.
What goes in a CLAUDE.md file?
A project summary in one paragraph, the current sprint or focus area, architectural constraints Claude must follow, file naming and coding conventions, links to relevant vault notes or docs, and a list of things Claude should avoid in this specific codebase. Keep it under 500 words so it loads efficiently. Update it at the end of each session as part of your close-down routine.
Why is MCP so much more expensive than CLI grep for vault search?
MCP loads vault content into the model's context window to perform searches. With a typical Obsidian vault, that context load is enormous. Buildmvpfast.com's analysis puts it at approximately 7 million tokens per search. CLI grep reads specific files on demand without loading the full vault, costing around 100 tokens per search. For most developers, CLI is the right default.
Does the obsidian claude workflow work with any Claude plan?
Yes. CLAUDE.md is a Claude Code feature available on all plans. The CLI search approach works regardless of plan because you are running grep in your terminal, not using model tokens for the search itself. The MCP approach requires an MCP server setup and may interact differently with rate limits depending on your plan. Start with CLI.
How should I structure my Obsidian vault for AI readability?
Flat beats deep. Keep AI-relevant notes in one or two top-level directories with descriptive file names. Avoid nesting project notes more than two levels deep. Use consistent naming patterns so grep queries are predictable. You do not need to restructure your entire vault, only the sections Claude will search. The rest can stay organized however you prefer.
