Limits and safeguards¶

Look up exact limits for a skipped file, a partial reply or a stopped program. For recovery steps, start with Troubleshooting; for what to review before collecting or sharing, see Privacy.

Size bounds¶

Folder entries:

• Each record takes one folder entry.
• bf status warns above 80,000 entries without failing --check.
• A tree over the limit fails the scan and names the folder.
• Split a crowded source's sensor or archive its older records.
• Keep bulky imports in the brain's root inputs/ or originals/, which are not scanned.

A long pasted question matches only its first 32 distinct words after function words are dropped: keep the distinctive terms.

Page sizes bound one reply, not the result: follow next_offset. SQLite still ranks every match up to a deep offset, so very deep pages take longer.

Processes and logs¶

Sensors, routines and assistants run from the brain folder with direct arguments, without a shell.

• Their standard input is /dev/null, with two exceptions: what a hook or bf run --stdin pipes to a routine, and the expanded prompt of an assistant command without {{prompt}}.
• They receive BF_BRAIN set to that brain, so a nested bf call reads the brain running it.

BF removes environment variables that could load code before your program starts, such as BASH_ENV or PYTHONPATH:

Other variables, including provider credentials and absolute PATH entries, remain. The list is best effort, not a sandbox.

• When a program needs dependencies, use an explicit runtime such as uv run --no-project sensors/example.py.
• A program that needs one of these variables sets it in its own command, such as [env, R_ENVIRON_USER=/path/to/Renviron, Rscript, sensors/example.R].

How a run ends:

• A run ends when the program exits and its standard output closes.
• When a run ends, successful or not, BF kills the program's whole process group. Background helpers end with it unless they leave that group, as daemons that start their own session do.
• A timeout, cancellation or closed terminal ends a run early, as does output beyond max_bytes from a sensor or action routine. Partial output never replaces stored records.
• Cancellation during startup waits until BF owns the new process, then kills its group too.
• A program that another process kills, such as the out-of-memory killer, fails naming the signal: program was killed by SIGKILL.
• A background helper that keeps standard output open more than a second after the exit fails the run. Redirecting its output, for example to /dev/null, avoids that failure, not the kill.
• A helper holding only stderr never delays or fails the run.
• Watch, and the service files in Run watch as a service, allow at least 60 seconds after a stop request, so an interrupted record write can roll back.

Each run appends entries to the program's logs/NAME.log in the brain:

1. a == TIME OUTCOME == heading when the program exits;
2. its stderr and a log routine's stdout;
3. another heading with the run's result, such as the records collected or the failure.

Log rules:

• The log keeps its newest whole entries within 1 MiB.
• Errors and run history name the log without quoting provider output.
• bf init ignores logs/ in Git, and search never reads it.
• A log can still hold provider output: keep it private and never paste it into a public issue.

Search and read keep a local usage.jsonl:

• Each event holds the time, operation, kind and result count, plus, on zero-result searches, up to 8 unmatched tokens of at most 64 characters each.
• A search's kind names its scope: none, period, folder, note, memories, source, source-period, record, identity, tag, or combined for a period with another scope. A source with a period, written either way, counts as source-period.
• A read's kind names its page: home, period, tasks, tags, tag, memories, source, source-period, record, folder, note, section, action, identity or relation.
• It never holds query text, refs, paths or identities.
• Beyond 1 MiB, BF sums each earlier UTC day into one line, with up to 32 unmatched tokens, and drops days older than 30. Today's events stay as they are unless they alone pass 768 KiB.
• bf status summarizes today with the 6 or 29 UTC days before it. Events written before kinds existed count in the totals only, and a cut made by an older release still marks the windows it shortened with since.

Assistants, channels and the queue:

See channel limits and recovery.