obsidian-brain

Give your vault a memory that actually understands what you wrote. Type a question and get real answers grounded in your own notes. Ask your AI assistants questions and they’ll draw from the same notes you just wrote. Share selectively with a community knowledge base.

---

What this plugin does, in plain English

You write notes in Obsidian. This plugin does three things with them:

1. It understands them. Press ⌘⇧B and type what you’re looking for. Instead of matching keywords, it finds notes that mean something similar to your question — even if you used different words. Press ⌘⇧K instead and you’ll get a Q&A view that pulls together the relevant passages across your whole vault.

2. It shares them with your AI tools. Claude Code, Codex CLI, Gemini CLI and other MCP-speaking assistants can read (and write) the same notes you see in Obsidian. No more re-explaining context at the start of every session — your agent already knows what you decided last week.

3. It connects you to a bigger brain. Optionally pull research, patterns, and solutions from the shared pi.ruv.io knowledge base — or publish your own notes back to it when you want to contribute. Everything is scanned for prompt-injection and personal data before it’s stored.

It does not replace your vault. Your notes stay as Markdown files you own. The plugin adds a fast, semantic index on top — one that your other tools can share.

---

Five-minute setup

1. Install the plugin (via BRAT — easy beta install)

1. Inside Obsidian, install the BRAT community plugin.
2. Open the command palette, run BRAT: Add a beta plugin for testing, and paste ruvnet/obsidian-brain.
3. Go to Settings → Community plugins → Installed and enable RuVector Brain.

(Alternatively, download main.js, manifest.json, and styles.css from the latest release and drop them into /.obsidian/plugins/obsidian-brain/.)

2. Start the brain and embedder

The plugin is intentionally thin — it talks to two small background services that do the heavy lifting. One call gets you both:

git clone https://github.com/ruvnet/RuVector
cd RuVector
cargo build --release -p mcp-brain-server --features local --bin mcp-brain-server-local
./target/release/mcp-brain-server-local &          # the "brain"
ruvultra-embedder &                                 # the embedder

Both listen only on your own machine (127.0.0.1). Nothing talks to the internet unless you explicitly turn on the pi.ruv.io integration.

Prefer a managed setup? Copy systemd/*.service into ~/.config/systemd/user/ and run systemctl --user enable --now ruvector-brain ruvector-embedder.

3. Point the plugin at them

Settings → RuVector Brain → Test connection. If it says “Brain OK” and “Embedder OK”, you’re done. Open any note, then press ⌘⇧B and start typing — results update as you type.

4. Index what you already have

Command palette → Brain: Bulk-sync vault → brain. Every note is scanned for prompt injection, embedded, and stored. Unchanged notes are skipped on re-runs.

---

What you can do with it

---

How it fits together

                   ┌──────────────────────────────────────┐
                   │           Obsidian vault             │
                   │  ┌─────────────────────────────┐     │
                   │  │  obsidian-brain plugin       │     │   you
                   │  └─────────────┬───────────────┘     │
                   └────────────────┼─────────────────────┘
                                    │  local HTTP
                                    ▼
                   ┌──────────────────────────────────────┐
                   │   RuVector brain (on your machine)    │
                   │  • Vector search (DiskANN)            │
                   │  • Prompt-injection + PII scanning    │
                   │  • SQLite store + MCP server          │◄── your
                   └────────────────┬─────────────────────┘    AI agents
                                    │  (optional, opt-in)
                                    ▼
                   ┌──────────────────────────────────────┐
                   │       pi.ruv.io shared brain          │
                   │  12,000+ memories across contributors │
                   └──────────────────────────────────────┘

The plugin is one client of many. Your editor, your command line, your AI coding assistant — all talk to the same brain. Index a note in Obsidian and Claude Code can cite it in the next message.

---

Sharing the brain with your AI agents

The brain already speaks MCP (Model Context Protocol). Point any MCP-capable assistant at it and they see the memories you indexed.

Claude Code — ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ruvector-brain": {
      "command": "http",
      "args": ["http://127.0.0.1:9876"]
    }
  }
}

Codex CLI — .codex/mcp.json:

{ "servers": [{ "name": "ruvector-brain", "endpoint": "http://127.0.0.1:9876" }] }

Gemini CLI — .gemini/settings.json:

{ "mcp": { "ruvector-brain": { "url": "http://127.0.0.1:9876" } } }

Settings → RuVector Brain → Copy MCP endpoint drops the right URL onto your clipboard.

---

Safety and privacy

• Nothing leaves your machine by default. Both the brain and the embedder bind to localhost. The shipped systemd units use IPAddressDeny=any + IPAddressAllow=127.0.0.0/8.
• Prompt-injection and PII screening run before every write — and you can’t turn them off from the plugin side. If the brain isn’t reachable, the plugin fails closed: your note is queued locally but not indexed, so nothing is ever silently bypassed.
• pi.ruv.io is entirely opt-in. It requires a bearer token you paste into settings; without it, the pull/publish commands simply say “not configured.”
• No telemetry, no third-party calls. The plugin talks to localhost and (if you turn it on) pi.ruv.io over authenticated HTTPS.
• A warning about Obsidian Sync. Your pi.ruv.io token is stored in .obsidian/plugins/obsidian-brain/data.json. If you use Obsidian Sync across machines, that file travels with your vault.

---

Settings cheat sheet

---

Development & testing

npm install
npm run dev        # rebuild on change — reload with "Reload plugin" in Obsidian
npm run build      # full typecheck + production bundle
npm test           # real-service protocol tests (no mocks)

Tests spin up a real mcp-brain-server-local subprocess and assert the exact response shapes the plugin parses. No mocking, no drift between what tests check and what production does.

Current baseline: 15 protocol tests + 11 real-Obsidian harness checks, all passing.

---

Troubleshooting

Status bar says “Brain: offline.” Your mcp-brain-server-local isn’t answering. Run curl http://127.0.0.1:9876/health. Writes you make while offline queue up and retry every 30 seconds.

Search results look semantically random. You’re probably on the fallback 16-dim stub embedder. Start ruvultra-embedder on :9877 before the brain, then wipe .brain-data/ — a vector index can’t mix dimensions.

Clicking a search result just shows a preview. The plugin doesn’t know which vault file that memory came from. Run Bulk-sync vault → brain once — idempotent and hash-deduped.

“Blocked by AIDefence” on a note you trust. It matched one of the injection patterns (e.g. phrases like “ignore all previous instructions”). Rephrase the content, or toggle AIDefence off in settings if you accept the tradeoff.

pi.ruv.io publish takes ~20 seconds. That’s expected — the server runs AIDefence, differential-privacy Gaussian noising, and RVF segmentation on ingest.

---

How this compares

obsidian-mind is more mature and has a richer “agent as co-pilot” story (session hooks, specialized subagents). obsidian-brain is stronger on embedding quality, federated knowledge, and security posture. They can coexist on the same machine pointing at different vaults.

---

What’s next

See ADR-152 §Phase-5. Tracked:

• Jump to the matching passage inside a note on result click
• Suggest [[wikilinks]] from semantically-related notes
• A memory explorer pane with category / date filters
• Diversity reranking for search
• Multi-brain federation (local + pi + team)
• Obsidian Canvas integration

Issues, feedback, and PRs are very welcome at github.com/ruvnet/obsidian-brain/issues.

---

Credits

Built on top of RuVector — the brain, the embedder, and the AIDefence regex set. The federated pi.ruv.io brain provides shared research memory. Inspired in parts by obsidian-mind’s agent-first memory vision.

License

MIT. Use it, fork it, ship it.