Give Claude a Memory with Obsidian

Claude is genuinely useful for engineering work — debugging, drafting configs, talking through architecture. But close the tab and it forgets everything. Next session, you're starting from scratch.

That's by design. Each conversation is stateless. For one-off tasks that's fine, but for anything with continuity — an ongoing incident investigation, a multi-sprint project, a production system you're iterating on — you end up re-explaining yourself every single time. It gets old fast.

Here's how I fixed it: Obsidian.

The Problem

Claude has no persistent memory between conversations. Anthropic does have a built-in memory feature, but it's automatic and opaque — you can't tell it "remember that this service uses a non-standard health check endpoint" and trust that detail to surface when you need it three weeks later.

For anything with real depth — a multi-sprint project, an evolving system design, production context that takes five minutes to re-establish — that's friction you feel every session.

Why Obsidian

Obsidian is a note-taking app built on plain Markdown files stored locally. No proprietary format, no cloud lock-in. Your notes are just .md files in a folder — version-controllable with Git, readable by anything, and as durable as your filesystem.

That's the key detail: if your notes are Markdown files and Claude can read Markdown files, your notes become something Claude can work with directly.

Why It Works for Engineering Context

Think about what you actually want Claude to carry between sessions: the decisions made in last week's architecture review, which approach you already ruled out and why, the quirks of a legacy service you're refactoring, the Jira tickets driving the current sprint.

That's exactly what a well-maintained set of notes contains. The pairing works because:

• You control the content. You decide what's written down. Claude reads what you give it, not some auto-generated summary you can't inspect or correct.
• It's bidirectional. Claude can read your notes and write to them — appending a decision log, updating ticket status, creating a dated session summary.
• It's persistent. Notes survive closed tabs and weeks of inactivity. Context is always there when you come back.
• It's transparent. No black box. Everything Claude knows from your vault, you can read yourself.

A concrete example: I keep a note for each active project — current status, architecture decisions, open questions, links to relevant tickets. When I open a new Claude session, I point it at the note. It immediately has everything it needs. No re-briefing, no copy-pasting Jira descriptions, no "let me remind you where we left off."

Setting It Up

Two components: an Obsidian plugin that exposes your vault via a local REST API, and an MCP server that connects Claude Desktop to it.

Step 1: Install the Obsidian Local REST API Plugin

In Obsidian, go to Settings > Community Plugins > Browse and search for Local REST API. Install and enable it.

The plugin starts a local HTTP server on port 27124 that exposes your vault over REST — read, search, write, all over localhost. Grab the API key from the plugin settings.

It supports HTTPS on port 27124 (self-signed cert) or plain HTTP on 27123. Either works for local use.

Step 2: Configure the MCP Connection

Claude Desktop (macOS/Windows) — add to your MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "obsidian-mcp",
        "https://127.0.0.1:27124",
        "YOUR_API_KEY_HERE"
      ]
    }
  }
}

Replace YOUR_API_KEY_HERE with the API key from the plugin settings.

Claude.ai (Web) — While technically possible to expose the Obsidian MCP over the internet, I haven't landed on a solution that clears corporate security requirements. I'll be addressing this in a separate project soon.

Step 3: Verify

Ask Claude to list the files in your vault root. If the MCP is connected, it'll return your folder structure. If not, check the API key and confirm Obsidian is running — the REST API only works while the app is open.

How to Use It

Scope Your Notes to What Makes Sense

Notes don't have to be one-size-fits-all. You can keep broad reference notes that apply globally across everything you work on — team conventions, service ownership, deployment topology — or you can keep them tightly scoped to a specific project, ticket, or task. Just tell Claude which note (or notes) to read at the start of a session and it'll calibrate accordingly. A note named PROJ-4821.md with context specific to that ticket is just as valid as a general auth-service.md covering the whole system.

Project Context Notes

For any active project, keep a dedicated note: status, repo, tech stack, architecture decisions, open questions, links to relevant tickets. Point Claude at it at the start of a session and skip the re-briefing entirely.

Template I use:

# Project Name

**Status:** [Active / On Hold / Done]
**Repo:** org/repo
**Last Updated:** YYYY-MM-DD

## Architecture
[Key decisions and rationale]

## Open Questions
[Unresolved design or implementation questions]

## Issues Resolved
[What broke, root cause, fix]

## Pending
- [ ] PROJ-123: Thing 1
- [ ] PROJ-456: Thing 2

Session Logs

At the end of a session, ask Claude to summarize what was decided and append it to the project note. "Summarize what we just worked through and append it to the auth-service note under a Session Log section." Next time you pick it up, that context is waiting.

Reference Notes

Anything you explain to Claude more than once belongs in a reference note. Service ownership and dependencies. Team conventions. Architectural constraints. Deployment topology. Write it once, reference it when relevant.

A Few Tips

Keep Obsidian running. The REST API only works while the app is open.

Structure deliberately. I use top-level folders like Projects/, Services/, Architecture/, Work/. Clean enough to navigate, specific enough to be useful.

Review what Claude writes. Claude writing to your vault is useful but deserves a sanity check. It's a collaborator, not ground truth.

Use frontmatter for metadata. Status, tags, last-updated — frontmatter YAML is readable by the MCP and useful for filtering.

The Bottom Line

Claude's stateless nature is a real limitation for sustained engineering work. Obsidian's plain-Markdown, local-first approach is a natural fix. Wire them together and you get a persistent context layer you fully own and control.

Sessions pick up where they left off. You stop re-explaining your stack to a tool that should already know it. The more you use it, the more useful it gets.