Quickstart¶

Get one grounded answer from local demo data in 5 minutes. No provider keys required. After the demo works, decide whether to configure your own vault, add provider-backed synthesis, or set up a contributor checkout.

Prerequisites¶

Python 3.12 or 3.13 (python3 --version)
git
A shell that can create a virtualenv

Wrong Python on the system path?

SecondBrain pins >=3.12,<3.14 because some ML/observability deps don't yet ship 3.14 wheels. If your default python3 is outside that range, pass an explicit interpreter: make quickstart PYTHON_BIN=/path/to/python3.12. The Makefile also auto-detects python3.12/python3.13 on PATH and prefers them over plain python3.

Provider keys are not required for the quickstart. They're only needed later if you want LLM-synthesized answers — see How-to → Provider keys.

1. Run the quickstart¶

git clone https://github.com/contextosai/SecondBrain.git
cd SecondBrain
make quickstart

This single command:

Creates .venv/ and installs secondbrain in editable mode.
Writes a repo-local config under .secondbrain/config/.
Stores state under .secondbrain/state/.
Points the vault at .secondbrain/demo_vault.
Asks the first demo question with --no-synthesize so it works without a live model provider.

2. Verify success¶

A successful run ends with:

============================================================
  SecondBrain quickstart complete
============================================================

  Config:        .../.secondbrain/config/config.yaml
  State:         .../.secondbrain/state
  Demo vault:    .../.secondbrain/demo_vault
  Indexed rows:  <N>
  Demo Q&A:      OK (citation-first, no provider key)
  ReAct demo:    OK (LocalEchoProvider, <N> steps)

  Next steps:
    1) sb ask "What is blocking the Orion release?" --no-synthesize
    2) sb pack "Summarize the Orion launch state"
    3) sb onboard --vault "$PWD/vault" --approval-mode safe --skip-knowledge --skip-index
============================================================

What the banner asserts

sb doctor finds the repo-local config, state directory, and demo vault.
sb context index reports Indexed rows > 0.
sb ask --no-synthesize returns Relevant Content with citations from the Orion demo notes, decisions, meetings, and open loops.
examples/patterns/01_react_agent.py runs with the offline provider.

If the banner doesn't appear, the make target exits non-zero — re-run sb doctor, then check the step that errored above the banner.

3. Try the demo questions¶

source .venv/bin/activate
export SB_CONFIG=$PWD/.secondbrain/config/config.yaml
export SB_STATE_DIR=$PWD/.secondbrain/state
export SB_VAULT_DIR=$PWD/.secondbrain/demo_vault

sb ask "What are the main active priorities for the Orion release?" --no-synthesize
sb ask "What is blocking the Orion release?" --no-synthesize
sb ask "Who owns the Orion follow-ups?" --no-synthesize
sb ask "What open loops remain before launch?" --no-synthesize

Each answer cites the demo files it pulled from. That's the citation-first mode — retrieval and grounding without depending on network access.

Run the steps manually¶

If you want to inspect each operation:

make setup
make doctor-local
make demo-knowledge
python examples/patterns/01_react_agent.py

Next: your own vault¶

Once the demo works, configure normal user defaults rather than the repo-local demo environment:

source .venv/bin/activate
mkdir -p vault

sb onboard --vault "$PWD/vault" --approval-mode safe --skip-knowledge --skip-index
sb home

Add markdown, text, or PDF files to vault/, then build the first local knowledge loop:

sb ingest vault/
sb context index
sb ask "What changed this week?" --no-synthesize

If your vault already has useful files, sb onboard can do the first build for you in one step:

sb onboard --vault "$PWD/vault" --approval-mode safe --build-knowledge --build-index

Mental model: the local knowledge loop¶

Capture — sb ingest <path> brings files in and promotes useful facts, decisions, and open loops into local stores.
Index — sb context index builds the optional offline context index.
Ask — sb ask, sb pack, and sb chat assemble task-specific context from that local state.

For more, read How-to → Ingest and index.

Provider-backed answers (optional)¶

The quickstart deliberately skips provider keys. That's enough for:

make demo-knowledge
citation-first sb ask --no-synthesize
context indexing and context-pack inspection
brain.patterns examples that use offline providers

For synthesized answers, provider-backed chat, and live model calls, follow How-to → Provider keys. Once a provider is configured, drop --no-synthesize or pass --provider and --model.

Troubleshooting¶

state/ is missing from a fresh checkout

That's expected. state/ is gitignored local runtime data — vector indexes, sqlite databases, ingest artifacts, and generated fixtures. It's regenerated per machine from your vault and config.

Populate it with any of:

sb onboard          # guided first-run, builds knowledge + index
sb ingest <path>    # add a folder or file to the index
sb context index    # build the offline context index

SecondBrain auto-migrates a legacy state/chroma/ folder into state/retrieval/ (LanceDB) on first run. To do it explicitly: sb memory migrate --from chroma --to lancedb.

sb doctor reports state directory failures

Use the repo-local config when you're following the demo path:

export SB_CONFIG=$PWD/.secondbrain/config/config.yaml
export SB_STATE_DIR=$PWD/.secondbrain/state
export SB_VAULT_DIR=$PWD/.secondbrain/demo_vault
sb doctor

The first answer tries to call a provider

Add --no-synthesize:

sb ask "What are the main active priorities for the Orion release?" --no-synthesize

Provider synthesis is useful later, but the first demo should prove retrieval and grounding without network access.

Ingest says files were skipped

Normal on repeat runs — the ingest pipeline is incremental and skips unchanged files. Continue with:

sb context index
sb ask "What is blocking the Orion release?" --no-synthesize

The repo feels too broad

Start with the supported surfaces:

sb setup, doctor, ingest, context, ask, pack, and onboard flows
.secondbrain/demo_vault (local) and demo_vault/ (committed fixtures)
brain.sdk
brain.patterns

The complete CLI surface is auto-generated at Reference → CLI.