Octonove/crbro-memory

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