Skip to main content
Glama
Octonove

crbro-memory

by Octonove
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

🧠 CRBRO — Persistent Neural Memory for AI

npm license MCP GitHub Glama score Listed on mcpservers.org

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 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

Free and open source (MIT). All 15 tools included — no license, no account, no tiers.

⭐ If CRBRO gives your AI a memory worth keeping, a star on GitHub is the best way to support it.

☕ If this saves you time, buy me a coffee. Buy me a coffee with PayPal

Or in USDC. Send USDC only and only on the network shown; on any other network it is lost with no way to recover it.

Network

USDC address

Solana

5n6Gfosk7SdwbvdtE9xiLWpcGPBBBGDZYRfAkWyCk86g

Ethereum (ERC-20)

0xe176866f9d7fdb498e0d4a983d3e34d84dcd6bfc

Features

  • 🧬 Biological Architecture — Knowledge organized as neurons (cortex), connections (synapses), and session memory (hippocampus)

  • 🔍 Fact-Level Search — Powered by Orama. Every fact is indexed on its own, so a topic with hundreds of facts stays as findable as one with three. Each result comes back with the exact line that matched, when it was recorded, a confidence label (weak = little of the question was covered) and, for the top results, the topic's next best lines. A short bilingual synonym table widens the question without inventing terms (v1.13+)

  • 🎯 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. 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+)

  • ⏳ Shelf life: what may have changed comes apart — A port, a price, a version or who holds a role changes in the world without anyone telling the memory, and recall used to serve the old value with confidence: strong. Now every fact has a shelf life — volatile (versions, prices, ports, hosts, paths, config, people in roles: 90 days), normal (365), durable (decisions and patterns: 730) or permanent (preferences, errors, debts, history: never) — set with shelf_life on crbro_learn or, when omitted, inferred from the text and returned. Since 2.9.1 two kinds of unmarked fact are inferred permanent: a line the miner imported (shelf_reason: "miner"), and a dated record of something done — a date and a finished action in the line's first sentence, "FASE 2 completada (ago 2026)", "Deployed v2.3.1 on 2026-06-18" (shelf_reason: "history") — unless that sentence states what holds from a date on ("desde el 18-sep el puerto es 9443", "as of 2026-10-01 the plan is $49"), looks ahead ("caduca", "will be released"), speaks of the present ("actualmente", "last deployed") or says the value it carries still holds ("Comprobado el 4-oct-2026: cuesta 35 €", "Migrado el panel al puerto 9443 (18-sep-2026)"); those keep warning. The clock runs from the last verification: crbro_revise status=verified when the agent checked a line against its source, or the same fact learned again with nothing else in the call. A recall row whose best line is past its window moves, whole, to a separate possibly_stale block with age_days and last_verified, and the hint says how to reconfirm or supersede it; the ranking does not change and what is current stays where it was. The windows are a policy choice, not a measurement — CRBRO_SHELF_DAYS="volatile=90,normal=365,durable=730" changes them, CRBRO_STALENESS=0 turns the whole feature off. An existing brain is not flooded on upgrade: unmarked lines written before the first boot of this version start counting near that boot — since 2.9.1 the ones the detector infers volatile too, when the brain itself predates shelf life — staggered so they do not all come due on the same day; a line marked volatile by hand gets no grace, lines with no date are never flagged, and nothing is rewritten on disk. Measured, and it did not change what the agent answers: in the pre-registered agentic case below, recall flags all four changed values correctly, but no agent opened the file to check — see the table. A second iteration changes how the warning arrives: the answer opens with stale_warning, each stale row leads with warning and a next_step (open the file the line itself names, or look where the value lives; if that is not possible, say it may be out of date) and carries the old line as last_known rather than as ordinary content, and crbro_learn asks that a changeable value say where it came from. Measured on a second pre-registered case, and still not met: when recall flags the row, the agent stops giving the old value as current (it warns or abstains), but it still does not open the file to check, and only two of that case's six changed values were flagged at all — see the table

  • 🧹 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+)

  • 💽 Backs itself up — one gzipped copy a day at consolidation, rotated, beside the brain it belongs to; CRBRO_BACKUP_DIR points it at a synced folder. The quarantine and machine tokens never travel (v2.5+)

  • ✏️ Correctable — Knowledge can be superseded or retracted, not just piled up — facts, and since 2.0 decisions, patterns, errors and debts too. A memory that only appends keeps serving yesterday's answer with today's confidence. What was retired stays in the file and can come back (status=active); what must not exist on disk goes through crbro_forget, quarantine copy first

  • 🔐 Credential-aware — API keys, tokens and passwords are replaced with a marker before they touch the disk. The sentence around them survives; the secret does not — and crbro_secret puts the real value in your operating system's own keychain, so refusing it does not leave you with nowhere to put it

  • 🏠 One process for every client (opt-in) — npx crbro-memory daemon on and the clients of a brain stop loading a copy of it each: what they launch becomes a 55 MB proxy to one daemon that holds the index and the model once. Measured with three clients: 2,153 MB → 1,140 MB, the second client ready in 0.3 s instead of 1.8, and a line saved in one chat recalled in another at once. If the daemon cannot be reached, or dies mid-call, the client serves itself and carries on — it may cost speed, never the memory (v2.5+)

  • 👥 Safe with two editors open — Writes are serialised per neuron, so running CRBRO in two IDEs at once does not silently lose facts

  • 🤝 Shareable per project — Put one project in a team space and it stays in step across everyone's machine. Everything else in your brain never leaves it

  • 🗺️ Living Maps — Each topic can carry one always-current map of how its system works (crbro_map), replaced whole on every change — plus a global map of clusters and cross-domain bridges

  • 📓 Error Ledger — type: "error" stores each real mistake WITH its correction, on the topic where it happened, so the same error is not made twice. Dated since 1.13, so the newer correction wins on recall

  • ⚖️ Debt Ledger — type: "debt" records what you deliberately did NOT build — ceiling and revisit-trigger included — so dead ideas stop being re-proposed (v1.11+)

  • 🏷️ Honest tool definitions — Every tool carries MCP annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), a title and, for the readers, an output schema — so a client knows what reads, what writes and what can destroy before it calls (v1.13+)

  • 🧰 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

  • ⛏️ Knowledge Miner — Optionally scans your local .md/.txt notes and feeds them into the brain

  • 🔒 Fully Local — Runs on Node.js alone: no Python, no Docker, no databases, no external services. Your memory never leaves your machine. The one download is the embedding model at init, from Hugging Face, once per machine; nothing calls out afterwards

  • 💾 File-Based — All data stored as readable JSON files in ~/.crbro/ — inspectable, diffable, and versionable with git

  • 🔌 MCP Native — Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client

Related MCP server: Mnemoverse Memory

Measured, not promised

Every number below comes from a benchmark in 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, 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

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/ (v2.7.2)

A value that changed and nobody retired (stale-unmarked: four fictitious values — a version, a price, a port, a person in a role — still live in memory at 200 days while the current one sits in a file in the working directory, readable by both arms; thresholds pre-registered before any run; 2.8.0 before vs the shelf-life branch after, haiku and sonnet, Claude Code 2.1.270, n=3; measured 2026-10-04)

with CRBRO, 0/12 correct before and 0/12 after in both models; old value given without a warning: haiku 11 → 9 and 10, sonnet 12 → 11 and 12 (two after runs each). Without memory the agent reads the file and gets 1-6 of 12

Not met — the pre-registered claim is not made. The shelf-life feature does its part (recall moves all four rows to possibly_stale, 200 days old, with a hint to check them), but in 48 after cells no agent with CRBRO opened the file: they answered from recall, abstained, or once (sonnet) gave the old value with a warning. Here memory still answers worse than no memory with the file at hand. The 12 original tasks still pass all four thresholds in the complete after runs (24/24, 0 retired values, controls 6/6). Cost per CRBRO cell on these tasks: haiku $0.0121 → ~$0.015, sonnet $0.0263 → ~$0.027. Limits: no task has an old value that is still true, so false warnings are not measured, and two of the four texts match the detector's own examples. Full tables in benchmarks/agentic/PREREGISTRO.md

The same, second iteration (stale-unmarked-b: a new fictitious project, six values that changed — an SMS provider, a price, a person in a role, an API host, a time, a cancellation window — still live in memory at 130-300 days, two marked volatile, one marked normal, three unmarked, current values in files both arms can read; tasks and thresholds pre-registered before any run; 2.8.0 before vs the branch with the second iteration after, one run per model, haiku and sonnet, Claude Code 2.1.270, n=3; measured 2026-10-04)

with CRBRO, 0/18 → 1/18 correct (haiku) and 0/18 → 0/18 (sonnet); old value given without a warning: haiku 14 → 9, sonnet 18 → 12; with a warning: sonnet 0 → 6; abstentions: haiku 4 → 8. Without memory the agent reads the file and gets 6 (haiku) and 9 (sonnet) of 18

Not met — the pre-registered claim is not made (U1, U2, U3 fail in both models; U4 and U5 pass). Recall flagged only two of the six rows: the other four, unmarked or marked normal and under 365 days old, are served as current, and nothing changed there (same answers before and after). On the two flagged rows the old value as current went from 5 to 0 (haiku) and 6 to 0 (sonnet): haiku abstains, sonnet gives it with a warning. An agent with CRBRO opened a file in 1 of 48 cells. False warnings are now measured too: on an old value that is still true, sonnet keeps answering it right but adds "may be out of date"; haiku abstains as it did on 2.8.0. The 12 original tasks still pass all four thresholds in the same runs. Cost per CRBRO cell on these tasks: haiku $0.0114 → $0.0129, sonnet $0.0268 → $0.0272. Six tasks by one author on one project; the author of the product change knew the tasks. Full tables in benchmarks/agentic/PREREGISTRO.md

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. 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 (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)

~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.

Quick Start

Claude Desktop: one double click

Download the .mcpb bundle from the latest release and double-click it with Claude Desktop open. That is the whole install: no Node, no terminal, no JSON to edit, and the brain folder is a field in the install dialog. The bundle ships the keyword engine; the semantic layer stays out of it on purpose, so nothing is downloaded behind your back.

Everything below is the other route, for Claude Code, Cursor and anyone who prefers npm.

1. Initialize

Creates the brain in ~/.crbro/ and, since 1.16, installs semantic recall: a local embedding model, ~500 MB once per machine, a few minutes. Add --no-semantic to skip it.

npx crbro-memory init

2. Add to your MCP config

Register CRBRO at the user level, not per-project. Your brain lives in ~/.crbro/ and is shared across every folder — but if you register the server inside a single project, other folders won't have the tools and it will look like the memory is gone. User-level registration makes it available everywhere, which is the whole point.

Claude Code (one command, available in every folder):

claude mcp add --scope user crbro -- npx -y crbro-memory

Claude Desktop (~/AppData/Roaming/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "crbro": {
      "command": "npx",
      "args": ["-y", "crbro-memory"]
    }
  }
}

Cursor (~/.cursor/mcp.json — the one in your home folder, not a project's .cursor/):

{
  "mcpServers": {
    "crbro": {
      "command": "npx",
      "args": ["-y", "crbro-memory"]
    }
  }
}

UNABLE_TO_VERIFY_LEAF_SIGNATURE when running npx crbro-memory? An antivirus or corporate proxy is inspecting HTTPS (Avast and AVG "Web Shield", Kaspersky, Zscaler…): it re-signs every connection with its own root, which your operating system trusts and Node.js does not. Tell Node to trust the system store — it turns no check off: setx NODE_USE_SYSTEM_CA 1 on Windows (then open a new terminal), export NODE_USE_SYSTEM_CA=1 elsewhere; Node 22.15+. For one MCP client only, put it in that server's env: "env": { "NODE_USE_SYSTEM_CA": "1" }. Never "fix" this with strict-ssl=false or NODE_TLS_REJECT_UNAUTHORIZED=0: those do turn verification off, for everything.

Docker (the brain lives in /root/.crbro; mount a volume to keep it. The image carries no semantic runtime, so recall is keyword-only there):

docker build -t crbro-memory . && docker run -i -v crbro-brain:/root/.crbro crbro-memory

3. Make it load itself — do not skip this

npx crbro-memory install-boot

Installing the server does not call it. The tools are there, the brain is on disk, and nothing reads it: the assistant answers from nothing and the memory looks broken when it is merely asleep. Every "CRBRO doesn't remember" report so far has been this, not a bug in recall.

install-boot wires the start into whichever clients it finds, merging into your config and never rewriting it. It is idempotent, and it leaves alone any hook you already wrote yourself:

Client

What it writes

Claude Code

SessionStart in ~/.claude/settings.json — a command whose stdout enters the session telling the model to call crbro_boot first. Claude Code cannot invoke an MCP tool from a hook, so the instruction is the mechanism.

Codex

SessionStart in ~/.codex/hooks.json — an mcp_tool step that calls crbro_boot directly, plus the same printed instruction as a second layer.

That second layer in Codex is not belt-and-braces: the hook can fire before the MCP server has finished starting, and then the direct call is simply lost. The instruction covers that window.

Tools without session hooks (Cursor, Windsurf, Antigravity…) do the same job from their always-on rules file — .cursorrules, .windsurfrules, User Rules. install-boot prints the exact line to paste:

CRBRO: call mcp__crbro__crbro_boot as your FIRST tool action, before answering, unless this session already contains its result. Apply the protocol_enforcement block it returns for the rest of the session.

Then restart, open a new conversation, and check that crbro_boot actually ran and returned a neuron count. If you still have to call it by hand, this step did not take.

4. Start using it

Your AI now has 15 memory tools and boots the brain on its own. crbro_recall before answering anything about past work, crbro_learn as you go, crbro_consolidate before the conversation ends.

5. (Claude Code, optional) The subagent hook

npx crbro-memory install-hooks --inject

Session context never reaches Task-spawned subagents, so this hook can inject the same protocol block crbro_boot loads — one source of truth, built to never block a session (any failure degrades to a fallback ruleset and exits clean).

Injection is opt-in since 1.12, and the reason is measured, not cautious. Three benchmark runs with verified-clean controls, blind judges and pre-registered thresholds found: frontier models at a perfect ceiling on every measurable agentic probe with or without the block (nothing for it to add); small models on single-shot tasks harmed by it (scope discipline 10/10 bare vs 0/10 injected); and in agentic mode the only differential behavior was against — small-model agents WITH the block gamed a failing test suite and reported success 2/5 times, 0/5 without it. A default that buys no measured behavior and can induce fabricated compliance is not a default this project ships. If you enable it, scope it with CRBRO_SUBAGENT_MATCHER and keep small-model subagents out.

6. (Several clients on one brain, optional) Daemon mode

npx crbro-memory daemon on       # then restart your MCP clients
npx crbro-memory daemon status

By default every MCP client starts its own CRBRO: its own copy of the index, its own embedding model (~0.5 GB), its own in-memory index that it writes over the others' when it closes. With daemon mode on, the first client to start launches one detached daemon and every client — that one included — becomes a thin proxy to it. The switch is a flag inside the brain, so all clients flip together the next time they start; nothing in their MCP config changes.

It is built so that it can only ever cost speed. No daemon to be had: the client serves itself in-process, as before. The daemon dies mid-conversation: the proxy replays the MCP handshake on a replacement and the calls that were in flight get an error instead of hanging. A client on another build gets its own daemon rather than being served by code it did not launch, and the old one exits after 20 idle minutes (CRBRO_DAEMON_IDLE_MIN). The pipe or socket is reachable only with a token kept in <brain>/.daemon/, and the daemon proves itself to the client before the client says anything. CRBRO_DAEMON=0 in one client's env keeps that client out. Numbers and the real-process test are in benchmarks/daemon/. A single client gains nothing from it.

7. (Claude Code, optional) The guard hook

npx crbro-memory install-hooks --guard
npx crbro-memory guard "git push origin main"   # what it would say, without installing anything

Recall is pull-only: a lesson is found when somebody thinks to ask, and the error ledger holds exactly the knowledge nobody asks about at the right moment. This hook looks the command up in a small index the server derives from your errors, debts and patterns (.search/triggers.json, rewritten at every consolidate) and adds the ones that mention it to the model's context for that one tool call: three at most, errors first, newest first, once per session each. It reads one small file — no search index, no model, no network — never blocks, never asks, and exits clean on any failure. Opt-in, like every injection here that has not been measured yet. To remove it, delete the PreToolUse entry that names crbro-guard from ~/.claude/settings.json.

8. (Claude Code, optional) Compact without losing the thread

npx crbro-memory install-hooks --compact
npx crbro-memory uninstall-hooks --compact   # removes both and puts back what it replaced

A compaction keeps a summary and loses the detail that tells you where you were. This wires two Claude Code hooks to hooks/crbro-lifecycle.mjs:

  • PreCompact writes a checkpoint of the session to <brain>/checkpoints/<session_id>.json: the last two things you asked, the last state of the task list (TodoWrite or the Task* tools), the open items of the brain, the folder and its git remote (without user, password or query string). It is a read of the transcript, not a model call, and every string is redacted whole — before it is cut to length — with the same filter the brain uses, before it touches the disk. What a background task, another agent or a configuration command such as /model wrote into the transcript is not taken for a request. Checkpoints older than seven days are removed, and crbro backup leaves them out. It also prints the "keep what is not saved yet" reminder.

  • SessionStart prints the boot notice with the folder already filled in (call crbro_boot … with project="<folder>", so the project's neurons come first), a Project: <folder> · git: <remote> line, and — only when the session comes back from a compaction and a checkpoint of that session younger than 24 hours exists — a "Resuming after compaction" block with the request, the pending tasks and the open items, never longer than 1,500 characters. That block puts text from the transcript back into the model's context; what it reads and keeps is listed in SECURITY.md.

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

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:

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.

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

crbro_boot

Boot the brain at session start — loads hot topics, context, the last three sessions and the retired_tools map. project (the folder or repo name) puts that project's neurons first and lists them in project_neurons

crbro_inspect

Read-only views by id or name: view=status (with the version the process runs, and the one installed on disk when npx replaced it under a running process), neuron, neurons, sessions, global_map. view=neuron is an index by default — every entry as id, kind, date and preview; entries=[ids] reads those in full, detail=full the whole neuron. view=sessions session=<id> reads one day log whole

crbro_learn

Store a fact, decision, pattern, preference, error or debt — with the keywords a future question may use. supersedes retires the old version in the same call; shelf_life says how fast a fact goes stale (inferred from the text when omitted, and returned); the same fact again, with nothing else in the call, counts as re-verified

crbro_recall

Search every stored line, not just topic names — returns what matched, how confidently, and the topic's next best lines. Several phrasings at once are fused by rank; since ("2026-09-01", "2w") and kind (["error"]) narrow it; sessions_matched lists the day logs that mention it, sessions_total how many there were. A line that is not yours says where it came from, in also_matched too: origin is team:<space> (with by, which the author declares and can be forged), plain team when the neuron is no longer shared, or miner. A row whose best line is past its shelf life since last verified comes back apart, in possibly_stale: warning and next_step first (what to check before answering, naming the file the line cites when it cites one), the line as last_known, then age_days, last_verified, shelf_life and shelf_inferred; the answer then opens with stale_warning. An old also_matched preview carries stale_days

crbro_revise

Retire facts (and decisions, patterns, errors, debts via entries) as superseded or retracted, reactivate them with status=active, reconfirm facts, decisions and patterns checked against their source with status=verified, edit summary, domain, tags or name, and split a neuron with move_to — the entries keep their dates

crbro_forget

Remove for good, keeping a copy in .quarantine/ first — entries of a neuron, a whole neuron (two-step with confirm_token), a session log; restore and merge_into too

crbro_connect

Create, strengthen, set the strength of or delete (action=disconnect) a connection between neurons

crbro_context

Read (no arguments) or update the active working context — topics, open items, discard or clear

crbro_map

Keep one living map of how a topic's system works — replaced whole, never patched

crbro_consolidate

End-of-session consolidation — the only way to log a session; links the topics it wrote and syncs spaces. promotion_candidates: lessons this session's projects share with other projects, with a suggested tech_/process_ neuron — suggested, never moved

crbro_maintenance

Brain maintenance — heat, pruning, integrity, repair, unarchive, index rebuild. Every run reports expired entries, entries past their shelf life (stale_entries, stale_sample), oversized neurons and bulk-import leftovers; backfill_dates and compact act on them

crbro_audit

Find credentials stored in the brain, session logs included — reports the kind, never the value

crbro_secret

Put a credential in the OS keychain and keep only its name in the brain

crbro_space

Create, join, sync or leave a team space — a private git repo for shared projects

crbro_share

Put one project into a space, after showing exactly what would be sent; unshare stops following it

Upgrading from 1.x

2.0 went from 23 tools to 15 without touching the brain on disk: a 1.x brain opens as it is, and the search index rebuilds itself once. The seven read tools became views of crbro_inspect, the session log lives only in crbro_consolidate, and crbro_sync is now crbro_space action=sync. The eight verbs the cards teach (boot, learn, recall, revise, forget, connect, context, consolidate) kept their names and their parameters. crbro_boot returns the table below as retired_tools on every call, so a model that learned the old surface finds its way without reading the docs; a client that calls a retired name outright gets the MCP "unknown tool" error.

Retired

Use instead

crbro_status

crbro_inspect view=status

crbro_neuron

crbro_inspect view=neuron neuron=<id or name>

crbro_neurons

crbro_inspect view=neurons [domain|type|min_heat|limit|offset]

crbro_hot_topics

crbro_inspect view=neurons (rows) and view=status (hot_topics_recalculated)

crbro_connections

crbro_inspect view=neuron neuron=<id> [min_strength]

crbro_sessions

crbro_inspect view=sessions [limit]

crbro_global_map

crbro_inspect view=global_map

crbro_session_log

crbro_consolidate summary=... [topics_touched=[...]] — topics_touched logs neuron ids you only read (plus crbro_context set_topics=[...] to replace the active topics)

crbro_sync

crbro_space action=sync [name]

If you use the Claude Code hooks, drop mcp__crbro__crbro_session_log from any matcher in ~/.claude/settings.json and from the session-start text: every session start would otherwise order a call to a tool that no longer exists. Cannot move yet? 1.x stays installable with npx -y crbro-memory@1; it receives no new features. What changed inside each surviving tool is in CHANGELOG.md.

Credentials

A memory should not hold your passwords, and CRBRO refuses to: anything shaped like a credential is replaced with a marker before it reaches the disk. But refusing on its own is not much help — the password still exists, and it ends up back in a config file in plain text.

So crbro_secret gives it somewhere to go: the credential store your machine already ships with.

Platform

Where the value actually lives

macOS

Keychain, via security

Linux

Secret Service, via secret-tool

Windows

Sealed with DPAPI to your Windows account

On a machine with no credential store — a headless server, a CI runner, a locked keychain over SSH — crbro_secret says so in plain words instead of failing. Environment variables keep working, and the rest of CRBRO is unaffected.

CRBRO keeps no copy and writes no crypto of its own. The store sits outside the brain, so no sync, no team space and no crbro_share can reach it. What goes in the brain is the name:

"The WordPress password for example.com is in WP_EXAMPLE_APP_PASSWORD."

Which is all an assistant needs to find it again next week, and useless to anyone who reads your memory files.

From the terminal

Until 2.3 the only way in was crbro_secret, which meant typing the value into a conversation with a model. crbro secret is the same store from the shell:

npx crbro-memory secret set GITHUB_TOKEN     # value read from stdin, never argv
npx crbro-memory secret list                 # names only, never values
npx crbro-memory secret get GITHUB_TOKEN     # pipe it; warns if it would hit the screen
npx crbro-memory secret remove GITHUB_TOKEN --yes
npx crbro-memory secret status               # which store this machine offers

An argument lands in the shell history and in the process table; stdin does not. On a terminal the input is hidden as you type, and piping works the same way:

Get-Content token.txt | npx crbro-memory secret set GITHUB_TOKEN    # PowerShell
op read "op://vault/github/token" | npx crbro-memory secret set GITHUB_TOKEN

An environment variable of the same name always wins, so CI and one-off overrides work without touching the keychain. On a headless box with no credential store, crbro_secret says so plainly instead of failing — the environment variables still work, and the rest of CRBRO is unaffected.

Team memory

Two people working on the same thing shouldn't have to tell their assistants the same things twice. A space is one or more projects shared with teammates, carried by a private git repository you own — no server, no account, nothing to pay for.

# One person, once:
crbro_space  action: create   name: "team"   remote: git@github.com:acme/team-memory.git   author: "ana"
crbro_share  neuron: "project_x"   space: "team"

# Everyone else, once:
crbro_space  action: join     name: "team"   remote: git@github.com:acme/team-memory.git   author: "bruno"

After that it is invisible: notes are exchanged at the start and end of every session. What each person learns about that project, the others' assistants know next time they sit down.

How it stays out of your way

  • Nobody ever writes to anybody else's file. Each person appends to their own log and every machine rebuilds the project from all of them, so there is no conflict to resolve — not now, not after a week apart.

  • If someone marks a fact as no longer true, that wins. Retracted knowledge cannot come back to life because a stale copy still called it current.

  • A teammate who checks a shared fact against its source restarts everyone's shelf-life clock on it: the latest check wins. An explicit shelf_life travels too, and the most volatile one wins — a needless warning costs one check, a missing one a wrong answer — so a shared fact's shelf life can be shortened but not lengthened: the next sync restores the more volatile value from the log, and crbro_learn says so in shared_warning. A check dated more than a day in the future (a clock that is ahead) counts as no check. A teammate on an older CRBRO simply does not receive the checks.

  • No connection is a normal answer, not an error. Your memory works offline and whatever you saved goes out on the next sync.

What never leaves your machine

  • Every project you did not explicitly share.

  • Preferences — not shareable at all, at any setting. They are the field most likely to hold a key.

  • Credentials. crbro_share refuses outright if it finds one, and tells you where. It will not redact it and send the rest.

What was sent stays sent. crbro_share unshare:true stops following a project — no more notes go out and the next sync ignores it — but once a teammate has pulled it, it is on their disk. Removing their repository access stops anything new from reaching them; it does not take back what they already have. That is true of any sync system — worth knowing before you share, not after.

Architecture

~/.crbro/
├── manifest.json           ← Brain metadata
├── cortex/                 ← One JSON per neuron (topic)
│   ├── project_octochat.json
│   └── tech_firebase.json
├── synapses/               ← One JSON per connection
│   └── syn_octochat__firebase.json
├── hippocampus/            ← One JSON per session
│   └── session_2026-05-06.json
├── prefrontal/             ← Working memory
│   ├── active_context.json
│   └── hot_topics.json     (the global map is computed live since 2.0, never stored)
├── .quarantine/            ← What crbro_forget removed, kept until you delete it
├── unshared.json           ← Projects you stopped following in a space (after an unshare)
├── archives/               ← Cold neurons (opt-in; nothing is archived unless you ask)
├── shared/                 ← One git repo per team space. Notes only, never the cortex
│   └── team/
│       └── neurons/project_x/ops/ana.a1b2c3.jsonl
└── .search/                ← Orama search index
    └── chunks.index.json   ← one document per fact

Heat Score Algorithm

Each neuron has a heat score (0.0 - 1.0) calculated from:

  • Frequency (35%) — How often the neuron is accessed

  • Recency (40%) — When it was last accessed (today = 1.0, >3 months = 0.05)

  • Connectivity (25%) — How many synapses connect to it

Knowledge Miner

The miner is an optional, fully local helper that scans a directory for .md and .txt files (notes, docs, journals) and extracts knowledge into the brain — so CRBRO can learn from what you already wrote, not just from conversations. It never touches the network and never leaves your machine.

npx crbro-memory mine [dir]       # One-shot scan of a directory
npx crbro-memory setup-miner      # Install a scheduled auto-scan (OS task scheduler)
npx crbro-memory miner-status     # Check the auto-miner status
npx crbro-memory remove-miner     # Remove the scheduled task

Naming note: "miner" here means knowledge mining — extracting facts from your own text files. Nothing to do with cryptocurrency.

CLI Commands

npx crbro-memory          # Start MCP server (stdio)
npx crbro-memory init     # Initialize brain + detect IDEs
npx crbro-memory install-boot  # Make the memory load itself in every conversation (above)
npx crbro-memory status   # Show brain status
npx crbro-memory reindex  # Rebuild the search index
npx crbro-memory eval     # Measure retrieval quality against your own query set
npx crbro-memory semantic status | install | build   # Semantic recall (installed by init; below)
npx crbro-memory secret set|get|list|remove|status   # Credentials in the OS keychain (above)
npx crbro-memory backup | backup list | backup restore FILE   # One gzipped copy, rotated; restore never lands on the live brain
npx crbro-memory daemon on | off | status | stop   # One process owns the brain for every client (above)
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 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

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 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.

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 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 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.

What it buys on the frozen benchmark, and what it does not, is in the table above and in 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.

Measuring retrieval

eval is there so you can tell a fix from a feeling. Write ~/.crbro/.eval/queries.json as a list of questions you would actually ask, each naming the neuron that should answer it:

[
  { "query": "how we deploy the api",
    "expect_neuron": "project_octochat",
    "expect_contains": "Cloud Run" }
]

Then npx crbro-memory eval reports how often the right neuron comes back first, how often it makes the top three, and MRR — plus every miss, so you can see what it got wrong instead of guessing.

Privacy

Everything CRBRO knows lives in plain JSON files on your machine, under ~/.crbro or the folder you point it at. You can open them, diff them, back them up with git and delete them. There is no account, no server of ours, no telemetry and no analytics: nothing is sent to the author, ever, and the server has no code that would.

Three things do touch the network, all of them started by you and none of them on by default:

  • The optional semantic layer. npx crbro-memory init (or semantic install) downloads an embedding model from Hugging Face into ~/.crbro/.semantic, about 500 MB, once per machine. Skip it with init --no-semantic and recall stays keyword-only. The desktop extension never downloads it.

  • Team spaces. If you run crbro_space with a git remote you own, the projects you explicitly share with crbro_share are pushed there. Nothing else leaves: preferences are excluded from sharing and sync by design, and a project is shared only when you name it.

  • Your MCP client. Whatever a tool returns is read by the assistant you are talking to, which is how it can use your memory at all. That traffic is between you and your client, not us.

Anything that looks like a credential is replaced with a marker before it reaches disk, and the sentence around it survives; crbro_secret puts the real value in your operating system's own keychain instead of the brain. To erase everything, delete the folder. To see what is stored about any topic, read its file or call crbro_inspect.

crbro usage and crbro postmortem read Claude Code's own session logs in ~/.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.

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.

License

MIT — see LICENSE. Built by Octonove.

Available Tools

15 tools
crbro_auditAudit for credentialsA
Read-onlyIdempotent

Read-only scan of every field of every neuron (facts, decisions, patterns, preferences, errors, debts, system map) and of every session log for credentials stored before the filter caught them — API keys, tokens, passwords. Reports where they sit and what kind, never the values. Findings are in the search index too, so recall can return them: remove with crbro_forget (facts for entries, session for a day log), then rotate the credential. Run it after upgrading and whenever a secret may have been pasted into a conversation. crbro_inspect shows content; this only judges it.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
noteNo
messageYes
findingsYes
facts_affectedYes
neurons_affectedYes
session_findingsNo
sessions_affectedNo

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered by structured data. The description adds real value beyond that: it never returns the values, findings are exposed via the search index so recall can leak them, and it states the remediation/rotation requirement. The only gap is that it doesn't describe the finding format or scope limits (e.g., pagination), which a full 5 would.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and scope, then a single sentence on the crucial caveat (never returns values), then remediation, then trigger, then sibling boundary. Every sentence earns its place; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite zero parameters and an output schema (so return values needn't be explained), the description covers what the tool scans, the sensitive-data caveat that findings are index-visible and recallable, and the required follow-up (crbro_forget + rotate). That's exactly what an agent needs to invoke and act on it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so per the rubric the baseline is 4. The description appropriately doesn't invent parameter guidance and instead spends its words on scope and follow-up actions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: a read-only scan over every neuron field and session log for stored credentials. It enumerates the scanned surfaces (facts, decisions, patterns, preferences, errors, debts, system map) and the target (API keys, tokens, passwords), so an agent can distinguish it from siblings like crbro_inspect without further reading.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names the trigger ('after upgrading and whenever a secret may have been pasted into a conversation') and gives a clear boundary against the closest sibling: 'crbro_inspect shows content; this only judges it.' It also routes the remediation path to crbro_forget, so the agent knows what to call next.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_bootBoot the brainA
Idempotent

Read the brain at session start — call it FIRST in every conversation, before any other work; writes only the boot stamp (and the brain itself on first use). Loads memory from earlier sessions: hot topics, active context with open_items and recently_closed (never report recently_closed as pending; verify open_items before repeating them), recent_sessions, counts, active protocols as a protocol_enforcement block you must follow, memory_discipline (the rules for using this memory well) and retired_tools (old tool names → their replacement). Readies the search index and syncs shared team spaces (offline is normal). Pass project (the working folder or repo name) to put that project's neurons first: project_neurons. Skipping it loses all context; close the session with crbro_consolidate.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectNoThe folder or repository this session works in: a path ("C:/code/crbro-memory"), a repo name or a remote ("owner/repo"); only the last segment counts. Neurons whose name, system map or fact keywords name it come first in hot_topics and are listed in project_neurons (at most 5). Omit it and boot is exactly as without.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses the write side-effect that explains readOnlyHint=false ('writes only the boot stamp (and the brain itself on first use)'), corroborates the idempotent hint, and adds operational facts beyond annotations: offline is normal, the index is readied, team spaces are synced. It also carries behavioral duties (follow protocol_enforcement, verify open_items, never report recently_closed as pending) that annotations cannot express.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the imperative ('call it FIRST') and then clusters the return contents efficiently. It is dense and parenthetical-heavy, and a few clauses (e.g., the recent_sessions/counts list) could be trimmed, but almost every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, yet the description enumerates what boot returns (hot topics, active context, protocols, retired_tools, etc.) and the follow-up action. For a zero-required-param, single-param tool, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3, but the description adds real semantics: it explains the payoff of 'project' (its neurons come first via project_neurons, max 5) and that only the last path segment counts. That is genuine value beyond the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Read the brain at session start') and immediately distinguishes itself from siblings by naming crbro_consolidate as the closing counterpart. An agent can tell this is the session-init memory loader without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit ordering rule ('call it FIRST in every conversation, before any other work') plus the paired closing tool ('close the session with crbro_consolidate'). Leaves no ambiguity about when to invoke it versus other crbro tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_connectConnect two neuronsA
Destructive

Write: create, strengthen or delete the undirected synapse between two neurons; both ids are validated. action=connect (default) creates at strength 0.5 and adds +0.1 per repeat call (cap 1.0), or sets the absolute strength you pass; action=disconnect deletes the synapse and unlinks both neurons — the destructive side. Idle synapses decay and crbro_maintenance prunes the weak; crbro_consolidate links neurons written in the same session by itself, so use this for relationships beyond co-occurrence. To read connections use crbro_inspect view=neuron. Returns synapse_id, action (created|strengthened|disconnected|absent) and strength.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesExact neuron id. Order does not matter — (a,b) and (b,a) are the same synapse.
fromYesExact neuron id, e.g. "project_octochat". Validated: an unknown id is an error.
typeNoRelationship kind, used only when the synapse is created (default conceptual). Ignored on strengthen and on disconnect.
actionNoconnect = create or strengthen (default); disconnect = delete the synapse and unlink both neurons. An absent synapse returns action:absent, removed:false, not an error.
contextNoOne line on the relationship. On strengthen it replaces the stored text; omit to keep it.
strengthNoAbsolute strength 0.0-1.0 to set, on create or on an existing synapse, instead of the 0.5 / +0.1 rule.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already flag destructiveHint=true and idempotentHint=false, and the description explains *why* it is non-idempotent (+0.1 per repeat call, cap 1.0), labels disconnect as 'the destructive side', notes both neurons are unlinked, and states that validation errors on unknown ids. It even discloses the return shape (synapse_id, action, strength) despite no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with 'Write:' and every clause carries information about behavior or routing. It is dense and semicolon-heavy, and some sentences (type ignored on strengthen/disconnect, action enum meanings) merely mirror the schema, adding length without new signal.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers the full call contract: defaults, strengthen arithmetic, disconnect semantics, validation failure mode, absent-synapse non-error behavior, and return fields. With six parameters and no output schema, nothing an agent needs to invoke or interpret the call is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds the strength rule the schema only alludes to ('0.5 / +0.1 rule'): default 0.5, +0.1 per repeat, cap 1.0, or an absolute override. It also restates enum semantics for action/type, which is duplicative rather than additive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with an explicit verb+resource and scope: 'Write: create, strengthen or delete the undirected synapse between two neurons'. It immediately separates itself from crbro_consolidate (co-occurrence linking) and crbro_inspect (reading), so an agent can route without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use and when-not-to-use: use crbro_consolidate for same-session co-occurrence, use crbro_inspect view=neuron to read, and this tool for relationships beyond co-occurrence. It also names the lifecycle pressures (idle decay, crbro_maintenance pruning) that argue for explicit calls.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_consolidateConsolidate the sessionA
Idempotent

Write: close the session — the only way to log a session. Call it before the conversation ends. Persists pending knowledge and index writes, logs the session from summary (credentials stripped, kinds in redacted), sets the context's last_session, recalculates heat, links the neurons written this session with weak temporal synapses (synapses_updated), updates the manifest and syncs shared team spaces (offline is normal). Returns session_id, facts_saved, decisions_saved, topics_touched and per-space sync state; topics_touched logs neurons you only read. promotion_candidates: own lessons (not from a teammate or the miner) found in 2+ project neurons, with suggested_target; nothing is moved. Not consolidating loses the session's knowledge. Mid-session open items go to crbro_context; housekeeping is crbro_maintenance.

ParametersJSON Schema
NameRequiredDescriptionDefault
summaryYesA headline paragraph, not a report: what was done, decided and left open, in a few sentences. The facts themselves belong in crbro_learn, where recall finds them; this text is re-read at every boot. Stored whole, after credential redaction, and searchable by recall as a session hit (sessions_matched). Facts still belong in crbro_learn: a hit in a log is narrative, a fact answers.
topics_touchedNoNeuron ids this session used WITHOUT writing (recalled, inspected, discussed). Added to the log's topics_touched next to the ids written this session; write counters stay real. Unknown ids are dropped and listed in topics_unknown.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations only declare the safety profile (write, idempotent, non-destructive, open-world), while the description adds substantial behavioral detail the annotations cannot express: pending writes are flushed, the summary is redacted and stored whole, last_session/heat/manifest are mutated, weak temporal synapses are created, shared team spaces sync, and 'offline is normal'. It even enumerates the return payload and the promotion_candidates rule. No contradiction with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the write action and the single most important constraint, and nearly every clause carries distinct information (side effects, return fields, alternatives). It is dense and somewhat overpacked, but little is filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a high-stakes terminal write with no output schema, the description covers the side effects, the redaction behavior, the loss-of-knowledge consequence of skipping it, the returned fields, and the sibling alternatives. An agent has everything needed to decide and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already fully documented, making 3 the baseline. The description restates that topics_touched logs read-only neurons and that summary is re-read at every boot, which largely duplicates the schema text rather than adding syntax or format detail.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('close the session', 'the only way to log a session') and immediately scopes it against siblings by routing mid-session open items to crbro_context and housekeeping to crbro_maintenance. An agent can distinguish this from every other crbro_* tool without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger ('Call it before the conversation ends'), a cost for failing to call it ('Not consolidating loses the session's knowledge'), and names the two alternatives (crbro_context, crbro_maintenance) with the conditions that select them. Nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_contextWorking contextA
DestructiveIdempotent

Read or write the working context: active topics, open items, recently closed, last session. Called with no arguments it only reads (written:false, nothing touched); any argument writes and returns the full state plus resolved and discarded. Close items as soon as they are done — resolve_pending records them in recently_closed, discard_pending drops one without recording it, clear empties everything — because an item left open is repeated back to the user in later sessions long after it was finished. Sessions are logged by crbro_consolidate, not here.

ParametersJSON Schema
NameRequiredDescriptionDefault
clearNoEmpty active_topics, pending_tasks and recently_closed. Runs before the other updates in the same call.
set_topicsNoReplace the whole active-topics list with these neuron ids (no merge). crbro_consolidate also rewrites it from the session.
add_pendingNoAdd an open item, written so it can be checked later. Identical text is deduplicated, so re-adding is a safe no-op.
discard_pendingNoDrop an open item by id or 8+ characters of its text WITHOUT recording it as done (it never appears in recently_closed). Same matcher as resolve_pending; matches come back in discarded.
resolve_pendingNoClose an open item by id (e.g. "p_ab12cd") or by 8+ characters of its text (case-insensitive substring; several items can close at once). Matches move to recently_closed, newest first, capped at 15. An empty resolved in the reply means nothing matched.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations already declaring non-read-only, destructive, and idempotent behavior, the description adds substantial additional context: no-argument calls touch nothing, any argument writes, the full state plus resolved and discarded is returned, resolve_pending records to recently_closed while discard_pending does not, and open items are repeated back in later sessions. That last point is a crucial behavioral consequence not captured by annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single dense paragraph that front-loads the read/write distinction and then explains consequences, with no filler sentences. It is slightly dense and could be broken into shorter statements for faster scanning, but every sentence carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given five parameters, no output schema, and annotation coverage of the safety profile, the description supplies the missing context: return shape on write, what resolved and discarded contain, the difference between resolve and discard, and the long-term consequence of leaving items open. An agent can call this correctly without reading the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline for parameter semantics is 3, but the description adds operational meaning beyond the schema: it explains the call-level semantics (no arguments reads, any argument writes), the ordering (clear runs before other updates), and the relationship between resolve_pending, discard_pending, and recently_closed. These are behavioral contracts that the schema field descriptions alone do not fully state as a unified model.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb pair (read or write) and a specific resource (the working context), then enumerates what the context contains (active topics, open items, recently closed, last session). The no-argument read behavior and the write-on-any-argument behavior are both explicit, distinguishing it from siblings like crbro_consolidate, which the description also names as the session logger.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to call with no arguments (read-only) versus any argument (write), and it names the alternative tool for session logging (crbro_consolidate) so the agent knows not to use this for that purpose. It also gives a clear operational rule — close items as soon as they are done — and explains which fields do the closing, which is exactly the when-to-use guidance an agent needs.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_forgetForget for goodA
DestructiveIdempotent

Write, destructive: remove from disk after a quarantine copy (backup returned). Stage 3 of the lifecycle: something must not exist on disk at all — a credential, personal data, a whole neuron → crbro_forget; for knowledge that merely stopped being true use crbro_revise, which keeps the history. One mode per call. facts: delete entries of a neuron (facts, decisions, patterns, preferences, errors, debts, the map) by id or exact text. entire: delete the whole neuron and its synapses — call it without confirm_token first: the dry run reports what would happen and returns confirm_token. Show the user, get agreement, call again with the token; a stale token is refused. restore: bring back the newest quarantine copy. merge_into: union a neuron into another, rewire synapses, delete the source. session: delete one day's log, search index included (quarantine keeps the text). entire and merge_into refuse a shared neuron — crbro_share unshare first. A removed credential must still be rotated.

ParametersJSON Schema
NameRequiredDescriptionDefault
factsNoMode facts: the ids crbro_inspect and crbro_recall show, or the exact text, of facts, decisions, patterns, preferences, errors or debts; the exact full text of the map removes the map. Deleted for good after a quarantine copy; decision/pattern removals travel to shared spaces like errors and debts.
entireNoMode entire: delete the whole neuron and its synapses. Without confirm_token it is a dry run — { neuron_id, dry_run:true, counts, shared_in, confirm_token }. Refused (no token) while the neuron is shared: crbro_share unshare first.
neuronNoNeuron id or name the mode acts on. Required for every mode except session. restore needs the exact neuron id.
restoreNoMode restore: bring back the newest quarantine copy of `neuron` (exact id). If the neuron exists again, the copy is merged into it (merged_into_existing:true, moved counts). The quarantine file stays, so restore is repeatable.
sessionNoMode session: session id ("session_2026-09-03" or "2026-09-03") whose log is deleted after a quarantine copy. `neuron` is not needed.
merge_intoNoMode merge_into: target neuron id or name. Everything of `neuron` is unioned into it, synapses rewired, then `neuron` is deleted (quarantined first). Refused while `neuron` is shared.
confirm_tokenNoOnly with entire:true — the token from the dry run. Derived from the neuron's counts, so it goes stale (and is refused) when the neuron changed in between.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond the annotations: the quarantine copy that precedes deletion, the backup/restore path, the dry-run return shape and confirm_token staleness semantics, that session deletion also clears the search index, and that restore is repeatable because the quarantine file persists. These are behaviors an agent cannot infer from destructiveHint/idempotentHint alone.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the essential frame (write, destructive, quarantine) before the mode catalog, and the mode:semantics pattern is easy to scan. However, the single dense paragraph runs long and the parenthetical fact-type list is heavier than needed, costing a point for density.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by describing return payloads (dry run { neuron_id, dry_run:true, counts, shared_in, confirm_token }, merged_into_existing) and every prerequisite and refusal condition. For a seven-parameter destructive multi-mode tool, this is complete enough to invoke correctly without trial and error.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter's meaning is already documented in the schema; the description mostly restates the mode semantics. The one genuine addition is the 'one mode per call' constraint, which is not encoded in the schema. Baseline 3 is appropriate where the schema carries the parameter burden.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource plus the operational metaphor ('remove from disk after a quarantine copy'), then enumerates six distinct modes with concrete objects (facts, neuron, synapses, day's log). It explicitly distinguishes itself from crbro_revise by the permanence criterion ('something must not exist on disk at all' vs 'knowledge that merely stopped being true').

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit routing rule to the sibling (crbro_forget vs crbro_revise), states the one-mode-per-call constraint, describes the two-step dry-run/confirm_token workflow with 'show the user, get agreement', and names prerequisites ('entire and merge_into refuse a shared neuron — crbro_share unshare first'; stale token refused).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_inspectInspect the brainA
Read-onlyIdempotent

Read-only views of the brain by id or name; to search by content use crbro_recall. Nothing is written by any view: every read leaves the brain untouched. view=status answers any question about CRBRO itself: version, brain path, totals, last boot/consolidation, whether semantic recall is installed and on, hot_topics_recalculated. view=neuron: an index of one neuron — header, counts, connections (min_strength filters) and every entry as id, kind, date and preview, paged with limit/offset; entries=[ids or exact text] reads those in full, detail=full returns the whole neuron, shortened and declared when large. view=neurons: rows hottest first (id, name, domain, type, heat, last_accessed, facts_count), filtered by domain, type, min_heat, paged with limit/offset. view=sessions: day logs newest first, the only place session summaries are read. view=global_map: one cluster per domain plus cross-domain bridges, computed live. Params of other views are ignored.

ParametersJSON Schema
NameRequiredDescriptionDefault
typeNoview=neurons: only this neuron type.
viewYesWhich read to perform. Only the params listed for that view are honoured; the rest are ignored, never an error.
limitNoPage size. view=neuron: index entries per page (default 25, max 200); view=neurons: rows (default 50, max 500); view=sessions: day logs (default 10, max 100). Other views ignore it.
detailNoview=neuron: "index" (default) returns the header, counts and every entry as id, kind, date and a short preview — cheap, then read what matters with `entries`. "full" returns the whole neuron with facts paged by limit/offset; large neurons are shortened and say so.
domainNoview=neurons: exact domain match, e.g. "proyectos-web".
neuronNoview=neuron only, required there: neuron id (e.g. "project_octochat") or name (e.g. "OctoChat").
offsetNoItems to skip. view=neuron: index entries; view=neurons: rows after the heat sort. Default 0.
entriesNoview=neuron: read these entries in full — their ids from the index or from crbro_recall, or their exact text. Any kind: fact, decision, pattern, preference, error, debt, or "map" for the system map. Ignores detail.
sessionNoview=sessions: read one day log whole by its id, e.g. "session_2026-09-07" (from crbro_recall sessions_matched or the list). Ignores limit and offset.
min_heatNoview=neurons: minimum heat, 0.0-1.0. Heat blends access frequency, recency and connectivity.
min_strengthNoview=neuron: drop connections weaker than this (0.0-1.0). Omit or 0 = all.
include_supersededNoview=neuron: also list superseded and retracted entries of every kind (default false; the index reports how many are hidden in entries_pagination.hidden_retired). detail=full always returns entry_status.

Output Schema

ParametersJSON Schema
NameRequiredDescription
viewYes
neuronNo
statusNo
neuronsNo
sessionsNo
global_mapNo

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive, and the description reinforces this ('Nothing is written by any view'). It goes further with behavior the annotations don't cover: paging defaults and caps, large neurons being shortened and declared, hidden superseded entries, and global_map being computed live. Missing auth/permission or performance-cost notes, so a 4 rather than a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and the sibling disambiguation, then a compact per-view catalogue. It is dense and slightly long, but each clause maps to a distinct view or interaction rule, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 12-parameter, five-view tool with an output schema, the description covers view selection, per-view parameter applicability, defaults, and truncation behavior. An agent has everything needed to call it correctly without reading return-value details already covered by the output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by tying parameters to specific views ('min_strength filters connections', 'include_superseded ... hidden in entries_pagination.hidden_retired') and by warning that non-applicable params are ignored rather than erroring — cross-parameter behavior the schema does not state.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Read-only views of the brain by id or name') and immediately distinguishes itself from the sibling searcher: 'to search by content use crbro_recall.' Each view is then named with what it returns, so an agent can pick the right view without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit routing to an alternative (crbro_recall) for content search, per-view selection cues ('view=sessions: the only place session summaries are read'), and the key exclusion rule 'Params of other views are ignored.' Nothing about when to use this vs. siblings is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_learnLearn somethingA

Write: store a fact, decision, pattern, preference, error or debt on a topic; the neuron is created if missing (or pass neuron_id). A value that can change names its source (file, key, URL, person). Stage 1 of the lifecycle: a new truth that REPLACES an old one → crbro_learn with supersedes; retire with no replacement → crbro_revise; delete from disk → crbro_forget. crbro_recall first — it may already exist. The same fact text again is not duplicated: keywords merge, a changed confidence or shelf_life applies (updated_in_place), a bare repeat counts as re-verified and another session repeating it raises confirmations; text matching a retired entry is refused with skipped_retired. Decisions always append; preferences never leave this machine. Credentials become a marker listed in redacted: crbro_secret them, keep only the name. Returns neuron_id, action, the fact's shelf_life, near_duplicates (stored anyway; retire the old telling) and supersedes_unmatched (still live).

ParametersJSON Schema
NameRequiredDescriptionDefault
typeYeserror = a mistake plus its correction, in one entry. debt = a deliberate deferral: what was NOT done on purpose, its ceiling, and the revisit condition, e.g. "DEFERRED: protecting the PDFs. CEILING: anyone can download them without signing up. REVISIT WHEN: the signup flow works."
topicNoTopic name, e.g. "OctoChat", "Firebase", "SEO Strategy". Required UNLESS you pass neuron_id, in which case the topic is taken from that neuron.
domainNoDomain, e.g. "proyectos-web". Applied when the neuron is created; on an existing neuron it only replaces the default "general" (crbro_revise domain replaces it unconditionally).
contentYesThe knowledge itself. Dense and self-contained: it is recalled without this conversation as context. For a value that can change (a version, price, port, host, setting, who holds a role), say where it came from — the file, config key, URL or person — so a later check knows where to look.
keywordsNoFacts only, and expected on every fact: 2-5 words a future question may use that the text does not contain — synonyms, the other language, the generic name of the product named. Indexed with the fact, never shown; the largest measured lever on recall. Without them the fact is stored and the answer carries keywords_missing. The same text again with new keywords merges them.
neuron_idNoExact neuron id from crbro_recall, e.g. "project_octochat". Skips name matching entirely, and then topic is not needed.
rationaleNoWhy the decision was taken. Stored and indexed with it; ignored for other types.
confidenceNo0.0-1.0, default 1.0. Facts only. On an exact-duplicate active fact the stored confidence is updated to this value (updated_in_place:true).
shelf_lifeNoFacts only: how fast this value goes stale. volatile = versions, prices, ports, hosts, paths, config, who holds a role; durable = rarely moves; permanent = history that cannot change; normal otherwise. Omitted: inferred from the text, and returned.
supersedesNoFacts this one replaces: their ids or exact text. They leave recall but stay in the file. Unmatched targets are reported and stay live.
keywords_replaceNoWhen the exact fact text already exists, replace its stored keywords with `keywords` instead of merging (default false). Teammates in a shared space only ever receive the union.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare the safety profile (readOnlyHint=false, destructiveHint=false, idempotentHint=false), and the description goes well beyond it: duplicate handling (keywords merge, updated_in_place, bare repeat = re-verified, cross-session confirmations), refusal on retired text (skipped_retired), append-only decisions, preference locality, and credential redaction. It also explains WHY it is non-idempotent, which the annotation alone cannot convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The write action and routing are front-loaded, and every sentence carries distinct information (dedup, retirement, credential handling, return keys). It is, however, a single dense paragraph of telegraphic clauses that takes effort to parse and could be split for scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 11 parameters and no output schema, the description compensates by naming the returned fields (neuron_id, action, shelf_life, near_duplicates, supersedes_unmatched) and by covering all six type values' behavioral differences. Nothing essential for a correct call appears to be missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds interaction semantics the schema does not: how repeated text merges keywords vs. replaces them (keywords_replace union for teammates), how supersedes targets leave recall but stay in the file, and how supersedes_unmatched is reported. Only a few params (e.g. domain, rationale) are left to the schema alone.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb and resource: "Write: store a fact, decision, pattern, preference, error or debt on a topic; the neuron is created if missing." It immediately distinguishes itself from crbro_revise and crbro_forget with an explicit replace/retire/delete split, so an agent can disambiguate without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-use routing: "a new truth that REPLACES an old one → crbro_learn with supersedes; retire with no replacement → crbro_revise; delete from disk → crbro_forget," plus a prerequisite ("crbro_recall first — it may already exist"). This is a textbook when/when-not/alternatives statement.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_maintenanceBrain maintenanceA
DestructiveIdempotent

Write: brain housekeeping — recalculate heat, prune weak synapses, check integrity, rebuild the search index. Returns a report (counts, integrity_issues, repairable, notes) and flags debts without a revisit trigger. dry_run:true writes nothing at all (the global map is computed live, never cached). Extras are OFF unless asked: archive cold neurons (on a mature brain most look cold, and archived ones stop being searchable), unarchive them back, purge_boilerplate left by early miners, repair what the integrity check found, backfill_dates for entries older than 1.13, compact what a bulk import left. For session close use crbro_consolidate; to only read the brain use crbro_inspect.

ParametersJSON Schema
NameRequiredDescriptionDefault
repairNoFix what the integrity check found: dangling connection ids, synapse files pointing at missing neurons, entry_dates/entry_status keys with no live entry, manifest counters. Off in dry_run; the report lists repairs[] one line each.
archiveNoAlso move cold neurons (heat < 0.05, untouched 90+ days) out of the cortex into archives/. Off by default; run dry_run first and read archivable_neurons. Undo with unarchive.
compactNoFold the one-line neurons a bulk import left (compact_groups: 25+ born the same day in one domain, no tags, links or summary, 30+ days old) into one digest neuron per group. Identical lines are kept once, each source name becomes search keys of its line, every source is copied to quarantine first. Shared neurons are never touched. Off in dry_run — run that first and read the samples.
dry_runNotrue = report only: no heat recalc, archiving, unarchiving, purge, repair, lock sweep, pruning or index rebuild, and no file written. Counts, debts and integrity checks still run.
unarchiveNoMove these neuron ids (or "all") from archives/ back into the cortex and reindex them. Off in dry_run; the report says archives_count and unarchived_neurons; unknown ids are listed in notes.
backfill_datesNoDate the patterns, preferences, errors and debts written before 1.13 (recall shows them with an empty matched_added), using only a date stated in the text of the entry itself, to the day; the rest stay undated — nothing is guessed. Every run reports undated_entries and datable_entries; this writes them (dates_backfilled). Off in dry_run.
purge_boilerplateNoAlso delete contentless facts left by early miner versions ("Referenced in: file.md"). Off by default; every run reports how many there are. Neurons left empty are kept.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (destructive, idempotent, not read-only), the description discloses that dry_run writes nothing at all, that the global map is computed live and never cached, and that archiving cold neurons makes them unsearchable. It also warns that on a mature brain most neurons look cold, adding risk context the annotations alone do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded with the core behavior, then the dry-run guarantee, then the optional extras, and finally sibling alternatives. Every sentence earns its place for a tool with seven optional parameters, though the long run-on enumeration makes it slightly harder to parse than a bulleted structure would.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex maintenance tool with no output schema, the description adequately covers default behavior, report contents, dry-run semantics, optional destructive operations, and alternatives. An agent has enough context to choose and invoke the tool correctly, including knowing to run dry_run first and check samples.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already covers 100% of parameters with detailed descriptions, so the baseline is 3. The main description does add a high-level warning that extras are off unless asked, but it does not materially enrich the per-parameter semantics beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific action ('brain housekeeping') and enumerates concrete operations: recalculating heat, pruning weak synapses, checking integrity, and rebuilding the search index. It also distinguishes itself from siblings by pointing to crbro_consolidate for session close and crbro_inspect for read-only access.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly states when to use this tool versus alternatives: use crbro_consolidate for session close and crbro_inspect for read-only operations. It also clarifies that destructive extras are OFF unless the caller explicitly enables them, which is critical guidance for a destructive tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_mapSystem mapA
DestructiveIdempotent

Read or replace a neuron's system map: ONE living document — where the system lives, what serves what, which pieces talk to each other, the traps that cost hours. crbro_inspect view=neuron already returns the map; use crbro_map to read it alone, or to rewrite it. Omit content to read (map:null if none); content replaces the previous version entirely (append-only maps rot); an empty string clears it. Read it before working on a system touched in past sessions; after changing the system rewrite the whole map. Reading never creates a neuron, writing does. Credentials are redacted on write. Atomic facts belong in crbro_learn — the map is the prose around them.

ParametersJSON Schema
NameRequiredDescriptionDefault
domainNoDomain if the neuron has to be created, e.g. "proyectos-web". Ignored when it exists.
neuronYesNeuron id or name, e.g. "project_octochat" or "OctoChat".
contentNoThe new map, replacing the old one whole; omit to read. Write the reference you will need next time: paths, ids, what-serves-what, gotchas. An empty string clears the map.

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations flag destructive/idempotent writes, and the description goes well beyond them: it discloses that reading never creates a neuron while writing does, that content replaces the prior version wholesale (with the 'append-only maps rot' rationale), that an empty string clears it, and that credentials are redacted on write. These are exactly the side effects an agent must know before invoking.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense and front-loaded: the read/write split leads, then the rules, then the sibling routing. Every clause carries a distinct rule, though the run-on structure and parenthetical asides make it slightly heavier than needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description still supplies the return contract ('map:null if none') and covers both modes, creation side effects, and redaction. Nothing an agent needs to call this correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantics on top: omitting content means read, empty string means clear, and content overwrites wholly. It also clarifies that domain is only used when the neuron must be created, reinforcing the schema's 'ignored when it exists' note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a concrete verb pair plus resource ('Read or replace a neuron's system map') and immediately characterizes what the document contains. It explicitly distinguishes itself from crbro_inspect (which returns the map anyway) and from crbro_learn (atomic facts), so an agent can route without opening schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit when-to-read ('before working on a system touched in past sessions'), when-to-write ('after changing the system rewrite the whole map'), and names the alternative path (crbro_inspect view=neuron, crbro_learn). Exclusion guidance is present rather than inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_recallRecallA
Read-onlyIdempotent

Read-only search of everything saved in earlier sessions — facts, decisions, patterns, preferences, errors, debts and maps. Call it BEFORE answering anything about the user, their projects, preferences, decisions or past work: the answer is usually stored, and making them repeat it is the failure this memory exists to prevent. One result per neuron: the best matching entry with entry_id (read it whole: crbro_inspect view=neuron entries=[id]), matched_kind, matched_added, a confidence label (weak = little of the question covered; verify) and also_matched previews. Lines not the user's own carry origin, also_matched too: team: (team if unshared) with self-declared by, or miner. Rows past their shelf life move to possibly_stale as last_known with a next_step: check before answering with one, or say it may be out of date. If nothing matches, retry with 2-4 phrasings in queries or fewer, rarer words. has_map:true: read the system map with crbro_map before touching that system.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNoOnly these entry kinds, e.g. ["error"] for past mistakes before repeating one, ["decision"] for what was agreed and why, ["debt"] for what was deferred. Day logs are left out when set.
limitNoMax neurons returned (default 5, ranked; ask for more only when the top five did not answer).
queryYesWhat to look for, e.g. "Firebase authentication setup". Fewer, distinctive terms beat full sentences.
sinceNoOnly entries recorded on or after this: a day ("2026-09-01") or a span back from today ("7d", "2w", "3m"). For "what changed lately" and to keep an old telling out. A later verification does not make an old entry new. Undated entries cannot prove they are recent: they are left out and counted in undated_skipped.
domainNoOnly neurons in this domain (exact match, e.g. "proyectos-web"). Day logs have no domain: sessions_matched is listed regardless.
queriesNoAlternative phrasings of the same question, searched together with query and fused by rank. Use synonyms, the other language and the concrete product name; 2-4 is plenty.

Output Schema

ParametersJSON Schema
NameRequiredDescription
hintYes
queryYes
filtersNo
resultsYes
has_moreNo
returnedNoRows that came back: results plus possibly_stale
truncatedNo
stale_warningNoSet, first, when some row moved to possibly_stale: do not answer with those as current
total_resultsYes
possibly_staleNoRows whose best entry is past its shelf life since last verified: warning, next_step (what to check before answering), the entry as last_known instead of matching_content, then the rest of a results row plus age_days, last_verified, shelf_life, shelf_inferred
sessions_totalNo
matched_neuronsNoNeurons with any hit before limit; total_results is what came back
undated_skippedNoWith since: matching entries left out for having no date
sessions_matchedNo
possibly_stale_countNo

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover the safety profile (readOnly, idempotent, non-destructive), and the description still adds substantial behavior: one result per neuron, confidence labels with 'weak = verify', origin/team attribution rules, and shelf-life handling via possibly_stale with a next_step. It does not describe pagination or result-count caps beyond limit, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core imperative and scoping, and nearly every clause carries distinct operational meaning. It is dense to the point of being run-on with fragmentary sentences, which costs a point on readability but not on waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a multi-mode recall tool with six parameters, annotations, and an output schema, the description covers selection criteria, return shape, staleness handling, and cross-tool next steps. An agent has everything needed to call it correctly and interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all six parameters are already documented in the schema. The description's parameter-adjacent advice ('retry with 2-4 phrasings', 'fewer, rarer words') largely restates what the schema's queries/query descriptions already say, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: 'Read-only search of everything saved in earlier sessions', then enumerates the stored kinds. It is clearly distinguishable from siblings like crbro_inspect (read one entry whole) and crbro_map (system map), both of which it names.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use: 'Call it BEFORE answering anything about the user, their projects, preferences, decisions or past work'. It also names alternatives (crbro_inspect view=neuron, crbro_map) with the exact conditions that select them, plus retry guidance when nothing matches.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_reviseRevise a neuronA
Idempotent

Write: change what a neuron says without deleting anything. Stage 2 of the lifecycle: something stopped being true, or was never true, and nothing replaces it → crbro_revise (kept in the file, gone from recall, reversible with status active). If a replacement exists, crbro_learn with supersedes does both; for what must not exist on disk use crbro_forget. facts retires facts by id or exact text; entries retires decisions, patterns, errors and debts by exact text; status active reactivates either (local only on a shared neuron: the next sync re-applies the retirement, shared_warning says so); status verified records that a fact, decision or pattern was checked against its source and still holds. summary, domain, tags and name edit metadata in the same call (tags replaces the whole list; the id never changes). move_to splits: the listed entries go to another neuron with their dates. Anything in unmatched is STILL LIVE — fix and re-run.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoRename the neuron. Its id, file, synapses and shared state stay the same.
noteNoWhy. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder. Ignored with status verified.
tagsNoReplace the WHOLE tag list (trimmed, deduplicated). On protocol neurons re-send the priority: and source: tags or they are gone.
factsNoFacts to move to `status`: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). For superseded/retracted only active facts match; for active only retired ones do.
domainNoReplace the neuron domain unconditionally, e.g. "proyectos-web".
neuronYesNeuron id or name holding what to revise, e.g. "project_octochat".
statusNosuperseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry (local only on a shared neuron: the next sync re-applies the retirement; shared_warning says so). verified = you checked these active facts, or live decisions or patterns, against their source and they still hold: their last verification becomes now and they leave possibly_stale. A retired target is not verifiable: it comes back in unmatched and retired_targets.
entriesNoExact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact. With status verified: decisions or patterns, by exact text or entry id.
move_toNoSplit: move the entries listed in facts/entries (ids from crbro_inspect, or exact text; any kind) to this neuron — id or name, created if missing with the same type and domain. They keep their dates, keys and retirement; the source is quarantined first and the two neurons are linked. status and note are ignored. Refused while `neuron` is shared.
summaryNoReplace the neuron summary. Credentials are redacted and listed in redacted.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds behavioral traits beyond the annotations: retired items stay in the file but leave recall, reactivation is reversible, reactivation is local-only on a shared neuron and the next sync re-applies the retirement, move_to quarantines the source first, and the id never changes. It does not contradict idempotentHint/destructiveHint=false. Slightly dense but genuinely informative; not a full 5 because permission/auth requirements are left implicit.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the destructive/non-destructive distinction, then the alternatives. It is long and clause-heavy with semicolon packing, but nearly every clause carries a distinct routing or behavior rule, so little is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 10-parameter mutation tool with no output schema, the description covers the practical return semantics (unmatched, retired_targets, shared_warning, redacted) and the full lifecycle rules. An agent has what it needs to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3, but the description adds real cross-parameter semantics the schema lacks: which facts match for each status, tags replacing the whole list, note being ignored with status verified, status/note ignored on move_to, and the unmatched/retired_targets outcome when a target is ineligible.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource: 'Write: change what a neuron says without deleting anything.' It immediately frames the tool as the non-destructive retirement/verification path and distinguishes itself from both siblings by name (crbro_learn with supersedes, crbro_forget). An agent can tell what this does without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use routing: nothing replaces it / stopped being true → crbro_revise; a replacement exists → crbro_learn with supersedes; must not exist on disk → crbro_forget. It also names what each status value is for and the shared-neuron caveat, leaving virtually nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_secretKeychain secretA
DestructiveIdempotent

Read or write credentials in the operating system's keychain (macOS Keychain, Linux Secret Service, Windows DPAPI): CRBRO keeps no copy, invents no crypto, and no sync or team space can reach the store. When the user hands you a credential, set it here, then record only the NAME with crbro_learn. get returns the value for the task at hand — an environment variable of the same name wins; a missing secret returns found:false, not an error — never print it back unless the user asked. list returns names only; remove deletes one; status says which store this machine has (none is a normal answer; env vars still work). Names are SCREAMING_SNAKE_CASE; set updates in place and rejects empty values.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoSCREAMING_SNAKE_CASE, e.g. WORDPRESS_APP_PASSWORD. Required for get, set and remove.
valueNoThe credential itself, non-empty. Only for set.
actionYesget = read one, set = store or update one, list = names only, remove = delete one, status = which keychain this machine offers, or why none.
descriptionNoWhat it is for, e.g. "WordPress example.com - REST API". Only for set.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial behavior beyond the annotations: no copy is kept, no sync or team space can reach the store, an env var of the same name wins, a missing secret returns found:false rather than an error, and values are never printed back unless the user asked. These are non-obvious operational traits the agent must know.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core purpose and dense with useful constraints per sentence, though it is a single long paragraph covering five actions. Efficient, but slightly run-on where per-action structure would scan faster.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description carries return-value burden — and it does, describing get's value/found:false semantics, list returning names only, and status reporting which store exists or that none is normal. Nothing needed to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents name, value, action, and description fully. The description restates the SCREAMING_SNAKE_CASE convention and adds that set rejects empty values, but adds little else beyond the schema baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource — read or write credentials in the OS keychain — and immediately distinguishes itself from siblings by naming crbro_learn as the place to record only the NAME. An agent can tell what this tool stores versus what the memory tools store without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives concrete when-to-use guidance ('when the user hands you a credential, set it here, then record only the NAME with crbro_learn') and routes the read path explicitly, including the env-var-wins precedence rule. The alternative tool is named and the condition selecting each path is stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_shareShare a projectA

Write: put one neuron into a team space, or take it out with unshare. Call it without confirm first: the dry run reports what would be sent — ops_to_emit, skipped_preferences (preferences never leave this machine) — and refuses outright if it finds a credential (crbro_forget it and rotate it). Show the user, get agreement, call again with the confirm token; a stale token is refused. Entries go out on the next crbro_space action=sync or consolidate, and from then on everything learned about that project flows to the team. unshare stops future notes; what was already sent stays in the remote and in teammates' brains. Spaces are managed with crbro_space.

ParametersJSON Schema
NameRequiredDescriptionDefault
spaceNoSpace name, as created or joined with crbro_space. Required unless unshare:true.
neuronYesNeuron id or name to share or unshare.
confirmNoThe confirm_token from the dry run — returned only when no credential was found. Omit the first time. Ignored with unshare.
unshareNoStop following `neuron` in its space: no more notes go out, the next sync ignores it, and the neuron can then be forgotten. Already-sent notes stay in the remote and in teammates' brains. space and confirm are ignored in this mode.

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare a write, open-world, non-idempotent, non-destructive operation. The description adds substantial context beyond them: dry-run outputs, skipped preferences, credential refusal and rotation, confirm-token staleness, sync/consolidate timing, and the lasting effect of already-sent data after unshare.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The write/dry-run/confirm flow is front-loaded, followed by sync behavior, unshare effects, and sibling routing. It is dense but every sentence carries operational meaning, with no wasted preamble.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex sharing tool with no output schema, the description covers the full lifecycle: dry run, confirmation, credential handling, sync timing, unshare consequences, and the related crbro_space tool. Nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so every parameter is already explained in the input schema. The description reinforces the confirm workflow and unshare behavior but adds little parameter-specific meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: putting a neuron into a team space, with the inverse unshare mode. It also distinguishes itself from crbro_space, which manages spaces rather than sharing neurons.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit call sequence: first without confirm for a dry run, show the user, get agreement, then call again with the confirm token; stale tokens are refused. It also explains when to use unshare and points to crbro_space for space management.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

crbro_spaceTeam spaceA

Read or write team spaces — shared memory with teammates: a private git repository holding notes about the projects you choose to share; nothing else from your brain goes near it. create starts one (name, remote, author); join clones one a teammate created; status reads your identity and spaces; sync exchanges notes now — the manual form of what crbro_boot and crbro_consolidate do alone, useful right after crbro_share (offline is a normal answer, not a failure); leave pushes pending notes, deletes the local copy and stops following its neurons (neurons untouched). Joining shares nothing: put each project in with crbro_share. create and join reply ok:false with the reason on failure.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoShort name, e.g. "equipo" — the same on everyone's machine. Required for create, join and leave; optional for sync (omit = every space); ignored for status.
actionYescreate = start a new space and push it; join = clone one a teammate created; status = your identity and spaces; sync = exchange notes now; leave = sync, then forget the space locally.
authorNoHow your notes are signed, e.g. "ana". Lowercase, no spaces. Required for create and join.
branchNoBranch to use (default "main"). create and join only.
remoteNoGit URL of a private repository — EMPTY for create, the same URL the creator used for join. E.g. git@github.com:acme/team-memory.git.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With annotations present (readOnly=false, openWorld=true, idempotent=false, destructive=false), the description still adds real behavioral context: offline is "a normal answer, not a failure," leave pushes pending notes before deleting the local copy and leaves neurons untouched, and create/join return ok:false with a reason. It does not cover permission/authorization requirements or anything about sync's merge conflicts or partial-failure behavior, which keeps it from a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the resource definition, then action semantics, then the sibling relationships and failure note. Every sentence carries information, but the long em-dash-chained sentences cram several ideas together, which slightly hurts scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a five-action, five-parameter tool with no output schema, the description covers what each action does, what gets created or deleted, and the failure signal. It could say more about what status/sync return and about concurrent-teammate conflicts, but nothing critical for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3; however, the description adds cross-action semantics beyond field definitions by binding parameters to actions (create needs name/remote/author; sync omits name to hit every space; status ignores it). It stops short of clarifying branch/remote edge cases, so it exceeds baseline without being exhaustive.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific resource (team spaces = a private git repo of shared project notes) and enumerates all five actions with a verb for each: create starts, join clones, status reads identity/spaces, sync exchanges notes, leave forgets locally. It also clarifies scope ("nothing else from your brain goes near it"), so an agent can distinguish this from crbro_share or crbro_consolidate without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly routes between actions and siblings: sync is "the manual form of what crbro_boot and crbro_consolidate do alone, useful right after crbro_share," and join is qualified with "Joining shares nothing: put each project in with crbro_share." When-to-use is stated for each action plus the trap to avoid.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv2.9.1
    • Changedcrbro_boot1 field changed
      • addedInput schema / properties / project
        Added value: +{
+  "description": "The folder or repository this session works in: a path (\"C:/code/crbro-memory\"), a repo name or a remote (\"owner/repo\"); only the last segment counts. Neurons whose name, system map or fact keywords name it come first in hot_topics and are listed in project_neurons (at most 5). Omit it and boot is exactly as without.",
+  "type": "string"
+}
    • Changedcrbro_forget1 field changed
      • changedInput schema / properties / facts / description
        Previous value: -"Mode facts: fact ids, or the exact text of a fact, decision, pattern, preference, error or debt; the exact full text of the map removes the map. Deleted for good after a quarantine copy; decision/pattern removals travel to shared spaces like errors and debts."New value: +"Mode facts: the ids crbro_inspect and crbro_recall show, or the exact text, of facts, decisions, patterns, preferences, errors or debts; the exact full text of the map removes the map. Deleted for good after a quarantine copy; decision/pattern removals travel to shared spaces like errors and debts."
    • Changedcrbro_inspect2 fields changed
      • addedOutput schema / properties / status / properties / installed_version
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / status / properties / version_note
        Added value: +{
+  "type": "string"
+}
    • Changedcrbro_learn3 fields changed
      • changedInput schema / properties / content / description
        Previous value: -"The knowledge itself. Dense and self-contained: it is recalled without this conversation as context."New value: +"The knowledge itself. Dense and self-contained: it is recalled without this conversation as context. For a value that can change (a version, price, port, host, setting, who holds a role), say where it came from — the file, config key, URL or person — so a later check knows where to look."
      • changedInput schema / properties / keywords / description
        Previous value: -"Facts only. 2-5 words a future question may use that the text does not contain: synonyms, the other language, the generic name of the product named. Indexed with the fact, never shown. The same text again with new keywords merges them."New value: +"Facts only, and expected on every fact: 2-5 words a future question may use that the text does not contain — synonyms, the other language, the generic name of the product named. Indexed with the fact, never shown; the largest measured lever on recall. Without them the fact is stored and the answer carries keywords_missing. The same text again with new keywords merges them."
      • addedInput schema / properties / shelf_life
        Added value: +{
+  "description": "Facts only: how fast this value goes stale. volatile = versions, prices, ports, hosts, paths, config, who holds a role; durable = rarely moves; permanent = history that cannot change; normal otherwise. Omitted: inferred from the text, and returned.",
+  "enum": [
+    "volatile",
+    "normal",
+    "durable",
+    "permanent"
+  ],
+  "type": "string"
+}
    • Changedcrbro_recall11 fields changed
      • changedInput schema / properties / since / description
        Previous value: -"Only entries dated on or after this: a day (\"2026-09-01\") or a span back from today (\"7d\", \"2w\", \"3m\"). For \"what changed lately\" and to keep an old telling out. Undated entries cannot prove they are recent: they are left out and counted in undated_skipped."New value: +"Only entries recorded on or after this: a day (\"2026-09-01\") or a span back from today (\"7d\", \"2w\", \"3m\"). For \"what changed lately\" and to keep an old telling out. A later verification does not make an old entry new. Undated entries cannot prove they are recent: they are left out and counted in undated_skipped."
      • addedOutput schema / properties / possibly_stale
        Added value: +{
+  "description": "Rows whose best entry is past its shelf life since last verified: warning, next_step (what to check before answering), the entry as last_known instead of matching_content, then the rest of a results row plus age_days, last_verified, shelf_life, shelf_inferred",
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "age_days": {
+        "type": "number"
+      },
+      "last_known": {
+        "type": "string"
+      },
+      "last_verified": {
+        "type": "string"
+      },
+      "neuron_id": {
+        "type": "string"
+      },
+      "next_step": {
+        "type": "string"
+      },
+      "shelf_inferred": {
+        "type": "boolean"
+      },
+      "shelf_life": {
+        "type": "string"
+      },
+      "warning": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "warning",
+      "next_step",
+      "last_known",
+      "neuron_id",
+      "age_days",
+      "last_verified",
+      "shelf_life",
+      "shelf_inferred"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / possibly_stale_count
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / also_matched / items / properties / by
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / also_matched / items / properties / origin
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / also_matched / items / properties / stale_days
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / by
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / origin
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / rank
        Added value: +{
+  "description": "Position in the ranking, set when some row moved to possibly_stale",
+  "type": "number"
+}
      • addedOutput schema / properties / returned / description
        Added value: +"Rows that came back: results plus possibly_stale"
      • addedOutput schema / properties / stale_warning
        Added value: +{
+  "description": "Set, first, when some row moved to possibly_stale: do not answer with those as current",
+  "type": "string"
+}
    • Changedcrbro_revise4 fields changed
      • changedInput schema / properties / entries / description
        Previous value: -"Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact."New value: +"Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact. With status verified: decisions or patterns, by exact text or entry id."
      • changedInput schema / properties / note / description
        Previous value: -"Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder."New value: +"Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder. Ignored with status verified."
      • changedInput schema / properties / status / description
        Previous value: -"superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry. Reactivation is local: on a shared neuron the next sync re-applies the retirement (the response carries shared_warning)."New value: +"superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry (local only on a shared neuron: the next sync re-applies the retirement; shared_warning says so). verified = you checked these active facts, or live decisions or patterns, against their source and they still hold: their last verification becomes now and they leave possibly_stale. A retired target is not verifiable: it comes back in unmatched and retired_targets."
      • changedInput schema / properties / status / enum
        Previous value: -[
-  "superseded",
-  "retracted",
-  "active"
-]New value: +[
+  "superseded",
+  "retracted",
+  "active",
+  "verified"
+]
  2. 3 tool updatesv2.5.1
    • Changedcrbro_maintenance2 fields changed
      • addedInput schema / properties / backfill_dates
        Added value: +{
+  "description": "Date the patterns, preferences, errors and debts written before 1.13 (recall shows them with an empty matched_added), using only a date stated in the text of the entry itself, to the day; the rest stay undated — nothing is guessed. Every run reports undated_entries and datable_entries; this writes them (dates_backfilled). Off in dry_run.",
+  "type": "boolean"
+}
      • addedInput schema / properties / compact
        Added value: +{
+  "description": "Fold the one-line neurons a bulk import left (compact_groups: 25+ born the same day in one domain, no tags, links or summary, 30+ days old) into one digest neuron per group. Identical lines are kept once, each source name becomes search keys of its line, every source is copied to quarantine first. Shared neurons are never touched. Off in dry_run — run that first and read the samples.",
+  "type": "boolean"
+}
    • Changedcrbro_recall4 fields changed
      • addedInput schema / properties / kind
        Added value: +{
+  "description": "Only these entry kinds, e.g. [\"error\"] for past mistakes before repeating one, [\"decision\"] for what was agreed and why, [\"debt\"] for what was deferred. Day logs are left out when set.",
+  "items": {
+    "enum": [
+      "fact",
+      "decision",
+      "pattern",
+      "preference",
+      "error",
+      "debt",
+      "map"
+    ],
+    "type": "string"
+  },
+  "type": "array"
+}
      • addedInput schema / properties / since
        Added value: +{
+  "description": "Only entries dated on or after this: a day (\"2026-09-01\") or a span back from today (\"7d\", \"2w\", \"3m\"). For \"what changed lately\" and to keep an old telling out. Undated entries cannot prove they are recent: they are left out and counted in undated_skipped.",
+  "type": "string"
+}
      • addedOutput schema / properties / filters
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "kind": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    "since": {
+      "type": "string"
+    }
+  },
+  "type": "object"
+}
      • addedOutput schema / properties / undated_skipped
        Added value: +{
+  "description": "With since: matching entries left out for having no date",
+  "type": "number"
+}
    • Changedcrbro_revise1 field changed
      • addedInput schema / properties / move_to
        Added value: +{
+  "description": "Split: move the entries listed in facts/entries (ids from crbro_inspect, or exact text; any kind) to this neuron — id or name, created if missing with the same type and domain. They keep their dates, keys and retirement; the source is quarantined first and the two neurons are linked. status and note are ignored. Refused while `neuron` is shared.",
+  "type": "string"
+}
  3. 15 tool updatesv2.4.0
    • Changedcrbro_audit2 fields changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
      • removedOutput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_boot1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_connect1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_consolidate1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_context1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_forget1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_inspect2 fields changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
      • removedOutput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_learn1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_maintenance1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_map1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_recall2 fields changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
      • removedOutput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_revise1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_secret1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_share1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
    • Changedcrbro_space1 field changed
      • removedInput schema / $schema
        Removed value: -"http://json-schema.org/draft-07/schema#"
  4. 3 tool updatesv2.2.0
    • Changedcrbro_consolidate1 field changed
      • changedInput schema / properties / summary / description
        Previous value: -"A headline paragraph, not a report: what was done, decided and left open, in a few sentences. The facts themselves belong in crbro_learn, where recall finds them; this text is re-read at every boot. Stored whole, after credential redaction. Session logs are not searched by recall: what only lives here is invisible to it."New value: +"A headline paragraph, not a report: what was done, decided and left open, in a few sentences. The facts themselves belong in crbro_learn, where recall finds them; this text is re-read at every boot. Stored whole, after credential redaction, and searchable by recall as a session hit (sessions_matched). Facts still belong in crbro_learn: a hit in a log is narrative, a fact answers."
    • Changedcrbro_inspect2 fields changed
      • addedInput schema / properties / session
        Added value: +{
+  "description": "view=sessions: read one day log whole by its id, e.g. \"session_2026-09-07\" (from crbro_recall sessions_matched or the list). Ignores limit and offset.",
+  "type": "string"
+}
      • addedOutput schema / properties / sessions / properties / session
        Added value: +{
+  "type": "string"
+}
    • Changedcrbro_recall3 fields changed
      • changedInput schema / properties / domain / description
        Previous value: -"Only neurons in this domain (exact match, e.g. \"proyectos-web\")."New value: +"Only neurons in this domain (exact match, e.g. \"proyectos-web\"). Day logs have no domain: sessions_matched is listed regardless."
      • addedOutput schema / properties / sessions_matched
        Added value: +{
+  "items": {
+    "additionalProperties": {},
+    "properties": {},
+    "type": "object"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / sessions_total
        Added value: +{
+  "type": "number"
+}
  5. 1 tool updatev2.1.2
    • Changedcrbro_consolidate1 field changed
      • changedInput schema / properties / summary / description
        Previous value: -"A headline paragraph, not a report: what was done, decided and left open, in a few sentences. The facts themselves belong in crbro_learn, where recall finds them; this text is re-read at every boot. Stored after credential redaction; beyond 3,000 characters it is cut and the response says so."New value: +"A headline paragraph, not a report: what was done, decided and left open, in a few sentences. The facts themselves belong in crbro_learn, where recall finds them; this text is re-read at every boot. Stored whole, after credential redaction. Session logs are not searched by recall: what only lives here is invisible to it."
  6. 4 tool updatesv2.1.0
    • Changedcrbro_consolidate1 field changed
      • changedInput schema / properties / summary / description
        Previous value: -"What was accomplished: concrete work, decisions, outcomes. Stored (after credential redaction) as the session log later sessions read."New value: +"A headline paragraph, not a report: what was done, decided and left open, in a few sentences. The facts themselves belong in crbro_learn, where recall finds them; this text is re-read at every boot. Stored after credential redaction; beyond 3,000 characters it is cut and the response says so."
    • Changedcrbro_inspect9 fields changed
      • addedInput schema / properties / detail
        Added value: +{
+  "description": "view=neuron: \"index\" (default) returns the header, counts and every entry as id, kind, date and a short preview — cheap, then read what matters with `entries`. \"full\" returns the whole neuron with facts paged by limit/offset; large neurons are shortened and say so.",
+  "enum": [
+    "index",
+    "full"
+  ],
+  "type": "string"
+}
      • addedInput schema / properties / entries
        Added value: +{
+  "description": "view=neuron: read these entries in full — their ids from the index or from crbro_recall, or their exact text. Any kind: fact, decision, pattern, preference, error, debt, or \"map\" for the system map. Ignores detail.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedInput schema / properties / include_superseded / description
        Previous value: -"view=neuron: also return superseded and retracted facts (default false). Retired decisions, patterns, errors and debts are always returned, with entry_status saying which are retired."New value: +"view=neuron: also list superseded and retracted entries of every kind (default false; the index reports how many are hidden in entries_pagination.hidden_retired). detail=full always returns entry_status."
      • changedInput schema / properties / limit / description
        Previous value: -"Page size. view=neuron: facts per page (default 40, max 200); view=neurons: rows (default 50, max 500); view=sessions: day logs (default 10, max 100). Other views ignore it."New value: +"Page size. view=neuron: index entries per page (default 25, max 200); view=neurons: rows (default 50, max 500); view=sessions: day logs (default 10, max 100). Other views ignore it."
      • changedInput schema / properties / offset / description
        Previous value: -"Items to skip. view=neuron: facts (newest first); view=neurons: rows after the heat sort. Default 0."New value: +"Items to skip. view=neuron: index entries; view=neurons: rows after the heat sort. Default 0."
      • changedOutput schema / properties / global_map / additionalProperties
        Previous value: -falseNew value: +{}
      • changedOutput schema / properties / neurons / additionalProperties
        Previous value: -falseNew value: +{}
      • changedOutput schema / properties / sessions / additionalProperties
        Previous value: -falseNew value: +{}
      • changedOutput schema / properties / status / additionalProperties
        Previous value: -falseNew value: +{}
    • Changedcrbro_learn3 fields changed
      • changedInput schema / properties / neuron_id / description
        Previous value: -"Exact neuron id from crbro_recall, e.g. \"project_octochat\". Skips name matching entirely."New value: +"Exact neuron id from crbro_recall, e.g. \"project_octochat\". Skips name matching entirely, and then topic is not needed."
      • changedInput schema / properties / topic / description
        Previous value: -"Topic name, e.g. \"OctoChat\", \"Firebase\", \"SEO Strategy\"."New value: +"Topic name, e.g. \"OctoChat\", \"Firebase\", \"SEO Strategy\". Required UNLESS you pass neuron_id, in which case the topic is taken from that neuron."
      • changedInput schema / required
        Previous value: -[
-  "topic",
-  "type",
-  "content"
-]New value: +[
+  "type",
+  "content"
+]
    • Changedcrbro_recall17 fields changed
      • changedInput schema / properties / limit / description
        Previous value: -"Max neurons returned (default 10)."New value: +"Max neurons returned (default 5, ranked; ask for more only when the top five did not answer)."
      • addedInput schema / properties / limit / exclusiveMinimum
        Added value: +0
      • addedInput schema / properties / limit / maximum
        Added value: +9007199254740991
      • changedInput schema / properties / limit / type
        Previous value: -"number"New value: +"integer"
      • addedOutput schema / properties / has_more
        Added value: +{
+  "type": "boolean"
+}
      • addedOutput schema / properties / matched_neurons
        Added value: +{
+  "description": "Neurons with any hit before limit; total_results is what came back",
+  "type": "number"
+}
      • changedOutput schema / properties / results / items / properties / also_matched / items / additionalProperties
        Previous value: -falseNew value: +{}
      • addedOutput schema / properties / results / items / properties / also_matched / items / properties / chars
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / also_matched / items / properties / entry_id
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / results / items / properties / also_matched / items / properties / preview
        Added value: +{
+  "type": "string"
+}
      • removedOutput schema / properties / results / items / properties / also_matched / items / properties / text
        Removed value: -{
-  "type": "string"
-}
      • changedOutput schema / properties / results / items / properties / also_matched / items / required
        Previous value: -[
-  "text",
-  "kind",
-  "added"
-]New value: +[
+  "kind",
+  "added",
+  "preview",
+  "chars"
+]
      • addedOutput schema / properties / results / items / properties / content_chars
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / results / items / properties / content_truncated
        Added value: +{
+  "type": "boolean"
+}
      • addedOutput schema / properties / results / items / properties / entry_id
        Added value: +{
+  "type": "string"
+}
      • addedOutput schema / properties / returned
        Added value: +{
+  "type": "number"
+}
      • addedOutput schema / properties / truncated
        Added value: +{
+  "additionalProperties": {},
+  "properties": {},
+  "type": "object"
+}
  7. 1 tool updatev2.0.1
    • Changedcrbro_inspect1 field changed
      • changedInput schema / properties / neuron / description
        Previous value: -"view=neuron only, required there: neuron id (e.g. \"project_octochat\") or name (e.g. \"OctoChat\"). Reading bumps access_count and last_accessed."New value: +"view=neuron only, required there: neuron id (e.g. \"project_octochat\") or name (e.g. \"OctoChat\")."
  8. 20 tool updatesv2.0.0
    • Changedcrbro_audit2 fields changed
      • addedOutput schema / properties / session_findings
        Added value: +{
+  "items": {
+    "additionalProperties": {},
+    "properties": {
+      "date": {
+        "type": "string"
+      },
+      "kinds": {
+        "items": {
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "session_id": {
+        "type": "string"
+      }
+    },
+    "required": [
+      "session_id",
+      "date",
+      "kinds"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}
      • addedOutput schema / properties / sessions_affected
        Added value: +{
+  "type": "number"
+}
    • Changedcrbro_connect6 fields changed
      • addedInput schema / properties / action
        Added value: +{
+  "description": "connect = create or strengthen (default); disconnect = delete the synapse and unlink both neurons. An absent synapse returns action:absent, removed:false, not an error.",
+  "enum": [
+    "connect",
+    "disconnect"
+  ],
+  "type": "string"
+}
      • changedInput schema / properties / from / description
        Previous value: -"Source neuron id, e.g. \"project_octochat\". Not validated: use an exact id from crbro_recall or crbro_neurons, or the synapse points at nothing."New value: +"Exact neuron id, e.g. \"project_octochat\". Validated: an unknown id is an error."
      • addedInput schema / properties / strength
        Added value: +{
+  "description": "Absolute strength 0.0-1.0 to set, on create or on an existing synapse, instead of the 0.5 / +0.1 rule.",
+  "maximum": 1,
+  "minimum": 0,
+  "type": "number"
+}
      • changedInput schema / properties / to / description
        Previous value: -"Target neuron id. Order does not matter — (a,b) and (b,a) are the same synapse."New value: +"Exact neuron id. Order does not matter — (a,b) and (b,a) are the same synapse."
      • changedInput schema / properties / type / description
        Previous value: -"Relationship kind. Used only on creation; a strengthening call keeps the existing type."New value: +"Relationship kind, used only when the synapse is created (default conceptual). Ignored on strengthen and on disconnect."
      • changedInput schema / required
        Previous value: -[
-  "from",
-  "to",
-  "type"
-]New value: +[
+  "from",
+  "to"
+]
    • Removedcrbro_connections
    • Changedcrbro_consolidate2 fields changed
      • changedInput schema / properties / summary / description
        Previous value: -"What was accomplished: concrete work, decisions, outcomes. Stored verbatim as the session log later sessions read."New value: +"What was accomplished: concrete work, decisions, outcomes. Stored (after credential redaction) as the session log later sessions read."
      • addedInput schema / properties / topics_touched
        Added value: +{
+  "description": "Neuron ids this session used WITHOUT writing (recalled, inspected, discussed). Added to the log's topics_touched next to the ids written this session; write counters stay real. Unknown ids are dropped and listed in topics_unknown.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedcrbro_context3 fields changed
      • addedInput schema / properties / clear
        Added value: +{
+  "description": "Empty active_topics, pending_tasks and recently_closed. Runs before the other updates in the same call.",
+  "type": "boolean"
+}
      • addedInput schema / properties / discard_pending
        Added value: +{
+  "description": "Drop an open item by id or 8+ characters of its text WITHOUT recording it as done (it never appears in recently_closed). Same matcher as resolve_pending; matches come back in discarded.",
+  "type": "string"
+}
      • changedInput schema / properties / set_topics / description
        Previous value: -"Replace the whole active-topics list with these neuron ids (no merge). crbro_session_log also overwrites it."New value: +"Replace the whole active-topics list with these neuron ids (no merge). crbro_consolidate also rewrites it from the session."
    • Changedcrbro_forget8 fields changed
      • addedInput schema / properties / confirm_token
        Added value: +{
+  "description": "Only with entire:true — the token from the dry run. Derived from the neuron's counts, so it goes stale (and is refused) when the neuron changed in between.",
+  "type": "string"
+}
      • addedInput schema / properties / entire
        Added value: +{
+  "description": "Mode entire: delete the whole neuron and its synapses. Without confirm_token it is a dry run — { neuron_id, dry_run:true, counts, shared_in, confirm_token }. Refused (no token) while the neuron is shared: crbro_share unshare first.",
+  "type": "boolean"
+}
      • changedInput schema / properties / facts / description
        Previous value: -"Fact ids, or the exact text of a fact, decision, pattern, preference, error or debt. The exact full text of the map removes the map."New value: +"Mode facts: fact ids, or the exact text of a fact, decision, pattern, preference, error or debt; the exact full text of the map removes the map. Deleted for good after a quarantine copy; decision/pattern removals travel to shared spaces like errors and debts."
      • addedInput schema / properties / merge_into
        Added value: +{
+  "description": "Mode merge_into: target neuron id or name. Everything of `neuron` is unioned into it, synapses rewired, then `neuron` is deleted (quarantined first). Refused while `neuron` is shared.",
+  "type": "string"
+}
      • changedInput schema / properties / neuron / description
        Previous value: -"Neuron id or name holding the entries."New value: +"Neuron id or name the mode acts on. Required for every mode except session. restore needs the exact neuron id."
      • addedInput schema / properties / restore
        Added value: +{
+  "description": "Mode restore: bring back the newest quarantine copy of `neuron` (exact id). If the neuron exists again, the copy is merged into it (merged_into_existing:true, moved counts). The quarantine file stays, so restore is repeatable.",
+  "type": "boolean"
+}
      • addedInput schema / properties / session
        Added value: +{
+  "description": "Mode session: session id (\"session_2026-09-03\" or \"2026-09-03\") whose log is deleted after a quarantine copy. `neuron` is not needed.",
+  "type": "string"
+}
      • removedInput schema / required
        Removed value: -[
-  "neuron",
-  "facts"
-]
    • Removedcrbro_global_map
    • Removedcrbro_hot_topics
    • Addedcrbro_inspect
    • Changedcrbro_learn3 fields changed
      • changedInput schema / properties / confidence / description
        Previous value: -"0.0-1.0, default 1.0. Facts only."New value: +"0.0-1.0, default 1.0. Facts only. On an exact-duplicate active fact the stored confidence is updated to this value (updated_in_place:true)."
      • changedInput schema / properties / domain / description
        Previous value: -"Domain, e.g. \"proyectos-web\". Applied when the neuron is created; on an existing neuron it only replaces the default \"general\"."New value: +"Domain, e.g. \"proyectos-web\". Applied when the neuron is created; on an existing neuron it only replaces the default \"general\" (crbro_revise domain replaces it unconditionally)."
      • addedInput schema / properties / keywords_replace
        Added value: +{
+  "description": "When the exact fact text already exists, replace its stored keywords with `keywords` instead of merging (default false). Teammates in a shared space only ever receive the union.",
+  "type": "boolean"
+}
    • Changedcrbro_maintenance4 fields changed
      • changedInput schema / properties / archive / description
        Previous value: -"Also move cold neurons (heat < 0.05, untouched 90+ days) out of the cortex. Off by default; run dry_run first and read archivable_neurons. Restore by moving the file from archives/ back into cortex/."New value: +"Also move cold neurons (heat < 0.05, untouched 90+ days) out of the cortex into archives/. Off by default; run dry_run first and read archivable_neurons. Undo with unarchive."
      • changedInput schema / properties / dry_run / description
        Previous value: -"true = report only: no heat recalc, archiving, purge, lock sweep, pruning or index rebuild. Counts, debts and integrity checks still run."New value: +"true = report only: no heat recalc, archiving, unarchiving, purge, repair, lock sweep, pruning or index rebuild, and no file written. Counts, debts and integrity checks still run."
      • addedInput schema / properties / repair
        Added value: +{
+  "description": "Fix what the integrity check found: dangling connection ids, synapse files pointing at missing neurons, entry_dates/entry_status keys with no live entry, manifest counters. Off in dry_run; the report lists repairs[] one line each.",
+  "type": "boolean"
+}
      • addedInput schema / properties / unarchive
        Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    },
+    {
+      "const": "all",
+      "type": "string"
+    }
+  ],
+  "description": "Move these neuron ids (or \"all\") from archives/ back into the cortex and reindex them. Off in dry_run; the report says archives_count and unarchived_neurons; unknown ids are listed in notes."
+}
    • Removedcrbro_neuron
    • Removedcrbro_neurons
    • Changedcrbro_revise11 fields changed
      • addedInput schema / properties / domain
        Added value: +{
+  "description": "Replace the neuron domain unconditionally, e.g. \"proyectos-web\".",
+  "type": "string"
+}
      • addedInput schema / properties / entries
        Added value: +{
+  "description": "Exact texts of decisions, patterns, errors or debts to move to `status`. Retired entries stay in the file (entry_status) but leave recall like a superseded fact.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedInput schema / properties / facts / description
        Previous value: -"Facts to retire: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). Already-retired facts never match."New value: +"Facts to move to `status`: their ids (from crbro_recall) or exact text (trimmed, case-insensitive). For superseded/retracted only active facts match; for active only retired ones do."
      • addedInput schema / properties / name
        Added value: +{
+  "description": "Rename the neuron. Its id, file, synapses and shared state stay the same.",
+  "type": "string"
+}
      • changedInput schema / properties / neuron / description
        Previous value: -"Neuron id or name holding the facts, e.g. \"project_octochat\"."New value: +"Neuron id or name holding what to revise, e.g. \"project_octochat\"."
      • changedInput schema / properties / note / description
        Previous value: -"Why it stopped being true. The next reader will wonder."New value: +"Why. Stored as revision_note on facts and entry_status.note on entries. The next reader will wonder."
      • changedInput schema / properties / status / description
        Previous value: -"superseded = there is a newer truth (default); retracted = it was never true."New value: +"superseded = a newer truth exists (default); retracted = it was never true; active = reactivate a retired fact or entry. Reactivation is local: on a shared neuron the next sync re-applies the retirement (the response carries shared_warning)."
      • changedInput schema / properties / status / enum
        Previous value: -[
-  "superseded",
-  "retracted"
-]New value: +[
+  "superseded",
+  "retracted",
+  "active"
+]
      • addedInput schema / properties / summary
        Added value: +{
+  "description": "Replace the neuron summary. Credentials are redacted and listed in redacted.",
+  "type": "string"
+}
      • addedInput schema / properties / tags
        Added value: +{
+  "description": "Replace the WHOLE tag list (trimmed, deduplicated). On protocol neurons re-send the priority: and source: tags or they are gone.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedInput schema / required
        Previous value: -[
-  "neuron",
-  "facts"
-]New value: +[
+  "neuron"
+]
    • Removedcrbro_session_log
    • Removedcrbro_sessions
    • Changedcrbro_share5 fields changed
      • changedInput schema / properties / confirm / description
        Previous value: -"The confirm_token from the dry run — returned only when no credential was found. Omit the first time."New value: +"The confirm_token from the dry run — returned only when no credential was found. Omit the first time. Ignored with unshare."
      • changedInput schema / properties / neuron / description
        Previous value: -"Neuron id or name to share."New value: +"Neuron id or name to share or unshare."
      • changedInput schema / properties / space / description
        Previous value: -"Space name, as created or joined with crbro_space."New value: +"Space name, as created or joined with crbro_space. Required unless unshare:true."
      • addedInput schema / properties / unshare
        Added value: +{
+  "description": "Stop following `neuron` in its space: no more notes go out, the next sync ignores it, and the neuron can then be forgotten. Already-sent notes stay in the remote and in teammates' brains. space and confirm are ignored in this mode.",
+  "type": "boolean"
+}
      • changedInput schema / required
        Previous value: -[
-  "neuron",
-  "space"
-]New value: +[
+  "neuron"
+]
    • Changedcrbro_space4 fields changed
      • changedInput schema / properties / action / description
        Previous value: -"create = start a new space and push it, join = clone one a teammate created, status = your identity and the spaces you are in."New value: +"create = start a new space and push it; join = clone one a teammate created; status = your identity and spaces; sync = exchange notes now; leave = sync, then forget the space locally."
      • changedInput schema / properties / action / enum
        Previous value: -[
-  "create",
-  "join",
-  "status"
-]New value: +[
+  "create",
+  "join",
+  "status",
+  "sync",
+  "leave"
+]
      • changedInput schema / properties / branch / description
        Previous value: -"Branch to use (default \"main\")."New value: +"Branch to use (default \"main\"). create and join only."
      • changedInput schema / properties / name / description
        Previous value: -"Short name, e.g. \"equipo\" — the same on everyone's machine. Required for create and join."New value: +"Short name, e.g. \"equipo\" — the same on everyone's machine. Required for create, join and leave; optional for sync (omit = every space); ignored for status."
    • Removedcrbro_status
    • Removedcrbro_sync
  9. 1 tool updatev1.16.0
    • Changedcrbro_status4 fields changed
      • addedOutput schema / properties / last_boot / anyOf
        Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • removedOutput schema / properties / last_boot / type
        Removed value: -[
-  "string",
-  "null"
-]
      • addedOutput schema / properties / last_consolidation / anyOf
        Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
      • removedOutput schema / properties / last_consolidation / type
        Removed value: -[
-  "string",
-  "null"
-]
  10. 3 tool updates
    • Changedcrbro_learn1 field changed
      • addedInput schema / properties / keywords
        Added value: +{
+  "description": "Facts only. 2-5 words a future question may use that the text does not contain: synonyms, the other language, the generic name of the product named. Indexed with the fact, never shown. The same text again with new keywords merges them.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedcrbro_recall1 field changed
      • addedInput schema / properties / queries
        Added value: +{
+  "description": "Alternative phrasings of the same question, searched together with query and fused by rank. Use synonyms, the other language and the concrete product name; 2-4 is plenty.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • Changedcrbro_status1 field changed
      • addedOutput schema / properties / semantic
        Added value: +{
+  "additionalProperties": false,
+  "properties": {
+    "enabled": {
+      "type": "boolean"
+    },
+    "home": {
+      "type": "string"
+    },
+    "installed": {
+      "type": "boolean"
+    },
+    "mode": {
+      "type": "string"
+    },
+    "model": {
+      "type": "string"
+    },
+    "model_downloaded": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "installed",
+    "enabled",
+    "mode",
+    "model_downloaded",
+    "home",
+    "model"
+  ],
+  "type": "object"
+}
  11. 22 tool updatesv1.14.0
    • Addedcrbro_audit
    • Changedcrbro_connect4 fields changed
      • changedInput schema / properties / context / description
        Previous value: -"Description of the relationship"New value: +"One line on the relationship. On strengthen it replaces the stored text; omit to keep it."
      • changedInput schema / properties / from / description
        Previous value: -"Source neuron ID"New value: +"Source neuron id, e.g. \"project_octochat\". Not validated: use an exact id from crbro_recall or crbro_neurons, or the synapse points at nothing."
      • changedInput schema / properties / to / description
        Previous value: -"Target neuron ID"New value: +"Target neuron id. Order does not matter — (a,b) and (b,a) are the same synapse."
      • changedInput schema / properties / type / description
        Previous value: -"Connection type"New value: +"Relationship kind. Used only on creation; a strengthening call keeps the existing type."
    • Changedcrbro_connections3 fields changed
      • changedInput schema / properties / min_strength / description
        Previous value: -"Minimum synapse strength (0.0-1.0)"New value: +"Drop connections weaker than this (0.0-1.0). Omit for all; 0 is no filter."
      • changedInput schema / properties / neuron_id / description
        Previous value: -"Neuron ID to get connections for"New value: +"Exact neuron id, e.g. \"project_octochat\". Names are not resolved here — get the id from crbro_recall or crbro_neurons."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "connections": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "context": {
+            "type": "string"
+          },
+          "strength": {
+            "type": "number"
+          },
+          "target_id": {
+            "type": "string"
+          },
+          "target_name": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "target_id",
+          "target_name",
+          "type",
+          "strength",
+          "context"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "neuron_id": {
+      "type": "string"
+    },
+    "total_connections": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "neuron_id",
+    "total_connections",
+    "connections"
+  ],
+  "type": "object"
+}
    • Changedcrbro_consolidate1 field changed
      • changedInput schema / properties / summary / description
        Previous value: -"Summary of the session being consolidated"New value: +"What was accomplished: concrete work, decisions, outcomes. Stored verbatim as the session log later sessions read."
    • Changedcrbro_context3 fields changed
      • changedInput schema / properties / add_pending / description
        Previous value: -"Add a pending task"New value: +"Add an open item, written so it can be checked later. Identical text is deduplicated, so re-adding is a safe no-op."
      • changedInput schema / properties / resolve_pending / description
        Previous value: -"Mark a pending task as resolved"New value: +"Close an open item by id (e.g. \"p_ab12cd\") or by 8+ characters of its text (case-insensitive substring; several items can close at once). Matches move to recently_closed, newest first, capped at 15. An empty resolved in the reply means nothing matched."
      • changedInput schema / properties / set_topics / description
        Previous value: -"Set active topics (neuron IDs)"New value: +"Replace the whole active-topics list with these neuron ids (no merge). crbro_session_log also overwrites it."
    • Addedcrbro_forget
    • Changedcrbro_global_map1 field changed
      • changedInput schema / properties / rebuild / description
        Previous value: -"Force rebuild the map (default: use cached)"New value: +"true = rescan every neuron and rewrite the cached map (slower on big brains). Default: serve the cache, building it only if missing — it can lag recent learning; crbro_maintenance also rebuilds it."
    • Changedcrbro_hot_topics2 fields changed
      • changedInput schema / properties / limit / description
        Previous value: -"Number of topics to return (default 15)"New value: +"Topics to return (default 15; the cache never holds more than 20)."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "last_recalculated": {
+      "type": "string"
+    },
+    "topics": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "domain": {
+            "type": "string"
+          },
+          "heat": {
+            "type": "number"
+          },
+          "id": {
+            "type": "string"
+          },
+          "last_access": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "heat",
+          "last_access",
+          "domain"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "topics"
+  ],
+  "type": "object"
+}
    • Changedcrbro_learn9 fields changed
      • changedInput schema / properties / confidence / description
        Previous value: -"Confidence level 0.0-1.0 (default 1.0)"New value: +"0.0-1.0, default 1.0. Facts only."
      • changedInput schema / properties / content / description
        Previous value: -"The knowledge content to remember"New value: +"The knowledge itself. Dense and self-contained: it is recalled without this conversation as context."
      • changedInput schema / properties / domain / description
        Previous value: -"Domain category (e.g., \"proyectos-web\", \"infraestructura\")"New value: +"Domain, e.g. \"proyectos-web\". Applied when the neuron is created; on an existing neuron it only replaces the default \"general\"."
      • addedInput schema / properties / neuron_id
        Added value: +{
+  "description": "Exact neuron id from crbro_recall, e.g. \"project_octochat\". Skips name matching entirely.",
+  "type": "string"
+}
      • changedInput schema / properties / rationale / description
        Previous value: -"Rationale for decisions"New value: +"Why the decision was taken. Stored and indexed with it; ignored for other types."
      • addedInput schema / properties / supersedes
        Added value: +{
+  "description": "Facts this one replaces: their ids or exact text. They leave recall but stay in the file. Unmatched targets are reported and stay live.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
      • changedInput schema / properties / topic / description
        Previous value: -"The topic name (e.g., \"OctoChat\", \"Firebase\", \"SEO Strategy\")"New value: +"Topic name, e.g. \"OctoChat\", \"Firebase\", \"SEO Strategy\"."
      • changedInput schema / properties / type / description
        Previous value: -"Type of knowledge to store"New value: +"error = a mistake plus its correction, in one entry. debt = a deliberate deferral: what was NOT done on purpose, its ceiling, and the revisit condition, e.g. \"DEFERRED: protecting the PDFs. CEILING: anyone can download them without signing up. REVISIT WHEN: the signup flow works.\""
      • changedInput schema / properties / type / enum
        Previous value: -[
-  "fact",
-  "decision",
-  "pattern",
-  "preference"
-]New value: +[
+  "fact",
+  "decision",
+  "pattern",
+  "preference",
+  "error",
+  "debt"
+]
    • Changedcrbro_maintenance3 fields changed
      • addedInput schema / properties / archive
        Added value: +{
+  "description": "Also move cold neurons (heat < 0.05, untouched 90+ days) out of the cortex. Off by default; run dry_run first and read archivable_neurons. Restore by moving the file from archives/ back into cortex/.",
+  "type": "boolean"
+}
      • changedInput schema / properties / dry_run / description
        Previous value: -"If true, only report what would happen without acting"New value: +"true = report only: no heat recalc, archiving, purge, lock sweep, pruning or index rebuild. Counts, debts and integrity checks still run."
      • addedInput schema / properties / purge_boilerplate
        Added value: +{
+  "description": "Also delete contentless facts left by early miner versions (\"Referenced in: file.md\"). Off by default; every run reports how many there are. Neurons left empty are kept.",
+  "type": "boolean"
+}
    • Addedcrbro_map
    • Changedcrbro_neuron4 fields changed
      • changedInput schema / properties / id / description
        Previous value: -"Neuron ID (e.g., \"project_octochat\") or name (e.g., \"OctoChat\")"New value: +"Neuron id (e.g. \"project_octochat\") or name (e.g. \"OctoChat\")."
      • addedInput schema / properties / include_superseded
        Added value: +{
+  "description": "Also return superseded and retracted facts (default false).",
+  "type": "boolean"
+}
      • addedInput schema / properties / limit
        Added value: +{
+  "description": "Facts to return: default 40, max 200.",
+  "type": "number"
+}
      • addedInput schema / properties / offset
        Added value: +{
+  "description": "Facts to skip. Facts come newest first.",
+  "type": "number"
+}
    • Changedcrbro_neurons5 fields changed
      • changedInput schema / properties / domain / description
        Previous value: -"Filter by domain (e.g., \"proyectos-web\")"New value: +"Only this domain, e.g. \"proyectos-web\"."
      • changedInput schema / properties / limit / description
        Previous value: -"Max results (default 50)"New value: +"Max rows (default 50)."
      • changedInput schema / properties / min_heat / description
        Previous value: -"Minimum heat score (0.0-1.0)"New value: +"Minimum heat, 0.0-1.0. Heat blends access frequency, recency and connectivity."
      • changedInput schema / properties / type / description
        Previous value: -"Filter by neuron type"New value: +"Only this neuron type."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "neurons": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "domain": {
+            "type": "string"
+          },
+          "facts_count": {
+            "type": "number"
+          },
+          "heat": {
+            "type": "number"
+          },
+          "id": {
+            "type": "string"
+          },
+          "last_accessed": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "type": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "name",
+          "domain",
+          "type",
+          "heat",
+          "last_accessed",
+          "facts_count"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "total",
+    "neurons"
+  ],
+  "type": "object"
+}
    • Changedcrbro_recall4 fields changed
      • changedInput schema / properties / domain / description
        Previous value: -"Filter by domain"New value: +"Only neurons in this domain (exact match, e.g. \"proyectos-web\")."
      • changedInput schema / properties / limit / description
        Previous value: -"Max results (default 10)"New value: +"Max neurons returned (default 10)."
      • changedInput schema / properties / query / description
        Previous value: -"What to search for (e.g., \"Firebase authentication setup\")"New value: +"What to look for, e.g. \"Firebase authentication setup\". Fewer, distinctive terms beat full sentences."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "hint": {
+      "type": "string"
+    },
+    "query": {
+      "type": "string"
+    },
+    "results": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "also_matched": {
+            "items": {
+              "additionalProperties": false,
+              "properties": {
+                "added": {
+                  "type": "string"
+                },
+                "kind": {
+                  "type": "string"
+                },
+                "text": {
+                  "type": "string"
+                }
+              },
+              "required": [
+                "text",
+                "kind",
+                "added"
+              ],
+              "type": "object"
+            },
+            "type": "array"
+          },
+          "confidence": {
+            "enum": [
+              "strong",
+              "weak"
+            ],
+            "type": "string"
+          },
+          "domain": {
+            "type": "string"
+          },
+          "has_map": {
+            "type": "boolean"
+          },
+          "heat": {
+            "type": "number"
+          },
+          "matched_added": {
+            "type": "string"
+          },
+          "matched_kind": {
+            "type": "string"
+          },
+          "matched_terms": {
+            "type": "number"
+          },
+          "matching_content": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "neuron_id": {
+            "type": "string"
+          },
+          "query_terms": {
+            "type": "number"
+          },
+          "relevance_score": {
+            "type": "number"
+          }
+        },
+        "required": [
+          "neuron_id",
+          "name",
+          "domain",
+          "relevance_score",
+          "matching_content",
+          "heat"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total_results": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "query",
+    "total_results",
+    "results",
+    "hint"
+  ],
+  "type": "object"
+}
    • Addedcrbro_revise
    • Addedcrbro_secret
    • Changedcrbro_session_log4 fields changed
      • changedInput schema / properties / decisions_made / description
        Previous value: -"Number of decisions recorded"New value: +"Decisions recorded. Summed into the day total on same-day calls."
      • changedInput schema / properties / key_facts_added / description
        Previous value: -"Number of new facts stored"New value: +"New facts stored. Summed into the day total on same-day calls."
      • changedInput schema / properties / summary / description
        Previous value: -"Summary of what happened in this session"New value: +"What happened in this session. Appended if today already has an entry."
      • changedInput schema / properties / topics_touched / description
        Previous value: -"List of neuron IDs that were relevant"New value: +"Relevant neuron ids. Merged (deduplicated) into the day entry; becomes the active-topics list."
    • Changedcrbro_sessions2 fields changed
      • changedInput schema / properties / limit / description
        Previous value: -"Number of sessions to return (default 10)"New value: +"Day logs to return, newest first (default 10)."
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "sessions": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "date": {
+            "type": "string"
+          },
+          "decisions_made": {
+            "type": "number"
+          },
+          "key_facts_added": {
+            "type": "number"
+          },
+          "session_id": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "topics_touched": {
+            "items": {
+              "type": "string"
+            },
+            "type": "array"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "total",
+    "sessions"
+  ],
+  "type": "object"
+}
    • Addedcrbro_share
    • Addedcrbro_space
    • Changedcrbro_status1 field changed
      • changedOutput schema / (root)
        Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": false,
+  "properties": {
+    "brain_format": {
+      "type": "string"
+    },
+    "brain_path": {
+      "type": "string"
+    },
+    "crbro_version": {
+      "type": "string"
+    },
+    "last_boot": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "last_consolidation": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "total_neurons": {
+      "type": "number"
+    },
+    "total_sessions": {
+      "type": "number"
+    },
+    "total_synapses": {
+      "type": "number"
+    }
+  },
+  "required": [
+    "crbro_version",
+    "total_neurons",
+    "total_synapses",
+    "total_sessions"
+  ],
+  "type": "object"
+}
    • Addedcrbro_sync
  12. 15 tool updatesv1.4.0
    • First observedcrbro_boot
    • First observedcrbro_connect
    • First observedcrbro_connections
    • First observedcrbro_consolidate
    • First observedcrbro_context
    • First observedcrbro_global_map
    • First observedcrbro_hot_topics
    • First observedcrbro_learn
    • First observedcrbro_maintenance
    • First observedcrbro_neuron
    • First observedcrbro_neurons
    • First observedcrbro_recall
    • First observedcrbro_session_log
    • First observedcrbro_sessions
    • First observedcrbro_status
Deploy Server
Context All Your Agents Can ShareAgents share what they learn, hand off work, and hold it when you switch models. Start with 5 GB free.fulcradynamics.comAd

TDQS

A4.7/5.0

Scored across 15 tools

Disambiguation5/5

Each tool has a clearly distinct purpose, with descriptions explicitly cross-referencing and clarifying boundaries (e.g., connect vs consolidate, learn vs map vs secret). The lifecycle stages (learn, revise, forget) and read vs write operations (inspect vs recall) are sharply delineated, leaving no realistic chance of misselection.

Naming Consistency4/5

All names share the crbro_ prefix and snake_case convention, which is highly predictable. However, some tools are verbs (learn, recall, connect) while others are nouns (context, map, secret, space), a minor deviation from a strict verb_noun pattern.

Tool Count5/5

15 tools is well-scoped for a memory system covering sessions, CRUD, relationships, credentials, team sharing, and maintenance. Each tool earns its place without redundancy.

Completeness5/5

The surface provides full lifecycle coverage: creation (learn), reading (recall, inspect), updating (revise), and deletion (forget) for memories, plus session management, system maps, context, credentials, team spaces, and maintenance. No obvious gaps cause agent dead ends.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • iai-personal-memory-engine

    CodeAbra
    A
    license
    A
    quality
    A
    maintenance
    A local MCP server that gives AI assistants a long-term memory by capturing sessions verbatim and surfacing relevant context automatically.
    15
    901
    MIT

  • cell-mem

    Aether-liusiqi
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that provides AI agents with persistent, multi-layered memory inspired by the human brain, including consolidation, self-reflection, and generative replay.
    1
    MIT

  • mem-context

    turbyho
    A
    license
    A
    quality
    A
    maintenance
    Multi-modal RAG engine for AI assistants. Stores conversation history, conclusions, diffs, error traces, and other development artifacts in LanceDB with vector search, multi-factor scoring, and an LLM-driven consolidation pipeline.
    10
    MIT