Getting started¶

By the end of this walkthrough, you will have a saved decision, a search that finds its reason and three checks that keep it retrievable. No sensor, account credentials or model is needed.

Install uv, then Brain Framework. uv supplies Python 3.14 if needed. If bf is not on PATH, run uv tool update-shell and open a new shell.

uv tool install --python 3.14 'brain-framework==9.2.0'
bf --version

Create a brain. init also registers it in ~/.config/bf/config.yaml, so bf search finds it from any directory and bf update may run its sensors on this machine.

bf init ~/knowledge --name brain
cd ~/knowledge && git init
bf search welcome
bf read concepts/welcome.md

Write one note per project in projects/ and reusable knowledge in concepts/. Search notices edits by itself. Add a sensor only when it answers a question you ask repeatedly; see sensors, then schedule bf update.

Save a decision¶

Create projects/archive.md in the brain:

---
type: project
status: active
summary: Keep original evidence so decisions remain explainable.
---

# Archive

## Decision

Keep original evidence because providers may delete old content.

## Next actions

- [ ] Document the retention policy.

bf search "providers delete old content"
bf read projects/archive.md#decision
bf validate

The result names the file and section; read returns that section directly. No indexing command is needed. As the project changes, update the note in place and let Git keep its history. Add dates, evidence links and retrieval cases as the note grows; see notes and retrieval cases.

Join a team brain¶

Clone the team's private repository and register it. Run the search outside either brain to cover both, with each result labelled by its brain.

git clone git@github.com:team/knowledge.git ~/team-knowledge
bf register ~/team-knowledge
cd ~
bf search "release process"

Registration without --collect never runs the team's sensors on your laptop. Team records are usually collected by CI; see team brains to create one or resolve a name already taken on your machine.

Check the answers your team needs¶

Before adding integrations, try a small pilot: one project, one owner who keeps its note current, and three questions a teammate needs answered. Return to ~/knowledge, where you saved the archive decision, and create queries.yaml there:

# https://fmind.github.io/brain-framework/docs/search/
version: 3
cases:
  - name: find-the-reason
    query: providers delete old content
    expect: [projects/archive.md#decision]
    text: [providers may delete old content]
  - name: find-the-next-action
    query: retention policy
    expect: [projects/archive.md#next-actions]
    text: [Document the retention policy]
  - name: avoid-an-unrelated-answer
    query: nonexistent-pilot-topic
    empty: true

cd ~/knowledge
bf eval
bf validate

The expected result is "score":"3/3" with "passed":true, and "valid":true. Replace these cases with your team's actual questions. Ask a teammate to repeat the walkthrough from a fresh clone and read the returned refs: retrieval checks establish that evidence is reachable; people still verify that it answers the question.

Commit reviewed notes and retrieval cases to your private team repository through your normal review process; create that brain with a team-specific name as described in team brains. Keep personal records in a separate brain, and pass --brain NAME when selecting context for work. Start collecting only when a recurring question needs evidence the notes do not contain.

Give agents access¶

Follow the skill installation guide to install bf-use in a directory your host discovers. Add bf-learn when you want the agent to maintain notes after work. Copy the whole skill folder, including any templates; installing the Python package does not install skills.

From a new agent session, ask: "Search my brain for why we keep original evidence. Read the source and cite its ref." The agent should search that brain and read projects/archive.md#decision before answering. This checks that the host actually reaches your knowledge. Hosts that prefer tools can register bf mcp --brain brain instead; see MCP.

For a work host, choose the team brain explicitly. An agent's model provider may receive retrieved text even though Brain Framework itself searches offline; see separating audiences.

Try the example¶

The runnable example contains a fictional project, OKF concept, resumable action, a credential-free sensor and retrieval cases. Follow its README in a disposable copy.

Update Brain Framework¶

Read the release notes, then update the tool and check your brain:

uv tool install --upgrade --python 3.14 'brain-framework==9.2.0'
bf --version
bf validate --brain brain
bf eval --brain brain

Run eval once your brain has queries.yaml. Review and update separately installed skills, and restart an MCP host that still runs the old process. Within a major version, the brain format (bf.yaml, queries.yaml and the folder layout) stays compatible. A new major version supports only its current format and documents manual upgrade steps; historical breaking changes are recorded in the changelog.

Transition from FKF¶

Brain Framework 9 uses one current format: version 3 of bf.yaml and queries.yaml. FKF 8 brains need a one-time transition before this package can read them: preserve the original files and machine state, pause collection, rename the brain layout and configuration, update authored links and integrations, carry over collection trust and successful-run windows, then rebuild and validate. Record payloads, IDs and provenance stay unchanged; pending transaction originals remain with memories/. There is no compatibility command or automatic migration.

The v9 release notes list the interface changes. Earlier release notes retain the names and formats used at the time.

When something is wrong¶

If an operation reports a pending record transaction, preserve memories/.pending/, inspect the brain and run bf build to recover durable originals and rebuild. Ordinary search/read never apply a journal from an untrusted brain.