# @remember-md/mcp

Local MCP server for the [Remember.md](https://github.com/remember-md/remember) second brain. Run via `npx`, point any MCP client at it, query your markdown brain semantically.

> **Status:** v0.1.0 — first functional release. One tool: `search_brain`. Active development continues.

## What it does

Exposes your local markdown brain (a folder of `.md` files organised PARA-style by the [Remember.md plugin](https://github.com/remember-md/remember)) as a set of MCP tools any MCP client can call — Claude Code, OpenClaw, Cursor, Codex CLI, Claude.ai web, ChatGPT custom GPTs, anything that speaks the Model Context Protocol.

Tools shipped in v0.1.0:

- `search_brain(query, top_k)` — hybrid retrieval. BM25 + vector + RRF fusion + 1-hop wikilink expansion. Lexical-first: BM25 results land immediately on first run, vector embeddings build in background and layer in once ready.

Tools planned for v0.2+:

- `get_file(path)` — read a brain file
- `list_recent(period, kind?)` — recent journal / notes / decisions
- `query_persona()` — current `Persona.md` content
- `dashboard_snapshot()` — counts + top beliefs + active projects
- `propose_belief(claim, evidence)` — write candidate to `Inbox/`

## How it works

- **Storage:** `node:sqlite` (Node 22.5+ stdlib) + [sqlite-vec](https://github.com/asg017/sqlite-vec) extension for vector search + FTS5 for BM25 — no server, no native compilation, no toolchain.
- **Embeddings:** [@huggingface/transformers](https://github.com/huggingface/transformers.js) running quantized `Xenova/all-MiniLM-L6-v2` (384d, ~23 MB) locally — no cloud calls.
- **Sync:** on-demand mtime + content-hash incremental reindex at query time. The brain (markdown) is the source of truth; the index in `.remember/index.db` is rebuildable.
- **Graceful degradation:** if vector loads fail, falls back to FTS5-only; if both fail, falls back to ripgrep.

## Install

You don't install it. Point your MCP client at it via `npx`:

### Claude Code (via the Remember.md plugin's `/remember:init`)

The [Remember.md plugin](https://github.com/remember-md/remember) automatically configures Claude Code's MCP layer to launch this server. Just run `/remember:init`.

### Cursor / Codex / other MCP clients

Add to your MCP config:

```json
{
  "mcpServers": {
    "remember": {
      "command": "npx",
      "args": ["-y", "@remember-md/mcp"],
      "env": {
        "REMEMBER_BRAIN_PATH": "/absolute/path/to/your/brain"
      }
    }
  }
}
```

First run downloads the package (~15–30s) and the embedding model (~23 MB, one-time). After that, queries are sub-second.

## Configuration

| Env var | Default | Purpose |
|---|---|---|
| `REMEMBER_BRAIN_PATH` | `~/remember` | Brain root directory (folder of markdown files) |
| `REMEMBER_INDEX_DIR` | `${brain}/.remember` | Where the SQLite index lives |
| `REMEMBER_EMBEDDING_MODEL` | `Xenova/all-MiniLM-L6-v2` | Hugging Face model id |
| `REMEMBER_TIER` | auto | `auto` / `vec` / `fts5` / `ripgrep` (force a fallback tier) |

## Privacy

Local-only. No cloud calls. No telemetry. The brain folder + index never leave your machine. Embedding model runs in-process via ONNX Runtime.

## License

MIT — see [LICENSE](LICENSE).

## Related

- [Remember.md plugin](https://github.com/remember-md/remember) — the capture / curate / persona side that produces the brain this server queries
- [Remember.md spec](https://remember.md/spec) — the markdown standard