Skip to main content
Glama

🧠 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: what you decided, how things are deployed, what is still pending. Everything is plain JSON on your own disk, organized like a brain β€” cortex, synapses, hippocampus. A correction replaces the old fact instead of sitting next to it, an old value comes back with a warning to check it, a question with nothing stored behind it is answered as such, and credentials are kept out. You can read and edit all of it in your browser, and one command installs it in Claude Code, Claude Desktop, Codex and Cursor.

CRBRO tour: memory across sessions, corrections that replace old facts, a warning on values that may be out of date, an honest answer when nothing is stored, secrets kept out, open items above the prompt, the memory edited in the browser, and the one-command install

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

This page has three layers. 1. Quick start gets you running in a minute. 2. Reference lists the tools, the commands and the environment variables. 3. Measurements says what it costs and how well it works, with dates. Troubleshooting covers the problems people actually hit.


1. Quick start

You need Node.js 20 or later (the Claude Desktop bundle below needs none).

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.

Every other client: one command

npx crbro-memory install

It finds the MCP clients on this machine (Claude Code, Claude Desktop, Cursor, Codex), copies the engine to one stable folder (~/.crbro-engine/<version>, or --engine-dir DIR), registers node <that folder>/crbro.mjs in each client with the timeouts that client needs, and makes the memory load itself at the start of every conversation. No npx at client start, so every client runs the same build and shares one daemon. It merges into your config files and never rewrites them: every file it touches keeps a timestamped backup beside it (<file>.crbro-bak-<stamp>). Pick clients with --clients claude-code,codex (default auto), see what it would do first with --dry-run, and get the report as JSON with --json. npx crbro-memory uninstall takes the same flags and removes only what CRBRO added β€” never the brain (complete uninstall).

Then restart the client, open a new conversation, and check that crbro_boot actually ran and returned a neuron count. npx crbro-memory doctor is a read-only check of what is installed where.

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. The install command above wires the start for you; the manual route is below.

Registering by hand

Prefer to edit config yourself? Register CRBRO at the user level, not per-project: the brain lives in ~/.crbro/ and is shared across every folder, but a server registered inside one project is missing everywhere else and it will look like the memory is gone.

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

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

Claude Desktop β€” %APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, ~/.config/Claude/claude_desktop_config.json on Linux:

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

Cursor β€” ~/.cursor/mcp.json (the one in your home folder, not a project's .cursor/): same JSON as above.

Codex β€” ~/.codex/config.toml. Give it a startup timeout: Codex starts MCP servers when a session opens and gives up after a short default (see Troubleshooting).

[mcp_servers.crbro]
command = "npx"
args = ["-y", "crbro-memory"]
startup_timeout_sec = 60
tool_timeout_sec = 120

install and install-boot add these two lines only when they are missing; values you set yourself are kept.

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

Making it load itself, by hand

npx crbro-memory install-boot

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

Semantic recall (optional)

npx crbro-memory init creates the brain and installs a local embedding model that is fused with the keyword engine, so paraphrases the words do not cover start to land. It is a download of several hundred MB once per machine (sizes and timings in Measurements); init --no-semantic skips it and CRBRO_SEMANTIC=0 turns it off any time. Details: docs/semantic-recall.md.

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.

To see what it knows, npx crbro-memory view opens a local page (127.0.0.1, one-time token) where you search the memory, edit or retire an entry, merge two neurons and close open items. npx crbro-memory export writes it all out as Markdown or JSON, and npx crbro-memory import brings in a CLAUDE.md / AGENTS.md, a Claude Code memory folder or an export (a dry run unless you pass --apply).

More that you can switch on, each in docs/hooks.md and docs/daemon.md: the guard hook (stored lessons speak before a shell command runs), the compaction checkpoint, the subagent hook, the open-items band in Claude Code, and the daemon for several clients on one brain.


Related MCP server: Mnemoverse Memory

2. Reference

The 15 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 search keywords. supersedes replaces old facts; shelf_life, reference and temporal describe the claim. Repeating it never verifies it; use an explicit crbro_revise status=verified with evidence after a real check

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. A line that is not yours says where it came from (origin). A row past its shelf life comes back apart, in possibly_stale, with what to check before answering

crbro_revise

Retire facts (and decisions, patterns, errors, debts via entries) as superseded or retracted, reactivate them with status=active, reconfirm checked ones 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 β€” suggested, never moved

crbro_maintenance

Brain maintenance β€” heat, pruning, integrity, repair, unarchive, index rebuild. Every run reports expired entries, entries past their shelf life, 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. See docs/credentials.md

crbro_space

Create, join, sync or leave a team space β€” a private git repo for shared projects. See docs/team-memory.md

crbro_share

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

A 1.x brain opens as it is: see Upgrading from 1.x for the retired tool names.

Commands

Every command is run as npx crbro-memory <command> (there is no separate crbro binary). --version prints the version and <command> --help explains one command.

Setup and checks

Command

What it does

install / uninstall

Register CRBRO in your MCP clients and wire the boot hook; remove what it installed. --dry-run lists the changes without making them

init

Create the brain and install semantic recall (--no-semantic skips it)

install-boot

Make the memory load itself in every conversation (above)

status

Show the brain's status

doctor [--json]

Read-only diagnostics: versions, brain and client paths, hooks, daemon leftovers, quarantine, backups' age, semantic files. Repairs nothing, reads no credential values. See docs/doctor.md

reindex

Rebuild the search index

eval

Measure retrieval quality against your own query set (docs/semantic-recall.md)

Viewing, moving and serving the memory

Command

What it does

view [--port N] [--no-open]

A local page in your browser (127.0.0.1 only, one-time token in the link): neurons, every entry with its date, status, verification and freshness, search, open items to resolve or discard, stale entries to verify or retire, and the text of any entry to edit and any neuron to merge into another

export [--out DIR] [--format md|json] [--include-retired]

Write the brain as an Obsidian-compatible Markdown vault or one JSON file. Read-only, safe while a client runs, credentials redacted

import PATH [--apply] [--topic NAME] [--type fact|preference|pattern]

Bring memory in from CLAUDE.md / AGENTS.md, a Claude Code memory folder or a CRBRO export. A dry run unless --apply; importing twice adds nothing

serve --http [--port 8787] [--host 127.0.0.1] [--allow-remote] [--new-token] [--allow-secrets]

MCP over Streamable HTTP at /mcp with a bearer token (CRBRO_HTTP_TOKEN or the keychain). Loopback unless --allow-remote; no TLS, no OAuth; crbro_secret is left out unless --allow-secrets. Some antivirus web shields (Avast's, for one) rewrite MCP traffic on loopback: exclude the port if requests fail

Credentials, backups, daemon

Command

What it does

secret set|get|list|remove|status

Credentials in the OS keychain; the value is read from stdin, never argv (docs/credentials.md)

backup, backup list, backup restore FILE

One gzipped copy of the brain, rotated; restore never lands on the live brain. backup --keep N sets how many to keep

daemon on|off|status|stop

One process owns the brain for every client (docs/daemon.md)

Claude Code hooks and mod

Command

What it does

install-hooks --guard

Stored lessons speak before a shell command runs. guard "<command>" shows what it would say

install-hooks --compact / uninstall-hooks --compact

Checkpoint before a compaction, picked back up after it

install-hooks --inject

Hand your protocols to spawned subagents (opt-in)

install-hooks --verify

SHA-256 of the installed hooks and mod against this package; changes nothing

install-mod [--lang en|es|auto] / uninstall-mod

The open-items band and /pending in Claude Code

All of these are described in docs/hooks.md.

Looking back, mining, semantic layer

Command

What it does

usage [--days N] [--session ID] [--project DIR] [--json]

Tokens per model and session from Claude Code's own logs, subagents apart. Read-only

postmortem [--days N] [--max N] [--json]

Candidate lessons from past sessions: corrections you repeated, a tool failing in a row. Stores nothing

mine [dir], setup-miner, miner-status, remove-miner

Optional, fully local scan of your .md/.txt notes into the brain; "miner" means knowledge mining (docs/architecture.md)

semantic status|install|build

The semantic layer's runtime, model and index (docs/semantic-recall.md)

Unknown commands are rejected with a non-zero exit code instead of starting the server by accident.

Environment variables

Set them in the env block of the MCP client's config to affect that client only, or in your shell. Flags (0/1) accept the values shown.

Variable

Default

What it does

CRBRO_PATH

~/.crbro

Where the brain lives. Also read by the hooks and the CLI. CRBRO_BRAIN_PATH is an older alias still read by the guard and subagent hooks

CRBRO_SEMANTIC

on where the runtime is installed

0 turns the semantic layer off: recall is the keyword engine alone

CRBRO_SEMANTIC_HOME

~/.crbro/.semantic

Where the semantic runtime and model are kept

CRBRO_SEMANTIC_MODEL

Xenova/multilingual-e5-small

Embedding model (any e5-family model)

CRBRO_SEMANTIC_DTYPE

q8

Model quantization

CRBRO_SEMANTIC_FLOOR

built in

Cosine floor under which a vector-only candidate is dropped

CRBRO_SEMANTIC_BATCH

built in

Lines embedded per batch

CRBRO_SEMANTIC_WAIT_MS

1500

How long a recall waits for the semantic model before answering keyword-only (semantic: "warming")

CRBRO_NO_ANSWER

on

0 turns off no_answer: recall then returns its usual rows even when nothing clearly matches

CRBRO_SYNONYMS

on

0 turns off the bilingual synonym table

CRBRO_RECENCY

on

0 turns off the small recency lift that breaks ties toward newer entries

CRBRO_IDF

on

0 turns off weighting query terms by rarity

CRBRO_STALENESS

on

0 switches off shelf-life tracking and possibly_stale

CRBRO_SHELF_DAYS

volatile=90,normal=365,durable=730

Override the shelf-life windows, e.g. volatile=60,normal=300

CRBRO_AUTOBACKUP

on

0 disables the daily backup made at consolidation

CRBRO_BACKUP_DIR

<brain parent>/<brain name>-backups/brain (~/.crbro-backups/brain)

Where backups go; point it at a synced folder

CRBRO_KEYS_DIR

~/.crbro-keys

Where the keychain file lives on platforms that use one

CRBRO_KEYS_COPIES

5

Sealed copies of the Windows keychain file kept in sealed-copies/ (2–100)

CRBRO_SECRET_<NAME>

β€”

An environment value crbro_secret get NAME may return (for CI or machines with no credential store). Plain variables are never read

CRBRO_SECRET_ENV

β€”

Comma-separated names whose plain environment variable crbro_secret get may return as well

CRBRO_ENCRYPT_AT_REST

off

1 seals backups and quarantine copies with AES-256-GCM, using a 32-byte key stored in the keychain as CRBRO_AT_REST_KEY (create it once, see docs/credentials.md). Without the key nothing is written in clear and nothing is deleted

CRBRO_DAEMON

the brain's own flag

1 / 0 forces daemon mode on or off for one client; see docs/daemon.md

CRBRO_DAEMON_IDLE_MIN

20

Minutes without a conversation before a daemon exits; 0 keeps it running

CRBRO_MOD

on

0 keeps this client from installing or updating the Claude Code mod

CRBRO_LANG

system locale

Language of the mod (en or es) when installed with --lang auto

CRBRO_SUBAGENT_INJECT

off

full makes the subagent hook inject the protocol block

CRBRO_SUBAGENT_MATCHER

β€”

Regex that scopes the subagent hook to some subagent types

CRBRO_STARTUP_TRACE

off

1 traces the startup steps, with timings, to stderr and <brain>/.daemon/startup-trace.log

CRBRO_QUARANTINE_DAYS

180

Days .quarantine/ keeps the copies taken before a forget, merge, compact or repair; 0 keeps them forever

CRBRO_ENGINE_DIR

~/.crbro-engine

Where install keeps the engine the clients run

CRBRO_HOOK_REFRESH

on

0 stops a newer release from refreshing the hook copies it installed earlier

CRBRO_GUARD_ORIGINS

own

all lets the guard also speak lessons from team spaces and the miner (labelled)

CRBRO_CODEX_HOOK

on

0 silences the packaged Codex boot hook

CRBRO_HTTP_TOKEN

β€”

Bearer token for serve --http (else read from the keychain under the same name)

CLAUDE_CONFIG_DIR

~/.claude

Where the hooks and the mod are installed, if you moved Claude Code's folder

CODEX_HOME

~/.codex

Same, for Codex

CLAUDE_CODE_PLUGIN_DIRS

β€”

Read and extended (never replaced) by the mod installer

NODE_USE_SYSTEM_CA

β€”

Node's own switch: trust the system certificate store (see Troubleshooting)

More documentation

docs/features.md

The full feature list, version by version

docs/hooks.md

Guard, compaction checkpoint, subagent hook, open-items mod

docs/daemon.md

One process for every client

docs/semantic-recall.md

The embedding layer, and measuring retrieval on your own queries

docs/credentials.md

The keychain and the secret command

docs/team-memory.md

Spaces: sharing projects through a git repo you own

docs/architecture.md

What is on disk, the heat score, the miner

docs/privacy.md

Exactly which data flows can touch the network

docs/doctor.md

What doctor reports and what it never does

docs/upgrading-from-1x.md

The 23 β†’ 15 tools change

docs/releasing.md

How releases are made (for maintainers)

llms-install.md

For an AI agent asked to set CRBRO up (Cline's marketplace reads it): the one config entry, and what not to run

CONTRIBUTING.md, SECURITY.md, CHANGELOG.md


3. Measurements

Every number about cost and quality comes from a script in benchmarks/ that you can run yourself. The unflattering results are published on purpose, and what the benchmarks deliberately do not claim β€” human productivity, "it knows you", comparisons against other memory systems β€” is in benchmarks/LIMITS.md.

What runs in CI on every push: the lexical retrieval benchmark (keyword engine alone, no model, no network) and the credential-redaction benchmark, both as gates that fail the build if they regress (npm run bench), plus the unit and integration test suite on Linux, Windows and macOS. Everything else below is run by hand, with the version and date next to it. The agentic benchmark puts a real Claude Code agent to work and spends tokens, so it is never run in CI.

Measured for 2.11.0 on 14-11-2026, on Windows 11 with Node 24; the rows marked 2.12.0 were measured for that release the same day. "Real brain" means a copy of one person's brain (563 neurons, 9 MB of neurons, 146 day logs, semantic layer installed); the 2.10.0 figure next to each is the same measurement on the same copy.

What

Result

How to reproduce

Cost: tools/list (what an MCP client that loads every tool pays on each request)

29,802 characters (β‰ˆ7,500 tokens) for the 15 tools, 2,918 of them output schemas. 2.10.0: 44,434

node benchmarks/cost/context.mjs

Cost: crbro_boot (paid once per session)

9,973 characters on the real brain (2.10.0: 21,704); 9,529 on the 503-neuron synthetic brain of context.mjs

node benchmarks/cost/context.mjs

Cost: crbro_recall (per search, default five results)

~7,700–8,800 characters for five results, plus the same as structuredContent (2.10.0: ~13,000). A question with nothing clearly stored behind it comes back flagged no_answer with at most three weak rows: 5,147 characters for one on the real brain, where 2.10.0 returned five rows and 13,205 characters

node benchmarks/cost/context.mjs

Cost: crbro_context

A read: 21,318 characters (unchanged on purpose: it is the door to everything pending). A write (add_pending and the like) now answers in ~430 characters instead of ~22,000

node benchmarks/cost/context.mjs

Retrieval, keyword engine alone (blind paraphrased queries; the CI gate)

recall@1 83 %, recall@3 90 %, MRR 0.865 on 48 blind paraphrased queries (2.10.0: 77 %, 83 %, 0.806). The CI gate's floor is 40/48, 42/48 and 0.85

node benchmarks/retrieval/run.mjs

Retrieval, semantic layer on

recall@1 85 %, recall@3 88 %, MRR 0.865 (2.10.0: 75 %, 81 %, 0.781). On the real brain a search takes ~140–220 ms with the layer on, ~60 ms keyword-only

CRBRO_SEMANTIC=1 node benchmarks/retrieval/run.mjs

Retrieval, Spanish (accents, hyphenated compounds, questions with no answer)

29 answerable questions: recall@1 25, recall@3 25 (2.10.0: 18, 21). Accents 17/17, hyphenated compounds 4/4, long entries answered with the part that matched 3/3; 5 of 8 unanswerable questions flagged no_answer (2.10.0: 0). On the real brain, diseΓ±o now finds 105 neurons (2.10.0: 14), tΓ­tulo 99 (17), categorΓ­a 77 (16), EspaΓ±a 72 (6)

node benchmarks/retrieval/run.mjs (see its README)

False confidence (questions about things that are not stored)

Keyword engine: 1 of 14 distractors reaches a real hit's score (2.10.0: 2). Semantic layer on: 0 of 14

node benchmarks/retrieval/run.mjs

Secret redaction (adversarial credentials and near-miss innocents; the CI gate)

24/24 caught, 0/28 false positives, counted per value: a case is caught only if every secret value in it is gone

node benchmarks/security/run.mjs

Startup (client connected until the first tool answers; with and without the daemon)

Real brain. Without the daemon: initialize ~0.28 s, crbro_boot ~0.9–1.4 s, first recall ~0.2 s. With the daemon warm: initialize 69 ms, crbro_boot 37 ms. With the daemon to be started: initialize 103 ms (2.10.0: 625 ms), first boot ~1.7 s

node benchmarks/daemon/startup.mjs

Memory use (RAM per client, with and without the daemon)

Without the daemon, one full engine per client: ~1 GB with the semantic model loaded, ~530 MB keyword-only (2.10.0: ~700 MB). With the daemon: ~62 MB per client plus one daemon (~0.8–1 GB)

node benchmarks/daemon/startup.mjs

Disk (semantic layer: runtime and model)

~500 MB in ~/.crbro/.semantic (runtime and model, downloaded once by semantic install)

npx crbro-memory semantic status

First boot after upgrading (the search index rebuilds once)

9.7 s on the real brain (563 neurons): the index rebuilds once in the new format. The semantic vectors of long entries, now split into parts, then fill in the background (~5,500 of them, about 4 minutes here); meanwhile recall stays at 0.05–0.4 s and answers keyword-only (semantic: "warming")

β€”

Performance gate (2.12.0; the real server over stdio on the synthetic ~500-neuron brain; runs every night in CI)

Keyword recall p50 19 ms, p90 52 ms. While the semantic vectors fill in after an upgrade (213 s here): p90 278 ms, worst 546 ms; then p50 43 ms, p90 79 ms. First boot 2.3 s, second 0.6 s. The run fails at roughly three times these figures

npm run perf

Tests

107 files, 1,337 passed, 6 skipped on Windows 11 (2.12.0); CI runs the suite on Linux, Windows and macOS with Node 20, 22 and 24

npx vitest run

A fresh session does not ask again (agentic; haiku and sonnet)

Not re-run for 2.11: the 2.7.2 result stands, with its caveats, in docs/measurements-2.7.2.md

node benchmarks/agentic/run.mjs

The figures published for 2.7.2 (retrieval, scale, false confidence, the agentic runs and the two stale-value experiments that did not meet their pre-registered claim) are kept, dated and with their caveats, in docs/measurements-2.7.2.md. They have not been re-measured for 2.11.


Troubleshooting and FAQ

CRBRO does not remember anything

Almost always the memory is asleep, not broken: the boot step is not wired, so the assistant never reads the brain. Run npx crbro-memory doctor, then npx crbro-memory install-boot (or install), restart the client and open a new conversation. Check that crbro_boot ran and returned a neuron count. If you have to call it by hand, the step did not take. If the server was registered inside one project instead of at the user level, other folders do not have the tools: register it with --scope user.

Codex says the MCP server timed out at startup

Codex starts MCP servers when a session opens and waits only a short default time. A first start through npx also downloads the package. Give the server more time in ~/.codex/config.toml:

[mcp_servers.crbro]
command = "npx"
args = ["-y", "crbro-memory"]
startup_timeout_sec = 60
tool_timeout_sec = 120

npx crbro-memory install writes these for you. The server answers initialize and tools/list at once, before it has loaded the brain, so a Codex that still times out is waiting on npx itself: install once with npm install -g crbro-memory and use crbro-memory as the command, or let install keep the engine in a stable folder. CRBRO_STARTUP_TRACE=1 in the server's env prints where the time goes.

Two daemons are running

Daemon mode is one process per version of CRBRO: after an upgrade, a client on the new version starts its own daemon and the old one exits by itself after 20 idle minutes (CRBRO_DAEMON_IDLE_MIN). Until then two are alive, and that is expected. npx crbro-memory daemon status lists them, daemon stop stops a daemon, and doctor flags leftovers of dead daemons. Never kill the process by hand while a client is mid-conversation; the client falls back to serving itself and carries on.

The first start after upgrading is slow

2.11 reads words with accents (Γ‘, Γ­, ΓΊ, Γ±, ΓΌ) and hyphenated compounds differently, so the search index is rebuilt once the first time a brain is opened. How long depends on the size of the brain; it does not happen again. Do not interrupt it. The semantic layer, if installed, is not re-embedded.

The keychain is missing or locked

npx crbro-memory secret status says which store this machine offers: Keychain on macOS (security), Secret Service on Linux (secret-tool, which needs a running D-Bus session), a DPAPI-sealed file on Windows. On a headless server, a CI runner or an SSH session with a locked keychain, crbro_secret says so in plain words instead of failing; use CRBRO_SECRET_<NAME> environment variables there. A missing keychain file is reported as missing, never treated as an empty keychain: if you moved or deleted ~/.crbro-keys, restore it from your own backup before storing anything new. See docs/credentials.md.

npx fails with UNABLE_TO_VERIFY_LEAF_SIGNATURE

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. Never "fix" this with strict-ssl=false or NODE_TLS_REJECT_UNAUTHORIZED=0: those turn verification off for everything.

Where does the memory live?

What

Where

The brain (readable JSON)

~/.crbro, or CRBRO_PATH. Neurons in cortex/, connections in synapses/, session logs in hippocampus/, the search index in .search/. Layout: docs/architecture.md

What crbro_forget removed

<brain>/.quarantine/ until its retention runs out

Backups

~/.crbro-backups/brain, or CRBRO_BACKUP_DIR

The semantic runtime and model

~/.crbro/.semantic, or CRBRO_SEMANTIC_HOME

Credentials

The OS keychain (Windows: ~/.crbro-keys, sealed with DPAPI). Never inside the brain, never in backups

Hooks and the mod

~/.claude/settings.json, ~/.claude/crbro-mods/, ~/.codex/hooks.json (and the CLAUDE_CONFIG_DIR / CODEX_HOME equivalents)

Team spaces

<brain>/shared/<space>, one git repo each

Complete uninstall

The one-command way, which lists everything first and removes only what CRBRO itself wrote:

npx crbro-memory uninstall --dry-run     # what it would remove
npx crbro-memory uninstall

It removes the registrations that run CRBRO in every client it finds, its hooks and boot wiring, the Claude Code mod and the engine folder install created. It keeps the backup of every file it edits, and it never touches the brain, your backups or the keychain: it prints where they are, and there is no flag that deletes them. That last step is yours (item 7 below).

By hand, or to check that nothing is left, in this order:

  1. Stop the daemon: npx crbro-memory daemon off, then daemon stop.

  2. Unregister the server from each client: claude mcp remove crbro --scope user; delete the crbro entry from Claude Desktop's claude_desktop_config.json, from ~/.cursor/mcp.json and the [mcp_servers.crbro] table of ~/.codex/config.toml. Uninstall the Claude Desktop extension from its settings if you used the .mcpb.

  3. Remove the hooks: npx crbro-memory uninstall-hooks --compact and delete any remaining entry naming crbro from ~/.claude/settings.json (SessionStart, PreCompact, PreToolUse, SubagentStart) and from ~/.codex/hooks.json. npx crbro-memory install-hooks --verify shows what is still installed.

  4. Remove the Claude Code mod: npx crbro-memory uninstall-mod.

  5. Remove the scheduled miner, if you set it up: npx crbro-memory remove-miner.

  6. Remove credentials you stored: npx crbro-memory secret list, then secret remove NAME --yes for each. Deleting the brain does not delete keychain entries.

  7. Delete the data, only if you want the memory gone for good: ~/.crbro (brain, quarantine and semantic model), ~/.crbro-backups, ~/.crbro-keys, and the engine folder that install created, if any (uninstall --dry-run names it).

  8. Copies you shared with a team space stay on your teammates' disks and in the git remote.

What does it send over the network?

Nothing to us, ever: there is no account, no telemetry. The optional semantic layer downloads a model once; team sync pushes only the projects you explicitly share, to a git remote you own; and what a tool returns is read by your AI client. docs/privacy.md lists each flow.


Contributing and support

Bug reports and pull requests are welcome: see CONTRIBUTING.md. Report vulnerabilities as described in SECURITY.md.

⭐ 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

License

MIT β€” see LICENSE. Built by Octonove.

Available Tools

15 tools
crbro_auditAudit for credentialsA
Read-onlyIdempotent

Read-only scan of every neuron (all entry kinds and the map) and every session log for credentials stored before the filter caught them: API keys, tokens, passwords. Reports where and what kind, never the values. Findings are also in the search index, so recall can return them: remove them with crbro_forget (facts for entries, session for a day log), then rotate them. Run it after upgrading or when a secret may have been pasted. crbro_inspect shows content; this judges it.

Inputs: no named parameters. Returns: note, message, findings, facts_affected, +3 more

crbro_bootBoot the brainA
Idempotent

Read the brain at session start β€” call it FIRST in every conversation; writes only the boot stamp. Returns protocol_enforcement (mandatory directives: follow them), counts, open_items (due first, then newest; review:true = over a month old, no due date), recently_closed (done: never report as pending), hot_topics, recent_sessions headlines and memory_discipline; more names the call for what is left out. Syncs team spaces (offline is normal). Pass project (working folder or repo) to scope open items and rank its neurons first; project_neurons binds them. Close with crbro_consolidate.

Inputs: project, project_id, project_aliases, project_neurons.

crbro_connectConnect two neuronsA
Destructive

Write: create, strengthen or delete the undirected synapse between two neurons (ids validated). action=connect (default) creates it at 0.5 and adds 0.1 per repeat (cap 1.0), or sets the strength given; action=disconnect deletes it β€” the destructive side. crbro_consolidate already links neurons written in one session: use this for relationships beyond co-occurrence. Read links with crbro_inspect view=neuron. Returns synapse_id, action (created, strengthened, disconnected, absent) and strength.

Inputs: to (required), from (required), type, action, +2 more.

crbro_consolidateConsolidate the sessionA
Idempotent

Write: close the session β€” the only way to log one; call it before the conversation ends, or the session's knowledge is lost. Logs the summary (credentials stripped), flushes the index, recalculates heat, links the neurons written this session and syncs team spaces (offline is normal). Returns session_id, facts_saved, decisions_saved, topics_touched and sync state; promotion_candidates: own lessons found in 2+ project neurons, with a suggested_target (nothing moves). Mid-session open items go to crbro_context; housekeeping, crbro_maintenance.

Inputs: summary (required), topics_touched.

crbro_contextWorking contextA
DestructiveIdempotent

Read or write the working context: active topics and open items. With no change field it reads (written:false) everything: each open item whole with due and done_when, and recently closed. A write returns what changed and the counts (return_context:true for the whole context). Scope: this connection's project plus global items; scope=all spans every project. resolve_pending closes items (the last 15 stay in recently_closed); discard_pending drops them without recording them as done. Prefer ids. Nothing is deleted by age. Sessions are logged by crbro_consolidate.

Inputs: due, clear, scope, project, +6 more.

crbro_forgetForget for goodA
DestructiveIdempotent

Write, destructive: remove from disk after a quarantine copy (backup returned) β€” for what must not exist on disk: a credential, personal data, a whole neuron. What merely stopped being true goes to crbro_revise, which keeps the history. One mode per call: facts (entries of any kind, or the map); entire (a neuron and its synapses, in two steps: without confirm_token it is a dry run β€” show the user, get agreement, call again with the token); restore (the newest quarantine copy); merge_into (union a neuron into another, delete the source); session (one day log). entire and merge_into refuse a shared neuron. Rotate any removed credential.

Inputs: facts, entire, neuron, restore, +3 more.

crbro_inspectInspect the brainA
Read-onlyIdempotent

Read-only views of the brain by id or name; nothing is written. Search by content is crbro_recall. view=status: CRBRO itself β€” version, brain path, totals, last boot, semantic recall, shelf-life windows, retired 1.x tool names. view=neuron: an index of one neuron (header, counts, connections, one line per entry: id, kind, date, preview), paged; entries=[ids] reads those whole; detail=full dumps it, shortened when large. Absent temporal, verification and freshness mean current_claim, none, unverified. view=neurons: rows hottest first. view=sessions: day logs newest first, where session summaries are read. view=global_map: domain clusters and bridges.

Inputs: view (required), type, limit, detail, +8 more. Returns: view, neuron, status, neurons, +2 more

crbro_learnLearn somethingA

Write a fact, decision, pattern, preference, error or debt to a neuron (created when the topic matches none). Recall first: it may exist. A replacement passes supersedes; retiring without one is crbro_revise; deleting is crbro_forget. A value that can change names its source (file, key, URL, person). Repeating a fact merges metadata, never verifies it (crbro_revise status=verified does). One claim per fact: past ~600 characters the answer suggests splitting; a huge neuron, crbro_revise move_to. Credentials become markers: crbro_secret them, store only the name. Returns neuron_id, action, shelf_life, near_duplicates, supersedes_unmatched (still live).

Inputs: type (required), content (required), topic, domain, +9 more.

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. Extras run only when asked: archive cold neurons (they stop being searchable), unarchive, purge_boilerplate, repair, backfill_dates, compact. Session close is crbro_consolidate; reading the brain is crbro_inspect.

Inputs: repair, archive, compact, dry_run, +5 more.

crbro_mapSystem mapA
DestructiveIdempotent

Read or replace a neuron's system map: ONE living document β€” where the system lives, what serves what, the traps that cost hours. Read it before working on a system touched in past sessions; after changing it, rewrite it whole. Omit content to read (map:null if none); content replaces the old map entirely; an empty string clears it. crbro_inspect view=neuron also returns it. Writing creates the neuron if needed and redacts credentials. Atomic facts go to crbro_learn β€” the map is the prose around them.

Inputs: neuron (required), domain, content.

crbro_recallRecallA
Read-onlyIdempotent

Read-only search of everything saved in earlier sessions. Call it BEFORE answering anything about the user, their projects, preferences, decisions or past work: the answer is usually stored. One row per neuron: the best entry (matching_content; entry_id β†’ crbro_inspect view=neuron entries=[id] reads it whole), confidence (weak: verify; a search match, not truth) and also_matched previews. Absent fields hold their default: temporal current_claim, verification none (present = a check the caller reported), freshness unverified, provenance local. Lines not the user's own carry origin, also_matched too: team: 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. has_map: read crbro_map before touching that system.

Inputs: query (required), kind, limit, scope, +6 more. Returns: hint, query, results, has_more, +9 more

crbro_reviseRevise a neuronA
Idempotent

Write: change what a neuron says without deleting anything β€” for what stopped being true, or never was, with nothing replacing it (a replacement is crbro_learn with supersedes; what must not exist on disk, crbro_forget). facts and entries take a status: superseded or retracted retire them (kept in the file, gone from recall), active reactivates, and status verified records a check against the source. summary, domain, tags and name edit metadata in the same call; 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.

Inputs: neuron (required), name, note, tags, +7 more.

crbro_secretKeychain secretA
Destructive

Read or write credentials in the OS keychain (macOS Keychain, Linux Secret Service, Windows DPAPI); no sync or team space reaches it. When the user hands you a credential, set it, then crbro_learn only the NAME. get returns value and source: never print it unless asked; missing = found:false. Environment variables count only as CRBRO_SECRET_ or when listed in CRBRO_SECRET_ENV. Overwriting with a different value, and remove, are two-step: the first call changes nothing and returns confirm_token; show the user, get agreement, call again with confirm. A missing store file is an error, never empty; on Windows crbro-memory secret restore puts back a sealed copy.

Inputs: action (required), name, value, confirm, +1 more.

crbro_shareShare a projectA

Write: put one neuron into a team space, or take it out with unshare. Without confirm it is a dry run: it reports what would be sent (ops_to_emit; preferences never leave this machine) and refuses outright if it finds a credential (crbro_forget it, rotate it). Show the user, get agreement, call again with the confirm token; a stale token is refused. From then on what is learned about that project reaches the team on each crbro_space sync or consolidate. unshare stops future notes; what was sent stays with the team.

Inputs: neuron (required), space, confirm, unshare.

crbro_spaceTeam spaceA

Read or write team spaces: shared memory in a private git repository holding only the projects you choose to share. create starts one; join clones a teammate's; status shows your identity and spaces; sync exchanges notes now (boot and consolidate do it on their own; offline is a normal answer); leave pushes pending notes and deletes the local copy, keeping your neurons. Joining shares nothing: each project goes in with crbro_share. create and join reply ok:false with the reason on failure.

Inputs: action (required), name, author, branch, +1 more.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 15 tools

    Disambiguation4/5

    The descriptions actively cross-reference each other to draw boundaries (learn vs revise vs forget, recall vs inspect, map vs learn, context vs consolidate vs maintenance), which keeps a large write surface navigable. Still, six write-ish tools (learn/revise/forget/connect/map/consolidate) have subtle conceptual boundaries that require reading long descriptions before an agent can pick confidently, so some misselection risk remains.

    Naming Consistency4/5

    All 15 tools share the crbro_ prefix and short, predictable suffixes, mostly verbs (learn, recall, revise, forget, connect, consolidate, audit, share). Minor inconsistency: a few suffixes are nouns rather than verbs (crbro_secret, crbro_space, crbro_context, crbro_map), and those tools act as both read and write, which the naming doesn't signal.

    Tool Count4/5

    15 tools sits at the top of the comfortable range but each covers a distinct layer of the system (local memory, sessions, keychain, team spaces, housekeeping), so the count is earned rather than padded. A couple could arguably be folded together (audit into inspect/maintenance), but nothing feels gratuitous.

    Completeness5/5

    The surface covers the full lifecycle: create (learn), search/read (recall, inspect, boot), update (revise), destroy (forget), relationships (connect), session logging (consolidate), housekeeping (maintenance), secrets (secret, audit), and team collaboration (space, share). No obvious dead ends for a persistent-memory server.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      A local MCP server that gives AI assistants a long-term memory by capturing sessions verbatim and surfacing relevant context automatically.
      15
      922
      MIT
    • 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
    • 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