Why this exists

Modern knowledge work generates more context than any human can hold — meetings, threads, docs, browser tabs, code windows. The tools that promise to help typically lock your memory inside a vendor or stream your screen to someone else's GPU.

SecondBrain is a personal memory daemon that runs entirely on your Mac. It captures your screen, indexes it across four storage layers, and exposes that memory to any MCP-aware assistant — Claude Desktop, Cursor, Codex — through seven first-class tools. The default LLM is local Ollama; if you opt into a hosted provider, only the prompt text leaves your machine, and only because you said so.

Quick start

macOS 14+ (Apple Silicon). Windows/Linux paths raise NotImplementedError today.

git clone https://github.com/openintelligence-labs/secondbrain && cd secondbrain
python3 -m venv .venv && .venv/bin/pip install -e '.[dev,ml]'
.venv/bin/secondbrain run --fps 1                 # start the capture daemon

The [ml] extra installs the local text embedder (sentence-transformers + PyTorch). Skip it if you plan to use Ollama-served embeddings or the --stub-embedder flag — local embeddings pull ~2 GB of model weights on first use. For visual recall via ColQwen2.5 add [visual]; for BYO hosted LLMs add [byo-llm].

For the full desktop app (Tauri shell + Swift sidecars), build the two extra components after the Python install:

( cd swift/SecondBrainCapture && swift build -c release )
( cd app && npm install && npm run build && cd src-tauri && cargo build --release )
.venv/bin/secondbrain ui                          # launches the desktop window

Want to drive it without granting macOS Screen Recording first? Run ./demo.sh for a seeded fixture workday.

Features

How it works

  screen ──▶ cascade ──▶ extract ──▶ ┬─▶ SQLite  (OLTP, SQLCipher)
  (SCK)     (dedup 6   (entities,    ├─▶ LanceDB (dense vectors)
            stages)    importance)   ├─▶ tantivy (BM25)
                                     └─▶ Kùzu    (bi-temporal KG)
                                           │
                               ┌───────────┴────────────┐
                               ▼                        ▼
                        hybrid retrieval         Tauri desktop
                        (RRF k=60 + rerank)      + MCP server (7 tools)

Everything above the retrieval line stays on disk, encrypted. The MCP server and desktop app sit on top of the same retrieval layer, so a query from Claude Desktop and a click in the timeline window run the identical pipeline.

CLI surface

Configuration

SecondBrain is configured by environment variables — no config file required for the local-only default. To point it at a hosted LLM, install the matching extra and export three vars:

# 1. Install the SDK for your chosen provider.
pip install -e '.[openai]'         # or [anthropic] / [gemini] / [groq] / [mistral]
                                    # or [byo-llm] for all five at once

# 2. Tell SecondBrain to use it.
export SECONDBRAIN_LLM_PROVIDER=openai         # ollama (default) | openai | anthropic
                                                # | gemini | groq | mistral
export SECONDBRAIN_LLM_MODEL=gpt-4o-mini       # any model the provider serves
export SECONDBRAIN_LLM_API_KEY=sk-...          # not needed for local Ollama
# export SECONDBRAIN_LLM_BASE_URL=...          # only for self-hosted endpoints

# 3. Verify.
secondbrain mcp-doctor                          # prints loaded providers + warnings

Captures, embeddings, KG nodes, and the audit log never leave your device. With a hosted LLM, only the prompted text egresses — and only on the calls you opted into.

Contributing

Contributions are welcome. Before opening a PR:

1. Browse src/secondbrain/ — modules are organised by pipeline stage (capture/, memory/, store/, search/, api/).
2. Run the deterministic suite: pytest tests/ --ignore=tests/test_macos_sck.py --ignore=tests/test_ocr.py (no network, no TCC required).
3. Project conventions: Pydantic models across module boundaries, heuristic fallback for every LLM hot path, capture IDs as hex UUIDs.

Questions, ideas, and bug reports go in GitHub Discussions and Issues.

Star history

License

MIT © Open Intelligence Labs.