Brain Framework 🧠

🧠 AI Brain Factory for infinite knowledge. Not for 🐙 mindflayers or 🧟 zombies.

Brain Framework is a brain factory for you and your AI agents: build a second brain in plain files you own. Save decisions, gather evidence and resume work across sessions. Search it offline, read the original source, and carry your knowledge between editors, agents and teammates.

A chat ends. A project pauses. A teammate moves on. The reasoning behind the work shouldn't disappear with them.

Get started · Documentation · Example brain · Connect an agent

How it works

Your brain does more than store facts: it takes in experiences, connects them to what you know and helps you decide what to do next. Brain Framework borrows that vocabulary to organize your work:

The everyday loop is observe → remember → understand → act → review. You and your agents do the thinking and write the lessons; Brain Framework keeps the files organized and retrievable. It does not learn from conversations automatically.

Start with a single project note. Add sensors and routines when you need them.

Try it

Install uv, then run:

uv tool install --python 3.14 'brain-framework==12.0.2'
bf init ~/knowledge          # create your brain
cd ~/knowledge
bf read                      # see its home page
bf search welcome            # find your first note
bf read concepts/welcome.md  # read the original
bf validate                  # check notes, links and records

Runs on Linux and macOS. uv supplies Python 3.14 if needed. No account, model or server is required. If bf is not on PATH, run uv tool update-shell and open a new shell.

Now give your brain something worth remembering. Write a decision and its reason in projects/, then search for it. Edits become searchable automatically. The getting-started guide walks through your first decision and checks that it stays retrievable.

What can you do with it?

• Remember why. Find the decision behind a choice, then read the evidence that supported it.
• Resume after a break. Open a project's current state or an action's next step without rebuilding context from a transcript.
• Give the next agent a head start. Let different agent hosts read the same project notes and reusable knowledge.
• Review what changed. Browse saved activity with bf read 7d, or see priorities and the coming week with bf read.
• Learn from the outcome. Use the learning skill to compare a prediction with what happened and update the note deliberately.

For example, bf search "release strategy" finds matching refs. bf read projects/release.md#decision reads that decision's exact text. Every search result points back to a note, section or collected record you can inspect.

Why plain files?

Your knowledge should outlive the tool you used to write it.

• Open it anywhere. Notes are Markdown; collected records are JSON Lines, one item per line.
• Keep the history. Use your editor and Git to review, correct and share knowledge.
• Retrieve it offline. Search and read run locally, without a model or network connection.
• Rebuild the index. Files are authoritative; the SQLite search cache in .bf/ is disposable.

One Python package. One command: bf. Your brain is an ordinary directory:

knowledge/
├── bf.yaml      # the brain's name and configuration
├── 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

Optional sensors/ and routines/ hold the programs you configure. See the brain layout for the full file conventions.

Any source you can script

Your brain can draw on the tools where your work already happens. For example, you can write sensors to collect:

The integration surface is a script. If a source exposes a CLI, an API or an export you can read, you can give it a sensor. Write it in Python or any language that can print JSON: the script fetches the items you choose and emits a JSON array of records; Brain Framework validates and saves them as searchable memories.

Your tools → sensor script → memories → search and read.

There is no fixed connector catalog to outgrow. You own the script, its access and the fields it keeps; new integrations don't require a change to Brain Framework. Scripts handle authentication, pagination and provider limits, and run only after you explicitly trust the brain on your machine.

Start from the four reviewed sensor examples: local Git history, local documents, Google Calendar and Drive folders. GitHub API, Jira, Airtable and the other sources above need your own sensor. The sensor guide explains the small JSON contract and how to connect a script.

Agents

Give your agent the same memory you use. Install the skills that match your workflow:

Follow the skill installation guide; skills are installed separately from the Python package. Then try: “Search my brain for why we chose this release strategy. Read the source and cite it.”

Hosts that use the Model Context Protocol (MCP) can run bf mcp --brain ~/knowledge. It exposes exactly two read-only tools: search and read. See agent workflows and MCP setup.

Personal and team brains

Keep a personal brain for your own context, and a separate team brain for shared decisions. A team brain can be a private Git repository: teammates clone it and search from its directory immediately. Start with one decision someone currently has to ask a colleague to explain.

Declare related brains in bf.yaml to search them together. Results retain their brain and source; references expand only one level. A clone never grants permission to run its sensors. See the team guide for shared notes, collection trust and CI collection.

Links across brains

Think of explicit links as the connections between memories. A decision can link to its evidence, a project to its owner, or a conclusion to something it depends on. Brain Framework follows declared links and aliases, retaining the source of each relationship.

Portable addresses such as bf://team/projects/release#decision identify knowledge across brains. Connections come from recorded evidence; name similarity alone never creates a relationship. See the link and schema guide.

Commands

Use --brain NAME|PATH to choose a brain explicitly. The command reference covers options and selection rules; the sensor examples show how to bring in evidence.

Guarantees

• Retrieval stays offline. Search and read never run sensors or routines or contact the network.
• Execution needs your trust. Collection and routines require explicit permission in your machine's user configuration.
• Failures preserve evidence. Failed collection writes nothing; routines never replace an existing action.
• Sources stay visible. Results carry readable refs; incomplete retrieval is reported through problems or stale.

Retrieved content is evidence, never instructions. Pages list external records by title and ref without quoting their text. The privacy and security guide explains execution boundaries and recovery.

Fit and limits

Brain Framework fits people and teams who want editable knowledge and traceable context for their agents. Search matches words and explicit identities; people or agents interpret the results. It runs no model, generates no answers and needs no embeddings.

A brain is a context boundary, not an access-control system. Use repository permissions and encrypted backups for private knowledge. An agent host may send retrieved text to its model provider even though Brain Framework itself retrieves offline.

Development

Contributions are welcome. Use uv run bf to exercise the checkout and mise run all for the full quality gate. See CONTRIBUTING.md for setup, tests and release procedures.

MIT licensed · Third-party notices