<div align="center">

🧠 rm-brain

A local-first "second brain" for your handwritten reMarkable notebooks — searched through a normal Claude Desktop conversation.

 

Built by Gabriel Anhaia · ☕ Buy me a coffee

<br/> <img src="docs/rm-brain-hero.gif" width="840" alt="rm-brain web app in motion — dashboard, typo-tolerant search, notebooks grouped by folder, page detail (scan beside transcription), and entities" />

_{The local web app — dashboard · search · notebooks · page detail · entities. Fictional example data.}

</div>

---

rm-brain quietly syncs the notebooks you drop into a Brain folder on your reMarkable, transcribes and classifies the handwriting with the Claude API, and stores everything in a local SQLite database. You then search and explore your notes as an ordinary conversation in Claude Desktop — no separate app, no hosted service, using your existing Claude subscription.

You: "What did I decide about the Acme pricing model?" Claude: Pulls it from your notes and answers with receipts — notebook name, page number, date, and the scanned page.

It's designed to feel less like a search box and more like a system that quietly organizes itself and surfaces things you forgot about.

Why it's different

• Your handwriting, actually understood. Claude vision transcribes messy handwriting and diagrams far better than built-in OCR, and classifies each page (journal / meeting / idea / decision / …), extracts people & projects, and flags open loops.
• The interface is a conversation, not a dashboard. Search happens inside Claude Desktop via MCP — you get a world-class chat UI for free.
• Local-first and private by design. The database, page images, and manifest never leave your machine. See Privacy.
• Answers with receipts. Every answer cites the notebook, page number, and date, and can show you the scanned page — so you verify, not trust blindly.

How it works

flowchart TD
    A["☁️ reMarkable Cloud"] -->|"rmapi: list Brain folder · stat · get"| B["📦 .rmdoc archive<br/>(.rm v6 vector files)"]
    B -->|rmc| C["🖼️ per-page SVG"]
    C -->|rsvg-convert| D["🏞️ page PNGs"]
    D -->|"Claude vision · 1 call/page"| E["✍️ Extraction<br/>text · type · entities · open loops"]
    E --> F[("🗄️ SQLite + FTS5<br/>~/.rm-brain")]
    CLI["⌨️ CLI<br/>sync · search · backup"] --> F
    F <--> G["🔌 MCP server"]
    G <--> H["💬 Claude Desktop"]
    G <--> H2["🤖 ChatGPT"]
    G <--> H3["✦ Gemini"]
    F --> W["🖥️ Web app<br/>browse · search (localhost)"]

    classDef cloud fill:#e8f0fe,stroke:#4285f4,color:#1a1a1a;
    classDef local fill:#e9f7ef,stroke:#27ae60,color:#1a1a1a;
    classDef ai fill:#f3e8fd,stroke:#8e44ad,color:#1a1a1a;
    class A cloud;
    class B,C,D,F,CLI,W local;
    class E,G,H,H2,H3 ai;

The MCP server speaks the open Model Context Protocol, so any MCP-capable assistant can use your notes — Claude Desktop (the primary, best-tested target), ChatGPT, Gemini, and others. See docs/mcp.md.

reMarkable notebooks are stored as proprietary .rm v6 vector files (not PDFs), so pages are rendered with rmc + rsvg-convert. See ARCHITECTURE.md for the full design.

🔒 Privacy & safety

• Local-first, always. db.sqlite, page images, and the manifest live in one folder (~/.rm-brain by default) and never leave your machine as a whole.
• The only things that ever go over the network are (a) individual page images sent to the Claude API during sync, and (b) individual queries + retrieved snippets sent through MCP while you search in Claude Desktop.
• Opt-in by folder. Nothing is indexed unless you put the notebook in your Brain folder.
• The folder is the source of truth. Remove a notebook from it and the next sync prunes it from your local index — pages and images included.
• Hard exclusion always wins. A notebook whose name matches /^\./, /private/i, or /noindex/i is skipped entirely, even inside the Brain folder — and so is anything filed under a subfolder with such a name (e.g. Brain/private/…).
• Read-only cloud access. rm-brain only ever reads from reMarkable (list / stat / get); it never uploads or modifies anything.
• No telemetry. rm-brain phones home to nobody. See SECURITY.md.

Prerequisites

✅ No jailbreak, rooting, developer mode, or SSH hacks — ever. rm-brain works entirely through reMarkable's official cloud sync (via rmapi). Your tablet stays completely stock, stock firmware, and under warranty. Nothing is installed on or modified on the device.

| Tool | Why | Install | | --- | --- | --- | | Node.js 20+ | runtime | nodejs.org | | rmapi (ddvk sync15 build) | reMarkable Cloud CLI | ddvk/rmapi releases — reMarkable's newer sync protocol returns HTTP 410 with older builds | | rmc | renders .rm v6 pages | pipx install rmc | | librsvg (rsvg-convert) | SVG → PNG | brew install librsvg | | Anthropic API key | handwriting extraction (used only during sync) | console.anthropic.com |

Quickstart

# 1. Install
git clone https://github.com/gabrielanhaia/remarkable-brain.git
cd remarkable-brain
npm install && npm run build
npm link            # puts `rm-brain` on your PATH

# 2. Guided setup (pairs rmapi, saves your API key, wires Claude Desktop)
rm-brain setup

# 3. On the tablet: create a "Brain" folder, move a notebook in, let it sync
rm-brain sync

# 4. Fully quit & reopen Claude Desktop, then just ask it about your notes

The setup wizard checks your tools, pairs rmapi, prompts for your API key once and saves it (to ~/.rm-brain/config.json, chmod 600 — no re-export needed), helps you pick the Brain folder, offers to run the first sync, and can write your Claude Desktop config automatically. Re-run it anytime — it's idempotent.

Usage

Once a notebook is indexed and Claude Desktop is connected, just talk to Claude:

• "What are my open loops?" / "What did I forget to follow up on?"
• "Search my notes for the Atlas pricing decision."
• "How has my thinking on the onboarding flow evolved?" (entity timeline)
• "Show me the page where I sketched the architecture."

Web interface

Prefer to see your notes? rm-brain ships a local-first, read-only web app — an alternative way to browse and search your indexed notebooks and view the actual scanned handwriting in the browser. Its design is a quiet, fountain-pen-ink-on-fine-paper reading room that follows your system light/dark theme (scans always stay light paper, so handwriting never inverts). It complements the conversation, it doesn't replace it: asking questions still happens in Claude Desktop (over MCP); the web app is for seeing and searching.

<p align="center"> <img src="docs/screenshots/search.png" width="49%" alt="rm-brain web — full-text search with filters and thumbnails" /> <img src="docs/screenshots/page-detail.png" width="49%" alt="rm-brain web — page detail: scanned handwriting beside the transcription" /> </p>

_{Screens shown with fictional example data. Everything runs on your machine.}

rm-brain web                       # builds nothing — opens http://localhost:4123 in your browser
rm-brain web --port 8080           # pick a different port
rm-brain web --host 127.0.0.1      # bind address (localhost only, by design)
rm-brain web --no-open             # don't auto-open the browser

It serves the Dashboard (counts + recent open loops and pages), forgiving search — word forms (meeting/meetings), partial words, and small misspellings all match — with filters (notebook, page type, open-loop only), a Notebooks grid grouped by reMarkable subfolder, per-page detail (scanned image side-by-side with the transcription), Open Loops, and Entity timelines.

Same guarantees as the rest of rm-brain: it binds 127.0.0.1 only, exposes GET endpoints only, has no auth surface, and makes no outbound network calls. The frontend ships prebuilt (in web/dist), so there's no build step for end users — just run rm-brain web.

CLI reference

| Command | What it does | | --- | --- | | rm-brain setup | Interactive setup wizard (start here) | | rm-brain sync | Pull Brain-folder notebooks, render, extract, index | | rm-brain reindex | Re-extract all indexed pages (after a prompt/model change) | | rm-brain search "<query>" | Search from the terminal (keyword + local semantic) | | rm-brain embed | Build local semantic-search vectors (optional; on-device, no API) | | rm-brain list | Show indexed notebooks and page counts | | rm-brain info | Where the data lives + stats | | rm-brain backup [dest] | Write a portable .tar.gz of the whole index | | rm-brain exclude "<name>" / include "<name>" | Exclude (purges) / re-include a notebook | | rm-brain purge | Delete the entire local index | | rm-brain doctor | Check dependencies | | rm-brain mcp | Start the MCP server (Claude Desktop runs this) | | rm-brain web | Open the local read-only web app to browse & search your notes (--port / --host / --no-open) |

Configuration

All config is via environment variables (env wins) or the saved store (~/.rm-brain/config.json).

| Env var | Default | Purpose | | --- | --- | --- | | RM_BRAIN_HOME | ~/.rm-brain | Where all local data lives | | RM_BRAIN_FOLDER | /Brain | reMarkable folder whose notebooks get indexed (case-insensitive) | | RMAPI_BIN | rmapi | Path/name of the rmapi binary (ddvk sync15 build) | | RMC_BIN | rmc | Path/name of the rmc renderer | | RSVG_BIN | rsvg-convert | Path/name of rsvg-convert | | ANTHROPIC_API_KEY | — | Required only for sync (extraction) | | ANTHROPIC_MODEL | claude-sonnet-5 | Vision model for extraction | | RM_BRAIN_SEARCH | auto | auto uses local semantic search when available; keyword forces keyword-only | | RM_BRAIN_EMBED_MODEL | Xenova/all-MiniLM-L6-v2 | On-device model for semantic embeddings |

Portability & backup

The whole index is one self-contained folder, so:

• Back up: rm-brain backup [dest.tar.gz], or just copy ~/.rm-brain.
• Roam / auto-backup: point RM_BRAIN_HOME at a Dropbox/iCloud/Syncthing folder.
• Restore: extract the archive anywhere and point RM_BRAIN_HOME at it.

Troubleshooting

<details> <summary><b>rmapi says "failed to build documents tree … status 410"</b></summary>

Your reMarkable account is on the newer sync protocol. Use the ddvk sync15 build of rmapi (a release binary is easiest), not the original juruen/rmapi. Then re-run rm-brain doctor.

</details> <details> <summary><b>Claude Desktop gives empty results even though the note exists</b></summary>

Claude Desktop launches the MC