Core concepts¶

A brain is a folder of notes and collected evidence that you own. People and agents use it to remember why decisions were made, find current work and carry context into the next session.

Four kinds of knowledge¶

Projects, concepts and action ACTION.md notes are Markdown with YAML metadata in the OKF format. Records are JSON files, one per collected item. A record shows what a source said, not that it is true.

From source to decision¶

Gather → normalize → organize and connect → act → learn.

Getting started runs the first three steps with one local file, then shows BF flagging the project when that file changes.

Programs¶

A brain can hold three kinds of programs, all declared in bf.yaml and reviewed by you:

Each program keeps its recent output and errors in logs/NAME.log. Sensors, routines and prompts explain their setup; timing and health says when they run.

Retrieval and connections¶

Linking knowledge shows how to add connections.

What stays authoritative¶

• Files are the source of truth: notes you write and records sensors collect.
• The cache in .bf/ is disposable SQLite data, rebuilt from the files.
• Provider tools stay authoritative for their own items; records keep what was collected and when.
• Retrieval cases in evals/ check that useful answers stay findable.
• Skills are procedures an agent follows; MCP lets an agent host call BF's search and read.
• Related brains are local folders declared under brains:; retrieval includes them, and nothing downloads or runs them.

What BF does not do¶

These boundaries hold everywhere; other pages link here instead of repeating them.

• It never runs a model itself. Search matches words and exact identities, without embeddings, translation or generated answers; prompts start your agent harness, which does the reasoning.
• It infers nothing. Similar names never establish an identity, and prose never creates a relation. Links, aliases and field mappings are explicit.
• It does not verify truth. Validation checks structure and links; a passing retrieval case checks the chosen evidence. A record shows what its source said.
• Retrieval never collects. bf search and bf read never contact providers or run programs. A fresh cache can hold old evidence: check source coverage before calling evidence current.
• An incomplete result proves no absence. A reply with problems or stale, a failed source or a missing period cannot show that something does not exist. One page of results is not the whole result.
• Reminders are not reviews. A review flag comes from dates, file edits and linked evidence. It never marks a note as checked.
• Programs run only when you ask. Sensors, routines and prompts run through bf collect, bf run, bf update, bf watch or a schedule you install, in one selected brain. Registration and references never grant execution.
• It is not a sandbox or a backup. Programs run with your account's permissions; keep backups of your brain.

Glossary¶