Reference¶
Complete contract lookup for Brain Framework (bf), flat brain layout, bf.yaml (version: 12), pure JSON memories/**/*.json and logs/*.json schemas, and exit codes.
CLI commands¶
Every command writes one compact UTF-8 JSON object to stdout (except bf --version, --help, and live bf watch) and single-line bf: ... diagnostics to stderr.
bf --version: print the installed package version.bf init PATH [--name NAME]: scaffold a flatversion: 12brain withbf.yaml,.gitignore,AGENTS.md,concepts/welcome.md,docs/index.md,evals/smoke.yaml,schemas/{record,concepts,logs,evals}.json,skills/bf/SKILL.md(.agents/skills/bf), andmemories/concepts/welcome.json.bf build [--brain PATH]: compileprojects/**/*.md,concepts/**/*.md, andactions/*/ACTION.mdintomemories/{projects,concepts,actions}/<slug>.json, pruning deleted notes.bf ingest SOURCE [--input FILE] [--mode upsert|snapshot] [--allow-removal] [--dry-run] [--brain PATH]: validate records againstschemas/record.json+ optionalschemas/<source>.jsonand writememories/<source>/<sha256(id)>.json.bf validate [--brain PATH]: read-only check ofbf.yaml,schemas/*.json, OKF notes,memories/**/*.json,logs/*.json,evals/*.yaml, and local/bf://links.bf review [--brain PATH]: read-only report ofstalenotes (newer_evidence,due,future_updated), opendraftactions, andtasks_open.bf read [TARGET] [--brain PATH]: inspect the brain overview (countsand failed-unitattention) or resolve a note path,#anchor,source:idrecord, cross-brainbf://<host>/<path>?...#<anchor|jq>, or#<jq_filter>fragment.bf query [PATTERN] [--jq EXPR | --sql SQL] [--scope PATH] [--limit N] [--brain PATH]: runrg,jq, or sandboxedduckdbovermemories/**/*.json.bf action TOPIC [--status draft|stable|deprecated] [--summary TEXT] [--brain PATH]: create or reuseactions/YYYY-MM-DD_<slug>/ACTION.md(withinputs/andoutputs/).bf eval [SUITE] [--brain PATH]: run deterministic query checks inevals/*.yaml.bf run [JOB ...] [--due] [--hook pre-commit|pre-push] [--dry-run] [--brain PATH] [-- EXTRA_ARGS...]: execute configured jobs, due schedules/events, or Git hooks.bf status [--check] [--brain PATH]: inspect"inside_brain",events_seq,jobs,channels, andservers(--checkexits1on failed units or missingrequiresbinaries).bf post [TEXT] [--stdin] [--to CHANNEL] [--thread ID] [--reply-to ID] [--run ID] [--dry-run] [--brain PATH]: send an outbound message viachannels.<name>.send(--tois optional when a single enabled channel definessend).bf watch [--once] [--json] [--brain PATH]: run thewatchfilessupervisor and Rich TUI dashboard (--onceruns one tick and prints JSON;--jsonstreams tick lines).bf mcp [--transport stdio|http] [--port PORT] [--brain PATH]: run the read-only MCP server (bf_review,bf_read,bf_query,bf_validate).
Brain selection resolves --brain PATH -> BF_BRAIN -> nearest enclosing bf.yaml -> DEFAULT_BRAIN_PATH (zero global config).
Exit codes¶
0: success (valid: trueonbf validate,ok: trueonbf eval/bf run/bf status --check).1: validation failure, failed job/eval, missing/corrupt files, schema violation, or lock contention.2: invalid CLI flags or malformed argument syntax (bf: invalid input: ...).130: interrupted (SIGINT).
Flat brain layout¶
projects/, concepts/, actions/, memories/, logs/, evals/, docs/, skills/, schemas/, optional operational folders created as needed (sensors/, routines/, channels/, prompts/, settings/), optional gitignored .env, plus private .bf/ (0700: locks/, state/).
bf.yaml schema¶
Published at bf.schema.json:
version: 12
name: my-brain
brains:
team-brain: ../team-brain
defaults:
timezone: UTC
env: {}
jobs: {}
channels: {}
servers: {}
watch:
interval: 5s
debounce: 300ms
Published JSON Schemas¶
bf.schema.json:bf.yaml(Config).record.schema.json:schemas/record.json(Record— frontmatter +headings, keyedattrs,elements,links,tasks,text,sha256).concepts.schema.json:schemas/concepts.json(Concept— user-defined concept metadata).logs.schema.json:schemas/logs.json(Log—logs/<name>.jsonandlogs/events.json).evals.schema.json:schemas/evals.json(Eval—evals/*.yamldeterministic checks).