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 triggers 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 thebfCLI, MCP, Agent Skills andAGENTS.md. - Explicit graph and provenance.
bf.yamlmap:rules or scripts map provider fields into shared relations once at collection. Every claim keeps its source record, andnewer_evidenceflags notes when upstream evidence changes. - Controlled autonomy. Scheduled or event-triggered jobs (
jobs:) with reviewedgate:scripts wake your harness only when needed and deliver answers viabf postor validatedACTION.mddrafts.
Try it · How it works · Agents · Your tools · Proactive agents · Boundaries · Documentation
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/ |
Standalone scripts printing JSON/JSONL or raw exports shaped by bf.yaml map: |
routines/ |
Deterministic scripts (like weekly-review.py) run on intervals, at, events or Git hooks |
bf.yaml declares shared fields and mappings and unified jobs: covering sensors, routines and channels. 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 withbf read review, verify and citeSOURCE:IDrefs and export graph claims.bf guide authoring: update owningprojects/andconcepts/, manage trackedactions/(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: configurejobs:,map:,bf watchtriggers, recover queues and use Git hooks.
See agent workflows and optional repository hooks.
Bring your tools
Copy a standalone stdlib script into sensors/ (or pair any JSON/JSONL CLI with bf.yaml map:): 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):
Let your agent come to you
A prompt job watches your brain offline and invokes your harness only when an event or gate: triggers it:
jobs:
triage:
prompt: prompts/triage.md
harness:
[
claude,
--print,
--output-format,
json,
--tools,
"Read,Grep,Glob,Bash",
--allowedTools,
"Bash(bf read *),Bash(bf search *)",
--permission-mode,
dontAsk,
]
extract: /result
emit: message
post: desktop
on:
- { every: 600, event: { kind: record, source: mail } }
Event rules and gate: scripts skip quiet intervals without starting a model, extract: unwraps harness JSON, and post: delivers answers through your channel (while emit: action writes validated draft ACTION.md notes). See safe prompts and propose, then act.
Good to know
- Local-first and private. No BF server, account or telemetry; retrieval is 100% offline (privacy and security).
- Harnesses reason; BF verifies. BF runs no LLM and ships no provider SDKs or embeddings (
bf export --kind itemsfeeds external retrievers; what BF does not do). - 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 24.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-24.0.0.tar.gz | 246.8 kB | With provenance | Details for brain_framework-24.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| brain_framework-24.0.0-py3-none-any.whl | Python 3 | none | any | Details for brain_framework-24.0.0-py3-none-any.whl |
Total release size: 511.6 kB
Release files / brain_framework-24.0.0.tar.gz
| Download URL | brain_framework-24.0.0.tar.gz |
|---|---|
| Size | 246.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
175ef90203851891f3421eecd99734722d32481a0393e91c2836d0f4cce32834
|
|
BLAKE2b-256 checksum How to use checksums |
a30c1ba30eab61d1ee50e36cde52200f0ccf6e596af2accf1bbc915f5ac95a42
|
| 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 logRelease files / brain_framework-24.0.0-py3-none-any.whl
| Download URL | brain_framework-24.0.0-py3-none-any.whl |
|---|---|
| Size | 264.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b600f06e41da34868553bfecf7527a37a0d065f33e416eb1b9e116eecf4841c4
|
|
BLAKE2b-256 checksum How to use checksums |
9ceed91aa923c64dd96c0b215f35b5a471328a9228e250bd21aaa3eef13dccc3
|
| 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 logSecurity for brain-framework 24.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-24.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 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.