brain-framework 18.4.0__tar.gz → 19.0.0__tar.gz

{brain_framework-18.4.0 → brain_framework-19.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: brain-framework
-Version: 18.4.0
+Version: 19.0.0
 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
@@ -21,6 +21,7 @@ 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: Changelog, https://fmind.github.io/brain-framework/changelog/
 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
@@ -43,12 +44,12 @@ A second brain for you, your team and your AI agents, on your own computer. Gath
 
 [![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)
 
-[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
+[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
 
 <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg">
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg"
-    alt="The Brain Framework loop: sensors gather evidence from your tools into a brain folder; bf.yaml declares the ontology, sensors, routines and watch; memories, projects, concepts and actions form a knowledge graph; agents read that context, act through the same CLIs, APIs, MCP servers and browsers, and write outcomes back."
+    alt="The Brain Framework loop: sensors gather evidence from your tools into a brain folder; bf.yaml declares the ontology, sensors, routines, assistants, channels and watch settings; memories, projects, concepts and actions form a knowledge graph; agents read that context, act through the same CLIs, APIs, MCP servers and browsers, and write outcomes back."
     width="960"
   >
 </a>
@@ -84,7 +85,7 @@ Questions that once took a tour of your tools become one prompt, once you write
 - **Every source, even the ones no product connects.** Mail, calendar, documents, chat, issues and pull requests, of course. But also the release notes and security advisories of the tools you depend on, model retirement dates, provider incidents, mentions of your projects on Hacker News or Bluesky, your domains' certificates and mail security, repository traffic that GitHub forgets after 14 days and your past agent sessions. If you can script it, you can collect it.
 - **Unlimited integrations, both ways.** A sensor is a small program that prints JSON: wrap a CLI such as `gh`, `gws` or `gcloud`, call an API, drive a browser, query a database or parse an export. The same CLIs, APIs and MCP servers then let your agent act on what it learned: draft the issue, answer the thread, fix the alert.
 - **One vocabulary, one knowledge graph.** Each tool names things its own way. You declare a small ontology in `bf.yaml` and sensors map provider fields into it at collection, so the same project, person or repository connects across every tool. BF turns those explicit links into a graph you navigate in one read, each claim pointing back to its evidence.
-- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and never runs a model itself: [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your agent harness. Search and read work offline.
+- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and never runs a model itself: [assistants](https://fmind.github.io/brain-framework/docs/prompts/) launch your agent harness. Search and read work offline.
 - **Portable and versioned.** Markdown notes, JSON records and scripts: open them in any editor, grep them, copy them to another machine. Keep the brain in a private Git repository for history, rollback, review and conflict resolution.
 - **For you or your whole team.** A personal brain stays on your laptop. A team brain is a private Git repository with one clone per teammate, so decisions, reviewed evidence and next steps are shared by everyone and their agents. Your personal brain can include the team's in its searches.
 - **Any agent, guided by skills.** Claude Code, Codex, GitHub Copilot, Antigravity or your own agent reach the same brain through the `bf` command, packaged skills or MCP. The skills teach them to find evidence, keep notes current, connect sources and maintain the brain.
@@ -95,7 +96,7 @@ Hosted personal agents run on someone else's computer, connect the sources their
 
 ### What one brain can gather
 
-The author's own brain runs more than 50 sensors and holds over 60,000 records (counted on 2026-10-04):
+The author's own brain runs more than 80 sensors and holds about 50,000 records (counted on 2026-10-16):
 
 | Area          | Collected evidence                                                                                                                   |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@@ -104,7 +105,7 @@ The author's own brain runs more than 50 sensors and holds over 60,000 records (
 | Agents        | Claude Code, Codex, Copilot and other agent sessions and memories, so a past conclusion is one search away.                          |
 | Your stack    | Release notes, security bulletins and advisories of the tools you use, model retirements and provider outages.                       |
 | Your presence | Mentions on GitHub, Hacker News and Bluesky; domain expiry, mail security and certificate transparency; site and repository traffic. |
-| Reading       | RSS feeds, newsletters, bookmarks, highlights and Hacker News.                                                                       |
+| Reading       | RSS feeds, newsletters, bookmarks and Hacker News.                                                                                   |
 
 These are personal sensors, not bundled connectors. The repository ships [reviewed starting points](https://github.com/fmind/brain-framework#bring-your-tools), and the `bf-setup` skill helps your agent connect a new source.
 
@@ -122,10 +123,11 @@ A brain gives your work the structure of a detective's case file, in plain files
 | `concepts/` | Knowledge you will reuse elsewhere, with its evidence and limits.            | “Explain the product before asking for signup.”                      |
 | `actions/`  | One work session: objective, inputs, outputs, outcome and next step.         | `actions/2026-09-27_website-review/ACTION.md`, resumed the next day. |
 | `routines/` | Deterministic programs you review, run on demand, on a schedule or from Git. | A weekly review that drafts an action listing projects to revisit.   |
-| `prompts/`  | Markdown prompts your agent harness runs on a schedule or on demand.         | An assistant that reviews new mail and chat every half hour.         |
+| `prompts/`  | Markdown prompts your agent harness runs; each run's reply is a record.      | An assistant that reviews new mail and chat every half hour.         |
+| `channels/` | Scripts you review that send, read or stream messages for assistants.        | A script that posts an assistant's answer in your chat thread.       |
 | `evals/`    | Saved questions with the evidence that search or read must return.           | “Why one page?” must return the project's Decision section.          |
 
-Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
+Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. `bf init --full` creates `sensors/` and `routines/`; create `prompts/` and `channels/` when you add an [assistant](https://fmind.github.io/brain-framework/docs/prompts/). An assistant's records hold model output, so search weighs them at half, like a low-priority source. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
 
 ### `bf.yaml`, the coordination hub
 
@@ -133,7 +135,7 @@ One file declares what the brain knows how to name, collect and check:
 
 ```yaml
 # https://fmind.github.io/brain-framework/docs/configuration/
-version: 7
+version: 8
 name: brain
 fields: # the ontology: shared fields and typed relations
   project: { type: identity, cardinality: one, relation: true, description: Project the source names. }
@@ -158,7 +160,9 @@ watch: # keep sources fresh and alert on failure
   notifications: failure
 ```
 
-BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed run never changes your evidence. `bf watch` keeps due sensors, routines and prompts fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
+BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed sensor run preserves its evidence; assistant answers and delivery obligations have durable recovery. `bf watch` keeps due sensors, routines and assistants fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
+
+[Assistants and channels](https://fmind.github.io/brain-framework/docs/prompts/) connect your own harness to any messaging surface through small scripts: receive messages, reply in their thread, review on a schedule and fan out saved answers. The [offline messaging example](https://github.com/fmind/brain-framework/tree/main/examples/channels) demonstrates the full loop without a provider or model.
 
 ### One vocabulary, set at collection
 
@@ -182,22 +186,7 @@ Reading files gives you one document at a time, and grep finds words, not connec
 bf read project:new-website
 ```
 
-The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs, kinds and statuses):
-
-```json
-{
-  "relation": "project",
-  "total": 4,
-  "items": [
-    { "ref": "gcloud:deployment", "fields": { "kind": "deployment", "status": "healthy" } },
-    { "ref": "github:implementation", "fields": { "kind": "pull-request", "status": "merged" } },
-    { "ref": "jira:review", "fields": { "kind": "issue", "status": "In review" } },
-    { "ref": "workspace:brief", "fields": { "kind": "brief", "status": "approved" } }
-  ]
-}
-```
-
-From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
+The reply holds the project note and its backlinks, grouped by relation: under `project`, four records from four tools side by side in the shared vocabulary, the Jira review `In review`, the GitHub pull request `merged`, the Gcloud deployment `healthy` and the Workspace brief `approved`. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#collect-four-tools) shows the reply. From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
 
 ### Act, then learn
 
@@ -211,64 +200,22 @@ Retrieval assembles the context; people and agents do the work, through the CLIs
   >
 </a>
 
-The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
+The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
 
 ## 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.
+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 --version
 ```
 
-If your shell cannot find `bf`, run `uv tool update-shell` and open a new shell. Then create your brain:
-
-```bash
-bf init ~/brain
-cd ~/brain
-```
-
-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 with its note's status and date, 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, and the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
+Then follow [Getting started](https://fmind.github.io/brain-framework/docs/getting-started/): create a brain, save a decision, find its reason and link it to a first collected source. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) then runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
 
 ## Open your agent in your brain
 
-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 any agent host that can run a command. Start your terminal agent in `~/brain` and give it this prompt:
+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 any agent host that can run a command. After Getting started, start your terminal agent in `~/brain` and give it this prompt:
 
 > 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.
 
@@ -285,11 +232,9 @@ Each host reads its own folder: for Claude Code, use `~/.claude/skills` instead.
 | `bf-use`      | Find evidence, cite it, and keep projects and concepts current.                 |
 | `bf-action`   | Start, resume and hand off a tracked work session: `/bf-action website-review`. |
 | `bf-setup`    | Install BF, create a brain, connect the agent and choose sources worth adding.  |
-| `bf-maintain` | Run sensors, routines and prompts, check the brain and upgrade it safely.       |
-
-Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. During collection, a usable cached reply carries an “Index refreshing” note. 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/).
+| `bf-maintain` | Run sensors, routines and assistants, check the brain and upgrade it safely.    |
 
-Agents can read this documentation as Markdown: [llms.txt](https://fmind.github.io/brain-framework/llms.txt) indexes every guide with a summary, [llms-full.txt](https://fmind.github.io/brain-framework/llms-full.txt) holds their full text, and each guide's Markdown sits at its URL followed by `index.md`.
+Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. During collection, a usable cached reply carries an “Index refreshing” note. 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/), which also points agents to this documentation as Markdown.
 
 ## Bring your tools
 
@@ -324,7 +269,7 @@ A brain is a folder, so Git gives it history, rollback, review and conflict reso
 
 1. **It runs on your computer, not in someone else's cloud.** That is a feature: your agent works where you can watch it, interrupt it and inspect every file it reads or writes, instead of a black box on a remote server. Sensors collect while your machine is on, through `bf watch` or a native schedule.
 1. **It takes some setup.** Each source needs its access: an API key, `gh auth login`, `gws` or `gcloud` authentication, then a sensor you review. Providers ship better CLIs and MCP servers every month, so this keeps getting easier, and the `bf-setup` skill walks your agent through it.
-1. **It needs an agent harness for the reasoning.** BF never runs a model itself: it collects, validates, searches and connects, and its [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your harness. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
+1. **It needs an agent harness for the reasoning.** BF never runs a model itself: it collects, validates, searches and connects, and its [assistants](https://fmind.github.io/brain-framework/docs/prompts/) launch your harness. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
 1. **It finds what was said and linked, not what was meant.** Search matches words and explicit identities, without embeddings, and incomplete results say so. Search and read never contact providers: collect again when you need newer evidence. 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)

{brain_framework-18.4.0 → brain_framework-19.0.0}/README.md

@@ -15,12 +15,12 @@ A second brain for you, your team and your AI agents, on your own computer. Gath
 
 [![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)
 
-[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
+[Why](https://github.com/fmind/brain-framework#why-a-second-brain) · [How it works](https://github.com/fmind/brain-framework#how-it-works) · [Try it](https://github.com/fmind/brain-framework#try-it) · [Agents](https://github.com/fmind/brain-framework#open-your-agent-in-your-brain) · [Good to know](https://github.com/fmind/brain-framework#good-to-know) · [Four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) · [Documentation](https://fmind.github.io/brain-framework/)
 
 <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg">
   <img
     src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg"
-    alt="The Brain Framework loop: sensors gather evidence from your tools into a brain folder; bf.yaml declares the ontology, sensors, routines and watch; memories, projects, concepts and actions form a knowledge graph; agents read that context, act through the same CLIs, APIs, MCP servers and browsers, and write outcomes back."
+    alt="The Brain Framework loop: sensors gather evidence from your tools into a brain folder; bf.yaml declares the ontology, sensors, routines, assistants, channels and watch settings; memories, projects, concepts and actions form a knowledge graph; agents read that context, act through the same CLIs, APIs, MCP servers and browsers, and write outcomes back."
     width="960"
   >
 </a>
@@ -56,7 +56,7 @@ Questions that once took a tour of your tools become one prompt, once you write
 - **Every source, even the ones no product connects.** Mail, calendar, documents, chat, issues and pull requests, of course. But also the release notes and security advisories of the tools you depend on, model retirement dates, provider incidents, mentions of your projects on Hacker News or Bluesky, your domains' certificates and mail security, repository traffic that GitHub forgets after 14 days and your past agent sessions. If you can script it, you can collect it.
 - **Unlimited integrations, both ways.** A sensor is a small program that prints JSON: wrap a CLI such as `gh`, `gws` or `gcloud`, call an API, drive a browser, query a database or parse an export. The same CLIs, APIs and MCP servers then let your agent act on what it learned: draft the issue, answer the thread, fix the alert.
 - **One vocabulary, one knowledge graph.** Each tool names things its own way. You declare a small ontology in `bf.yaml` and sensors map provider fields into it at collection, so the same project, person or repository connects across every tool. BF turns those explicit links into a graph you navigate in one read, each claim pointing back to its evidence.
-- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and never runs a model itself: [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your agent harness. Search and read work offline.
+- **Private by design.** Your brain is a folder on your disk. BF has no account, server or telemetry and never runs a model itself: [assistants](https://fmind.github.io/brain-framework/docs/prompts/) launch your agent harness. Search and read work offline.
 - **Portable and versioned.** Markdown notes, JSON records and scripts: open them in any editor, grep them, copy them to another machine. Keep the brain in a private Git repository for history, rollback, review and conflict resolution.
 - **For you or your whole team.** A personal brain stays on your laptop. A team brain is a private Git repository with one clone per teammate, so decisions, reviewed evidence and next steps are shared by everyone and their agents. Your personal brain can include the team's in its searches.
 - **Any agent, guided by skills.** Claude Code, Codex, GitHub Copilot, Antigravity or your own agent reach the same brain through the `bf` command, packaged skills or MCP. The skills teach them to find evidence, keep notes current, connect sources and maintain the brain.
@@ -67,7 +67,7 @@ Hosted personal agents run on someone else's computer, connect the sources their
 
 ### What one brain can gather
 
-The author's own brain runs more than 50 sensors and holds over 60,000 records (counted on 2026-10-04):
+The author's own brain runs more than 80 sensors and holds about 50,000 records (counted on 2026-10-16):
 
 | Area          | Collected evidence                                                                                                                   |
 | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@@ -76,7 +76,7 @@ The author's own brain runs more than 50 sensors and holds over 60,000 records (
 | Agents        | Claude Code, Codex, Copilot and other agent sessions and memories, so a past conclusion is one search away.                          |
 | Your stack    | Release notes, security bulletins and advisories of the tools you use, model retirements and provider outages.                       |
 | Your presence | Mentions on GitHub, Hacker News and Bluesky; domain expiry, mail security and certificate transparency; site and repository traffic. |
-| Reading       | RSS feeds, newsletters, bookmarks, highlights and Hacker News.                                                                       |
+| Reading       | RSS feeds, newsletters, bookmarks and Hacker News.                                                                                   |
 
 These are personal sensors, not bundled connectors. The repository ships [reviewed starting points](https://github.com/fmind/brain-framework#bring-your-tools), and the `bf-setup` skill helps your agent connect a new source.
 
@@ -94,10 +94,11 @@ A brain gives your work the structure of a detective's case file, in plain files
 | `concepts/` | Knowledge you will reuse elsewhere, with its evidence and limits.            | “Explain the product before asking for signup.”                      |
 | `actions/`  | One work session: objective, inputs, outputs, outcome and next step.         | `actions/2026-09-27_website-review/ACTION.md`, resumed the next day. |
 | `routines/` | Deterministic programs you review, run on demand, on a schedule or from Git. | A weekly review that drafts an action listing projects to revisit.   |
-| `prompts/`  | Markdown prompts your agent harness runs on a schedule or on demand.         | An assistant that reviews new mail and chat every half hour.         |
+| `prompts/`  | Markdown prompts your agent harness runs; each run's reply is a record.      | An assistant that reviews new mail and chat every half hour.         |
+| `channels/` | Scripts you review that send, read or stream messages for assistants.        | A script that posts an assistant's answer in your chat thread.       |
 | `evals/`    | Saved questions with the evidence that search or read must return.           | “Why one page?” must return the project's Decision section.          |
 
-Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
+Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. `bf init --full` creates `sensors/` and `routines/`; create `prompts/` and `channels/` when you add an [assistant](https://fmind.github.io/brain-framework/docs/prompts/). An assistant's records hold model output, so search weighs them at half, like a low-priority source. The SQLite search cache in `.bf/` is disposable and rebuilds itself from the files. See the [file conventions](https://fmind.github.io/brain-framework/docs/brain/#directory-reference).
 
 ### `bf.yaml`, the coordination hub
 
@@ -105,7 +106,7 @@ One file declares what the brain knows how to name, collect and check:
 
 ```yaml
 # https://fmind.github.io/brain-framework/docs/configuration/
-version: 7
+version: 8
 name: brain
 fields: # the ontology: shared fields and typed relations
   project: { type: identity, cardinality: one, relation: true, description: Project the source names. }
@@ -130,7 +131,9 @@ watch: # keep sources fresh and alert on failure
   notifications: failure
 ```
 
-BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed run never changes your evidence. `bf watch` keeps due sensors, routines and prompts fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
+BF runs each program with its configured arguments and no shell, bounds its time and output, validates what it prints and keeps its stderr in `logs/`. A failed sensor run preserves its evidence; assistant answers and delivery obligations have durable recovery. `bf watch` keeps due sensors, routines and assistants fresh in a terminal dashboard, and `bf schedule` generates native systemd, launchd or cron jobs for you to install. See [sensors](https://fmind.github.io/brain-framework/docs/sensors/), [routines](https://fmind.github.io/brain-framework/docs/routines/) and [watch and schedule](https://fmind.github.io/brain-framework/docs/schedule/).
+
+[Assistants and channels](https://fmind.github.io/brain-framework/docs/prompts/) connect your own harness to any messaging surface through small scripts: receive messages, reply in their thread, review on a schedule and fan out saved answers. The [offline messaging example](https://github.com/fmind/brain-framework/tree/main/examples/channels) demonstrates the full loop without a provider or model.
 
 ### One vocabulary, set at collection
 
@@ -154,22 +157,7 @@ Reading files gives you one document at a time, and grep finds words, not connec
 bf read project:new-website
 ```
 
-The reply holds the project note and its backlinks, grouped by relation: four records from four tools, side by side, in the shared vocabulary (trimmed here to refs, kinds and statuses):
-
-```json
-{
-  "relation": "project",
-  "total": 4,
-  "items": [
-    { "ref": "gcloud:deployment", "fields": { "kind": "deployment", "status": "healthy" } },
-    { "ref": "github:implementation", "fields": { "kind": "pull-request", "status": "merged" } },
-    { "ref": "jira:review", "fields": { "kind": "issue", "status": "In review" } },
-    { "ref": "workspace:brief", "fields": { "kind": "brief", "status": "approved" } }
-  ]
-}
-```
-
-From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
+The reply holds the project note and its backlinks, grouped by relation: under `project`, four records from four tools side by side in the shared vocabulary, the Jira review `In review`, the GitHub pull request `merged`, the Gcloud deployment `healthy` and the Workspace brief `approved`. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#collect-four-tools) shows the reply. From there, follow typed [relations](https://fmind.github.io/brain-framework/docs/links/#name-a-relation) such as `author`, `owner`, `depends-on` or your own. Each claim keeps the note section or record that asserted it, so an answer can always cite its evidence. `bf export` prints the whole graph as JSON Lines for DuckDB or networkx.
 
 ### Act, then learn
 
@@ -183,64 +171,22 @@ Retrieval assembles the context; people and agents do the work, through the CLIs
   >
 </a>
 
-The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
+The graph keeps conclusions current. Each project knows the evidence it links to: when a linked record changes after the note's last edit, `bf read` flags the project for review and names the record to read first, so a decision does not silently outlive its linked evidence. Try it in the [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/#follow-a-change). [Routines](https://fmind.github.io/brain-framework/docs/routines/) run deterministic reviews and checks, such as a weekly review action or `bf validate` before each Git commit, and retrieval cases in `evals/` confirm that the questions you rely on still find their evidence as the brain grows.
 
 ## 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.
+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 --version
 ```
 
-If your shell cannot find `bf`, run `uv tool update-shell` and open a new shell. Then create your brain:
-
-```bash
-bf init ~/brain
-cd ~/brain
-```
-
-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 with its note's status and date, 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, and the [four-tool demo](https://fmind.github.io/brain-framework/docs/context-hub/) runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
+Then follow [Getting started](https://fmind.github.io/brain-framework/docs/getting-started/): create a brain, save a decision, find its reason and link it to a first collected source. The [four-tool walkthrough](https://fmind.github.io/brain-framework/docs/context-hub/) then runs the whole loop offline on fictional Workspace, Jira, GitHub and Gcloud records.
 
 ## Open your agent in your brain
 
-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 any agent host that can run a command. Start your terminal agent in `~/brain` and give it this prompt:
+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 any agent host that can run a command. After Getting started, start your terminal agent in `~/brain` and give it this prompt:
 
 > 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.
 
@@ -257,11 +203,9 @@ Each host reads its own folder: for Claude Code, use `~/.claude/skills` instead.
 | `bf-use`      | Find evidence, cite it, and keep projects and concepts current.                 |
 | `bf-action`   | Start, resume and hand off a tracked work session: `/bf-action website-review`. |
 | `bf-setup`    | Install BF, create a brain, connect the agent and choose sources worth adding.  |
-| `bf-maintain` | Run sensors, routines and prompts, check the brain and upgrade it safely.       |
-
-Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. During collection, a usable cached reply carries an “Index refreshing” note. 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/).
+| `bf-maintain` | Run sensors, routines and assistants, check the brain and upgrade it safely.    |
 
-Agents can read this documentation as Markdown: [llms.txt](https://fmind.github.io/brain-framework/llms.txt) indexes every guide with a summary, [llms-full.txt](https://fmind.github.io/brain-framework/llms-full.txt) holds their full text, and each guide's Markdown sits at its URL followed by `index.md`.
+Working in a code repository instead? The [example session hook](https://github.com/fmind/brain-framework/tree/main/examples/hooks) prints the project that declares the repository, its next task and linked evidence when the session starts. During collection, a usable cached reply carries an “Index refreshing” note. 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/), which also points agents to this documentation as Markdown.
 
 ## Bring your tools
 
@@ -296,7 +240,7 @@ A brain is a folder, so Git gives it history, rollback, review and conflict reso
 
 1. **It runs on your computer, not in someone else's cloud.** That is a feature: your agent works where you can watch it, interrupt it and inspect every file it reads or writes, instead of a black box on a remote server. Sensors collect while your machine is on, through `bf watch` or a native schedule.
 1. **It takes some setup.** Each source needs its access: an API key, `gh auth login`, `gws` or `gcloud` authentication, then a sensor you review. Providers ship better CLIs and MCP servers every month, so this keeps getting easier, and the `bf-setup` skill walks your agent through it.
-1. **It needs an agent harness for the reasoning.** BF never runs a model itself: it collects, validates, searches and connects, and its [prompts](https://fmind.github.io/brain-framework/docs/prompts/) launch your harness. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
+1. **It needs an agent harness for the reasoning.** BF never runs a model itself: it collects, validates, searches and connects, and its [assistants](https://fmind.github.io/brain-framework/docs/prompts/) launch your harness. Claude Code, Codex, Copilot, Antigravity or another harness does the thinking, so the privacy of what your agent reads depends on that harness's data terms. BF sends no telemetry or personal data to us; see [privacy and security](https://fmind.github.io/brain-framework/docs/privacy/) for a fully local setup.
 1. **It finds what was said and linked, not what was meant.** Search matches words and explicit identities, without embeddings, and incomplete results say so. Search and read never contact providers: collect again when you need newer evidence. 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)

{brain_framework-18.4.0 → brain_framework-19.0.0}/THIRD_PARTY_NOTICES.md

@@ -745,15 +745,15 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 ```
 
-## mcp 2.2.0
+## mcp 2.3.0
 
 Source: <https://github.com/modelcontextprotocol/python-sdk>
 
 License: `MIT`
 
-Evidence: `mcp-2.2.0.dist-info/licenses/LICENSE`
+Evidence: `mcp-2.3.0.dist-info/licenses/LICENSE`
 
-### mcp-2.2.0.dist-info/licenses/LICENSE
+### mcp-2.3.0.dist-info/licenses/LICENSE
 
 ```text
 MIT License
@@ -779,15 +779,15 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## mcp-types 2.2.0
+## mcp-types 2.3.0
 
 Source: <https://github.com/modelcontextprotocol/python-sdk>
 
 License: `MIT`
 
-Evidence: `mcp_types-2.2.0.dist-info/licenses/LICENSE`
+Evidence: `mcp_types-2.3.0.dist-info/licenses/LICENSE`
 
-### mcp_types-2.2.0.dist-info/licenses/LICENSE
+### mcp_types-2.3.0.dist-info/licenses/LICENSE
 
 ```text
 MIT License
@@ -872,15 +872,15 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 IN THE SOFTWARE.
 ```
 
-## opentelemetry-api 1.45.0
+## opentelemetry-api 1.45.1
 
 Source: <https://github.com/open-telemetry/opentelemetry-python>
 
 License: `Apache-2.0`
 
-Evidence: `opentelemetry_api-1.45.0.dist-info/licenses/LICENSE`
+Evidence: `opentelemetry_api-1.45.1.dist-info/licenses/LICENSE`
 
-### opentelemetry_api-1.45.0.dist-info/licenses/LICENSE
+### opentelemetry_api-1.45.1.dist-info/licenses/LICENSE
 
 ```text
                                  Apache License
@@ -1086,20 +1086,20 @@ Evidence: `opentelemetry_api-1.45.0.dist-info/licenses/LICENSE`
    limitations under the License.
 ```
 
-## pycparser 3.0
+## pycparser 3.11
 
 Source: <https://github.com/eliben/pycparser>
 
 License: `BSD-3-Clause`
 
-Evidence: `pycparser-3.0.dist-info/licenses/LICENSE`
+Evidence: `pycparser-3.11.dist-info/licenses/LICENSE`
 
-### pycparser-3.0.dist-info/licenses/LICENSE
+### pycparser-3.11.dist-info/licenses/LICENSE
 
 ```text
 pycparser -- A C parser in Python
 
-Copyright (c) 2008-2022, Eli Bendersky
+Copyright (c) 2008-2027, Eli Bendersky
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
@@ -1126,15 +1126,15 @@ LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
 OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ```
 
-## pydantic 2.13.5
+## pydantic 2.14.1
 
 Source: <https://github.com/pydantic/pydantic>
 
 License: `MIT`
 
-Evidence: `pydantic-2.13.5.dist-info/licenses/LICENSE`
+Evidence: `pydantic-2.14.1.dist-info/licenses/LICENSE`
 
-### pydantic-2.13.5.dist-info/licenses/LICENSE
+### pydantic-2.14.1.dist-info/licenses/LICENSE
 
 ```text
 The MIT License (MIT)
@@ -1160,15 +1160,15 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## pydantic-core 2.46.5
+## pydantic-core 2.50.1
 
 Source: <https://github.com/pydantic/pydantic/tree/main/pydantic-core>
 
 License: `MIT`
 
-Evidence: `pydantic_core-2.46.5.dist-info/licenses/LICENSE`
+Evidence: `pydantic_core-2.50.1.dist-info/licenses/LICENSE`
 
-### pydantic_core-2.46.5.dist-info/licenses/LICENSE
+### pydantic_core-2.50.1.dist-info/licenses/LICENSE
 
 ```text
 The MIT License (MIT)
@@ -1577,15 +1577,15 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## rpds-py 2026.6.3
+## rpds-py 2026.9.1
 
 Source: <https://github.com/crate-py/rpds>
 
 License: `MIT`
 
-Evidence: `rpds_py-2026.6.3.dist-info/licenses/LICENSE`
+Evidence: `rpds_py-2026.9.1.dist-info/licenses/LICENSE`
 
-### rpds_py-2026.6.3.dist-info/licenses/LICENSE
+### rpds_py-2026.9.1.dist-info/licenses/LICENSE
 
 ```text
 Copyright (c) 2023 Julian Berman
@@ -1675,15 +1675,15 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ```
 
-## starlette 1.7.0
+## starlette 1.8.0
 
 Source: <https://github.com/Kludex/starlette>
 
 License: `BSD-3-Clause`
 
-Evidence: `starlette-1.7.0.dist-info/licenses/LICENSE.md`
+Evidence: `starlette-1.8.0.dist-info/licenses/LICENSE.md`
 
-### starlette-1.7.0.dist-info/licenses/LICENSE.md
+### starlette-1.8.0.dist-info/licenses/LICENSE.md
 
 ```text
 Copyright © 2018, [Encode OSS Ltd](https://www.encode.io/).
@@ -1715,15 +1715,15 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ```
 
-## truststore 0.10.4
+## truststore 0.10.5
 
 Source: <https://github.com/sethmlarson/truststore>
 
 License: `MIT`
 
-Evidence: `truststore-0.10.4.dist-info/licenses/LICENSE`
+Evidence: `truststore-0.10.5.dist-info/licenses/LICENSE`
 
-### truststore-0.10.4.dist-info/licenses/LICENSE
+### truststore-0.10.5.dist-info/licenses/LICENSE
 
 ```text
 The MIT License (MIT)
@@ -1749,7 +1749,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 THE SOFTWARE.
 ```
 
-## typer 0.27.2
+## typer 0.27.3
 
 Source: <https://github.com/fastapi/typer>
 
@@ -1757,9 +1757,9 @@ License: `MIT`
 
 The distribution vendors code adapted from Click in `typer/_click/`; its bundled `BSD-3-Clause` license is included below.
 
-Evidence: `typer-0.27.2.dist-info/licenses/LICENSE`
+Evidence: `typer-0.27.3.dist-info/licenses/LICENSE`
 
-### typer-0.27.2.dist-info/licenses/LICENSE
+### typer-0.27.3.dist-info/licenses/LICENSE
 
 ```text
 The MIT License (MIT)