Skip to main content

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 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 by schemas/*.json, plus structlog JSON lines in logs/*.log), 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 and jq, cross-references to relative Markdown paths and standard bf:// URLs, and orchestration (timezone, env, jobs, channels, services, watch) to bf.yaml — with zero custom databases, built-in LLMs, or provider SDKs.

CI PyPI Python License: MIT

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

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 cron/duration schedules, structlog JSON logs, event triggers, channels, services, and Rich TUI monitoring via bf.yaml (jobs, channels, services, watch).
  • Standard JSON retrieval & MCP (Retrieval): Resolve bf:// URLs and #anchor sections with bf read, search and filter memories/**/*.json via bf query (rg, jq), run deterministic bf eval checks, or expose read-only tools via bf mcp.
  • Integrity & freshness (Reference): bf validate checks every schema, compiled-note sync, 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, and private 0700 .bf/ locks/state (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

Metadata

Release files for brain-framework 27.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for brain-framework 27.0.0
File Size Uploaded Provenance Actions
brain_framework-27.0.0.tar.gz 99.4 kB With provenance Details for brain_framework-27.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for brain-framework 27.0.0
File Interpreter ABI Platform Actions
brain_framework-27.0.0-py3-none-any.whl Python 3 none any Details for brain_framework-27.0.0-py3-none-any.whl

Total release size: 209.1 kB

Release files / brain_framework-27.0.0.tar.gz

Download URL brain_framework-27.0.0.tar.gz
Size 99.4 kB
Tags Source
SHA-256 checksum
How to use checksums
ee1095864c6de5472f64c846c37d1ba464aaacf6721549180ab0483296b311a8
BLAKE2b-256 checksum
How to use checksums
46f444264da3c3177d26950e8895ce714526b7473005a5bda56c4514eeafd57f
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 log

Release files / brain_framework-27.0.0-py3-none-any.whl

Download URL brain_framework-27.0.0-py3-none-any.whl
Size 109.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
61f0eee5b17ef0c220752d01bb95325b61b79a4d504848570b5ff46e0d3092cf
BLAKE2b-256 checksum
How to use checksums
803a9b8efbc653725356bb63df18708e0f958aa964cac2a3229467316e7ea95a
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 log

Security for brain-framework 27.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.

Select from 2 files

Attestation for brain_framework-27.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 log

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

Release history Release notifications | RSS feed

This release

27.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page