crbro-memory 2.4.0 → 2.5.0

package/README.md

@@ -15,6 +15,16 @@ Free and open source (MIT). All 15 tools included — no license, no account, no
 
 > ⭐ **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.**
 
+<!-- invokard-coffee -->
+**&#9749; If this saves you time, buy me a coffee.** [![Buy me a coffee with PayPal](https://img.shields.io/badge/PayPal-Buy%20me%20a%20coffee-00457C?logo=paypal&logoColor=white)](https://www.paypal.com/donate/?business=stradoxx%40gmail.com&no_recurring=0&currency_code=EUR&item_name=Support%20crbro%20memory)
+
+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)
@@ -24,8 +34,12 @@ Free and open source (MIT). All 15 tools included — no license, no account, no
 - **🗣️ 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
@@ -33,6 +47,7 @@ Free and open source (MIT). All 15 tools included — no license, no account, no
 - **⚖️ 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
@@ -156,6 +171,26 @@ Session context never reaches Task-spawned subagents, so this hook can inject th
 
 **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
+
+```bash
+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/`](https://github.com/Octonove/crbro-memory/tree/master/benchmarks/daemon). A single client gains nothing from it.
+
+### 7. (Claude Code, optional) The guard hook
+
+```bash
+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`.
+
 ## Tools
 
 | Tool | Description |
@@ -163,14 +198,14 @@ Session context never reaches Task-spawned subagents, so this hook can inject th
 | `crbro_boot` | Boot the brain at session start — loads hot topics, context, the last three sessions and the `retired_tools` map |
 | `crbro_inspect` | Read-only views by id or name: `view=status`, `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 the keywords a future question may use. `supersedes` retires the old version in the same call |
-| `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; `sessions_matched` lists the day logs that mention it, `sessions_total` how many there were |
-| `crbro_revise` | Retire facts (and decisions, patterns, errors, debts via `entries`) as superseded or retracted, reactivate them with `status=active`, and edit summary, domain, tags or name |
+| `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, `sessions_total` how many there were |
+| `crbro_revise` | Retire facts (and decisions, patterns, errors, debts via `entries`) as superseded or retracted, reactivate them with `status=active`, 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 |
-| `crbro_maintenance` | Brain maintenance — heat, pruning, integrity, `repair`, `unarchive`, index rebuild |
+| `crbro_maintenance` | Brain maintenance — heat, pruning, integrity, `repair`, `unarchive`, index rebuild. Every run reports expired entries, 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 |
 | `crbro_space` | Create, join, `sync` or `leave` a team space — a private git repo for shared projects |
@@ -365,6 +400,10 @@ npx crbro-memory reindex  # Rebuild the search index
 npx crbro-memory eval     # Measure retrieval quality against your own query set
 npx crbro-memory semantic status | install | build   # Semantic recall (installed by init; below)
 npx crbro-memory secret set|get|list|remove|status   # Credentials in the OS keychain (above)
+npx crbro-memory backup | backup list | backup restore FILE   # One gzipped copy, rotated; restore never lands on the live brain
+npx crbro-memory daemon on | off | status | stop   # One process owns the brain for every client (above)
+npx crbro-memory install-hooks --guard   # Stored lessons speak before a shell command runs (above)
+npx crbro-memory guard "<command>"       # What the guard would say for a command
 npx crbro-memory --help   # Help
 ```
 

package/bin/crbro.mjs

@@ -504,6 +504,164 @@ if (command === 'init') {
     console.log('');
   }).catch(console.error);
 
+} else if (command === 'daemon') {
+  // ─── One process owns the brain for every client (opt-in) ──────
+  //
+  //   crbro daemon status     is it on, who is running, how much it holds
+  //   crbro daemon on         every client of this brain becomes a thin proxy
+  //   crbro daemon off        back to one full server per client, and stop what runs
+  //   crbro daemon stop       stop the running daemon(s); clients start a new one on demand
+  //
+  // The switch is a flag inside the brain, so every client flips together the
+  // next time it starts. Nothing is lost by turning it off, or by the daemon
+  // dying: a client that cannot reach one serves itself, as before 2.5.
+  (async () => {
+    const { resolveBrainDir } = await import('../dist/engine/brain.js');
+    const ep = await import('../dist/daemon/endpoint.js');
+    const { controlDaemon } = await import('../dist/daemon/proxy.js');
+    const fs = await import('fs');
+    const root = resolveBrainDir();
+    const sub = args[1] || 'status';
+
+    const running = async () => {
+      const out = [];
+      for (const st of await ep.listStates(root)) {
+        const reply = await controlDaemon(root, 'status', st.build);
+        if (reply) { out.push({ st, reply }); continue; }
+        // No answer is not proof of death: a daemon in the middle of a rebuild
+        // answers late, and deleting its state file would orphan it — alive,
+        // holding the brain, and unreachable by every client. Only a pid the
+        // system says is gone loses its file.
+        let alive = true;
+        try { process.kill(st.pid, 0); } catch (e) { alive = e.code === 'EPERM'; }
+        if (alive) out.push({ st, reply: null });
+        else { try { fs.rmSync(ep.stateFile(root, st.build), { force: true }); } catch { /* stale file, best effort */ } }
+      }
+      return out;
+    };
+
+    if (sub === 'on' || sub === 'off') {
+      await ep.setDaemonEnabled(root, sub === 'on');
+      console.log('');
+      if (sub === 'on') {
+        console.log('  ✅ Daemon mode ON for ' + root);
+        console.log('     Restart your MCP clients (Claude Code, Claude Desktop, Codex...). The first one to start');
+        console.log('     launches the daemon; the rest attach to it. One index, one model, one writer.');
+        console.log('     Clients older than 2.5 keep running their own server — update them to get the benefit.');
+      } else {
+        for (const { st, reply } of await running()) if (reply) await controlDaemon(root, 'stop', st.build);
+        console.log('  ✅ Daemon mode OFF. Clients go back to one full server each the next time they start.');
+      }
+      console.log('');
+    } else if (sub === 'stop') {
+      const list = await running();
+      for (const { st, reply } of list) if (reply) await controlDaemon(root, 'stop', st.build);
+      console.log(list.length ? `\n  ✅ Asked ${list.length} daemon(s) to stop. Connected clients carry on: they start a new one on their next call.\n`
+                              : '\n  No daemon is running for this brain.\n');
+    } else {
+      const list = await running();
+      console.log('');
+      console.log('  🧠 CRBRO daemon');
+      console.log('  ───────────────');
+      console.log(`  Brain:    ${root}`);
+      console.log(`  Mode:     ${ep.daemonEnabled(root) ? '✅ on' : 'off  (npx crbro-memory daemon on)'}`);
+      if (list.length === 0) console.log('  Running:  none' + (ep.daemonEnabled(root) ? ' — the next client to start launches it' : ''));
+      for (const { st, reply } of list) {
+        if (!reply) { console.log(`  Running:  pid ${st.pid} · ${st.version} (${st.build}) · alive but not answering right now (busy, or another user's)`); continue; }
+        console.log(`  Running:  pid ${reply.pid} · ${reply.version} (${reply.build}) · ${reply.connections} conversation(s) · ${reply.rss_mb} MB · up ${Math.round(reply.uptime_s / 60)} min · idle exit ${reply.idle_minutes} min`);
+      }
+      if (list.length > 1) console.log('  ⚠️  More than one build is serving this brain. Point every client at the same install to share one.');
+      console.log(`  Log:      ${root}${root.includes('\\') ? '\\' : '/'}.daemon${root.includes('\\') ? '\\' : '/'}daemon.log`);
+      console.log('');
+    }
+  })().catch(e => { console.error(e.message); process.exit(1); });
+
+} else if (command === 'guard') {
+  // ─── What the PreToolUse guard would say for a command ─────────
+  //
+  //   crbro guard "firebase deploy --only hosting"
+  //   crbro guard --rebuild        write the trigger index now
+  //
+  // Reads <brain>/.search/triggers.json, the lookup crbro_consolidate
+  // derives from the error, debt and pattern ledgers. Read-only unless
+  // --rebuild is passed.
+  (async () => {
+    const { Brain } = await import('../dist/engine/brain.js');
+    const { writeTriggerIndex, triggerIndexPath, lessonsFor } = await import('../dist/engine/triggers.js');
+    const fs = await import('fs');
+    const brain = new Brain();
+    if (process.argv.includes('--rebuild')) {
+      const r = await writeTriggerIndex(brain);
+      if ('error' in r) { console.error(`  ❌ ${r.error}`); process.exit(1); }
+      console.log(`  ✅ Trigger index written: ${r.entries} lessons under ${r.keys} commands.`);
+      console.log(`     ${triggerIndexPath(brain)}`);
+    }
+    const texto = process.argv.slice(3).filter(a => !a.startsWith('--')).join(' ').trim();
+    if (!texto) {
+      if (!process.argv.includes('--rebuild')) console.log('  Usage: crbro guard "<command line>"   |   crbro guard --rebuild');
+      return;
+    }
+    let index;
+    try {
+      index = JSON.parse(fs.readFileSync(triggerIndexPath(brain), 'utf8'));
+    } catch {
+      console.log('  No trigger index yet. Run: crbro guard --rebuild (crbro_consolidate writes it too).');
+      return;
+    }
+    const lessons = lessonsFor(index, texto, 10);
+    if (lessons.length === 0) { console.log('  Nothing stored mentions that command.'); return; }
+    for (const l of lessons) console.log(`  • [${l.k}${l.d ? ' · ' + l.d : ''} · ${l.n}] ${l.t}\n`);
+  })().catch(e => { console.error(e.message); process.exit(1); });
+
+} else if (command === 'install-hooks' && process.argv.includes('--guard')) {
+  // ─── Wire the PreToolUse guard into Claude Code (opt-in) ───────
+  //
+  // Before a Bash or PowerShell call, hooks/crbro-guard.mjs looks the command
+  // up in the trigger index and adds the stored errors, debts and patterns
+  // that mention it to the model's context — once per session each, three at
+  // most. It never blocks and never asks. Remove the PreToolUse entry from
+  // ~/.claude/settings.json to uninstall.
+  import('fs').then(async fs => {
+    const settingsPath = join(homedir(), '.claude', 'settings.json');
+    const here = dirname(fileURLToPath(import.meta.url));
+    const hookDir = join(homedir(), '.claude', 'crbro-hooks');
+    const hookScript = join(hookDir, 'crbro-guard.mjs');
+    fs.mkdirSync(hookDir, { recursive: true });
+    fs.copyFileSync(join(here, '..', 'hooks', 'crbro-guard.mjs'), hookScript);
+
+    let settings = {};
+    try {
+      const raw = fs.readFileSync(settingsPath, 'utf8');
+      settings = JSON.parse(raw.charCodeAt(0) === 0xFEFF ? raw.slice(1) : raw);
+    } catch (e) {
+      if (fs.existsSync(settingsPath)) {
+        console.error(`  ❌ ${settingsPath} exists but could not be parsed — not touching it.`);
+        console.error(`     ${e.message}`);
+        process.exit(1);
+      }
+    }
+    settings.hooks = settings.hooks || {};
+    const list = settings.hooks.PreToolUse = settings.hooks.PreToolUse || [];
+    if (JSON.stringify(list).includes('crbro-guard')) {
+      console.log('  ✅ PreToolUse guard already installed. Script refreshed.');
+    } else {
+      list.push({
+        matcher: 'Bash|PowerShell',
+        hooks: [{ type: 'command', command: `node "${hookScript.split('\\').join('/')}"`, timeout: 5 }],
+      });
+      const tmp = settingsPath + '.' + process.pid + '.tmp';
+      fs.writeFileSync(tmp, JSON.stringify(settings, null, 2), 'utf8');
+      fs.renameSync(tmp, settingsPath);
+      console.log('  ✅ PreToolUse guard installed.');
+      console.log(`     ${settingsPath}`);
+    }
+    const { Brain } = await import('../dist/engine/brain.js');
+    const { writeTriggerIndex } = await import('../dist/engine/triggers.js');
+    const r = await writeTriggerIndex(new Brain());
+    if (!('error' in r)) console.log(`     Trigger index: ${r.entries} lessons under ${r.keys} commands. Try: crbro guard "git push"`);
+    console.log('     It adds context, never blocks. New sessions pick it up.');
+  }).catch(console.error);
+
 } else if (command === 'install-hooks') {
   // ─── Wire the SubagentStart hook into Claude Code ──────────────
   //
@@ -852,6 +1010,67 @@ if (command === 'init') {
     process.exit(1);
   });
 
+} else if (command === 'backup') {
+  // ─── Backup: one gzipped file per copy, rotated ────────────────
+  // `backup` makes one · `backup list` · `backup restore FILE [--into DIR]`
+  const sub = args[1] && !args[1].startsWith('--') ? args[1] : 'create';
+  const flag = (name) => { const i = args.indexOf(name); return i !== -1 ? args[i + 1] : undefined; };
+  Promise.all([import('../dist/engine/brain.js'), import('../dist/engine/backup.js')]).then(async ([{ BrainPaths }, bk]) => {
+    const paths = new BrainPaths();
+    const dir = flag('--dir') || bk.resolveBackupDir(paths.root);
+    const kb = (n) => `${(n / 1024).toFixed(0)} KB`;
+    try {
+      if (sub === 'create') {
+        const keep = flag('--keep') ? Number(flag('--keep')) : undefined;
+        const r = await bk.createBackup(paths, { dir, keep });
+        console.log('');
+        console.log(`  ✅ Backup written: ${r.path}`);
+        console.log(`     ${r.counts.neurons} neurons · ${r.counts.sessions} sessions · ${r.counts.synapses} synapses · ${kb(r.counts.bytes)} of text → ${kb(r.size_bytes)} on disk`);
+        if (r.rotated_out.length) console.log(`     Rotated out: ${r.rotated_out.join(', ')}`);
+        console.log('     Left out on purpose: the quarantine, machine tokens, the search index and the semantic runtime.');
+        if (!process.env.CRBRO_BACKUP_DIR) {
+          console.log('');
+          console.log('  ⚠️  This folder is on the same disk as the brain. It survives a bad write or a wrong');
+          console.log('     forget, not a dead disk. Point CRBRO_BACKUP_DIR at a folder that is already synced');
+          console.log('     (Drive in mirror mode, Dropbox, an external disk) to cover that too.');
+        }
+        console.log('');
+      } else if (sub === 'list') {
+        const all = await bk.listBackups(dir);
+        console.log('');
+        console.log(`  Backups in ${dir}`);
+        if (!all.length) console.log('    (none yet — run: npx crbro-memory backup)');
+        for (const b of all) console.log(`    ${b.file}   ${b.created.slice(0, 16).replace('T', ' ')} UTC   ${kb(b.size_bytes)}`);
+        console.log('');
+      } else if (sub === 'restore') {
+        const file = args[2];
+        if (!file || file.startsWith('--')) {
+          console.error('  Usage: npx crbro-memory backup restore FILE [--into DIR]');
+          process.exit(1);
+        }
+        const src = existsSync(file) ? file : join(dir, file);
+        const into = flag('--into') || join(homedir(), `.crbro-restored-${Date.now()}`);
+        const r = await bk.restoreBackup(src, into);
+        console.log('');
+        console.log(`  ✅ Restored ${r.files} files into ${r.into}`);
+        console.log('     Nothing was written over your live brain. To switch to the restored copy, close every');
+        console.log('     client using CRBRO, move ~/.crbro aside, rename this folder to ~/.crbro, then run:');
+        console.log('       npx crbro-memory reindex');
+        console.log('');
+      } else {
+        console.error('  Usage: npx crbro-memory backup [list | restore FILE [--into DIR]] [--dir DIR] [--keep N]');
+        process.exit(1);
+      }
+    } catch (err) {
+      console.error(`  ❌ ${err.message}`);
+      process.exit(1);
+    }
+  }).catch(err => {
+    console.error('  ❌ Build required. Run: npm run build');
+    console.error('  ', err.message);
+    process.exit(1);
+  });
+
 } else if (command === '--help' || command === '-h') {
   // ─── Help ──────────────────────────────────────────────────────
   console.log('');
@@ -869,6 +1088,21 @@ if (command === 'init') {
   console.log('    npx crbro-memory miner-status     Check auto-miner status');
   console.log('    npx crbro-memory remove-miner     Remove auto-miner');
   console.log('');
+  console.log('  Backup (one gzipped file per copy; consolidate makes one a day on its own):');
+  console.log('    npx crbro-memory backup           Back the brain up now (keeps the newest 7)');
+  console.log('    npx crbro-memory backup list      What there is, newest first');
+  console.log('    npx crbro-memory backup restore FILE   Unpack into a NEW folder, never over the live brain');
+  console.log('    CRBRO_BACKUP_DIR=<synced folder>  Put them somewhere that survives the disk');
+  console.log('');
+  console.log('  Guard (opt-in, Claude Code): stored lessons speak before a shell command runs:');
+  console.log('    npx crbro-memory install-hooks --guard   Wire the PreToolUse hook (adds context, never blocks)');
+  console.log('    npx crbro-memory guard "<command>"       What it would say for a command · --rebuild writes the index');
+  console.log('');
+  console.log('  Daemon (opt-in): one process owns the brain for every client — one index, one model, one writer:');
+  console.log('    npx crbro-memory daemon on | off  Switch every client of this brain, the next time each starts');
+  console.log('    npx crbro-memory daemon status    Is it on, who is running, how much it holds');
+  console.log('    npx crbro-memory daemon stop      Stop it; clients start a new one on demand');
+  console.log('');
   console.log('  Search:');
   console.log('    npx crbro-memory reindex          Rebuild the search index');
   console.log('    npx crbro-memory eval             Measure retrieval against .crbro/.eval/queries.json');

package/dist/daemon/daemon.d.ts

@@ -0,0 +1,25 @@
+import { type Engines } from '../server.js';
+import { type DaemonState } from './endpoint.js';
+export interface DaemonHandle {
+    endpoint: string;
+    state: DaemonState;
+    /** MCP conversations being served — not sockets: a status probe is not a conversation. */
+    connections(): number;
+    /** Flush, remove the state file, close every client. Resolves when done. */
+    stop(reason?: string): Promise<void>;
+    /** Resolves when the daemon has stopped, for whatever reason. */
+    stopped: Promise<string>;
+}
+export interface DaemonOptions {
+    /** Minutes with no conversation before it exits. 0 = never. Default 20, or CRBRO_DAEMON_IDLE_MIN. */
+    idleMinutes?: number;
+    /** Tests inject their own; production builds them here. */
+    engines?: Engines;
+    build?: string;
+    log?: (line: string) => void;
+}
+export declare function idleDelayMs(opt?: number, env?: NodeJS.ProcessEnv): number;
+export declare function startDaemon(options?: DaemonOptions): Promise<DaemonHandle>;
+/** `node dist/index.js --daemon`: run until idle, asked to stop, or signalled. */
+export declare function runDaemon(): Promise<void>;
+//# sourceMappingURL=daemon.d.ts.map

package/dist/daemon/daemon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon.d.ts","sourceRoot":"","sources":["../../src/daemon/daemon.ts"],"names":[],"mappings":"AAuBA,OAAO,EAA+B,KAAK,OAAO,EAAE,MAAM,cAAc,CAAC;AAIzE,OAAO,EAGwC,KAAK,WAAW,EAC9D,MAAM,eAAe,CAAC;AAYvB,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,WAAW,CAAC;IACnB,0FAA0F;IAC1F,WAAW,IAAI,MAAM,CAAC;IACtB,4EAA4E;IAC5E,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,iEAAiE;IACjE,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,qGAAqG;IACrG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,wBAAgB,WAAW,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAOtF;AAoCD,wBAAsB,WAAW,CAAC,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CA8NpF;AAED,kFAAkF;AAClF,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CA4B/C"}