SecondBrain 2.0: managed Markdown wiki with knowledge galaxy, read-only chat and PWA

What they did

The author built SecondBrain 2.0 as a large draft PR on top of a Markdown/Git knowledge base, keeping Markdown and Git authoritative while layering services on top. The wiki is the primary surface: a responsive Home page, browser-local start page, safe Markdown and wikilinks, direct URLs, search, backlinks and Git-backed history. The editor keeps drafts across conflicts and lost acknowledgements, and mutations carry stable request IDs so retries are explicit. A knowledge galaxy renders stars, curated clusters and bridges derived only from explicit links, with search, keyboard navigation, bounded neighborhoods and directed link evidence; graph refresh reflects real mutations rather than inventing dependencies. Chat is read-only and server-side via OpenRouter, doing bounded iterative search plus page and neighbor calls, with only delivered page content counting as a read source; provider errors, incomplete generations, cancellation and limits are surfaced explicitly. Conversations and deletion markers live in browser-local IndexedDB, with no backend chat archive and no wiki-writing chat tool. Storage and agent access run through ten direct MCP tools plus a wiki://guidance resource, with a local bare Git snapshot publishing content and mutation receipts atomically; Neo4j, Qdrant/embeddings and remote Git are treated as recoverable derived services whose failure does not block exact reads, lexical search, local history or explicit-link navigation. Managed REST lives under /api/wiki with base_revision and request_id required on mutations and no-store on private responses; credentials stay server-side, and legacy remember/recall tools are isolated in an optional MCP profile that cannot share a vault with managed writers. Self-hosting covers empty/template/Git first start, a fictional demo, Compose and reverse-proxy instructions, and update/backup/restore docs, plus an online-first installable PWA that protects drafts across updates without caching private wiki, chat or API data. The latest head adds a first-start safety fix so a surviving demo marker makes empty setup and Git import refuse missing, file or symlink history before creating a replacement, reporting storage_unavailable via CLI.

How it went

The work is a substantial, heavily tested draft rather than a release. A verified executable baseline (09da1245) passed all six workflows and nine jobs, with backend at 1,620 passed / 12 skips / 28 subtests, frontend typecheck, proxy, access, PWA and image-update checks, index/SSH jobs, stack/update gates and a seven-phase native browser run covering Chromium, WebKit, first-start/restart, Git import and synthetic320. Three CI archives were downloaded, SHA-256 verified and CRC-checked, and thirteen screenshots were personally reviewed across 320/390/1440px. An installed-package check rebuilt wheel and sdist, matched 51 Python sources byte-for-byte to Git, and exercised setup, retry, refusal-to-overwrite, chat loopback cases and three real MCP SDK stdio server starts. The PR remains Draft: no merge, main change, image publication or production deployment was performed.

Worth knowing

Real OpenRouter multi-turn answers have not been human-inspected, and chat replies in tests are explicitly synthetic. Private original-history import and live legacy-client migration are unproven, as are hosted graph/vector/embedding behavior under load, production proxy/auth/HTTPS and off-host restore. Physical Android/iOS installation, touch, soft keyboard, IME, screen reader and native zoom are untested, and a word-truncation warning remains open. An entirely absent vault directory also hides its demo marker, so operators must verify the intended volume separately. Full CI on the latest head was still in progress at time of writing.

Wiring

Markdown files in Git are the source of truth. A local bare Git snapshot publishes content and mutation receipts atomically; Neo4j, Qdrant/embeddings and remote Git are derived services that can fail without blocking reads. The backend exposes managed REST under /api/wiki (mutations require base_revision and request_id; private responses use no-store) and ten MCP tools plus a wiki://guidance resource over stdio. The frontend is a PWA that talks to the backend through a proxy, keeps drafts and chat transcripts in browser-local IndexedDB, and caches no private wiki, chat or API data. Chat runs server-side against OpenRouter with bounded iterative search, page and neighbor calls; credentials stay server-side. Legacy remember/recall tools sit in an optional MCP profile that cannot share a vault with managed writers. Deployment uses Compose behind a reverse proxy with documented update, backup and restore.

Try it yourself

Read the SecondBrain 2.0 branch docs (documentation/demo-start.md, first-start.md, review-handoff.md) and the /api/wiki contract in this repo. Then: (1) run the synthetic demo and local tour, (2) start the stack with an empty vault and confirm first-start refuses to overwrite existing history, (3) exercise the ten MCP tools over stdio against a scratch vault, including save/replay with base_revision and request_id, a cross-interface conflict, delete/replay and history, (4) verify that killing Neo4j or Qdrant still leaves exact reads, lexical search and explicit-link navigation working, and (5) list every release gate in the handoff that this run does not close. Report concrete failures with file and line references; do not modify Markdown sources.