Metadata-Version: 2.4
Name: brain-framework
Version: 16.0.1
Summary: 🧠 Brain Framework: from information to informed actions.
Keywords: ai,ai-agents,agent-memory,context-engineering,knowledge-management,local-first,mcp,model-context-protocol,python,second-brain
Author: Médéric Hurier
License-Expression: MIT
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES.md
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: markdown-it-py>=4.2.0,<5
Requires-Dist: mcp>=2.1.1,<3
Requires-Dist: pydantic>=2.13.5,<3
Requires-Dist: pyyaml>=6.0.3,<7
Requires-Dist: rich>=15.0.0,<16
Requires-Dist: typer>=0.27.2,<1
Requires-Python: >=3.14
Project-URL: Documentation, https://fmind.github.io/brain-framework/
Project-URL: Issues, https://github.com/fmind/brain-framework/issues
Project-URL: Repository, https://github.com/fmind/brain-framework
Description-Content-Type: text/markdown

<p align="center">
  <img
    src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-framework.svg"
    alt="Brain Framework: an exposed brain in an opening shell above twin aperture eyes"
    width="256"
    height="256"
  >
</p>

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

[![CI](https://github.com/fmind/brain-framework/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fmind/brain-framework/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/brain-framework?color=174EA6)](https://pypi.org/project/brain-framework/) [![Python](https://img.shields.io/pypi/pyversions/brain-framework)](https://pypi.org/project/brain-framework/) [![License: MIT](https://img.shields.io/badge/license-MIT-174EA6)](https://github.com/fmind/brain-framework/blob/main/LICENSE)

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

[Try it](https://github.com/fmind/brain-framework#try-it) · [Connect an agent](https://github.com/fmind/brain-framework#agents) · [Four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)

## What can you do with it?

| When you need to…       | BF helps you…                                                       |
| ----------------------- | ------------------------------------------------------------------- |
| Resume a project        | Find the last verified outcome and next step.                       |
| Explain a decision      | Read the original reasoning and linked evidence.                    |
| Check work across tools | Follow explicit connections between briefs, issues and deployments. |
| Notice what changed     | See which conclusions newer evidence has overtaken.                 |

In the [runnable four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/), GitHub says the implementation is merged and Gcloud shows a healthy preview, but Jira still blocks launch on accessibility review. You record that conclusion in the project; when Jira later moves to Done, BF flags the project for review. The records are fictional and everything runs locally. The [examples](https://github.com/fmind/brain-framework/tree/main/examples) also cover decision reviews, retrieval checks, hooks, routines, monitoring and teams.

## Try it

Start with one decision you can find again. You need Linux or macOS and [uv](https://docs.astral.sh/uv/getting-started/installation/), which installs the tested Python 3.14 if needed ([install details](https://fmind.github.io/brain-framework/docs/upgrades/#install)). No model or provider account is required.

```bash
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.

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

```markdown
---
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:

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

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

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

`read` returns the original Decision section, and validation reports `"valid":true`. Edit the note and search again: BF notices changes on its own. The [getting-started guide](https://fmind.github.io/brain-framework/docs/getting-started/) continues with a first collected source and a link from the decision to its evidence.

## Agents

Use the same brain with [Claude Code](https://code.claude.com/docs/en/overview), [Codex](https://openai.com/codex/), [GitHub Copilot](https://github.com/features/copilot) or another agent host. 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 cites `projects/new-website.md#decision` and names “Draft the product page.” as the next task. For ongoing use, install the packaged skills into your host's skills folder:

```bash
bf skills ~/.agents/skills
```

`bf-use` finds evidence and keeps notes and actions current, `bf-setup` onboards brains and sources, and `bf-maintain` runs integrations and checks. Hosts that prefer tools can call `search` and `read` through [MCP](https://fmind.github.io/brain-framework/docs/mcp/). See the [agent guide](https://fmind.github.io/brain-framework/docs/agents/).

## How it works

**Gather → normalize → organize and connect → act → learn.** Sensors collect selected evidence; field mappings give sources shared fields and explicit relations. You and your agents do the work, then keep the outcome and next step in the brain.

```text
brain/
├── bf.yaml      # configuration: fields, sensors and routines
├── AGENTS.md    # instructions for agents working in the brain
├── projects/    # what you're working on and why
├── concepts/    # what you've learned and can reuse
├── actions/     # work sessions to start, resume and review
├── evals/       # questions the brain must keep answering
├── memories/    # records collected by your sensors
└── logs/        # each program's recent output, ignored by Git
```

Notes are Markdown with structured metadata; each record is a JSON file. Open them in any editor and use Git for history; the search cache is disposable. [Links and backlinks](https://fmind.github.io/brain-framework/docs/links/) connect decisions to evidence, and identities are always explicit: BF never guesses them from similar names. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/) and [team brains](https://fmind.github.io/brain-framework/docs/team/).

## Bring your tools

A **sensor** is a small program that reads a CLI, API or file and prints JSON records; BF validates, maps and saves them. Start with a reviewed example or write one for another source:

| Source                                    | Starting point                                                                                                                                                                                                                                                                                                    |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Local files, highlights and Git           | [Document](https://github.com/fmind/brain-framework/blob/main/examples/sensors/local-documents.py), [highlight](https://github.com/fmind/brain-framework/blob/main/examples/sensors/highlights.py) and [Git history](https://github.com/fmind/brain-framework/blob/main/examples/sensors/git-history.py) sensors. |
| Google Calendar and Drive                 | [Calendar](https://github.com/fmind/brain-framework/blob/main/examples/sensors/google-calendar.py) and [Drive folder](https://github.com/fmind/brain-framework/blob/main/examples/sensors/google-drive-folders.py) sensors using [`gws`](https://github.com/googleworkspace/cli).                                 |
| GitHub, Jira, Confluence and Google Cloud | The [GitHub history sensor](https://github.com/fmind/brain-framework/blob/main/examples/sensors/github-history.md), or your own using [`acli`](https://developer.atlassian.com/cloud/acli/), [`gcloud`](https://cloud.google.com/sdk/gcloud) or their APIs.                                                       |

Start with [one local source](https://fmind.github.io/brain-framework/docs/getting-started/#collect-your-first-source), then connect sources through [field mappings](https://fmind.github.io/brain-framework/docs/schema/#shared-fields-and-sensor-mappings). Provider tools handle authentication; your program selects what to collect. For example, [collect Calendar notes](https://fmind.github.io/brain-framework/docs/sensors/#from-meeting-notes-to-github-issues) and ask your agent to turn them into GitHub issues.

After reviewing your sensors, run `bf watch` to keep them refreshed and see failures as they happen. [Routines](https://fmind.github.io/brain-framework/docs/routines/) run your own programs, such as a weekly review or a Git pre-commit validation. See [Watch and schedule updates](https://fmind.github.io/brain-framework/docs/schedule/) for timing, alerts and native schedules.

<a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/watch.svg">
  <img
    src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/watch.svg"
    alt="Watch dashboard for the fictional offline demo: five sensors sorted by state, with a failed sensor's details beside their last success, next due time, item count and record changes."
    width="720"
  >
</a>

The dashboard shows the fictional [offline watch demo](https://github.com/fmind/brain-framework/tree/main/examples/watch), which needs no provider account.

## Fit and limits

BF fits projects where decisions and evidence must outlive a chat session. Start with one recurring question and the sources that 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](https://fmind.github.io/brain-framework/docs/privacy/).
- **Offline retrieval.** Search and read never contact providers or run programs. Collect again when you need newer evidence; incomplete results say so.
- **People and agents supply the judgment.** BF matches words and explicit identities, runs no model and learns nothing on its own. See [what BF does not do](https://fmind.github.io/brain-framework/docs/concepts/#what-bf-does-not-do).

[Browse the commands](https://fmind.github.io/brain-framework/docs/commands/) · [Report an issue](https://github.com/fmind/brain-framework/issues) · [Contribute](https://github.com/fmind/brain-framework/blob/main/CONTRIBUTING.md) · [MIT licensed](https://github.com/fmind/brain-framework/blob/main/LICENSE) · [Third-party notices](https://github.com/fmind/brain-framework/blob/main/THIRD_PARTY_NOTICES.md)
