Skip to content

About

🧠 Brain Framework: from information to informed actions.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Latest commit

 

History

207 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Brain Framework — Plain-file knowledge and offline retrieval for humans and AI agents

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/**/*.json and logs/*.json, enforced by schemas/*.json), and Markdown for humans (projects/, concepts/, and actions/ parsed with Python-Markdown attr_list metadata, plus plain Markdown inputs under prompts/).
  • Agents always query JSON. bf build compiles Markdown notes, headings, keyed attr_list metadata (attrs), links, and open tasks into memories/{concepts,projects,actions}/*.json; bf ingest writes validated sensor records into memories/<source>/*.json.
  • Minimal, standard-driven core. Under 4,500 lines of Python delegating retrieval to rg, jq, and sandboxed duckdb, cross-references to relative Markdown paths and standard bf:// URLs, and orchestration (defaults, jobs, channels, servers, watch, mcp) to bf.yaml — with zero custom databases, built-in LLMs, or provider SDKs.

CI PyPI Python License: MIT

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
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

Gather, normalize, organize, act, and learn loop
  • 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 with bf:// 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 via bf.yaml (defaults, jobs, channels, servers, watch).
  • Standard JSON retrieval & MCP (Retrieval): Resolve bf:// anchors and #<jq_filter> fragments with bf read, search and join memories/**/*.json via bf query (rg, jq, duckdb), run deterministic bf eval checks, or expose read-only tools via bf mcp.
  • Integrity & freshness (Reference): bf validate checks every schema, link, #anchor, and cross-brain bf:// reference; bf review surfaces newer_evidence, overdue stale_after notes, and open draft actions.

Good to know

  1. Local-first and private. Zero global config (--brain -> BF_BRAIN -> enclosing bf.yaml -> DEFAULT_BRAIN_PATH), O_NOFOLLOW path confinement, private 0700 .bf/ locks/state, and locked read-only DuckDB queries (Operations).
  2. Harnesses reason; BF verifies. Coding agents load the single /bf Agent Skill from .agents/skills/bf, automatically track actions inside a brain (or respond to explicit /bf outside), and run bf build && bf validate && bf eval (Example brain).
  3. Git-native collaboration. Track notes, bf.yaml, evals/, and schemas/ in Git while ignoring compiled note JSON files, logs/, actions/, and .bf/.

Documentation · Reference · Issues · Contribute · Governance · MIT License · Third-party notices

About

🧠 Brain Framework: from information to informed actions.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

6 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages