Crbro Memory MCP Server

🧠 CRBRO — Persistent Neural Memory for AI

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.

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.

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.

Features

• 🧭 Project continuity (2.10+) — Full-path/repository identities and explicit aliases bind neurons to a project. Each MCP connection has its own current project, with scoped pending items, optional due dates and completion criteria. crbro_recall scope=all can still find other projects. Scope is organization, not an access-control boundary. Examples and compatibility.

• 🩺 Read-only diagnostics (2.10+) — npx crbro-memory doctor --json reports observed versions, brain/client paths, last boot, semantic files, backups and local Git state. It does not repair, read credential values, install anything or fetch/push. Unknown means unknown; see doctor.

• 🧬 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 and explicit evidence — Facts have volatile (90 days), normal (365), durable (730) or permanent shelf life, configurable through CRBRO_SHELF_DAYS; expired claims move to possibly_stale with a source-check warning. Since 2.10, repeating a fact never verifies it: only crbro_revise status=verified restarts a check. Optional evidence records source with its reference, or user; older explicit calls remain unspecified, and legacy dates are not promoted into evidence. References are data, never executed. temporal distinguishes current claims from history; intent=current separates historical matches. Relevance, provenance, verification and freshness are separate labels, not a truth guarantee. Earlier agent benchmarks showed that warnings alone did not reliably make agents check sources; those historical measurements remain in the design report.

• 🧹 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 — Only explicitly shared neurons sync to your configured Git remote. A failed push remains unsent; leaving a space preserves a local recovery archive. Information returned by memory tools still reaches your AI client even when it is not shared with a team.

• 🗺️ 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

• 🔒 Local storage, explicit data flows — The server and optional embedding model run locally, with no hosted CRBRO account or telemetry. MCP tool results go to your AI client and may reach its model provider; team sync and synced backup folders use the destinations you choose. The keychain is separate from normal memory backups and release packages, but reading a secret through MCP returns it to that client. See Security.

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

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

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

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

Documentation truncated — see the full README on GitHub.