v20.1.0

A feature release for integrations and evidence hygiene. The brain format (version: 8), existing bf.yaml files, the search and read reply schemas and the search cache are unchanged. Upgrade steps: run bf skills DIR to update the packaged skills, and check that no sensor relies on the silent cut of record text above 4 MiB fixed below: set truncate_text: true on such a sensor. A new brain from bf init declares the standard vocabulary; an existing brain keeps its fields.

Added

• Skill behavior eval. mise run eval:skills runs five cases in headless Claude Code against a fresh copy of the example brain, isolated from user settings and provider tools, and grades the skill used, the cited ref, forbidden commands and written files. It needs a Claude login and spends tokens, so it stays out of mise run all (contributing).
• Sensor kit and standard vocabulary. examples/sensors/_sensor.py is a standard-library helper file to copy next to your sensors: window and state from the environment, bounded provider CLI calls and HTTPS fetches, identities, credential masking and records within BF's bounds; github-issues.py shows a sensor built on it. bf init now declares the standard vocabulary with default paths, so a sensor printing author_refs, sender_refs, status and the like needs no fields: mapping in a new brain. The Gmail example prints sender_refs and recipient_refs instead of from_refs and to_refs, and the GitHub history example status instead of state: update a mapping copied from them.
• Check saved sensor output. bf collect SENSOR --input FILE (or - for stdin) validates and projects saved output with the brain's current mappings without running the sensor or saving anything, even for a disabled sensor: a contract test for sensors (check saved output).
• Program environment. Sensors and routines receive BF_PROGRAM, their window as BF_START and BF_END, and BF_STATE_DIR, a private directory on this machine for cursors and tokens kept between runs (what a program receives).
• Forget and expire records. bf forget REF... removes collected records and lists their digests in memories/SOURCE/.forgotten, so collection never stores them again; a sensor's expire_after removes records older than its retention and skips older ones it prints again. Runs report forgotten and expired counts (keep, forget and expire records).
• Retired sources. A sensor or routine with enabled: false may omit command, so a retired source keeps its records searchable without a placeholder command.
• Period plus scope. A search scope can combine a period with one other scope, such as --scope "7d repo:github.com/owner/name" for the records naming a repository this week (scopes).
• Text export. bf export --kind items prints every note and record with its metadata, fields and text as JSON Lines, for retrievers outside BF such as embedding or multilingual search.
• Assistant trigger and harness status. A harness learns why it runs from BF_TRIGGER (input, schedule or manual), BF_SCHEDULE and its BF_START/BF_END window, so a wrapper no longer parses the prompt. The optional status: {path, success} setting turns a failure the harness reports in its JSON output while exiting 0, such as a model API error, into a failed attempt with the usual uncertain or idempotent retry rules; the error names at most a one-word status, never the output (assistants).

Fixed

• Oversized record text. A record whose text exceeds 4,194,304 characters now fails its collection, as documented, unless the sensor sets truncate_text or max_text_bytes; it was cut silently. The sensor settings now state the actual 4 MiB default and 1–4,194,304 byte range of max_text_bytes.

Changed

• Usage counts. bf status usage covers the full 7 and 30 days on busy brains: rotation sums each past UTC day into one line instead of dropping the oldest events; since remains only while a cut made by an earlier release falls inside a window. Each window adds kinds, the searches by scope kind and reads by page kind, and empty_kinds, the scope kinds of zero-result searches; the log still keeps no query text, refs or paths (limits). Windows now count today and the 6 or 29 UTC days before it, instead of the last 168 or 720 hours.
• Packaged skills. bf-use and bf-action check the bf version once per session instead of before every task, and ask bf status about a pinned runtime only in a brain with a uv.lock. Helpers run by their literal path (python3 SKILL_DIR/scripts/NAME.py with the absolute folder) and take multi-line text from files, because hosts with strict permissions refused the $SKILL_DIR variable and $'…' quoting, which blocked saving a decision and starting an action. bf-action resumes only an action whose folder topic matches, not one that mentions the subject, and bf-maintain's description leaves choosing sources to bf-setup. Run bf skills DIR after upgrading.
• README. About half as long, with a quickstart after the first figure and each point made once; details moved to the linked documentation.
• Documentation. Every page reads faster with the same content: guides open with the main path, edge cases sit in reference sections or collapsed blocks, and dense paragraphs became tables and lists. Sentences over 40 words dropped from 84 to 30. Page paths, heading anchors and examples are unchanged.
• Major releases. A breaking change ships in a major release whenever the design needs it, instead of waiting for a quarterly window; related breaks still batch where practical (Contributing). AGENTS.md is about half as long and names the current scope: no model inference, provider SDKs or record sync in the core, integration helpers as a copy-in kit, and assistants, channels, watch and multi-brain retrieval open to improvements backed by real use.
• Release tooling. scripts/release.py prepares a release in a clean clone that ships only the named paths, runs the gate, publishes after CI and CD, verifies the artifacts and syncs the primary checkout only when no other session changed a released path. The release checklist keeps only the judgment steps.