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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. {brain_framework-18.5.0 → brain_framework-19.0.0}/PKG-INFO +14 -10
  2. {brain_framework-18.5.0 → brain_framework-19.0.0}/README.md +12 -9
  3. {brain_framework-18.5.0 → brain_framework-19.0.0}/THIRD_PARTY_NOTICES.md +31 -31
  4. {brain_framework-18.5.0 → brain_framework-19.0.0}/pyproject.toml +3 -2
  5. {brain_framework-18.5.0 → brain_framework-19.0.0}/pyproject.toml.orig +5 -3
  6. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/__init__.py +1 -1
  7. brain_framework-19.0.0/src/bf/assistants.py +1074 -0
  8. brain_framework-19.0.0/src/bf/channels.py +235 -0
  9. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/cli.py +161 -41
  10. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/collect.py +131 -203
  11. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/config.py +47 -15
  12. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/evaluate.py +36 -21
  13. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/graph.py +34 -16
  14. brain_framework-19.0.0/src/bf/health.py +521 -0
  15. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/history.py +17 -6
  16. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/index.py +140 -87
  17. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/links.py +6 -7
  18. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/markdown.py +75 -12
  19. brain_framework-19.0.0/src/bf/messages.py +55 -0
  20. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/models.py +216 -54
  21. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/ontology.py +4 -1
  22. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/pages.py +67 -45
  23. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/records.py +76 -22
  24. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/replies.py +14 -4
  25. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/retrieve.py +22 -11
  26. brain_framework-19.0.0/src/bf/runtime.py +946 -0
  27. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/schedule.py +20 -8
  28. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/README.md +4 -4
  29. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-action/SKILL.md +3 -3
  30. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-action/references/context.md +1 -1
  31. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-action/references/handoff.md +1 -1
  32. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-action/scripts/check-handoff.py +2 -6
  33. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-action/scripts/new-action.py +22 -5
  34. brain_framework-19.0.0/src/bf/skills/bf-maintain/SKILL.md +57 -0
  35. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-maintain/references/integrations.md +11 -28
  36. brain_framework-19.0.0/src/bf/skills/bf-maintain/references/operations.md +63 -0
  37. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-setup/SKILL.md +1 -1
  38. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/SKILL.md +3 -3
  39. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/evidence.md +2 -2
  40. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/learn.md +2 -0
  41. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/retrieval.md +4 -4
  42. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/scripts/evidence.py +29 -10
  43. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/scripts/guarded-write.py +3 -3
  44. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/templates/concept.md +1 -1
  45. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/starter/AGENTS.md +4 -4
  46. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/storage.py +76 -27
  47. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/update.py +75 -110
  48. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/validate.py +66 -27
  49. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/watch.py +280 -110
  50. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/watch_settings.py +8 -4
  51. brain_framework-18.5.0/src/bf/health.py +0 -313
  52. brain_framework-18.5.0/src/bf/skills/bf-maintain/SKILL.md +0 -55
  53. brain_framework-18.5.0/src/bf/skills/bf-maintain/references/operations.md +0 -61
  54. {brain_framework-18.5.0 → brain_framework-19.0.0}/LICENSE +0 -0
  55. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/__main__.py +0 -0
  56. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/install.py +0 -0
  57. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/mcp.py +0 -0
  58. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/py.typed +0 -0
  59. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/schemas.py +0 -0
  60. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-action/references/actions.md +0 -0
  61. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-action/templates/action.md +0 -0
  62. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-maintain/references/conflicts.md +0 -0
  63. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-setup/references/discovery.md +0 -0
  64. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-setup/references/import.md +0 -0
  65. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-setup/references/scan.md +0 -0
  66. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-setup/scripts/inventory.py +0 -0
  67. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/consolidate.md +0 -0
  68. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/decisions.md +0 -0
  69. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/links.md +0 -0
  70. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/review.md +0 -0
  71. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/references/share.md +0 -0
  72. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/skills/bf-use/templates/project.md +0 -0
  73. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/starter/concepts/index.md +0 -0
  74. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/starter/concepts/welcome.md +0 -0
  75. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/starter/evals/retrieval.yaml +0 -0
  76. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/starter/gitignore +0 -0
  77. {brain_framework-18.5.0 → brain_framework-19.0.0}/src/bf/usage.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: brain-framework
3
- Version: 18.5.0
3
+ Version: 19.0.0
4
4
  Summary: 🧠 Brain Framework: from information to informed actions.
5
5
  Keywords: ai,ai-agents,agent-memory,context-engineering,knowledge-management,local-first,mcp,model-context-protocol,python,second-brain
6
6
  Author: Médéric Hurier
@@ -21,6 +21,7 @@ Requires-Dist: pyyaml>=6.0.3,<7
21
21
  Requires-Dist: rich>=15.0.0,<16
22
22
  Requires-Dist: typer>=0.27.2,<1
23
23
  Requires-Python: >=3.14
24
+ Project-URL: Changelog, https://fmind.github.io/brain-framework/changelog/
24
25
  Project-URL: Documentation, https://fmind.github.io/brain-framework/
25
26
  Project-URL: Issues, https://github.com/fmind/brain-framework/issues
26
27
  Project-URL: Repository, https://github.com/fmind/brain-framework
@@ -48,7 +49,7 @@ A second brain for you, your team and your AI agents, on your own computer. Gath
48
49
  <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg">
49
50
  <img
50
51
  src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg"
51
- 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."
52
+ 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."
52
53
  width="960"
53
54
  >
54
55
  </a>
@@ -84,7 +85,7 @@ Questions that once took a tour of your tools become one prompt, once you write
84
85
  - **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.
85
86
  - **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.
86
87
  - **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.
87
- - **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.
88
+ - **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.
88
89
  - **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.
89
90
  - **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.
90
91
  - **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
95
96
 
96
97
  ### What one brain can gather
97
98
 
98
- The author's own brain runs more than 50 sensors and holds over 60,000 records (counted on 2026-10-04):
99
+ The author's own brain runs more than 80 sensors and holds about 50,000 records (counted on 2026-10-16):
99
100
 
100
101
  | Area | Collected evidence |
101
102
  | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@@ -104,7 +105,7 @@ The author's own brain runs more than 50 sensors and holds over 60,000 records (
104
105
  | Agents | Claude Code, Codex, Copilot and other agent sessions and memories, so a past conclusion is one search away. |
105
106
  | Your stack | Release notes, security bulletins and advisories of the tools you use, model retirements and provider outages. |
106
107
  | Your presence | Mentions on GitHub, Hacker News and Bluesky; domain expiry, mail security and certificate transparency; site and repository traffic. |
107
- | Reading | RSS feeds, newsletters, bookmarks, highlights and Hacker News. |
108
+ | Reading | RSS feeds, newsletters, bookmarks and Hacker News. |
108
109
 
109
110
  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.
110
111
 
@@ -123,9 +124,10 @@ A brain gives your work the structure of a detective's case file, in plain files
123
124
  | `actions/` | One work session: objective, inputs, outputs, outcome and next step. | `actions/2026-09-27_website-review/ACTION.md`, resumed the next day. |
124
125
  | `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. |
125
126
  | `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. |
127
+ | `channels/` | Scripts you review that send, read or stream messages for assistants. | A script that posts an assistant's answer in your chat thread. |
126
128
  | `evals/` | Saved questions with the evidence that search or read must return. | “Why one page?” must return the project's Decision section. |
127
129
 
128
- Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. `bf init --full` creates `sensors/` and `routines/`; create `prompts/` when you add a [prompt](https://fmind.github.io/brain-framework/docs/prompts/). A prompt'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).
130
+ 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).
129
131
 
130
132
  ### `bf.yaml`, the coordination hub
131
133
 
@@ -133,7 +135,7 @@ One file declares what the brain knows how to name, collect and check:
133
135
 
134
136
  ```yaml
135
137
  # https://fmind.github.io/brain-framework/docs/configuration/
136
- version: 7
138
+ version: 8
137
139
  name: brain
138
140
  fields: # the ontology: shared fields and typed relations
139
141
  project: { type: identity, cardinality: one, relation: true, description: Project the source names. }
@@ -158,7 +160,9 @@ watch: # keep sources fresh and alert on failure
158
160
  notifications: failure
159
161
  ```
160
162
 
161
- 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/).
163
+ 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/).
164
+
165
+ [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.
162
166
 
163
167
  ### One vocabulary, set at collection
164
168
 
@@ -228,7 +232,7 @@ Each host reads its own folder: for Claude Code, use `~/.claude/skills` instead.
228
232
  | `bf-use` | Find evidence, cite it, and keep projects and concepts current. |
229
233
  | `bf-action` | Start, resume and hand off a tracked work session: `/bf-action website-review`. |
230
234
  | `bf-setup` | Install BF, create a brain, connect the agent and choose sources worth adding. |
231
- | `bf-maintain` | Run sensors, routines and prompts, check the brain and upgrade it safely. |
235
+ | `bf-maintain` | Run sensors, routines and assistants, check the brain and upgrade it safely. |
232
236
 
233
237
  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.
234
238
 
@@ -265,7 +269,7 @@ A brain is a folder, so Git gives it history, rollback, review and conflict reso
265
269
 
266
270
  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.
267
271
  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.
268
- 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.
272
+ 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.
269
273
  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).
270
274
 
271
275
  [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)
@@ -20,7 +20,7 @@ A second brain for you, your team and your AI agents, on your own computer. Gath
20
20
  <a href="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg">
21
21
  <img
22
22
  src="https://raw.githubusercontent.com/fmind/brain-framework/main/docs/assets/brain-loop.svg"
23
- 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."
23
+ 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."
24
24
  width="960"
25
25
  >
26
26
  </a>
@@ -56,7 +56,7 @@ Questions that once took a tour of your tools become one prompt, once you write
56
56
  - **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.
57
57
  - **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.
58
58
  - **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.
59
- - **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.
59
+ - **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.
60
60
  - **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.
61
61
  - **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.
62
62
  - **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
67
67
 
68
68
  ### What one brain can gather
69
69
 
70
- The author's own brain runs more than 50 sensors and holds over 60,000 records (counted on 2026-10-04):
70
+ The author's own brain runs more than 80 sensors and holds about 50,000 records (counted on 2026-10-16):
71
71
 
72
72
  | Area | Collected evidence |
73
73
  | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
@@ -76,7 +76,7 @@ The author's own brain runs more than 50 sensors and holds over 60,000 records (
76
76
  | Agents | Claude Code, Codex, Copilot and other agent sessions and memories, so a past conclusion is one search away. |
77
77
  | Your stack | Release notes, security bulletins and advisories of the tools you use, model retirements and provider outages. |
78
78
  | Your presence | Mentions on GitHub, Hacker News and Bluesky; domain expiry, mail security and certificate transparency; site and repository traffic. |
79
- | Reading | RSS feeds, newsletters, bookmarks, highlights and Hacker News. |
79
+ | Reading | RSS feeds, newsletters, bookmarks and Hacker News. |
80
80
 
81
81
  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.
82
82
 
@@ -95,9 +95,10 @@ A brain gives your work the structure of a detective's case file, in plain files
95
95
  | `actions/` | One work session: objective, inputs, outputs, outcome and next step. | `actions/2026-09-27_website-review/ACTION.md`, resumed the next day. |
96
96
  | `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. |
97
97
  | `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. |
98
+ | `channels/` | Scripts you review that send, read or stream messages for assistants. | A script that posts an assistant's answer in your chat thread. |
98
99
  | `evals/` | Saved questions with the evidence that search or read must return. | “Why one page?” must return the project's Decision section. |
99
100
 
100
- Notes are Markdown with YAML metadata, records are JSON, and `bf validate` checks both. `bf init --full` creates `sensors/` and `routines/`; create `prompts/` when you add a [prompt](https://fmind.github.io/brain-framework/docs/prompts/). A prompt'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).
101
+ 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).
101
102
 
102
103
  ### `bf.yaml`, the coordination hub
103
104
 
@@ -105,7 +106,7 @@ One file declares what the brain knows how to name, collect and check:
105
106
 
106
107
  ```yaml
107
108
  # https://fmind.github.io/brain-framework/docs/configuration/
108
- version: 7
109
+ version: 8
109
110
  name: brain
110
111
  fields: # the ontology: shared fields and typed relations
111
112
  project: { type: identity, cardinality: one, relation: true, description: Project the source names. }
@@ -130,7 +131,9 @@ watch: # keep sources fresh and alert on failure
130
131
  notifications: failure
131
132
  ```
132
133
 
133
- 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/).
134
+ 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/).
135
+
136
+ [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.
134
137
 
135
138
  ### One vocabulary, set at collection
136
139
 
@@ -200,7 +203,7 @@ Each host reads its own folder: for Claude Code, use `~/.claude/skills` instead.
200
203
  | `bf-use` | Find evidence, cite it, and keep projects and concepts current. |
201
204
  | `bf-action` | Start, resume and hand off a tracked work session: `/bf-action website-review`. |
202
205
  | `bf-setup` | Install BF, create a brain, connect the agent and choose sources worth adding. |
203
- | `bf-maintain` | Run sensors, routines and prompts, check the brain and upgrade it safely. |
206
+ | `bf-maintain` | Run sensors, routines and assistants, check the brain and upgrade it safely. |
204
207
 
205
208
  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.
206
209
 
@@ -237,7 +240,7 @@ A brain is a folder, so Git gives it history, rollback, review and conflict reso
237
240
 
238
241
  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.
239
242
  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.
240
- 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.
243
+ 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.
241
244
  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).
242
245
 
243
246
  [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)
@@ -745,15 +745,15 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
745
745
  OTHER DEALINGS IN THE SOFTWARE.
746
746
  ```
747
747
 
748
- ## mcp 2.2.0
748
+ ## mcp 2.3.0
749
749
 
750
750
  Source: <https://github.com/modelcontextprotocol/python-sdk>
751
751
 
752
752
  License: `MIT`
753
753
 
754
- Evidence: `mcp-2.2.0.dist-info/licenses/LICENSE`
754
+ Evidence: `mcp-2.3.0.dist-info/licenses/LICENSE`
755
755
 
756
- ### mcp-2.2.0.dist-info/licenses/LICENSE
756
+ ### mcp-2.3.0.dist-info/licenses/LICENSE
757
757
 
758
758
  ```text
759
759
  MIT License
@@ -779,15 +779,15 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
779
779
  SOFTWARE.
780
780
  ```
781
781
 
782
- ## mcp-types 2.2.0
782
+ ## mcp-types 2.3.0
783
783
 
784
784
  Source: <https://github.com/modelcontextprotocol/python-sdk>
785
785
 
786
786
  License: `MIT`
787
787
 
788
- Evidence: `mcp_types-2.2.0.dist-info/licenses/LICENSE`
788
+ Evidence: `mcp_types-2.3.0.dist-info/licenses/LICENSE`
789
789
 
790
- ### mcp_types-2.2.0.dist-info/licenses/LICENSE
790
+ ### mcp_types-2.3.0.dist-info/licenses/LICENSE
791
791
 
792
792
  ```text
793
793
  MIT License
@@ -872,15 +872,15 @@ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
872
872
  IN THE SOFTWARE.
873
873
  ```
874
874
 
875
- ## opentelemetry-api 1.45.0
875
+ ## opentelemetry-api 1.45.1
876
876
 
877
877
  Source: <https://github.com/open-telemetry/opentelemetry-python>
878
878
 
879
879
  License: `Apache-2.0`
880
880
 
881
- Evidence: `opentelemetry_api-1.45.0.dist-info/licenses/LICENSE`
881
+ Evidence: `opentelemetry_api-1.45.1.dist-info/licenses/LICENSE`
882
882
 
883
- ### opentelemetry_api-1.45.0.dist-info/licenses/LICENSE
883
+ ### opentelemetry_api-1.45.1.dist-info/licenses/LICENSE
884
884
 
885
885
  ```text
886
886
  Apache License
@@ -1086,20 +1086,20 @@ Evidence: `opentelemetry_api-1.45.0.dist-info/licenses/LICENSE`
1086
1086
  limitations under the License.
1087
1087
  ```
1088
1088
 
1089
- ## pycparser 3.0
1089
+ ## pycparser 3.11
1090
1090
 
1091
1091
  Source: <https://github.com/eliben/pycparser>
1092
1092
 
1093
1093
  License: `BSD-3-Clause`
1094
1094
 
1095
- Evidence: `pycparser-3.0.dist-info/licenses/LICENSE`
1095
+ Evidence: `pycparser-3.11.dist-info/licenses/LICENSE`
1096
1096
 
1097
- ### pycparser-3.0.dist-info/licenses/LICENSE
1097
+ ### pycparser-3.11.dist-info/licenses/LICENSE
1098
1098
 
1099
1099
  ```text
1100
1100
  pycparser -- A C parser in Python
1101
1101
 
1102
- Copyright (c) 2008-2022, Eli Bendersky
1102
+ Copyright (c) 2008-2027, Eli Bendersky
1103
1103
  All rights reserved.
1104
1104
 
1105
1105
  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
1126
1126
  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1127
1127
  ```
1128
1128
 
1129
- ## pydantic 2.13.5
1129
+ ## pydantic 2.14.1
1130
1130
 
1131
1131
  Source: <https://github.com/pydantic/pydantic>
1132
1132
 
1133
1133
  License: `MIT`
1134
1134
 
1135
- Evidence: `pydantic-2.13.5.dist-info/licenses/LICENSE`
1135
+ Evidence: `pydantic-2.14.1.dist-info/licenses/LICENSE`
1136
1136
 
1137
- ### pydantic-2.13.5.dist-info/licenses/LICENSE
1137
+ ### pydantic-2.14.1.dist-info/licenses/LICENSE
1138
1138
 
1139
1139
  ```text
1140
1140
  The MIT License (MIT)
@@ -1160,15 +1160,15 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1160
1160
  SOFTWARE.
1161
1161
  ```
1162
1162
 
1163
- ## pydantic-core 2.46.5
1163
+ ## pydantic-core 2.50.1
1164
1164
 
1165
1165
  Source: <https://github.com/pydantic/pydantic/tree/main/pydantic-core>
1166
1166
 
1167
1167
  License: `MIT`
1168
1168
 
1169
- Evidence: `pydantic_core-2.46.5.dist-info/licenses/LICENSE`
1169
+ Evidence: `pydantic_core-2.50.1.dist-info/licenses/LICENSE`
1170
1170
 
1171
- ### pydantic_core-2.46.5.dist-info/licenses/LICENSE
1171
+ ### pydantic_core-2.50.1.dist-info/licenses/LICENSE
1172
1172
 
1173
1173
  ```text
1174
1174
  The MIT License (MIT)
@@ -1577,15 +1577,15 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
1577
1577
  SOFTWARE.
1578
1578
  ```
1579
1579
 
1580
- ## rpds-py 2026.6.3
1580
+ ## rpds-py 2026.9.1
1581
1581
 
1582
1582
  Source: <https://github.com/crate-py/rpds>
1583
1583
 
1584
1584
  License: `MIT`
1585
1585
 
1586
- Evidence: `rpds_py-2026.6.3.dist-info/licenses/LICENSE`
1586
+ Evidence: `rpds_py-2026.9.1.dist-info/licenses/LICENSE`
1587
1587
 
1588
- ### rpds_py-2026.6.3.dist-info/licenses/LICENSE
1588
+ ### rpds_py-2026.9.1.dist-info/licenses/LICENSE
1589
1589
 
1590
1590
  ```text
1591
1591
  Copyright (c) 2023 Julian Berman
@@ -1675,15 +1675,15 @@ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
1675
1675
  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1676
1676
  ```
1677
1677
 
1678
- ## starlette 1.7.0
1678
+ ## starlette 1.8.0
1679
1679
 
1680
1680
  Source: <https://github.com/Kludex/starlette>
1681
1681
 
1682
1682
  License: `BSD-3-Clause`
1683
1683
 
1684
- Evidence: `starlette-1.7.0.dist-info/licenses/LICENSE.md`
1684
+ Evidence: `starlette-1.8.0.dist-info/licenses/LICENSE.md`
1685
1685
 
1686
- ### starlette-1.7.0.dist-info/licenses/LICENSE.md
1686
+ ### starlette-1.8.0.dist-info/licenses/LICENSE.md
1687
1687
 
1688
1688
  ```text
1689
1689
  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
1715
1715
  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1716
1716
  ```
1717
1717
 
1718
- ## truststore 0.10.4
1718
+ ## truststore 0.10.5
1719
1719
 
1720
1720
  Source: <https://github.com/sethmlarson/truststore>
1721
1721
 
1722
1722
  License: `MIT`
1723
1723
 
1724
- Evidence: `truststore-0.10.4.dist-info/licenses/LICENSE`
1724
+ Evidence: `truststore-0.10.5.dist-info/licenses/LICENSE`
1725
1725
 
1726
- ### truststore-0.10.4.dist-info/licenses/LICENSE
1726
+ ### truststore-0.10.5.dist-info/licenses/LICENSE
1727
1727
 
1728
1728
  ```text
1729
1729
  The MIT License (MIT)
@@ -1749,7 +1749,7 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
1749
1749
  THE SOFTWARE.
1750
1750
  ```
1751
1751
 
1752
- ## typer 0.27.2
1752
+ ## typer 0.27.3
1753
1753
 
1754
1754
  Source: <https://github.com/fastapi/typer>
1755
1755
 
@@ -1757,9 +1757,9 @@ License: `MIT`
1757
1757
 
1758
1758
  The distribution vendors code adapted from Click in `typer/_click/`; its bundled `BSD-3-Clause` license is included below.
1759
1759
 
1760
- Evidence: `typer-0.27.2.dist-info/licenses/LICENSE`
1760
+ Evidence: `typer-0.27.3.dist-info/licenses/LICENSE`
1761
1761
 
1762
- ### typer-0.27.2.dist-info/licenses/LICENSE
1762
+ ### typer-0.27.3.dist-info/licenses/LICENSE
1763
1763
 
1764
1764
  ```text
1765
1765
  The MIT License (MIT)
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "brain-framework"
3
- version = "18.5.0"
3
+ version = "19.0.0"
4
4
  description = "🧠 Brain Framework: from information to informed actions."
5
5
  readme = "README.md"
6
6
  requires-python = ">=3.14"
@@ -43,6 +43,7 @@ dependencies = [
43
43
  name = "Médéric Hurier"
44
44
 
45
45
  [project.urls]
46
+ Changelog = "https://fmind.github.io/brain-framework/changelog/"
46
47
  Documentation = "https://fmind.github.io/brain-framework/"
47
48
  Issues = "https://github.com/fmind/brain-framework/issues"
48
49
  Repository = "https://github.com/fmind/brain-framework"
@@ -51,7 +52,7 @@ Repository = "https://github.com/fmind/brain-framework"
51
52
  bf = "bf:main"
52
53
 
53
54
  [build-system]
54
- requires = ["uv_build>=0.12.10,<0.13"]
55
+ requires = ["uv_build>=0.12.10,<0.14"]
55
56
  build-backend = "uv_build"
56
57
 
57
58
  [tool.uv.build-backend]
@@ -1,7 +1,7 @@
1
1
  # https://packaging.python.org/en/latest/specifications/pyproject-toml/
2
2
  [project]
3
3
  name = "brain-framework"
4
- version = "18.5.0"
4
+ version = "19.0.0"
5
5
  description = "🧠 Brain Framework: from information to informed actions."
6
6
  readme = "README.md"
7
7
  requires-python = ">=3.14"
@@ -39,6 +39,7 @@ dependencies = [
39
39
  ]
40
40
 
41
41
  [project.urls]
42
+ Changelog = "https://fmind.github.io/brain-framework/changelog/"
42
43
  Documentation = "https://fmind.github.io/brain-framework/"
43
44
  Issues = "https://github.com/fmind/brain-framework/issues"
44
45
  Repository = "https://github.com/fmind/brain-framework"
@@ -47,7 +48,7 @@ Repository = "https://github.com/fmind/brain-framework"
47
48
  bf = "bf:main"
48
49
 
49
50
  [build-system]
50
- requires = ["uv_build>=0.12.10,<0.13"]
51
+ requires = ["uv_build>=0.12.10,<0.14"]
51
52
  build-backend = "uv_build"
52
53
 
53
54
  [tool.uv.build-backend]
@@ -56,8 +57,9 @@ module-name = "bf"
56
57
  [dependency-groups]
57
58
  dev = [
58
59
  "jsonschema>=4.26.0,<5",
59
- # Imported directly by tests/test_readme.py, as Zensical renders headings, and scripts/notices.py.
60
+ # Imported directly by tests/test_readme.py: Zensical slugs headings with Python-Markdown.
60
61
  "markdown>=3.11",
62
+ # Imported directly by scripts/notices.py to parse requirements and normalize names.
61
63
  "packaging>=26.3",
62
64
  "pytest-cov>=7.1.0",
63
65
  "pytest-watcher>=0.6.3",
@@ -2,7 +2,7 @@
2
2
 
3
3
  import os
4
4
 
5
- __version__ = "18.5.0"
5
+ __version__ = "19.0.0"
6
6
 
7
7
 
8
8
  def main() -> None: