Operations¶
Orchestrate one-shot jobs, bidirectional channels, and constant servers declaratively in bf.yaml (defaults, jobs, channels, servers, watch), auto-load local .env overrides, validate schemas and Git hooks, and preserve strict filesystem and process boundaries.
Ingest sensor records and orchestrate jobs, channels, and servers¶
Sensors are standalone scripts (examples/sensors/: git-history.py, github-issues.py, gmail-headers.py, local-documents.py, and circular agent-telemetry.py) emitting a JSON array, {"records": [...], "incomplete": {"missed": N}} envelope, or JSON Lines. Pipe them into bf ingest SOURCE or declare them in bf.yaml:
version: 12
name: my-brain
defaults:
timezone: UTC
env:
GOOGLE_WORKSPACE_CLI_CONFIG_DIR: "{{home}}/.config/gws"
jobs:
github-issues:
run: [python3, sensors/github-issues.py, acme/demo, "{{start}}", "{{end}}"]
ingest:
source: github-issues
mode: upsert
every: 30m
lookback: 1d
overlap: 5m
build:
builtin: build
events:
- kind: records.ingested
morning-brief:
run: [claude, -p, "Context file: {{context}}"]
input: prompts/morning-brief.md
at: "08:00"
days: [mon, tue, wed, thu, fri]
channel: chat
assistant:
run: [claude, -p, "Context file: {{context}}"]
input: prompts/reactive.md
events:
- kind: channel.message
source: chat
filter: ".data.direct == true"
channel: chat
pre-commit-check:
builtin: validate
hook: pre-commit
channels:
chat:
listen: [python3, channels/google-chat.py, listen]
send: [python3, channels/google-chat.py, send]
timeout: 1m
servers:
mcp:
run: [bf, mcp, --transport, http, --port, "8765"]
enabled: false
watch:
interval: 5s
debounce: 300ms
- Humanized durations:
every,lookback,overlap,timeout,watch.interval,watch.debounce, and notestale_afteraccept humanized strings (300ms,30s,15m,1h30m,1d,1w) or numeric seconds. - Explicit
env:map +.envoverrides:defaults.envand unitenv:define non-secretKEY: "value"settings (expanding{{brain}},{{home}}, and{{state}}), while an optional gitignored.envin the brain root supplies local secrets or overrides even whenbfruns from another folder via--brain PATH. - Generic
jobs(input:,ingest:,channel:):jobsrun any one-shot command on schedules, Git hooks, orlogs/events.jsontriggers.input: prompts/foo.mdfeeds the file verbatim onstdinand exposes its path as{{input}}(and"input"in{{context}});ingest:accepts shorthandingest: fooor{source: foo, mode: snapshot, allow_removal: false};channel: chatposts stdout viachannels.chat.send. - Bidirectional
channels& constantservers:channels.<name>.listenstreams inboundchannel.messageevents andchannels.<name>.senddelivers outbound messages (bf postauto-selects the channel when only one enabled channel definessend).servers.<name>.runsupervises constant daemons (bf watch). - Pure JSON storage &
.forgotten:bf ingestvalidates records againstschemas/record.json+ optionalschemas/<source>.jsonand writesmemories/<source>/<sha256(id)>.jsonatomically while honoringmemories/<source>/.forgotten. - Snapshot removal guard & incomplete batches:
--mode snapshotskips pruning whenincomplete.missed > 0and refuses >50% drops on 10+ saved records unless--allow-removal(allow_removal: true) is set.
Limits and safeguards¶
- Confined
O_NOFOLLOWaccess:bfopens every brain file (including.env) throughO_NOFOLLOWdirectory descriptors; symlinks inside managed folders are rejected. - Bounded sizes:
bf.yamlandschemas/*.jsoncap at1 MiB(.envcaps at64 KiB); OKF notes cap at4 MiB;bf ingestbatches cap at16 MiB; scanned trees cap at100,000entries and64levels. - Sandboxed DuckDB SQL:
bf query --sqlrejects dot-commands, appliesSET memory_limit = '512MB';before materializingCREATE TEMP TABLE recordswith explicit columns, and locks configuration withSET enable_external_access = false; SET lock_configuration = true;before running user SQL.
Privacy and security boundaries¶
- No built-in LLM or provider SDK:
bfnever calls model APIs directly;run,listen, andsendcommands execute with literalargv(shell=False), clean allowlisted environments merged withdefaults.env, unitenv:, and brain-root.env(never overridingBF_BRAIN,BF_STATE_DIR,BF_START,BF_END,BF_TRIGGER,LC_ALL, orLANG), dedicated process groups, and.bf/state/<name>.context.json(0600). - Private
.bf/state & sanitized errors:.bf/(locks/,state/) is enforced as0700owned bygeteuid(),bf mcpredacts local filesystem roots, and diagnostics strip control/format characters and omit raw schema failure values.