crbro-memory 2.7.2 → 2.8.0

package/README.md

@@ -9,7 +9,7 @@
 
 **CRBRO** is a local MCP (Model Context Protocol) server that gives your AI assistant **persistent long-term memory** across sessions. It uses a biological neural architecture — cortex, synapses, hippocampus — to store, connect, and retrieve knowledge automatically.
 
-![CRBRO demo](https://raw.githubusercontent.com/Octonove/crbro-memory/master/docs/demo.gif)
+![CRBRO tour: memory across sessions, corrections that replace old facts, secrets kept out, the guard before a shell command, the compaction checkpoint and the open-items band](https://raw.githubusercontent.com/Octonove/crbro-memory/master/docs/crbro-tour.gif)
 
 Free and open source (MIT). All 15 tools included — no license, no account, no tiers.
 
@@ -49,6 +49,7 @@ Or in USDC. Send **USDC only** and **only on the network shown**; on any other n
 - **🧰 15 tools, one lifecycle** — Every read is a view of `crbro_inspect`; `crbro_learn`, `crbro_revise` and `crbro_forget` are the three stages of one rule (a new truth supersedes the old, an outdated one is retired, a dangerous one is removed), and every description says in its first sentence whether it reads or writes and which neighbour does the adjacent job. Down from 23 in 1.x without touching the brain on disk; `crbro_boot` maps the old names to the new calls *(v2.0+)*
 - **🔁 Lessons that outgrow their project** — Storing the same fact again counts it (`confirmations`, shown by `crbro_inspect` when above 1), and `crbro_consolidate` points out lessons that already live in two or more project neurons, with the `tech_` or `process_` neuron they belong in. It suggests; it never moves anything *(v2.7+)*
 - **🧷 Compact without losing the thread (opt-in)** — `npx crbro-memory install-hooks --compact` saves a redacted checkpoint of a Claude Code session before it compacts — last requests, task list, open items, folder and git remote — and hands it back when the session resumes, in 1,500 characters at most. No model call *(v2.7+)*
+- **📌 Open items in sight (on by default for Claude Code, opt-out)** — where Claude Code is installed, `crbro_boot` adds a Claude Code mod on its own, keeps it up to date, and has the assistant tell you once when it does: the newest open item of the brain above the prompt, whole — its label apart, its numbered steps one per line, its age in color — with ‹ › to go through the rest, and `/pending` (alias `/pendientes`) with every one as a card: filter, *work on this*, *done* and *discard* behind a confirmation, and what was closed lately. It reads through `crbro_context` and closes through it; the brain file is only read when the server is not reachable. English or Spanish (`--lang`). Needs Claude Code 2.1.286 or later: the CLI and the desktop app's Code tab. Remove it with `npx crbro-memory uninstall-mod` — it is never put back on its own, whichever app runs CRBRO — or keep one MCP client from installing it with `CRBRO_MOD=0` in that client's env *(v2.8+)*
 - **🔎 Look back at your sessions (read-only)** — `crbro usage` sums the tokens each model took per session, subagents apart; `crbro postmortem` lists candidate lessons — corrections you had to repeat, a tool failing in a row, the same request asked again — and stores nothing. Both read Claude Code's own logs on your disk *(v2.7+)*
 - **⏱️ Memory at the moment of action (opt-in)** — `npx crbro-memory install-hooks --guard` wires a Claude Code `PreToolUse` hook: before a shell command runs, the stored errors, debts and patterns that mention *that command* are added to the model's context — three at most, once per session, never blocking. Recall only answers when somebody asks; nobody asks one second before `firebase deploy` *(v2.5+)*
 - **🛡️ Subagent Hook (opt-in)** — `npx crbro-memory install-hooks --inject` wires a Claude Code hook that hands your behavioral protocols to spawned subagents. Injection is off by default since 1.12 — three clean-control benchmark runs found no measured benefit in any model and real harm in small ones, and shipping an unmeasured default is not what this project does
@@ -221,6 +222,38 @@ A compaction keeps a summary and loses the detail that tells you where you were.
 
 The `install-boot` entry for Claude Code prints the same notice, so it is replaced (and put back by `uninstall-hooks --compact`). A CRBRO hook you wrote yourself is never replaced: the new hooks are added next to it with `--no-boot` / `--no-reminder`, so nothing is read twice. Only Claude Code has `PreCompact`; Codex and the rest are not touched. Like the other hooks, it never blocks: it reads no network, starts no `git` process, ends on its own if stdin never closes, and always exits 0.
 
+### 9. (Claude Code, on by default) Open items in sight
+
+![The open-items band above the Claude Code prompt and the /pending pane: an item read whole, filtered, sent to the prompt and closed through CRBRO](https://raw.githubusercontent.com/Octonove/crbro-memory/master/docs/pending-band.gif)
+
+Nothing to run: if Claude Code is on the machine (`~/.claude` exists), the first `crbro_boot` installs this mod exactly as `install-mod` below would, with the language on auto, and the boot answer carries a `mod_notice` the assistant passes on to you — what was installed, that it appears in *new* Claude Code sessions, and how to remove it. The notice goes to the first boot of up to three server processes (one each) within a week, because the first one may be a background run nobody reads. After an update of CRBRO, a boot that finds the installed files different from the package (SHA-256, line endings aside) refreshes them, without touching `settings.json`, and says so too; an older CRBRO on the same machine never takes back the files of a newer one, and two builds of the same version (a checkout beside the npm copy) do not rewrite each other. It runs once per server process (once per daemon) and never fails the boot. The files are copied without blocking and the boot waits for the install 1.5 s at most; the few settings reads and writes left are synchronous and take milliseconds. Two sessions starting at once take turns through a lock file, and `settings.json` is written only if it is still what was read: a change Claude Code saves at the same moment is merged, not lost.
+
+To opt out:
+
+```bash
+npx crbro-memory uninstall-mod             # removes it and leaves a mark: never put back on its own, from any app
+CRBRO_MOD=0                                # in one MCP client's env: that client never installs or updates it
+```
+
+`uninstall-mod` is the machine-wide way out: the mark sits in `~/.claude/crbro-mods/state.json`, which every CRBRO reads. `CRBRO_MOD=0` only covers the client whose MCP configuration sets it — CRBRO in Codex, Cursor or Claude Desktop installs in the same `~/.claude` unless it has the variable too — so set it in each, or run `uninstall-mod` once. Taking `~/.claude/crbro-mods/crbro-pending` out of `CLAUDE_CODE_PLUGIN_DIRS` by hand counts as a no as well, and the next boot says so once, with the way back. `install-mod` lifts the mark. A `settings.json` that does not parse is never touched, and the same failure is not retried until that file or the package changes, or a day goes by (a file held open by another program is retried at the next start). If the list already holds another `crbro-pending` (a checkout of this repository, say), nothing is installed beside it. If `CLAUDE_CODE_PLUGIN_DIRS` is set only in the environment Claude Code starts from and not in `settings.json`, nothing is installed either — `settings.json`'s `env` wins over the environment, so writing the variable there would stop those plugins from loading — and the boot says so once; move the variable into `settings.json` and the next start adds the mod beside them. Claude Code before 2.1.286 has not been tried with the mod.
+
+```bash
+npx crbro-memory install-mod               # --lang en | es | auto (default: leave it as it is; auto on a first install)
+npx crbro-memory install-mod --verify      # SHA-256 of the installed copy against this package; changes nothing
+npx crbro-memory uninstall-mod
+```
+
+An open item left in `crbro_context` is only seen when `crbro_boot` lists it, which is how finished work gets repeated back for weeks and unfinished work gets forgotten. This installs `mods/crbro-pending`, a Claude Code mod (a plugin of function hooks):
+
+- **The band**, above the prompt: the newest open item, whole. A short `Label:` is drawn apart and `(1) … (2) …` steps go one per line; the age is green up to 3 days, amber up to two weeks, red after. ‹ › walks the others, *Compact* folds it to one line, *See all* opens the list, *Hide* puts it away until `/pending`.
+- **`/pending`** (alias `/pendientes`): every open item as a card, with a filter that ignores accents, *Work on this* (writes the item into the prompt for you to send), *Done* and *Discard*, each behind a yes/no, and the items closed lately.
+
+It reads with `crbro_context` and no arguments, which only reads, on whichever MCP server has that tool (`crbro` in a standard install, found with the session's tool list), and refreshes every minute and after every CRBRO tool call. When no CRBRO server is reachable it reads `<CRBRO_PATH or ~/.crbro>/prefrontal/active_context.json` instead, resolved as the server resolves it, and says so. That fallback only sees a `CRBRO_PATH` set where Claude Code itself runs (the system, your shell, or the `env` block of `~/.claude/settings.json`), not one set only in the MCP server's own `env` block; with a brain configured only there, the band reads `~/.crbro` until the server connects, and the pane names the file it read. *Done* and *Discard* always go through the server — `resolve_pending` keeps the item under recently closed, `discard_pending` does not — and the mod never writes the brain.
+
+`install-mod` copies the mod to `~/.claude/crbro-mods/crbro-pending` and adds that folder to `env.CLAUDE_CODE_PLUGIN_DIRS` in `~/.claude/settings.json` (`;` between folders on Windows, `:` elsewhere), once; nothing else in that file is touched, except the mod's own language when `--lang en` or `--lang es` is given (`pluginConfigs.crbro-pending.options.language`, also a row in `/config`). `auto` follows `CRBRO_LANG`, then `LC_ALL` / `LC_MESSAGES` / `LANG`, then the system locale. A `settings.json` that does not parse is left alone, the write is atomic, and running it again changes nothing. If the list already holds a folder whose plugin is named `crbro-pendientes` — the copy made by hand before this existed — it is replaced in place and named; its folder stays on disk. Any other copy, another `crbro-pending` in the list or one in `~/.claude/mods`, is pointed out and never touched, and `--verify` fails while it is there, because Claude Code would draw two bands. `uninstall-mod` takes the path out of the list (and the variable, if it ends up empty), puts back the `crbro-pendientes` folder it replaced if that folder is still there, and deletes `~/.claude/crbro-mods/crbro-pending`, nothing else. If `CLAUDE_CODE_PLUGIN_DIRS` is also set in your shell with folders `settings.json` does not list, `install-mod` names them: the `env` block of `settings.json` is applied on top of the environment, so add them there if those plugins stop loading. `install-hooks --verify` checks the mod too.
+
+Mods need Claude Code 2.1.286 or later and are drawn in the CLI and in the desktop app's Code tab; Claude Desktop chat, Codex, Cursor and the VS Code extension do not draw them. Open a new session after installing.
+
 ## Tools
 
 | Tool | Description |
@@ -435,7 +468,9 @@ npx crbro-memory daemon on | off | status | stop   # One process owns the brain
 npx crbro-memory install-hooks --guard   # Stored lessons speak before a shell command runs (above)
 npx crbro-memory install-hooks --compact # Checkpoint before a compaction, picked back up after it (above)
 npx crbro-memory guard "<command>"       # What the guard would say for a command
-npx crbro-memory install-hooks --verify  # SHA-256 of the installed hooks against this package; changes nothing
+npx crbro-memory install-hooks --verify  # SHA-256 of the installed hooks and mod against this package; changes nothing
+npx crbro-memory install-mod [--lang en|es|auto]   # Open items above the prompt and /pending in Claude Code (above)
+npx crbro-memory uninstall-mod           # Remove that mod and its CLAUDE_CODE_PLUGIN_DIRS entry
 npx crbro-memory usage [--days N] [--session ID] [--project DIR] [--json]   # Tokens per model and session, subagents apart
 npx crbro-memory postmortem [--days N] [--max N] [--json]   # Candidate lessons from past sessions; stores nothing
 npx crbro-memory --help   # Help
@@ -509,7 +544,20 @@ read its file or call `crbro_inspect`.
 `~/.claude/projects`, locally and read-only: `usage` reads only the model name
 and token counts of each response, `postmortem` only what you typed and the
 names of the tools called — never a tool's input or output — and redacts what
-it prints. What each defense is for, and how to report a vulnerability, is in
+it prints.
+
+The one thing CRBRO writes in Claude Code's folder without being asked is the
+open-items mod: `~/.claude/crbro-mods/` (the mod itself, a `state.json` with
+the opt-out mark and the installed version, a lock held for the seconds an
+install takes, and a notice kept until the boots that hand it over have had
+it) and its one entry in `env.CLAUDE_CODE_PLUGIN_DIRS` of
+`~/.claude/settings.json`. No other key in that file is changed; it is
+rewritten as JSON with its indentation and line endings (on Windows the new
+file takes the folder's permissions). Nothing is downloaded or sent, and none
+of it happens without `~/.claude`, in a client with `CRBRO_MOD=0`, or after
+`uninstall-mod`.
+
+What each defense is for, and how to report a vulnerability, is in
 [SECURITY.md](https://github.com/Octonove/crbro-memory/blob/master/SECURITY.md).
 
 ## License

package/SECURITY.md

@@ -15,6 +15,7 @@ like friction, and nobody trusts one for more than it does.
 | | What the miner extracted from files on disk | Neurons, marked `source: miner` |
 | | Claude Code session logs, read by `crbro usage`, `crbro postmortem` and the lifecycle hook | `~/.claude/projects/` |
 | | Compaction checkpoints written by the lifecycle hook (requests, task list, folder, remote) | `<brain>/checkpoints/`, seven days |
+| **Code CRBRO runs in Claude Code without a command** | The open-items mod, installed and updated by `crbro_boot` | `~/.claude/crbro-mods/`, one entry in `env.CLAUDE_CODE_PLUGIN_DIRS` of `~/.claude/settings.json` |
 | **Communication out** | Team-space sync | A git remote you configure |
 | | The optional semantic model | Downloaded once from Hugging Face by `semantic install` |
 
@@ -158,6 +159,41 @@ cannot explain is worth looking at before the next session.
 It compares against the package on disk, so it cannot catch a change made to
 both. It runs when you run it, not on its own.
 
+### The mod CRBRO installs on its own — `crbro_boot`, `install-mod --verify`
+
+Since 2.8, `crbro_boot` copies the open-items mod (`mods/crbro-pending`, TSX
+that Claude Code runs in every new session) into
+`~/.claude/crbro-mods/crbro-pending` and adds that folder to
+`env.CLAUDE_CODE_PLUGIN_DIRS` of `~/.claude/settings.json`, wherever
+`~/.claude` exists, without being asked. The author chose that so the band
+reaches everyone who has CRBRO; this section is what it costs and how to
+check it.
+
+- **What runs is what the package ships.** On every new server process, the
+  installed copy is compared file by file (SHA-256) with the package that
+  process runs, and a different build of a newer or equal version replaces it.
+  Updating CRBRO therefore updates code Claude Code executes, with no step in
+  between. A file edited by hand in the installed copy is overwritten at the
+  next start; to work on the mod, list your own checkout in the variable and
+  the automatic install stays out.
+- **Check it.** `npx crbro-memory install-mod --verify` hashes the installed
+  copy against the package you run, names any other copy Claude Code would
+  load, writes nothing and exits 1 on a difference. The same limits as hook
+  verification apply: it compares with the package on disk.
+- **It says what it did.** The boot that installs or updates it carries
+  `mod_notice` for the assistant to pass on, with the paths and the way out.
+- **The way out is final.** `npx crbro-memory uninstall-mod` removes the
+  entry and the folder and writes `optedOut` in
+  `~/.claude/crbro-mods/state.json`; no CRBRO, from any client, installs it
+  again until `install-mod` is run. Taking the folder out of the list by hand
+  counts the same. `CRBRO_MOD=0` in an MCP client's env keeps that client
+  out (a daemon started without it does not serve it), but not the others.
+- **What it will not do.** It does not write a `settings.json` that does not
+  parse, does not overwrite a change saved to that file while it was working
+  (the file is hashed again right before the rename), and does not write the
+  variable there when only the environment sets it. It downloads nothing:
+  the files come from the installed npm package.
+
 ### Reading session logs — `crbro usage`, `crbro postmortem`, the lifecycle hook
 
 Claude Code's logs hold everything said in a session, tool output included.