Obsidian + Claude Code: Give Your AI a Persistent Memory
The problem nobody talks about
Most people use Claude like a search engine:
- Ask a question
- Get an answer
- Close the tab when the usage limit hits
- Open a new chat tomorrow and start from zero
Here's what nobody tells you: Claude forgets everything the moment the session ends. Every preference you set, every decision you walked through, every architectural choice you made together, gone. Next session you're re-explaining your stack, your goals, and the blocker you solved last Tuesday. Again.
The usage cap isn't the limiter. The forgetting is.
The fix: make Obsidian Claude's external brain
Obsidian is a free local markdown notes app. Every note is a plain .md file on your hard drive. No cloud, no lock-in, no account. Because the files are plain markdown, Claude Code can read and write them natively, which means your Obsidian vault can double as Claude's persistent memory.
The loop becomes:
Before each session: Claude reads relevant notes from your vault so it walks into the conversation already knowing what you're building, what you prefer, and what decisions you've already made.
During the session: full context is already loaded. No re-explaining.
After the session: Claude writes a clean, structured note back to the vault capturing what changed, what was decided, and what's still open.
Next time you open Claude: it remembers.
Not because of cloud sync. Not because of a paid memory feature. Because your vault is acting as Claude's external brain, local, private, fully yours.
Once you feel the difference (opening a new chat and having your AI already know you're building a SaaS, you prefer clean code, you had a blocker last Tuesday, and you wanted to revisit pricing this week) you can't go back.
Why you should be doing this
- Stop repeating yourself. The cost of re-briefing Claude every session adds up to hours per week.
- Compounding context. Each session makes the next one smarter. Your assistant gets sharper over time, not reset every morning.
- Local and private. Your preferences, decisions, product strategy, and code notes never leave your machine.
- Portable across tools. The vault is plain markdown. If you ever switch from Claude to Cursor, Zed, or local Llama, your memory travels with you.
- Better than "custom GPTs" or paid memory tiers. Those lock you into a vendor, are opaque, and cap your storage. A local vault has none of those limits.
- It's the same pattern Claude Code uses for
CLAUDE.md. You're just scaling it up from one file per repo to a structured vault.
How to do it: step by step
Step 1. Install Obsidian
- Download Obsidian at obsidian.md.
- Create a new vault called something like
claude-brain. Pick a folder that syncs with iCloud, Dropbox, or Syncthing if you want it on multiple machines, but this is optional. - Inside the vault, create these starting folders:
claude-brain/
├── 00-index/
│ └── README.md ← pointer notes ("who I am", "current projects")
├── 10-projects/ ← one folder per active project
├── 20-preferences/ ← how you like code, tools, communication
├── 30-decisions/ ← architecture / design decisions with rationale
├── 40-sessions/ ← dated session logs Claude writes after each run
└── 50-snippets/ ← code patterns worth remembering
Step 2. Install Claude Code (the CLI)
# install via npm (requires Node 18+)
npm install -g @anthropic-ai/claude-code
# or via pip
pip install claude-code
Authenticate once with your Anthropic API key:
claude login
Step 3. Connect Claude Code to Obsidian via MCP
Claude Code speaks MCP (Model Context Protocol), the standard way to plug external tools into Claude. The Filesystem MCP server lets Claude read and write files anywhere you allow.
Create or edit ~/.claude/config.json (Mac/Linux) or %APPDATA%\Claude\config.json (Windows):
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/absolute/path/to/claude-brain"
]
}
}
}
Restart Claude Code. It now has read and write access to that folder, and only that folder.
Alternative: the dedicated Obsidian MCP server (gives you search, backlinks, and metadata on top of raw file I/O):
npm install -g @cyanheads/obsidian-mcp-server
Add to the same config:
"obsidian-advanced": {
"command": "npx",
"args": ["-y", "@cyanheads/obsidian-mcp-server"],
"env": { "OBSIDIAN_VAULT_PATH": "/absolute/path/to/claude-brain" }
}
Step 4. Write the "boot" notes
These are the notes Claude reads first every session. Keep them short. Context length is precious.
00-index/README.md, the top-level pointer:
# Start here
I am a [your role], working on:
- [[10-projects/saas-x]] — primary project
- [[10-projects/blog]] — secondary
Preferences:
- [[20-preferences/code-style]]
- [[20-preferences/communication]]
Open decisions / blockers:
- [[30-decisions/pricing-v2]]
- [[30-decisions/auth-stack]]
Before answering any question, read the relevant notes.
After this session, write a session log at 40-sessions/YYYY-MM-DD-brief.md.
20-preferences/code-style.md:
# Code style
- TypeScript over JS for anything > 50 lines
- Functions over classes unless state demands otherwise
- No inline comments unless explaining a non-obvious "why"
- Tests required for any business logic; UI tested manually
10-projects/saas-x.md:
# SaaS X
Stack: Next.js 15, Postgres, Stripe, Clerk
Goal: MRR $10k by Q3 2026
Current blocker: webhook retry semantics for failed Stripe events
Recent decisions: see [[30-decisions/]]
The pattern: short, linked, opinionated. Claude reads them the way a new hire reads a handbook.
Step 5. Define the session ritual
In Claude Code, start each session with a system prompt or a pasted opener:
Before anything else:
1. Read 00-index/README.md
2. Follow the [[wikilinks]] it points to that are relevant to my question
3. Then answer
At the end of this session, append a summary to 40-sessions/YYYY-MM-DD-<short-slug>.md with:
- what we worked on
- decisions made
- open questions
- links to any notes you updated
Even better: save this as a reusable slash command at ~/.claude/commands/brain-session.md:
Start a brain-connected session.
1. Read /absolute/path/to/claude-brain/00-index/README.md
2. Follow relevant wikilinks
3. Answer the user's first question
4. At end, append a session log to claude-brain/40-sessions/$(date +%Y-%m-%d)-session.md
Now typing /brain-session auto-primes Claude with your full memory.
Step 6. Let Claude write back
After Claude answers, end the turn with:
"Before we wrap: update any notes that are now outdated, and write a session log with what we decided."
Claude will:
- Patch
10-projects/saas-x.mdif you agreed on a new stack piece - Create
30-decisions/2026-04-19-stripe-retry-policy.mdif you made a decision - Append to
40-sessions/2026-04-19-stripe.mdwith the summary
Next time you open Claude: the vault has grown, and Claude reads the new state.
Step 7. (Optional) Sync across devices
If you want the same brain on your laptop, desktop, and phone:
- iCloud / Dropbox / OneDrive: put the vault folder inside a synced folder. Works fine.
- Obsidian Sync: paid ($4/mo), end-to-end encrypted, Obsidian-native.
- Syncthing: free, peer-to-peer, no cloud.
Claude Code always points at the local path. Sync is a separate concern.
Step 8. Guard against drift
- Once a week, have Claude read the whole
40-sessions/folder and write aweekly-digest.mdso the vault doesn't turn into a pile of session logs. - Once a month, ask Claude to audit
30-decisions/for contradictions. - Keep
00-index/README.mdunder 200 lines. If it grows, split into sub-indexes.
Architecture at a glance
┌───────────────────────────────────────────────────────────┐
│ │
│ You ─── prompt ────▶ Claude Code │
│ │ │
│ │ (reads via MCP) │
│ ▼ │
│ ┌────────────────────┐ │
│ │ Obsidian vault │ │
│ │ (plain markdown) │ │
│ │ │ │
│ │ 00-index/ │ │
│ │ 10-projects/ │ │
│ │ 20-preferences/ │ │
│ │ 30-decisions/ │ │
│ │ 40-sessions/ │ │
│ │ 50-snippets/ │ │
│ └────────────────────┘ │
│ ▲ │
│ │ (writes via MCP) │
│ │ │
│ You ◀── answer ─── Claude Code │
│ │
└───────────────────────────────────────────────────────────┘
The vault is the source of truth. Claude is the interface that reads from it, reasons over it, and writes to it.
One rule nobody tells you
Curate, don't hoard. The temptation is to write everything into the vault. Don't. Claude's context window is not infinite, and even with Opus 4.7's long context, noisy notes degrade the signal. Keep each note focused: one project, one preference, one decision. If a note grows past a screen, split it.
The vault is a memory, not a landfill.
What changes once you have this
Before:
You: "I'm building a SaaS in Next.js with Stripe and Clerk..."
Claude: "Great, let me help. What's your question?"
After:
You: "Why is my webhook retry firing twice?"
Claude: "Based on [[10-projects/saas-x]] and your prior decision in [[30-decisions/stripe-retry-policy]], you're using exponential backoff with jitter. The double-fire is likely because..."
That difference is the whole point. Your AI stops being a search engine and starts being a colleague who remembers you.