Brain Thing

A local knowledge base that connects your markdown notes to AI assistants via MCP.

You write in Obsidian (or any markdown editor). Brain Thing indexes your vault, builds semantic embeddings, and gives Claude direct access to search, read, create, and organise your entries — without uploading anything to the cloud.

Edit a note in Obsidian — Claude sees it in seconds. Create an entry through Claude — it appears in Obsidian immediately. Same .md files, no sync layer.

🖐️ Hold on!

This tool emerged as something I used for myself, and wasn't tested on Mac or Win 11, so in case of any issues, don't be shy - report it https://github.com/vovchisko/brain-thing/issues And indeed make a backup of your Obsidian Vault, if you use it.

Features

🔍 Semantic search — "find my notes about sourdough fermentation" works even if you never used those exact words. Brain Thing runs a local embedding model and matches by meaning.

📊 Structured queries — search by dates, numbers, tags, and custom fields with operators. One tool call, not a manual scan of your vault.

🏷️ Tag hierarchy — tags like work/task and cooking/bread/sourdough support prefix matching. Search work and get everything under it.

📁 Projects — group entries with a simple project field. Every tool supports project filtering. Say "create a note for Novel" and the AI sets the field automatically.

🔗 Backlinks — when Claude reads an entry, it sees which other entries reference it. Relationship graph without reading the whole vault.

📂 Auto-organise — map projects and tags to folders. The AI creates an entry → Brain Thing puts the file where it belongs. Obsidian sees the same folder structure.

🩺 Diagnostics — broken links, missing summaries, health checks — all as a tool call.

Install

1. Download the latest release from GitHub Releases — pre-built only for Windows (-setup.exe).

   • Mac / Linux users: build from source — see Development below. Pre-built Mac/Linux releases dropped because GitHub's free macOS Intel runner was deprecated and Apple Silicon-only builds excluded too many users to be worth maintaining the CI complexity.

2. Run the installer. The app isn't signed yet, so Windows will show "Unknown Publisher" — click More info → Run anyway.

3. On first launch, point Brain Thing to your vault folder.

4. It downloads the embedding model (~1 GB) and indexes everything.

Connect to Claude

Brain Thing auto-registers its MCP server in Claude Desktop and Claude Code on startup. Toggle in Settings → General → MCP, then restart Claude.

Once connected, the AI starts with a single look_around call that loads the full toolset and shows your vault overview.

For Obsidian Users

Brain Thing is Obsidian-compatible by data format — standard markdown with YAML frontmatter and [[wikilinks]].

What Brain Thing adds

Brain Thing manages a few core fields in every entry:

Your existing notes work as-is — Brain Thing reads whatever frontmatter is already there and won't rename or remove your fields.

You can also define custom fields (string, number, date, list) in Settings → Fields so the AI can follow your Obsidian habits. It sees them, can set them on create/update, and structured search uses type-aware operators.

Where files go

By default, new files are created in your vault root. To auto-sort them into folders:

Settings → Organise lets you map projects to folders (Novel → Novel/, Work → Work/Notes/) and add rules per project — for example, entries tagged novel/chapter go to Chapters/, entries with status: done go to Archive/. There's also a fallback for entries without a project.

This is purely file management. The AI works with entry names, not file paths.

Settings & sync

Brain Thing stores vault-specific settings (fields, ignore rules, organize config, features, guideline) inside your vault at .brain-thing/settings.json. The vector cache also lives in .brain-thing/vector-cache.

This means if you sync your vault across machines (Syncthing, Dropbox, etc.), your settings and embedding cache travel with it — same config everywhere, no re-indexing.

Machine-specific settings (server port, window position, embedding model) stay in the app's local data folder.

How it syncs

Brain Thing watches your vault folder for changes. Both directions are live:

• Create/Edit in Obsidian → AI sees the update right away
• Create/Edit through Claude → file appears in Obsidian immediately
• Rename updates all [[wikilinks]] across the vault, same as Obsidian does
• Settings changed on another machine → detected and applied automatically

No import/export, no conflict resolution needed. You can have both open side by side.

Why not just give Claude filesystem access?

Claude can read files, but a folder of markdown is just text. It would need dozens of reads and custom prompting to approximate what Brain Thing does in one tool call. Backlinks, tags, projects, and structured search aren't possible with a filesystem adapter.

Why not an Obsidian plugin?

Brain Thing runs as a standalone desktop app with its own HTTP server. The embedding model (~1 GB) runs in a separate process — in a plugin, this would freeze the editor. Claude needs a stdio process to connect to, which a plugin can't provide.

Under the Hood

MCP Tools (16)

Read & Search

Write & Organize

Data Format

Standard Obsidian-compatible markdown with YAML frontmatter:

---
project: MyProject
tags:
  - work/task
  - urgent
status: active
priority: 3
due: 2026-05-01
summary: Implement the new auth flow
created: 2026-03-15
modified: 2026-04-01
---

Task details here. Supports `[[wikilinks]]` to other entries.

Roadmap, maybe

• TTS narration — pipe matching entries to a text-to-speech engine. There's a working local XTTS v2 setup behind it already, but the server side isn't public yet. Future direction: either ship the local setup as a companion install, or wire it up to a hosted TTS service so people can actually use it.

Development

npm i
npm run dev
npm test

Build for yourself

npm run build:win
npm run build:mac