BlackBullet

A personal, local-first, AI-native notes app. Your notes stay plain Markdown files in a folder you own. On top of them you get a Notion-like editor, search that understands meaning as well as words, a graph of related notes, database views, and an MCP server so AI assistants can read and write the same notes. Everything runs on your own machine; note text leaves it only when you ask a question with Ask.

BlackBullet is a fork of SilverBullet (v2.11 line; Rust server, TypeScript / CodeMirror 6 client) and is not affiliated with that project. It keeps SilverBullet's internal names (crates, SB_* environment variables, plug API), so SilverBullet plugs and libraries keep working. Upstream's manual is in docs/.

Features

• Write: block editor with drag handles and folding, page tree with drag-and-drop, page cover and icon, quick notes (Ctrl-q q) and a daily journal (Ctrl-q j); a mode chip in the header shows Edit or Preview (Ctrl-Alt-p, Editor: Toggle Preview), and with vim keys (on by default where there is a mouse) NORMAL / INSERT / VISUAL, where Esc steps Insert → Normal → Preview; beside it a Styled | Code segment hides or shows the Markdown marks (Ctrl-Alt-k, Editor: Toggle Code, :code / :styled).
• Find: one search over every section by words and meaning (Ctrl-q s), related notes for the page you are on (Ctrl-q r), and a graph of links and similar pages (Ctrl-Shift-g).
• Organise: databases declared once (typed properties, folder, template) and shown as table, board or calendar views you edit in place; one New for pages, rows, quick notes and journal entries (Ctrl-Alt-n); a trash you can restore from.
• Ask: answers from your own notes with citations, follow-up questions, and answers saved as pages (Ctrl-q a, needs an Anthropic API key).
• Documents: PDF, Word, Excel, PowerPoint, OpenDocument and HTML files in the folder are searchable too, with optional OCR.
• Export: a page as PDF, Word (.docx) or Markdown with its images (.zip), from Ctrl-e, the tree's Export… or Export: PDF / Export: Word / Export: Markdown with Images (PDF and Word are made by the sidecar).
• AI assistants: an MCP server over the same notes for Claude Code, Claude Desktop and other MCP clients.
• Phone and other devices: works at phone width, and an optional tailnet-only HTTPS front door (Tailscale) with no password screen.

Quick start

You need Docker with Compose v2.

git clone https://github.com/HayatoShimada/blackbullet.git
cd blackbullet
./setup.sh

The first run builds the images (10 to 20 minutes); later runs just start them. Then open http://127.0.0.1:3000.

• Your notes live in ./space. To use an existing folder of Markdown files, set SPACE_DIR=/path/to/notes in .env before running setup.sh.
• setup.sh also starts the search sidecar and connects it. The first indexing downloads a ~120 MB embedding model once and runs it on the CPU. MEMO_EMBED=off in .env keeps search word-based with no download.
• All settings are in .env; .env.example explains each one.

Command	What it does
./setup.sh --status	Health of the app and the sidecar, index and model state, disk use
./setup.sh --backup [dir] [--with-secrets]	A timestamped .tar.gz of the notes (secrets blanked unless --with-secrets)
./setup.sh --restore <file>	Merges a backup into the notes folder after saving a safety copy
./setup.sh --upgrade	git pull, rebuild and restart
./setup.sh --stop	Stops everything; the notes stay where they are

Use it from an AI assistant

The sidecar speaks MCP at http://127.0.0.1:3010/mcp, protected by MEMO_MCP_TOKEN from .env (setup.sh prints this command with the token filled in):

claude mcp add --scope user --transport http memo http://127.0.0.1:3010/mcp \
  --header "Authorization: Bearer <MEMO_MCP_TOKEN>"

Tools include search_notes, read_note, read_section, related_notes, list_tasks, list_projects, list_journal, recent_changes, append_journal, add_inbox, complete_task, write_note, edit_note, update_section, doc_status and reindex_docs. CONFIG (where tokens and keys live) is never readable or writable through MCP, and the general edit tools do not write Library/ or Templates/. packages/memo-mcp/contrib/plan_to_memo.py is a Claude Code hook that records each approved agent plan under the project's page. Other clients and the options are described in packages/memo-mcp/README.md.

Ask your notes

Ask: Notes sends the sections that match your question to the Anthropic API and shows the answer with [n] links back to each section. Run Ask: Set up once to store an API key in the space's CONFIG page. Nothing is sent unless you run the command, and a space marked :confidential is never sent unless you allow it. Scopes (#tag, in:Folder/, kind:pdf, since:2026-01-01), follow-ups, saved answers and limits are described in Memo Ask.md.

Databases

Declare a database once in CONFIG:

database.define {
  name = "projects",
  folder = "Projects/",
  template = "Templates/Project",
  properties = {
    { key = "status", type = "select", options = {"active", "someday", "done"}, default = "active" },
    { key = "due", type = "date" },
  },
}

Then a ```db block with database: projects shows it as a table, board or calendar with + New, filters, a row menu (rename, duplicate, archive, move to trash) and Save view. Database: Insert View (or /database) writes the block for you. See DB View.md and Database.md.

Phone and other devices

The layout adapts to phones: 44 px touch targets, cards instead of wide tables, and a drawer with Search, New and Journal.

./setup.sh --tailnet adds a front door reachable only from your Tailscale network and only by the logins you allow, with a real domain and certificate and no password screen. The same address serves the MCP endpoint (https://<SITE_DOMAIN>/mcp) to other machines on the tailnet. Setup steps are in deploy/tailnet-proxy/README.md.

Help

The ? button in the header opens the in-app guide (Japanese). The command palette (Ctrl-/) lists every command with its shortcut. Esc then Tab moves the keyboard from the editor to the header.

Develop

Without a local Rust toolchain or Node 24, use Docker: docker compose build for release images, scripts/fork-dev.sh for a fast client loop, and scripts/ui-tour.mjs for a fixed set of screenshots on the demo space in examples/demo-space. With the toolchains installed:

npm run build:client
SB_DISABLE_SERVICE_WORKER=1 cargo run -p silverbullet -- <space-dir>
npm test
cd packages/memo-mcp && npm test

Design references: dev-docs/product-design.md (what the interface means), dev-docs/design-system.md (how it looks), and a Japanese summary in dev-docs/design.ja.md. See also CONTRIBUTING.md and STYLE.md.

License

BlackBullet is licensed under the GNU General Public License v2.0 only (GPL-2.0-only).

It is based on SilverBullet, which is MIT-licensed; the MIT license lets that code be redistributed under the GPL as long as its copyright and permission notice stay with it, which NOTICE.md reproduces.

Copyright (C) 2026 HayatoShimada.