Skip to content

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 (for Python 3.14 tool installation)
  • Standard CLI tools for retrieval: ripgrep (rg), jq, and duckdb

Install and initialize a brain

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:

{ "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:

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:

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)

# 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 for any manual bf.yaml or schemas/ steps, and run bf build && bf validate && bf eval inside your brain.