Skip to main content

Brain Framework: a robot head whose shell opens on a brain, above twin aperture eyes

Brain Framework 🧠

🧠 Brain Framework: from information to informed actions.

Brain Framework (BF) is a local-first brain for you and your AI agents. It collects evidence from your tools into plain files you own, connects them through an explicit ontology, lets any agent harness search and read offline, and wakes your harness when declarative when: rules or reviewed gates spot new evidence.

  • Plain files you own, open to any agent. Markdown notes (projects/, concepts/, actions/) and JSON records (memories/), reached through the bf CLI, MCP, Agent Skills and AGENTS.md.
  • Explicit graph and provenance. bf.yaml maps provider fields into shared relations once at collection. Every claim keeps its source record, and newer_evidence flags notes when upstream evidence changes.
  • Controlled autonomy. Built-in when: gates (sources, review, actions, attention) wake your harness offline with zero wasted model runs, and propose: true lets read-only assistants draft validated ACTION.md proposals.

CI PyPI Python License: MIT

Try it · How it works · Agents · Your tools · Proactive agents · Boundaries · Documentation

The Brain Framework loop: sensors gather evidence into a brain folder; bf.yaml declares the ontology, sensors, routines, assistants, channels and watch settings; memories, projects, concepts and actions form a knowledge graph; agents read context, act and compile outcomes back.

Try it

Requires Linux or macOS and uv — no model or cloud account needed:

uv tool install --python 3.14 brain-framework
bf init ~/brain && cd ~/brain

Save projects/new-website.md:

---
type: project
status: draft
updated: 2026-11-01
summary: Launch a product website that helps visitors understand the product.
---

# New website

## Decision

Start with a single product page because visitors need a clear explanation before signing up.

## Next actions

- [ ] Draft the product page.

Search and read the exact section:

bf search "visitors clear explanation"
bf read projects/new-website.md#decision
bf validate && bf eval

Continue with Getting started or the four-tool walkthrough across Workspace, Jira, GitHub and Google Cloud fixtures.

How it works

Five steps run in one loop: gather → normalize → organize and connect → act → learn.

Folder Role
memories/ Collected JSON records keyed by SHA-256 of id, with provenance, @type, relations and attributes
projects/ Project state (Now), decisions (Decision) and open tasks (Next actions)
concepts/ Durable reusable patterns and reference syntheses
actions/ Tracked work sessions (draft open, stable settled, deprecated retired)
sensors/ Stdlib scripts (built on _sensor.py) printing JSON or JSONL from your tools
routines/ Deterministic scripts (built on _bf.py) run on intervals, at or Git hooks

bf.yaml declares shared fields and mappings, sensors, routines and assistants. A disposable SQLite cache in .bf/ powers offline BM25 search, graph backlinks (bf read project:new-website), triage (bf read review) and JSONL exports (bf export --kind items). See the directory reference.

Open your agent in your brain

Install the packaged /bf skill for Claude Code, Codex, GitHub Copilot or any Agent Skills host:

bf skill install --global         # ~/.agents/skills/bf (and links ~/.claude/skills/bf if present)
bf skill install                  # inside a brain: skills/bf, linked to .agents/skills/bf and .claude/skills/bf

The /bf router connects your harness to built-in offline documentation via bf guide:

  • bf guide retrieval: orient with bf read review, verify and cite SOURCE:ID refs and export graph claims.
  • bf guide authoring: update owning projects/ and concepts/, manage tracked actions/ (bf action new, bf action status) and connect entities.
  • bf guide getting-started / bf guide operations: initialize or register brains, run MCP, validate, evaluate and troubleshoot.
  • bf guide jobs / bf guide events: configure sensors, routines, assistants and bf watch, recover queues and use Git hooks.

See agent workflows and optional repository hooks.

Bring your tools

Copy a reviewed stdlib sensor into sensors/ alongside _sensor.py: local documents, highlights, Git history, GitHub history, Google Calendar, Gmail headers, Drive folders, or any source you can script. Keep them fresh in a terminal or background service with bf watch (offline demo):

Watch dashboard for the fictional offline demo: five sensors sorted by state, with a failed sensor's details beside their last success, next due time, item count and record changes.

Let your agent come to you

An assistant watches your brain offline and invokes your harness only when when: matches:

assistants:
  triage:
    prompt: prompts/triage.md
    command:
      [
        claude,
        --print,
        --output-format,
        json,
        --json-schema,
        "{{schema}}",
        --tools,
        "Read,Grep,Glob,Bash",
        --allowedTools,
        "Bash(bf read *),Bash(bf search *)",
        --permission-mode,
        dontAsk,
      ]
    reply: { path: /structured_output }
    propose: true
    post: desktop
    schedules:
      mail: { every: 600, when: { sources: [mail] } }

when: checks SQLite with zero subprocesses, passes new events to your harness, posts replies to your channel and saves validated draft ACTION.md proposals when propose: true. See safe prompts and propose, then act.

Good to know

  1. Local-first and private. No BF server, account or telemetry; retrieval is 100% offline (privacy and security).
  2. Harnesses reason; BF verifies. BF runs no LLM and ships no provider SDKs or embeddings (bf export --kind items feeds external retrievers; what BF does not do).
  3. Git-native collaboration. Version notes, ontology, programs and evals in Git while keeping local memories and .bf/ caches out of shared history; major releases batch breaking changes cleanly (versioning).

Commands · Issues · Contribute · Governance · MIT License · Third-party notices

Metadata

Release files for brain-framework 23.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brain-framework 23.0.0
File Size Uploaded Provenance Actions
brain_framework-23.0.0.tar.gz 292.2 kB With provenance Details for brain_framework-23.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for brain-framework 23.0.0
File Interpreter ABI Platform Actions
brain_framework-23.0.0-py3-none-any.whl Python 3 none any Details for brain_framework-23.0.0-py3-none-any.whl

Total release size: 604.0 kB

Release files / brain_framework-23.0.0.tar.gz

Download URL brain_framework-23.0.0.tar.gz
Size 292.2 kB
Tags Source
SHA-256 checksum
How to use checksums
fbb783b61458ff3c9825d0a2b9a406f595ebbb0b7e02ad80ec81a05ee79efb3c
BLAKE2b-256 checksum
How to use checksums
611d0a0fc3f1512e7c6412dceaca98f8cf2bfae18fb4a985918844eb6d176999
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / brain_framework-23.0.0-py3-none-any.whl

Download URL brain_framework-23.0.0-py3-none-any.whl
Size 311.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
236e52ca0fdc9bfe5697c83c1eba7ecf12a487ea55ee01edc742ee44dab84044
BLAKE2b-256 checksum
How to use checksums
4822a6783d7facd025bda96c4f969946249d6b316033b15014c7e5d9eb37f75a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for brain-framework 23.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for brain_framework-23.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

23.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page