Brain Framework 🧠

🧠 Brain Framework: from information to informed actions.

Collect information from your tools, connect it to your decisions and pick up work with the evidence at hand. Reusable context for you and your AI agents.

Your meeting notes, issues and project decisions live in different places. Brain Framework (BF) brings selected information into a folder of Markdown notes and source records you own. Search it across sessions, trace decisions to their sources and use the same context with different agents.

Try it · Connect an agent · Four-tool demo · Documentation

What can you do with it?

Example: Turn meeting notes into GitHub issues. Collect Calendar event descriptions, then ask your agent:

Turn today's meeting notes into GitHub issues in my chosen repository. Cite the source event for each issue.

BF supplies the saved notes; your agent uses gh to create the issues you authorize. Follow the Calendar-to-issues example for setup and prerequisites.

See the runnable four-tool demo: GitHub says the implementation is merged and Gcloud shows a healthy preview, but Jira still blocks launch on accessibility review. Reading all four sources explains what remains. The records are fictional; the collection and retrieval are runnable locally. The examples index also covers decision reviews, retrieval checks, hooks, routines, monitoring and team collaboration.

Try it

Start with one decision you can find again. This walkthrough needs Linux or macOS and uv, which installs the tested Python 3.14 if needed (install details). No model or provider account is required.

uv tool install --python 3.14 brain-framework
bf init ~/brain
cd ~/brain

If bf is not on PATH, run uv tool update-shell and open a new shell. You can choose another empty folder instead of ~/brain.

Create projects/new-website.md in your editor, or ask your agent to save this fictional decision. Use today's date for updated:

---
type: project
status: draft
updated: 2026-09-27
summary: Launch a product website that helps visitors understand the product.
---

# New website

## Decision

Start with a single product page because visitors need a clear explanation before signing up.

## Next actions

- [ ] Draft the product page.

Find the reason, read its source and check the brain:

bf search "visitors clear explanation"
bf read projects/new-website.md#decision
bf validate

Search returns this match in items (other fields omitted):

{ "ref": "projects/new-website.md#decision", "title": "New website — Decision" }

read returns the original Decision section; validation reports "valid":true. Edit the note and search again: BF notices changes automatically. You now have a decision an agent can find and cite.

The getting-started guide continues with a local source, a schema mapping and a link from the decision to its evidence.

Agents

Use the same brain with Claude Code, Codex, GitHub Copilot or another agent host.

After the quickstart, give your terminal agent this prompt:

Work in ~/brain and use the bf CLI. Find why we chose a single product page. Read the source, cite its ref and tell me the project's next action.

Check that it reads the decision and next actions, cites projects/new-website.md#decision and identifies “Draft the product page.” as the next task.

MCP exposes two read-only tools: search and read. For ongoing use, install the optional workflow skills: bf-use for retrieval, bf-action to track work and bf-learn to retain verified outcomes. See the agent guide for setup and examples.

How it works

Gather → normalize → organize and connect → act → learn. Sensors collect selected evidence; configured mappings give sources shared fields and explicit relationships. You and your agents use that context to do work, then keep the outcome and next step in the brain.

brain/
├── bf.yaml      # configuration and source mappings
├── projects/    # what you're working on and why
├── concepts/    # what you've learned and can reuse
├── actions/     # work to start, resume and review
└── memories/    # evidence gathered from your sources

Notes are Markdown with structured metadata; each collected record is a JSON file. Open them in any editor and use Git for history. The local search cache is disposable. See the file conventions.

Links and backlinks connect decisions to evidence. Keep personal and shared context in separate team brains, and search related brains together. Identities and relationship meanings are explicit; BF never guesses them from similar names.

Bring your tools

A sensor is a small script that reads a CLI, API or file and prints JSON records. BF validates, maps and saves them. Start with the reviewed examples or write a script for another source:

Start with one local source; use schema mappings to connect sources. Provider tools handle authentication; your script selects what to collect.

After reviewing your sensors, run bf watch to keep sources refreshed and see recent changes. See Watch and schedule updates for timing, desktop alerts and optional native schedules.

The dashboard above shows the fictional offline terminal demo, which runs without provider accounts.

Fit and limits

BF fits projects where decisions and evidence need to survive a chat session. Start with one recurring question and the sources needed to answer it.

• Your files, your control. BF sends no telemetry or personal data to us. A connected cloud agent may send what it reads to its provider; see privacy and security.
• Offline retrieval. Search and read never contact providers or run sensors. Refresh sources explicitly when you need newer evidence; incomplete retrieval is reported.
• People and agents supply the judgment. BF uses word search and explicit identities, runs no model and does not learn automatically from conversations. Keep notes current as work changes.

Next steps

• Browse the commands for home pages, tasks, freshness and retrieval checks.
• Share a team brain or run a pilot on your own work.
• Report an issue or contribute.

MIT licensed · Third-party notices