Skip to content

README.md

Latest commit

 

History

History
130 lines (93 loc) · 6.16 KB

README.md

File metadata and controls

130 lines (93 loc) · 6.16 KB
Raw
image

ShadowBrain

Version

ShadowBrain is a personal knowledge management system that treats every thought - raw captures, journal entries, knowledge notes, bookmarks, people, projects, questions, and events - as nodes in a rich, typed graph.

  • Everything in one database — no split between "journal here" and "notes there." One query across your entire brain.
  • Semantic search — find thoughts by meaning, not just keywords.
  • Typed links — inspired by, contradicts, builds upon, involves, bookmarked for — not just "related to."
  • Frictionless capture — Discord, web, voice. Under 3 seconds from thought to saved.
  • Hermes is the interface — your AI assistant is the primary interaction layer. Talk to it like a person.
  • Web chat at /chat — talk to Hermes (with tool-progress + approval for admin actions) or an OpenCode Go model, optionally grounded in your knowledge base. Save messages back to ShadowBrain with one click.
  • Local-first, portable forever — SQLite database. One file. Copy it anywhere. Export everything to Markdown.

Tech Stack

Layer Technology
Database SQLite + sqlite-vec (semantic search) + FTS5 (full-text)
Backend Next.js (App Router, TypeScript)
Frontend React 19 + Tailwind CSS + shadcn/ui
AI Interface Hermes Agent + OpenCode Go models (web chat at /chat)
Capture Discord WebSocket listener, Web UI, API
AI Processing OpenRouter (background jobs: nightly compilation, auto-tag, auto-title)
Deployment Docker Compose + nginx reverse proxy

Security

ShadowBrain is designed for a public-VPS deployment and ships with a defense-in-depth security baseline. The full policy is in the App Security Baseline spec; at a glance:

  • Session-based auth with HttpOnly / Secure / SameSite=Lax cookies, rate-limited login, constant-time credential check (OWASP ASVS V3.2.2).
  • Two-level visibility on every item: is_hidden (out of casual views, AI-OK) and is_private (out of views; AI only on per-thread opt-in).
  • CSRF via origin check (constant-time compare, exact-pathname exempt list), standard security headers (CSP, HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy), global rate limiting per IP.
  • Regular backups of the database to Proton Drive (E2E encrypted by the destination), with an in-app reminder — see the backup reminder spec.
  • SSRF protection on URL-fetch endpoints (bookmark auto-fetch, image capture) — private / loopback / link-local addresses are blocked.
  • CI security (CodeQL, lint CI, Renovate, SECURITY.md) so every PR is scanned, linted, typechecked, and tested.

Back up your database to Proton Drive regularly — the in-app reminder at /backup will prompt you, and the guide there walks through the one-time setup (Proton Drive CLI + /ShadowBrain Backups folder) and the backup script.

Development

pnpm install
pnpm dev          # Start dev server (localhost:3000)
pnpm test         # Run tests
pnpm typecheck    # TypeScript type check
pnpm lint         # Lint
pnpm format       # Format

The full technical reference (commands, code style, security scanning, agent skills) is in AGENTS.md.

Documentation

Design specs

Docker Deployment

ShadowBrain includes Docker Compose configuration for production deployment with nginx reverse proxy.

Prerequisites

  • Docker and Docker Compose installed
  • A .env file (copy from .env.template and fill in your values)
  • The Proton Drive CLI installed on the VPS for the backup flow (see the in-app /backup guide)

Running with Docker

# Start all services (app + nginx)
docker compose up -d

# View logs
docker compose logs -f

# Stop services
docker compose down

# Stop and remove volumes (cleans database)
docker compose down -v

The app will be available at http://localhost (ports 80/443).

Services

  • app: Next.js application on port 3000 (internal)
  • nginx: Reverse proxy on ports 80 and 443
  • data: Persistent volume for SQLite database and uploads