# Getting started

Create a brain, ingest one piece of evidence, author a Markdown decision with `attr_list` metadata and a `bf://` link, compile it to JSON, and query `memories/` with `bf query`, `bf read`, and `bf review`.

## Prerequisites

- Linux or macOS
- [uv](<https://docs.astral.sh/uv/getting-started/installation/>) (for Python 3.14 tool installation)
- Standard CLI tools for retrieval: [`ripgrep` (`rg`)](<https://github.com/BurntSushi/ripgrep>), [`jq`](<https://jqlang.org/>), and [`duckdb`](<https://duckdb.org/>)

## Install and initialize a brain

```bash
uv tool install --python 3.14 brain-framework
bf init ~/brain
cd ~/brain
bf validate
bf eval
```

`bf init` creates a minimal flat layout (`projects/`, `concepts/`, `actions/`, `memories/`, `logs/`, `evals/`, `docs/`, `skills/bf/SKILL.md`, `schemas/{record,concepts,logs,evals}.json`, linking `.agents/skills/bf`, with operational folders like `sensors/`, `routines/`, `channels/`, `prompts/`, and `settings/` added as needed) and compiles `concepts/welcome.md` into `memories/concepts/welcome.json`. `bf validate` prints:

```json
{ "brain": "brain", "notes": 1, "problems": [], "records": 0, "valid": true }
```

## Ingest evidence and author a Markdown note

Pipe one sensor record into `memories/workspace/<sha256>.json`:

```bash
printf '%s\n' '[{"id":"brief","title":"Website brief","text":"Visitors need one clear product page before signup.","time":"2026-09-20T09:00:00Z"}]' | bf ingest workspace
```

Write `projects/new-website.md` using Python-Markdown `attr_list` metadata and relative Markdown links, then compile it into `memories/projects/new-website.json`:

```bash
cat > projects/new-website.md <<'EOF'
---
type: project
status: draft
updated: 2026-09-25
tags: [launch, web]
summary: Launch a single-page product site.
---

# New website

## Decision {#decision owner=product}

Start with one product page so visitors understand who the product helps before signing up. Evidence: [Workspace brief](../memories/workspace/29a8825bd242f14386ee528d76e0e8f1e38f3c8c4047d7b2d6df7493368a17d0.json){rel=cites} and [Conventions](../concepts/welcome.md#conventions){rel=follows}.
{: #launch-scope confidence=high}

## Next actions

- [ ] Draft the hero copy.
  {: #task-hero assignee=alice}
EOF
bf build
bf validate
```

## Query pure JSON records (`bf query`, `bf read`, `bf review`)

```bash
# Lexical search across all compiled note and sensor JSON records (rg)
bf query "product page"

# Filter heading and keyed attr_list metadata (jq)
bf query --jq 'select(.attrs.decision.owner == "product") | {ref, title, attrs}'

# Run sandboxed analytical SQL over memories/**/*.json (duckdb)
bf query --sql "SELECT source, kind, ref, title FROM records ORDER BY source"

# Read an exact section or JSON filter via bf:// URL
bf read "bf:///projects/new-website.md#decision"

# Check stale notes, newer evidence, and open tasks
bf review
```

## Connect your coding agent

There is zero global config file. `bf` resolves `--brain PATH` -\> `BF_BRAIN` -\> nearest enclosing `bf.yaml` -\> `DEFAULT_BRAIN_PATH`. Inside a brain directory, agents automatically open or reuse an action workspace (`bf action "<topic>"`); outside a brain directory, set `export DEFAULT_BRAIN_PATH="$HOME/brain"`, copy `skills/bf` to `~/.agents/skills/bf`, and invoke `/bf` explicitly (or configure `bf mcp`).

## Upgrade and pinned runtimes

Upgrade the installed CLI with `uv tool upgrade brain-framework`, check the [changelog](<https://github.com/fmind/brain-framework/blob/main/CHANGELOG.md>) for any manual `bf.yaml` or `schemas/` steps, and run `bf build && bf validate && bf eval` inside your brain.
