crbro-memory 2.7.1 → 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.
 
@@ -32,7 +32,7 @@ Or in USDC. Send **USDC only** and **only on the network shown**; on any other n
 - **🎯 Read the entry, not the neuron** — `crbro_inspect view=neuron` returns an index: every fact, decision, pattern, preference, error, debt and the map as an id, a kind, a date and a preview. `entries=[ids]` reads just those; every recall hit carries its `entry_id`. The whole-neuron read still exists as `detail=full`, behind a declared ceiling. A 307-fact neuron went from 66,952 tokens to 1,887 to open *(v2.1+)*
 - **📓 The diary is searchable** — every session summary is in the index, as paragraphs. `crbro_recall` returns the days that mention the question in a list of their own, `sessions_matched`, so narrative never outranks a fact; `crbro_inspect view=sessions session=<id>` reads one day whole. Lexical only, rebuilt once on upgrade *(v2.2+)*
 - **🗣️ The model in the loop** — Two levers no embedding model replaces, measured blind: keywords written at save time (the caller knows the synonyms: a line about Hetzner gets *hosting, alojamiento, servidor*) and several phrasings searched at once, fused by rank. Zero disk, zero RAM; numbers in the table below *(v1.15+)*
-- **🧭 Semantic recall** — `npx crbro-memory init` installs a local embedding model (`multilingual-e5-small`, int8) fused with the keyword engine, so paraphrases the words do not cover start to land. Measured: +8 points of recall@1 over the keyword engine, +2 to +5 on top of save-time keywords. Costs ~500 MB on disk once per machine and ~0.5 GB of RAM while a server runs; `init --no-semantic` skips it, `CRBRO_SEMANTIC=0` turns it off *(v1.14+, installed by default since v1.16)*
+- **🧭 Semantic recall** — `npx crbro-memory init` installs a local embedding model (`multilingual-e5-small`, int8) fused with the keyword engine, so paraphrases the words do not cover start to land. It matters most in a big brain: with 1,482 unrelated facts around the test set it lifts recall@1 from 54% to 67% on the original exam and from 31% to 48% on a new 96-question one; on a small brain it measures within 2 points of the keyword engine (75% vs 77% on 2.7.2). Costs ~500 MB on disk once per machine and ~0.5 GB of RAM while a server runs; `init --no-semantic` skips it, `CRBRO_SEMANTIC=0` turns it off *(v1.14+, installed by default since v1.16)*
 - **🔥 Heat Scores** — Automatic relevance tracking based on frequency, recency, and connectivity. Topics written in the same session are linked at consolidation, so the graph fills itself in *(v1.13+)*
 - **🕰️ Dates that mean something** — A recency lift of at most 4% breaks ties towards the newer telling (measured: it only ever flipped exact ties), `crbro_recall since` / `kind` narrow a search to "the last two weeks" or "only past mistakes", and `crbro_maintenance backfill_dates` dates the entries written before 1.13 from the date stated in their own text — never guessed *(v2.5+)*
 - **🧹 Housekeeping that reports before it acts** — every maintenance run lists entries whose own deadline has passed, neurons that outgrew one read (with `crbro_revise move_to` to split them keeping every date) and the one-line neurons a bulk import left behind (`compact:true` folds them into a digest). All read-only until asked *(v2.5+)*
@@ -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
@@ -59,18 +60,20 @@ Or in USDC. Send **USDC only** and **only on the network shown**; on any other n
 
 ## Measured, not promised
 
-Every number below comes from a deterministic benchmark in [`benchmarks/`](https://github.com/Octonove/crbro-memory/tree/master/benchmarks) that runs in CI — no API calls, reproducible on your machine with `node benchmarks/<name>/run.mjs`. The unflattering ones are published on purpose.
+Every number below comes from a benchmark in [`benchmarks/`](https://github.com/Octonove/crbro-memory/tree/master/benchmarks), reproducible on your machine with `node benchmarks/<name>/run.mjs`. All of them are deterministic and run in CI with no API calls, except the agentic one, which puts a real Claude Code agent to work and spends tokens. The unflattering ones are published on purpose.
 
-The short version, re-measured on 2026-10-03 with 2.7.0: as installed, **73%** of blind questions land on the right fact at rank 1 and **90%** within the topic's top three lines; with the two free habits the card teaches, **90%** at rank 1 and **96%** within the top lines. The keyword engine underneath, with nothing installed, is the floor at 71%. Some of these figures are lower than the ones published with 1.14–1.16 (79% at rank 1 as installed); 2.6.0 measures the same as 2.7.0, and the cause of the drop has not been traced yet. Not one credential in the adversarial set gets through, and a session pays about 750 tokens for all of it.
+The short version, measured on 2026-10-03 with 2.7.2: **a fresh session did not ask again what memory already held** — with CRBRO a real agent answered 24 of 24 questions whose answer lived only in memory, without it 0 of 24 (haiku and sonnet, Claude Code 2.1.270, n=3). As installed, **75%** of blind questions land on the right fact at rank 1 and **90%** within the topic's top three lines; with the two free habits the card teaches, **92%** at rank 1 and **98%** within the top lines. A second, harder exam of 96 new questions lands 57% at rank 1, and the semantic layer earns its place as the brain grows: inside 1,482 unrelated facts it holds 48% where the keyword engine alone falls to 31%. The drop of the semantic layer since 2.5 (79% → 73%) is traced to two changes in how ties and vectors are computed, not to a search bug. Not one credential in the adversarial set gets through, and a session pays about 1,000 tokens for all of it.
 
 | What | Result | The honest part |
 |------|--------|-----------------|
-| **Retrieval, as installed** (48 blind paraphrased queries, written by someone who never saw the stored text; the semantic layer is on by default since 1.16; measured 2026-10-03, `CRBRO_SEMANTIC=1 node benchmarks/retrieval/run.mjs`) | recall@1 **73%** · recall@3 **79%** · MRR 0.760 — **81% / 90%** counting `also_matched` | Vectors from `multilingual-e5-small` (int8) fused with BM25 by reciprocal rank. Alone, the model scored 63% / 81% when it was measured in 1.14; fused, it now adds 2 points at recall@1 over the keyword engine (it added 8 in 1.14) and no distractor reaches a real hit's score (0 of 14; 11 return something, 10 of them labelled `weak`). The cosine floor under which a vector-only candidate is dropped (0.84) was picked on this same set — a tuned number, not a blind one. Costs ~500 MB on disk, ~0.5 GB of RAM while the server runs, a one-time embedding pass (~3 min for a 4k-line brain) and ~13 s of model load per process. Installed by `init` since 1.16; `CRBRO_SEMANTIC=0` turns it off *(v1.14+)* |
-| **Retrieval with the two habits the card teaches** (same 48 queries; keywords at save time and several phrasings at recall, both written blind by a model that saw only one half of the test; measured 2026-10-03) | keywords alone: recall@1 **83%** · recall@3 **90%** — everything on (keywords + rewrites + semantic layer): **90% / 92%**, and **94% / 96%** counting `also_matched` | The biggest lever costs nothing: 2-5 keywords written when a fact is saved close exactly the gaps no embedding model closed. Rewrites alone do not move the keyword engine at rank 1 (71% → 71% / 83%); they add up on top of keywords. With everything on, all 14 distractors return something, none at a real hit's score, all 14 labelled `weak`. Every configuration and the three questions still missed are in [`benchmarks/README.md`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/README.md) *(v1.15+)* |
-| **The keyword engine alone** (same 48 queries; `CRBRO_SEMANTIC=0`, or before the model is installed; measured 2026-10-03, `node benchmarks/retrieval/run.mjs`) | recall@1 **71%** · recall@3 **77%** · MRR 0.744 — and **77% / 83%** counting the neuron's `also_matched` lines (79% / 85% when published in 1.13) | Was 56% / 69% in 1.12. Of the 13 misses, 8 were the *right neuron answering with the wrong line* (its name chunk, or a sibling fact) — fixed in the engine; the rest are vocabulary gaps, which a short bilingual synonym table now closes in part. A naive substring search scores 38% / 58%. This is the floor every install starts from, and the misses are listed in the benchmark output |
-| **Retrieval — false confidence** (14 questions about things that are NOT stored; measured 2026-10-03) | keyword engine: 11 return *something*; **2** at a real hit's score; **10 of 11** labelled `weak`. As installed: 11 return something, **0** at a real hit's score, 10 of 11 labelled `weak` | A keyword memory answers almost anything. Every result now carries `confidence`, and the label catches nearly every distractor — at the price of also calling 18 of 48 real hits weak. Weak means "little of the question was covered", not "wrong" |
+| **A fresh session does not ask again** (a new Claude Code session, no history, gets a question whose answer lives only in a memory seeded earlier; the prompt never mentions memory; 12 frozen fictitious tasks, 4 thresholds fixed before running; haiku and sonnet, Claude Code 2.1.270, n=3; measured 2026-10-03, `node benchmarks/agentic/run.mjs`) | with CRBRO **24/24** on answers that live only in memory, **0** retired values given (12/12 where an old value was replaced) — without it **0/24**, and sonnet invented 4 | Both controls behave: when the answer is in the question both arms get it (6/6), and when it is nowhere CRBRO abstains as often as the bare agent (6/6, nothing invented). The server's instructions were fixed twice between runs on these same 12 tasks — the published run is the one where the fix works, not a blind one — and these are short single-question sessions. A result holds for that model and that Claude Code version; another needs its own run. Pre-registration and every run are in [`benchmarks/agentic/`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/agentic/PREREGISTRO.md) *(v2.7.2)* |
+| **Retrieval, as installed** (48 blind paraphrased queries, written by someone who never saw the stored text; the semantic layer is on by default since 1.16; measured 2026-10-03 on 2.7.2, `CRBRO_SEMANTIC=1 node benchmarks/retrieval/run.mjs`) | recall@1 **75%** · recall@3 **81%** · MRR 0.781 — **81% / 90%** counting `also_matched` | Vectors from `multilingual-e5-small` (int8) fused with BM25 by reciprocal rank. On this small set the fusion now sits 2 points below the keyword engine at rank 1 (75% vs 77%) — the keyword engine got better in 2.7.2, the fusion barely moved — and no distractor reaches a real hit's score (0 of 14). It added 8 points in 1.14; the −6 since 2.5 is traced in [`benchmarks/README.md`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/README.md). The cosine floor under which a vector-only candidate is dropped (0.84) was picked on this same set and re-checked on a separate tuning set — a tuned number, not a blind one. Costs ~500 MB on disk, ~0.5 GB of RAM while the server runs, a one-time embedding pass (~3 min for a 4k-line brain when it was measured in batches; one line at a time since 2.7.2 takes 1.6× as long) and ~13 s of model load per process. Installed by `init` since 1.16; `CRBRO_SEMANTIC=0` turns it off *(v1.14+)* |
+| **Retrieval with the two habits the card teaches** (same 48 queries; keywords at save time and several phrasings at recall, both written blind by a model that saw only one half of the test; measured 2026-10-03 on 2.7.2) | keywords alone: recall@1 **83%** · recall@3 **92%** — everything on (keywords + rewrites + semantic layer): **92% / 96%**, and **94% / 98%** counting `also_matched` | The biggest lever costs nothing: 2-5 keywords written when a fact is saved close exactly the gaps no embedding model closed — which is why `crbro_learn` now asks for them when a fact arrives without. Rewrites alone do not move the keyword engine at rank 1 (77% → 77% / 90%); they add up on top of keywords. With everything on, no distractor reaches a real hit's score. Every configuration and the questions still missed are in [`benchmarks/README.md`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/README.md) *(v1.15+)* |
+| **The keyword engine alone** (same 48 queries; `CRBRO_SEMANTIC=0`, or before the model is installed; measured 2026-10-03 on 2.7.2, `node benchmarks/retrieval/run.mjs`) | recall@1 **77%** · recall@3 **83%** · MRR 0.806 — the same counting `also_matched` (71% / 77% on 2.7.1) | Was 56% / 69% in 1.12. 2.7.2 weighs each query term by its rarity, chosen on a separate tuning set: +6 here, +12 inside the 1,482-fact haystack, and nothing on the new 96-question exam (49%). A naive substring search scores 38% / 58%. This is the floor every install starts from, and the misses are listed in the benchmark output |
+| **Retrieval at scale** (a second blind exam of 96 questions + 20 distractors, and a haystack of 1,482 facts in 114 unrelated topics learned before the test brain; both frozen before measuring; measured 2026-10-03 on 2.7.2) | as installed: recall@1 **57%** · recall@3 **60%**; inside the haystack **48% / 52%**. Keyword engine alone: 49% / 53%, inside the haystack **31% / 40%** | The new exam is harder than the original one and gives more false confidence: 8 of its 20 distractors come back at a real hit's score as installed, 11 with the keyword engine. Its numbers did not move between 2.7.1 and 2.7.2. What it shows is what the semantic layer is for: the more unrelated facts a brain holds, the more it carries recall — 17 points here |
+| **Retrieval — false confidence** (14 questions about things that are NOT stored; measured 2026-10-03 on 2.7.2) | keyword engine: **2** at a real hit's score. As installed: **0** at a real hit's score | A keyword memory answers almost anything. Every result carries `confidence`, and the label catches nearly every distractor on this set — at the price of also calling some real hits weak. Weak means "little of the question was covered", not "wrong". On the harder 96-question exam it catches far fewer (see the row above) |
 | **Secret redaction** (20 credentials in adversarial disguises, 19 near-miss innocents) | **100%** caught · **0%** false positives | 100% on *this frozen set* — a floor, not a security proof. The set grows as new evasion shapes appear; four of its entries were misses in the first run and were fixed, not hidden |
-| **Cost** (what CRBRO adds to a session) | ~**750 tokens** of protocol block · **~2.8k tokens** for the whole boot payload on a 1,145-neuron brain · **~2k** per recall (five ranked results) · **~6.8k tokens** of tool definitions · **<1 ms** local recall over 300 facts | The boot block is paid once. The 750 figure is the protocol text alone; what boot RETURNS also carries hot topics, the active context and recent sessions, and on a mature brain that reached 20,352 tokens until 2.0.3 put a declared ceiling on it — 4,989 measured after 2.0.3 and 2,758 after 2.1, which also made the neuron view an index (a 307-fact neuron: 66,952 → 1,887 tokens to open), cut recall to five ranked results by default and dropped the pretty-printing every response paid for. No read is allowed past that ceiling now, and anything shortened says so. The 15 tool definitions (27,095 characters of description + input schema, measured with a real `tools/list` on 2.1.0 and divided by 4; 32,246 counting the output schemas of the three readers, ~8.1k tokens) are paid on every request by clients that load all tools (Claude Desktop, Cursor); Claude Code defers them and pays only for the ones it uses. Fewer tools, not fewer characters: the 23 of 1.13 measured 21,662 (~5.4k tokens), because each parameter's text now lives in the tool that absorbed it |
+| **Cost** (what CRBRO adds to a session) | ~**1,000 tokens** of protocol block · **~2.8k tokens** for the whole boot payload on a 1,145-neuron brain · **~2k** per recall (five ranked results) · **~7.5k tokens** of tool definitions · **~1 ms** local recall over 300 facts with the keyword engine, **~10 ms** with the semantic layer, which embeds the question | The boot block is paid once. The 1,000 figure is the protocol text alone — Card Zero's ten protocols, 4,035 characters, measured on 2026-10-03 (750 before its tenth protocol); what boot RETURNS also carries hot topics, the active context and recent sessions, and on a mature brain that reached 20,352 tokens until 2.0.3 put a declared ceiling on it — 4,989 measured after 2.0.3 and 2,758 after 2.1, which also made the neuron view an index (a 307-fact neuron: 66,952 → 1,887 tokens to open), cut recall to five ranked results by default and dropped the pretty-printing every response paid for. No read is allowed past that ceiling now, and anything shortened says so. The 15 tool definitions (29,897 characters of description + input schema, measured with a real `tools/list` on 2.7.2 on 2026-10-03 and divided by 4; 35,416 counting the output schemas of the three readers, ~8.9k tokens; 29,757 on 2.7.1; 27,095 and 32,246 on 2.1.0) are paid on every request by clients that load all tools (Claude Desktop, Cursor); Claude Code defers them and pays only for the ones it uses. Fewer tools, not fewer characters: the 23 of 1.13 measured 21,662 (~5.4k tokens), because each parameter's text now lives in the tool that absorbed it |
 
 What these benchmarks deliberately do **not** claim — human productivity, "it knows you", comparisons against other memory systems — is written down in [`benchmarks/LIMITS.md`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/LIMITS.md).
 
@@ -219,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 |
@@ -433,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
@@ -441,17 +478,17 @@ npx crbro-memory --help   # Help
 
 ### Semantic recall
 
-The keyword engine has no synonyms, and the blind benchmark shows exactly where that bites: paraphrases — *"where are the sites hosted"* for a fact about a Hetzner VPS. Keywords written at save time close most of that gap for free (above); a small embedding model closes a little more. Since 1.16 `npx crbro-memory init` installs it by default, once per machine, and the layer is on wherever its runtime is present. What it costs, measured: ~500 MB on disk (runtime ~380 MB + model 118 MB), ~0.5 GB of RAM while a server runs, ~13 s of model load per process (in the background) and a one-time embedding pass. Skip it with `init --no-semantic`; turn it off any time with `CRBRO_SEMANTIC=0` in the server's env.
+The keyword engine has no synonyms, and the blind benchmark shows exactly where that bites: paraphrases — *"where are the sites hosted"* for a fact about a Hetzner VPS. Keywords written at save time close most of that gap for free (above); a small embedding model closes a little more on a small brain and a lot more on a big one. Since 1.16 `npx crbro-memory init` installs it by default, once per machine, and the layer is on wherever its runtime is present. What it costs, measured: ~500 MB on disk (runtime ~380 MB + model 118 MB), ~0.5 GB of RAM while a server runs, ~13 s of model load per process (in the background) and a one-time embedding pass. Skip it with `init --no-semantic`; turn it off any time with `CRBRO_SEMANTIC=0` in the server's env.
 
 ```bash
 npx crbro-memory init                 # installs it (skip with --no-semantic)
 npx crbro-memory semantic status      # runtime, model, on or off, and why
-npx crbro-memory semantic build       # embed an existing brain once (a 4k-line brain: ~3 min)
+npx crbro-memory semantic build       # embed an existing brain once (a 4k-line brain: ~3 min in batches; 2.7.2 embeds one line at a time, 1.6x that)
 ```
 
 Every new line is embedded when it is saved (ids are content hashes, so nothing is embedded twice), the model warms in the background after boot, and `crbro_recall` fuses both rankings by reciprocal rank. Results the vectors ranked carry `semantic_score`; a vector-only match is `strong` from cosine 0.86. With `CRBRO_SEMANTIC=0`, or without the runtime, no vectors are read and no model is loaded: recall is the keyword engine byte for byte.
 
-The model is `multilingual-e5-small` and stays so on purpose. `CRBRO_SEMANTIC_MODEL` accepts any e5-family model, and `e5-base` and `e5-large` were measured on the same benchmark: the large one is the better model alone (71% vs 63% recall@1) but fused with the keyword engine it scores the same or worse (75% / 85% vs 79% / 83%) for 4× the disk, 1.2 GB of RAM and 6× the time per line. The table is in [`benchmarks/README.md`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/README.md).
+The model is `multilingual-e5-small` and stays so on purpose. `CRBRO_SEMANTIC_MODEL` accepts any e5-family model, and `e5-base` and `e5-large` were measured on the same benchmark: the large one is the better model alone (71% vs 63% recall@1) but fused with the keyword engine it scored the same or worse when measured in 1.16 (75% / 85% vs 79% / 83%) for 4× the disk, 1.2 GB of RAM and 6× the time per line. The table is in [`benchmarks/README.md`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/README.md).
 
 What it buys on the frozen benchmark, and what it does not, is in the table above and in [`benchmarks/README.md`](https://github.com/Octonove/crbro-memory/blob/master/benchmarks/README.md) — including the fact that the 0.84 cosine floor was chosen on that same set. One limit worth knowing before you install 500 MB: the model does not understand the question. Queries that share no concrete word with the stored line ("which machine serves the pages" for a fact about a Hetzner VPS) land in a flat 0.80–0.84 cosine band with near-random ordering — measured, and the reason the floor exists. What it adds is tolerance to vocabulary variation and to entities, which is where the benchmark gain comes from.
 
@@ -507,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.