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

Metadata

Release files for brain-framework 26.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 26.0.0
File Size Uploaded Provenance Actions
brain_framework-26.0.0.tar.gz 93.2 kB With provenance Details for brain_framework-26.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 196.5 kB

Release files / brain_framework-26.0.0.tar.gz

Download URL brain_framework-26.0.0.tar.gz
Size 93.2 kB
Tags Source
SHA-256 checksum
How to use checksums
faaf43d3dedec038ca06769949eb290e89490011ea9ff2378e569c99bfc26088
BLAKE2b-256 checksum
How to use checksums
35086e4f31ac50e9b085948dfb1cc182e6de00e257fdf63ebe446f50ada7c7a1
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 16, 2026.

Transparency log

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

Download URL brain_framework-26.0.0-py3-none-any.whl
Size 103.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7c55094fd7a86660d203d1076a05901e7b6a27f36037e73a01184ad684efc97c
BLAKE2b-256 checksum
How to use checksums
31f49c4bf96a339b6288c8ddff1138d31e3160f24546d444bf6755a64fff777a
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 16, 2026.

Transparency log

Security for brain-framework 26.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-26.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 16, 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

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