Brain Framework (bf) turns a folder of plain Markdown notes and collected JSON records into a local, verifiable knowledge graph for you and any coding agent.

• Plain files you own. Notes (projects/, concepts/, actions/), records (memories/), and config (bf.yaml, evals/), accessible through bf, local stdio MCP, Agent Skills, and AGENTS.md.
• Gather, connect, act offline. Scheduled or streaming jobs: collect or ingest records (bf collect, bf ingest), declarative map: normalizes fields, BM25 + graph links trace every claim, and prompt jobs wake harnesses only when events or gates fire.
• No lock-in or built-in LLM. BF runs zero models, accounts, or telemetry; search and read stay 100% offline.

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 guide                      # Offline documentation inside the CLI
bf validate
bf eval

Explore the four-tool walkthrough (Workspace, Jira, GitHub, and Google Cloud fixtures) or read Getting started.

How it works

• Notes & graph (Authoring): OKF Markdown notes with explicit relations: and attributes:, plus tracked ACTION.md workflows (bf action new|status).
• Offline retrieval (Retrieval): Disposable .bf/cache.sqlite3 powers bf search, bf read, review pages, bf export, bf eval, and bf mcp.
• Agents & skills (Getting started): Install the /bf skill (bf skill install --global) and register brains (bf register . --default); optional host hooks surface brain state automatically.
• Sensors, ingest & routines (Jobs): Copy stdlib scripts from sensors and routines, pipe external JSON via bf ingest, and normalize fields with declarative map:.
• Prompts, channels & watch (Assist): Event-driven prompt jobs (record.*, note.changed, message.received, job.failed), DM allowlists ({{lines:...}}), durable channel queues, failure incidents, and bf watch (demo).

Good to know

1. Local-first and private. Retrieval runs offline; .bf/ locks, caches, and durable queues (runtime.sqlite3) never touch the network (Operations).
2. Harnesses reason; BF verifies. BF invokes your configured CLI harness only on explicit runs, schedules, or event/gate matches, and validates every note, record, and bf.yaml (version: 11) (Reference).
3. Git-native collaboration. Track notes, bf.yaml, jobs/, and evals/ in Git while ignoring memories/, actions/, logs/, and .bf/.

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