Brain Framework (bf) turns a 3x3 folder of human-authored Markdown notes, shell/Python loops, and JSONL records (memories/<source>.jsonl, usages/<source>.jsonl, logs/<loop>.jsonl) into a schema-validated, UNIX-native knowledge brain with zero database or external indexer—ready for humans and AI coding harnesses to query offline with rg, jq, and DuckDB.
- Three formats, one job each. YAML for config (
bf.yamlversion: 17+ note frontmatter), Markdown for humans (concepts/,projects/,actions/with flat<slug>.mdand universal<slug>/index.mdbundles), and JSONL for records (memories/,usages/, and privatelogs/, validated by bundledbf/recordschemas plusschemas/<source>.jsonandschemas/usages.json). - Strict read/write boundary & UNIX composability.
bf status,bf review,bf read,bf query,bf check, andbf schemaare strictly read-only and never mutate disk; flat JSONL files stay directly inspectable withrg,jq, and DuckDB. - Convention-first
loops:with zero built-in LLMs. Under 6,500 lines of Python with just 5 minimal runtime dependencies (croniter,jsonschema,markdown,pyyaml,watchfiles), unifying deterministic collectors (sensors/), routines (routines/), coding-harness agents (agents/), and daemons (when: daemon) viaBF_*env +stdinJSON,stdoutJSONL data/events,stderrstructured JSONL logs, andlogs/events.jsonl.
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 check
bf status --format text
bf review
bf query --jq '{ref, title, headings}'Explore the four-tool walkthrough (Workspace, Jira, GitHub, and Google Cloud fixtures) or read Getting started.
- Uniform notes,
index.mdbundles, & required schemas (Authoring): Organize Markdown acrossconcepts/,projects/,actions/(or customnotes:dirs) using flat<slug>.mdfiles or universal<slug>/index.mdbundles, enforce bundledrecord+schemas/<source>.json/schemas/usages.json, attach#idheading anchors and{rel=...}link metadata, and link across notes, records (source:id), or declared sibling brains (bf://). - Convention
loops:(sensors/,routines/,agents/), two-stream JSONL, &bf watch(Operations): Drop shell (.sh), Python (.py), or executable scripts insensors/(auto-impliesingest: upsert),routines/, oragents/(15m default timeout), stream structured JSONL logs onstderrintologs/<loop>.jsonl, coordinate overlogs/events.jsonl, and supervise withbf watch(bird's-eye status + live text or--format jsonl). - Strictly read-only retrieval & FinOps separation (Retrieval): Resolve notes,
#anchorsections,source:idrecords, orbf://URIs uniformly withbf read, searchmemories/*.jsonlorusages/*.jsonlviabf query(rg/jq) or DuckDB, and inspect live health withbf status --format text. - Integrity, freshness, & schemas (Reference):
bf checkvalidatesbf.yaml, schemas, compiled-note sync,memories/&usages/, enabledloops:, links,#anchorheadings, and declared cross-brainbf://refs;bf reviewsurfacesnewer_evidence, overduestale_afternotes, and open tasks;bf schemaprints the 2 bundled Draft 2020-12 JSON Schemas (bf,record).
- Local-first and private. Zero global config (
--brain-> enclosingbf.yaml->BF_BRAIN->$BRAIN_LOCATION->~/brain),O_NOFOLLOWpath confinement, disposable0700.bf/(locks + loop cursors), and private0700logs/(Operations). - Harnesses reason; BF verifies. Coding agents orient with
bf statusandbf review, author Markdown notes directly, emit events viabf emit, and verify withbf build && bf checkplus Python/pytest suites inevals/(Example brain). - Git-native collaboration. Track notes,
bf.yaml,schemas/,sensors/,routines/,agents/,clients/,prompts/, andevals/in Git while ignoringmemories/(keeping*.forgotten),usages/,logs/, and.bf/.
Documentation · Reference · Issues · Contribute · Governance · Security · MIT License · Third-party notices