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, andduckdb
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.