Introducing MindCache

Every conversation with an AI assistant starts from zero. You explain your project. You repeat the decision you made last week. You paste three paragraphs from a note you wrote a month ago. Your AI has no memory of any of it, because it can't see where you keep your knowledge.

I use Obsidian for everything — project notes, architectural decisions, meeting summaries, learnings, ideas. It's my second brain. But every time I start a Claude Code session, that brain is invisible. I'm the bridge between two tools that should already be connected.

I built MindCache to make that bridge disappear. It's an open-source MCP server that gives AI assistants direct access to your Obsidian vault. Two commands, no plugins, and your AI can search, read, and write to your notes.

The Problem

The gap between personal knowledge and AI tools is wider than it looks. It's not just about search — it's about context. When I ask Claude to help me design an auth system, it doesn't know that three weeks ago I wrote a decision record explaining why I chose JWT over sessions. It doesn't know I have meeting notes from a conversation where we decided to prioritize stateless architecture. It doesn't know any of this, so it gives me generic advice instead of building on what I've already decided.

The workaround is copy-paste. Find the relevant note, select the relevant section, paste it into the conversation. For one note, that's fine. For the accumulated context of a real project — decisions, constraints, prior art, open questions — it's a tax on every session.

CLAUDE.md files help for project-specific context, but they don't cover your broader knowledge. Your learnings from a previous project. Your preferences. The meeting note from Tuesday. The idea you captured on your phone. That's vault knowledge, and it lives in Obsidian.

The Design

MindCache is an MCP server. The Model Context Protocol is an open standard that lets AI assistants connect to external tools — and Claude Code, Claude Desktop, and Cursor all support it natively.

The first design decision was to read the vault directly from the filesystem. Your Obsidian vault is just a folder of markdown files. There's no reason to add a plugin dependency, an API layer, or a database between the AI and your notes. MindCache opens the files, reads them, searches them, and writes to them. Obsidian watches the folder and picks up changes automatically.

This means MindCache works even when Obsidian isn't running. It means there's nothing to install inside Obsidian. And it means reads are as fast as your disk — microseconds, not milliseconds.

The second design decision was to organize tools around how people actually think about their knowledge: finding things, reading things, capturing things, and connecting things. Not around API primitives.

What You Get

MindCache exposes 40 tools to your AI assistant, organized into nine categories.

Find is the entry point. Full-text search with multi-word fuzzy matching. If you search for "auth decision JWT", it finds notes containing any of those words, scores them by relevance, and ranks recent notes higher. There's also an ask tool — a natural language query that searches your vault and returns the content of matching notes so the AI can synthesize an answer.

Read lets the AI access your notes directly. Read a full note, a specific section under a heading, or just the frontmatter. It can read today's daily note, this week's daily notes, or the currently active file.

Remember is where MindCache starts giving back. Seven tools for capturing knowledge with structure — quick thoughts, meeting notes, decision records, ideas, learnings, people notes, and bookmarks. Each one uses a template with frontmatter and consistent formatting, so your vault stays organized even when your AI is writing to it.

Journal appends timestamped entries to your daily note. "Log that I deployed v2 to staging" adds a line under today's date with the time. There's also a task tool that adds checkbox items.

Write handles note creation with templates, appending to existing notes, and replacing content under specific headings.

Connect is about the knowledge graph. It suggests links between notes based on shared tags and content. It finds broken links — concepts you reference but haven't written about. It finds orphan notes that aren't connected to anything.

Organize handles tags, frontmatter properties, renaming, and moving notes between folders.

Understand gives you a bird's-eye view. Vault statistics, tag distribution, folder structure. Useful for understanding what you've accumulated.

Tasks finds checkbox items across your vault and lets the AI mark them complete.

The Search

Search quality is what makes or breaks a tool like this. A naive substring match won't find "that auth thing from last month" because you titled the note "Decision - JWT vs Sessions."

MindCache scores matches on multiple signals. Exact phrase matches score highest. Individual word matches contribute proportionally — a note containing three out of four query words ranks higher than one containing only one. Title matches get a significant boost, because a note named after your query is almost certainly what you want. And recent notes score higher than old ones, because the thing you wrote yesterday is more likely relevant than the thing you wrote a year ago.

The file listing is sorted by modification time, so find_recent actually shows your most recently edited notes first. A filesystem watcher invalidates the cache when files change, so edits in Obsidian are reflected immediately in MindCache queries.

The Architecture

The entire server is a single TypeScript file that compiles to a 54KB bundle. It has two runtime dependencies: the MCP SDK and Zod for schema validation. It runs via npx — no global install, no build step, no Docker.

Configuration is a YAML file with one required field: the path to your vault. Everything else has sensible defaults.

vault: ~/Documents/Obsidian Vault

daily_notes:
  folder: Daily
  format: YYYY-MM-DD

The server communicates with Claude Code over stdio — the standard MCP transport for local tools. It starts in under a second, uses minimal memory, and exits cleanly on SIGINT.

Templates for note creation are bundled with the package — ten defaults covering decisions, meetings, learnings, ideas, people, projects, books, articles, weekly reviews, and session logs. They use {{variable}} substitution with built-in date variables.

What It Doesn't Do

MindCache doesn't do semantic search. It can't find notes "about scaling" if the word "scaling" never appears. That requires embeddings, and embeddings require either a local model or an API call. It's on the roadmap, but the keyword-based search works well enough for most vaults, and I'd rather ship something useful now than wait for something perfect.

It also can't detect the active note in Obsidian — that would require a plugin, which contradicts the zero-dependency design. If you need to reference what you're currently looking at, use search or read_note with the path.

Try It

npx @augmnt-sh/mindcache init
claude mcp add --scope user mindcache -- npx @augmnt-sh/mindcache@latest

First command configures your vault path. Second command registers MindCache with Claude Code across all your projects. After that, your AI knows what you know.

The --scope user flag means MindCache is available in every project, not just the current one. Your vault is project-agnostic — your knowledge doesn't live in a single repo.

It's MIT licensed. No cloud, no accounts, no telemetry. Your notes stay on your machine.

→ usemindcache.com · GitHub · npm