Brain Framework (bf) turns a flat folder of human-authored Markdown notes and collected JSON records into a schema-validated, pure-JSON knowledge store (memories/**/*.json) that humans and AI agents query offline with rg and jq (bf query, bf read, or bf mcp).
- Three formats, one job each. YAML for config (
bf.yaml,evals/*.yaml, note frontmatter), JSON for records (memories/**/*.json, enforced byschemas/*.json, plusstructlogJSON lines inlogs/*.log), and Markdown for humans (projects/,concepts/, andactions/parsed with Python-Markdownattr_listmetadata, plus plain Markdown inputs underprompts/). - Agents always query JSON.
bf buildcompiles Markdown notes, headings, keyedattr_listmetadata (attrs), links, and open tasks intomemories/{concepts,projects,actions}/*.json;bf ingestwrites validated sensor records intomemories/<source>/*.json. - Minimal, standard-driven core. Under 4,500 lines of Python delegating retrieval to
rgandjq, cross-references to relative Markdown paths and standardbf://URLs, and orchestration (timezone,env,jobs,channels,services,watch) tobf.yaml— with zero custom databases, built-in LLMs, or provider SDKs.
Try it
Requires Linux or macOS, uv, ripgrep (rg), and jq — no model or cloud account needed:
uv tool install --python 3.14 brain-framework
bf init ~/brain
cd ~/brain
bf validate
bf eval
bf review
bf query --jq '{ref, title, attrs}'
Explore the four-tool walkthrough (Workspace, Jira, GitHub, and Google Cloud fixtures) or read Getting started.
How it works
- Notes,
attr_list, &bf://URLs (Authoring): Separate volatile TODOs (projects/), durable knowledge (concepts/), and dated workspaces (actions/*/ACTION.md). Attach metadata on headings (## MCP {#mcp creator=Anthropic}) and blocks ({: #summary confidence=high}), and cross-reference notes or sibling brains withbf://URLs. - User schemas, jobs, & live watch (Operations): Ship user-owned JSON Schemas in
schemas/, copy stdlib sensors from examples/sensors, and orchestrate cron/duration schedules,structlogJSON logs, event triggers, channels, services, and Rich TUI monitoring viabf.yaml(jobs,channels,services,watch). - Standard JSON retrieval & MCP (Retrieval): Resolve
bf://URLs and#anchorsections withbf read, search and filtermemories/**/*.jsonviabf query(rg,jq), run deterministicbf evalchecks, or expose read-only tools viabf mcp. - Integrity & freshness (Reference):
bf validatechecks every schema, compiled-note sync, link,#anchor, and cross-brainbf://reference;bf reviewsurfacesnewer_evidence, overduestale_afternotes, and opendraftactions.
Good to know
- Local-first and private. Zero global config (
--brain->BF_BRAIN-> enclosingbf.yaml->DEFAULT_BRAIN_PATH),O_NOFOLLOWpath confinement, and private0700.bf/locks/state (Operations). - Harnesses reason; BF verifies. Coding agents load the single
/bfAgent Skill from.agents/skills/bf, automatically track actions inside a brain (or respond to explicit/bfoutside), and runbf build && bf validate && bf eval(Example brain). - Git-native collaboration. Track notes,
bf.yaml,evals/, andschemas/in Git while ignoring compiled note JSON files,logs/,actions/, and.bf/.
Documentation · Reference · Issues · Contribute · Governance · MIT License · Third-party notices
Metadata
Release files for brain-framework 28.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| brain_framework-28.0.0.tar.gz | 99.3 kB | With provenance | Details for brain_framework-28.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| brain_framework-28.0.0-py3-none-any.whl | Python 3 | none | any | Details for brain_framework-28.0.0-py3-none-any.whl |
Total release size: 208.9 kB
Release files / brain_framework-28.0.0.tar.gz
| Download URL | brain_framework-28.0.0.tar.gz |
|---|---|
| Size | 99.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
850f867f9b33ec7a5e2f7ad01b9f6a6c07acdafbb6b37e014c1cdf851e72adac
|
|
BLAKE2b-256 checksum How to use checksums |
e5acf4b512de5aceb28594b926380994437688c7783e433dd338b459f7b0c848
|
| 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 17, 2026.
Transparency logRelease files / brain_framework-28.0.0-py3-none-any.whl
| Download URL | brain_framework-28.0.0-py3-none-any.whl |
|---|---|
| Size | 109.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b09df2b153593c5fc150748c3bf005024be8f267f03fe4e0ce5aa58b70dd1d36
|
|
BLAKE2b-256 checksum How to use checksums |
f2aa92d3f20e9ebb74dc565dcd5a01f8359c43215f8cdffffb10831a7205f42e
|
| 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 17, 2026.
Transparency logSecurity for brain-framework 28.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.
Attestation for brain_framework-28.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 17, 2026.
Transparency logA 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.