Crbro Memory

🧠 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](https://github.com/Octonove/crbro-memory) 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= 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 se