secondbrain

A self-hosted, ADHD-friendly second brain. Externalize your memory — essentials, habits, notes, links, people — and let the system resurface the right thing at the right time.

Purpose

Built for minds that forget: capture anything in seconds, mark what must never be forgotten, track habits gently, and always know what needs attention today.

Technology

• Go — net/http, html/template, database/sql + pgx
• PostgreSQL — the only database
• CSS + vanilla JavaScript — no frameworks, no build step
• go:embed — templates and static assets ship inside the binary

One binary, one database, one deployable artifact.

Architecture

A modular monolith with strict layering:

Handlers → Application Services → Storage → PostgreSQL

See docs/architecture.md for the full picture and adr/0001-simple-stack.md for why the stack is deliberately boring.

Getting Started

See CONTRIBUTING.md for detailed setup instructions including PostgreSQL configuration.

Quick start:

git clone <repo> && cd secondbrain
make run

make run starts a development PostgreSQL container and supplies development configuration. For direct binary or deployment use, configure the variables in .env.example in the process environment.

Development

Command	What it does
make fmt	Format all Go code
make test	Run tests with race detector
make lint	Run golangci-lint
make check	fmt check + vet + lint + tests
make run	Run the server from source
make build	Build the OCI image
make clean	Remove build artifacts

See CONTRIBUTING.md for the full workflow.

Testing

make test

Tests are written first (TDD). See AGENT.md for the engineering rules that agents and humans follow in this repo.

Project Structure

cmd/server/        main entrypoint
internal/
  auth/            authentication (password hashing, user/session/invite stores)
  capture/         capture model, service, and storage
  essential/       essential model and storage
  habit/           habits, daily entries, streaks, and storage
  people/          contacts, follow-ups, and storage
  http/            handlers, middleware, routing
  config/          environment configuration
  db/              database connection pool
  migrate/         migration runner
  web/             embedded templates and static assets
  testutil/        test database helpers
migrations/        numbered SQL migrations
docs/              long-form documentation
adr/               architecture decision records
.ai/               AI-assisted development structure

AI-Assisted Development

Three commands drive development:

shape   — Analyze, plan, update TASKS.md
build   — Implement first unfinished task (TDD)
review  — Senior review against AGENT.md

See .ai/prompts/ for instructions. The repository provides all persistent context.

Philosophy

• Clarity over cleverness.
• Boring technology, deliberately chosen.
• Small commits, small files, small functions.
• Minimal dependencies; every one must justify itself.
• YAGNI, KISS, TDD, and the Ponytail Rule.

The operating manual is AGENT.md. The product contract is SPEC.md. The backlog is TASKS.md.