🧠 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

• 🧬 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. Measured: +8 points of recall@1 over the keyword engine, +2 to +5 on top of save-time keywords. Costs ~500 MB on disk once per machine and ~0.5 GB of RAM while a server runs; init --no-semantic skips it, CRBRO_SEMANTIC=0 turns it off (v1.14+, installed by default since v1.16)
• 🔥 Heat Scores — Automatic relevance tracking based on frequency, recency, and connectivity. Topics written in the same session are linked at consolidation, so the graph fills itself in (v1.13+)
• 🕰️ Dates that mean something — A recency lift of at most 4% breaks ties towards the newer telling (measured: it only ever flipped exact ties), crbro_recall since / kind narrow a search to "the last two weeks" or "only past mistakes", and crbro_maintenance backfill_dates dates the entries written before 1.13 from the date stated in their own text — never guessed (v2.5+)
• 🧹 Housekeeping that reports before it acts — every maintenance run lists entries whose own deadline has passed, neurons that outgrew one read (with crbro_revise move_to to split them keeping every date) and the one-line neurons a bulk import left behind (compact:true folds them into a digest). All read-only until asked (v2.5+)
• 💽 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+)
• ⏱️ 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

Measured, not promised

Every number below comes from a deterministic benchmark in benchmarks/ that runs in CI — no API calls, reproducible on your machine with node benchmarks/<name>/run.mjs. The unflattering ones are published on purpose.