# brain-mcp [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/debashishthakur/brain-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 46  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/brain-mcp

## Description
Your Obsidian vault as private, searchable memory for Claude, Cursor, Hermes and any MCP client

## Tools
Capabilities this server exposes over MCP:

- **brain_identity** — Persona bundle: profile note, memory notes, facts captured with `brain_remember`, skills, project list and recent focus. The server instructions ask clients to call this first. Pass `topic` for a smaller bundle.
- **brain_context** — The sections most relevant to a question, with source note ids and a coverage label, from the hybrid ranker, packed under a size budget. Says so explicitly when the vault does not record the answer.
- **brain_search** — Hybrid search (keywords, meaning, reranker, spelling correction) with project, type, topic and date filters. Returns ranked notes with snippets.
- **brain_read** — One note, or one section of it, with metadata, topics and resolved links.
- **brain_project** — Briefing on a project: description, latest progress, decisions, recent changes and notes grouped by type. With no argument it lists projects.
- **brain_graph** — Links out, backlinks grouped by project, and notes that share topics.
- **brain_recent** — Notes modified in the last N days, newest first.
- **brain_capture** — Writes a new note with graph-ready frontmatter into the capture folder.
- **brain_remember** — Appends a fact to the memory file; it joins `brain_identity` straight away. Near duplicates are refused (token Jaccard ≥ 0.6 or containment ≥ 0.85), partial overlaps get a `Supersedes` line, and `force=true` overrides.
- **brain_write** — Creates a note at a chosen path in a writable folder (`Notes/` and the capture folder by default), or replaces one with `overwrite=true`. A `hub` note groups every note whose `project` matches its title.
- **brain_edit** — Changes part of a note in one of three ways: replace text that matches once, replace a section under a heading, or append. Keeps the file's line endings and bumps `modified`.
- **brain_move** — Moves or renames a note within the writable folders. Never overwrites, and names any notes whose links stop resolving.
- **brain_delete** — Moves a note into `.trash/`, which is never indexed. Nothing is erased.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "brain-mcp": {
    "command": "npx",
    "args": ["-y","debawho-brain-mcp"]
  }
}
```

## Documentation

## What brain-mcp MCP server does

The brain-mcp MCP server exposes an Obsidian vault as persistent context for MCP-compatible AI clients. Notes remain as Markdown files in a folder controlled by the user, while the server maintains a SQLite index containing full-text search data, section embeddings, links, topics, and project metadata.

It supports both reading and writing. Agents can load identity and project context, search notes, inspect individual sections, follow links, review recent changes, capture new notes, remember facts, edit existing content, move notes, or send notes to `.trash/` instead of permanently deleting them.

## How it works

A file watcher updates the index after vault changes. Notes are divided into sections, with links, topics, and project information extracted for retrieval and graph operations. Embeddings use the `bge-small-en-v1.5` model, and candidate results can be reranked with `bge-reranker-base`. These models run locally on the CPU and are downloaded into `data/models`.

Queries are expanded for known shorthand and corrected against words found in the vault. Retrieval combines BM25 keyword matches, semantic similarity, exact dates, and note-title matches. Reciprocal rank fusion combines those result sets before reranking selected candidates. If the strongest passage is below the configured relevance floor, the server reports that the vault does not contain a relevant answer rather than presenting a weak match.

The server can communicate over stdio, HTTP with a bearer token, or OAuth 2.1 with PKCE through Cloudflare Tunnel. Notes do not leave the server during normal local operation. Remote access includes scopes, secret redaction, and an audit log of calls.

## Setup and configuration

The repository targets Node.js 22 or newer and uses strict TypeScript. The provided material describes a local Obsidian vault as the source of truth and a single Node process with one SQLite file as the main architecture.

Hybrid retrieval is enabled by default according to the documentation. Set `BRAIN_MCP_HYBRID=0` to use keyword-only retrieval. Retrieval behavior can also be adjusted in `brain.config.json`, including embedding and reranker models, candidate counts, score blending, the relevance floor, shorthand expansions, and context budgets. Additional constants such as `RRF_K` and `TITLE_BONUS` are available in the indexing code.

## Tools and capabilities

- `brain_identity` returns profile, memory, facts, skills, projects, and recent focus; it accepts an optional topic.
- `brain_context` selects relevant sections under a size budget and reports source notes and coverage.
- `brain_search` returns ranked note snippets with project, type, topic, and date filters.
- `brain_read`, `brain_project`, `brain_graph`, and `brain_recent` inspect notes, projects, links, backlinks, shared topics, and recent changes.
- `brain_capture`, `brain_remember`, `brain_write`, `brain_edit`, `brain_move`, and `brain_delete` provide constrained write operations.

`brain_remember` rejects near-duplicate facts unless forced, can mark partial overlaps with a supersession line, and feeds captured facts into identity results. Writes are limited to allowed folders, with `Notes/` and the capture folder writable by default. Moving does not overwrite existing notes and reports links that no longer resolve; deletion moves content to `.trash/`.

## Limitations and notes

The brain-mcp MCP server depends on the structure and content of the connected vault. It can explicitly report missing coverage, but it cannot supply information that the notes do not contain. The hybrid models are local and retrieval falls back to keywords while they are unavailable. The current design uses fixed retrieval rules, one process, and one SQLite database; the documentation identifies pluggable retrievers, storage, and graph strategies as future possibilities rather than current features.

_Full upstream README: https://allmcps.com/mcp/brain-mcp/readme_