Obsidian Web Brain
A small, self-hosted, Obsidian-style markdown vault with a web UI and a built-in shared-memory MCP server, so Claude Code on all your devices can share one "brain". Notes stay plain .md files on disk and are backed up to a private git repository.
Independent, clean-room project, not affiliated with or endorsed by Obsidian (Obsidian is a trademark of Dynalist Inc.). No Obsidian code or assets are used. The behavior is designed to be compatible with Obsidian vault conventions, so the same folder also opens in Obsidian.
Live showcase: https://tabtq.github.io/obsidian-web-brain/ is an interactive tour of the architecture, data flows, editor and MCP tools. To view it offline, download docs/showcase/index.html and open it in a browser; it's a single self-contained file.
Features
Editor and notes
- Live-preview editor (CodeMirror 6). Markdown renders as you type, and syntax appears only where the cursor is:
- per token for bold, italic, code, links and math;
- per line for headings, tasks and rules;
- per block for callouts, code fences and math blocks.
- Links:
[[wikilinks]] with aliases, #heading and ^block references. Ambiguous names resolve the way Obsidian resolves them.
- Embeds: notes, headings, images (with size), audio, video and PDF.
- Renames update links everywhere: wikilinks, markdown links (URL-encoded) and frontmatter links.
Navigation and search
- Backlinks, outgoing links, outline, properties (YAML frontmatter) and a tag tree.
- Search operators:
"phrase", OR, -exclude, file:, path:, content:, tag:, line:(), section:(), block:(), task-todo:, task-done:, [property:value], /regex/ and match-case:.
- Graph view (global and local; d3-force on canvas), quick switcher, command palette, daily notes and templates (
{{title}}, {{date}}, {{time}}, {{date:FORMAT}}).
- KaTeX math and lazy-loaded Mermaid diagrams.
Git backup and sync
- Every save is committed, and pushes are debounced.
- Manual commit, sync and pull are available.
- Edits made on GitHub flow back into the vault.
- A per-file conflict resolver (keep vault, keep remote, or edit a merged version) means nothing is lost. Conflicts are detected with
git merge-tree, so the working tree never contains conflict markers.
Safety
- Soft delete to
.trash/, restorable from the UI.
- Stale-write protection: writes carry an etag, so concurrent edits are rejected with a clear error instead of silently overwriting.
MCP server at /mcp (Streamable HTTP, bearer token) with 25 tools:
- search, read, create, append, prepend and edit notes;
- replace lines, update, rename and delete;
- backlinks, outgoing links and outline;
- tags, properties and daily notes;
- unresolved links, orphans, dead-ends and templates.
Footprint: about 20–90 MB RAM at idle. The server is a single Node.js process with one runtime dependency (yaml), and ships as a ~400 KB bundle.
How it fits together
Browser (any device on your tailnet) ─┐ ┌─> Claude Code (laptop, desktop, ...)
│ HTTPS (real │ MCP over HTTPS + bearer token
tailscale serve ┴─ certificate) ─┘
│
127.0.0.1:8090 Node.js server (systemd)
┌──────────┬───────────┼─────────────┬──────────────┐
REST API MCP /mcp live events web UI git sync
└──────────┴─────┬─────┴─────────────┘ │
vault service + in-memory index │
(links, backlinks, tags, properties, search) │
│ │
/var/lib/brain/vault/*.md ── commits/pushes ─┴─> private GitHub repo
Repository layout
server/ Node.js + TypeScript backend: vault, index, search, git, REST API, MCP
web/ Vite + TypeScript frontend (no framework): editor, panels, graph, settings
clients/claude-code/ CLAUDE.md section, SessionStart hook and 5 skills for Claude Code
deploy/ release packaging, systemd unit, installer, optional Proxmox LXC helper
docs/showcase/ self-contained interactive showcase page (open offline)
Run locally
npm install
npm test # server test suite
BRAIN_DATA_DIR=.dev-data npm run dev:server # API on http://127.0.0.1:8090
npm run dev:web # UI on http://localhost:5173 (proxies /api and /mcp)
On first start the server prints a one-time setup code, which is also written to $BRAIN_DATA_DIR/setup-code.txt. Open the UI, enter the code and choose a password. The UI then shows your MCP token.
Deploy (any Debian/Ubuntu host or container)
- Build a release on a machine with Node.js 22+:
bash deploy/package.sh # -> release/brain-<version>.tar.gz
- Install on the target as root. This installs Node.js 24 (official tarball, checksum verified), git and the OpenSSH client, creates the
brain user, and installs a hardened systemd unit listening on 127.0.0.1:8090 only.
tar xzf brain-*.tar.gz && bash brain/install.sh
- Expose it privately with Tailscale (recommended). You get HTTPS with a real certificate, reachable only from your tailnet:
tailscale up --hostname brain
tailscale serve --bg 8090 # -> https://brain.<your-tailnet>.ts.net
Your tailnet needs MagicDNS and HTTPS certificates enabled.
以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗
