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, jq, and duckdb (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/**/*.jsonandlogs/*.json, enforced byschemas/*.json), 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
rg,jq, and sandboxedduckdb, cross-references to relative Markdown paths and standardbf://URLs, and orchestration (defaults,jobs,channels,servers,watch,mcp) tobf.yaml— with zero custom databases, built-in LLMs, or provider SDKs.
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
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.
- 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 schedules, JSON event triggers, channels, daemons, and Rich TUI monitoring viabf.yaml(defaults,jobs,channels,servers,watch). - Standard JSON retrieval & MCP (Retrieval): Resolve
bf://anchors and#<jq_filter>fragments withbf read, search and joinmemories/**/*.jsonviabf query(rg,jq,duckdb), run deterministicbf evalchecks, or expose read-only tools viabf mcp. - Integrity & freshness (Reference):
bf validatechecks every schema, link,#anchor, and cross-brainbf://reference;bf reviewsurfacesnewer_evidence, overduestale_afternotes, and opendraftactions.
- Local-first and private. Zero global config (
--brain->BF_BRAIN-> enclosingbf.yaml->DEFAULT_BRAIN_PATH),O_NOFOLLOWpath confinement, private0700.bf/locks/state, and locked read-only DuckDB queries (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