klypix-mcp 1.9.0 → 1.10.1

package/bin/klypix-install.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// klypix-install — lay the project-brain down into ~/.claude/project-brain from THIS
+// package and wire the 4 Claude Code hooks into ~/.claude/settings.json. This makes
+// npm the SINGLE delivery for the WHOLE brain (hook + engine + local MCP/A2A
+// servers), so one `gh release create` (OIDC auto-publish) + `npx klypix-mcp install`
+// updates every brain on a machine — the global ~/.claude/project-brain copy serves
+// EVERY project (each project just needs a ./brain.klypix). The desktop app installs
+// the SAME flat layout, so the two delivery channels converge on one install.
+//
+//   npx klypix-mcp install            # install / update the brain on this machine
+//   npx klypix-mcp install --force    # overwrite even a newer / dev-deployed brain
+//
+// Never-throws-silently: it's an explicit CLI, so it reports what it did and exits
+// non-zero on a real failure. Never wires a broken settings.json (refuse + restore).
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = path.resolve(__dirname, '..');
+const SRC = path.join(PKG_ROOT, 'src');
+const BIN = path.join(PKG_ROOT, 'bin');
+const VERSION = (() => { try { return JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version || ''; } catch { return ''; } })();
+const FORCE = process.argv.includes('--force');
+
+const HOME = os.homedir();
+const CLAUDE_DIR = path.join(HOME, '.claude');
+const BRAIN_DIR = path.join(CLAUDE_DIR, 'project-brain');
+const SETTINGS = path.join(CLAUDE_DIR, 'settings.json');
+const HOOK_MARK = 'global-brain-hook';
+const exists = (p) => { try { fs.statSync(p); return true; } catch { return false; } };
+const fwd = (p) => p.replace(/\\/g, '/');
+function copyDir(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+        const s = path.join(src, e.name), d = path.join(dest, e.name);
+        if (e.isDirectory()) copyDir(s, d); else if (e.isFile()) fs.copyFileSync(s, d);
+    }
+}
+
+// ── Never-downgrade gate ─────────────────────────────────────────────────────
+// The brain version is a UNIFIED namespace = the klypix-mcp version, stamped by BOTH
+// the npm install (here) and the desktop bundle, so the two channels compare cleanly.
+// A dev deploy ({dev:true}) is authoritative; a strictly-newer install is not
+// downgraded. --force overrides both.
+const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
+const cur = (() => { try { return JSON.parse(fs.readFileSync(path.join(BRAIN_DIR, '.brain-version.json'), 'utf8')); } catch { return null; } })();
+if (!FORCE && cur) {
+    if (cur.dev === true) { console.log(`• A dev deploy owns ${BRAIN_DIR} (dev:true) — leaving it untouched. Re-run with --force to override.`); process.exit(0); }
+    if (cur.brainVersion && cmpSemver(cur.brainVersion, VERSION) > 0) { console.log(`• Installed brain v${cur.brainVersion} is newer than this package v${VERSION} — not downgrading. Re-run with --force to override.`); process.exit(0); }
+}
+
+// ── Flatten: the repo's bin servers import '../src/…'; the flat runtime layout needs
+// './…'. Also bake the version (the flat layout has no ../package.json). Mirrors
+// scripts/sync-bundled-mcp.mjs in the KLYPIX repo. ──────────────────────────────
+const flatten = (code) => code
+    .replace(/from '\.\.\/src\/klypix-core\.mjs'/g, "from './klypix-core.mjs'")
+    .replace(/from '\.\.\/src\/klypix-format\.mjs'/g, "from './klypix-format.mjs'")
+    .replace(/\.\.\/src\/klypix-(core|format)\.mjs/g, './klypix-$1.mjs')
+    .replace(/const PKG_VERSION = \(\(\) => \{[\s\S]*?\}\)\(\);/, `const PKG_VERSION = '${VERSION}'; // baked at install (flat layout has no package.json)`);
+
+try {
+    fs.mkdirSync(BRAIN_DIR, { recursive: true });
+    // 1) flat engine + hook scripts (their imports are already './…' → verbatim)
+    let n = 0;
+    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs']) {
+        const s = path.join(SRC, f); if (exists(s)) { fs.writeFileSync(path.join(BRAIN_DIR, f), fs.readFileSync(s, 'utf8')); n++; }
+    }
+    // 2) the two servers, flattened to the *-server.mjs names the runtime/config expect
+    for (const [src, dst] of [['klypix-mcp.mjs', 'klypix-mcp-server.mjs'], ['klypix-a2a.mjs', 'klypix-a2a-server.mjs']]) {
+        const s = path.join(BIN, src); if (exists(s)) { fs.writeFileSync(path.join(BRAIN_DIR, dst), flatten(fs.readFileSync(s, 'utf8'))); n++; }
+    }
+    // 3) runtime dependency CLOSURE (jszip+fractional-indexing for the hook/engine,
+    //    @modelcontextprotocol/sdk+zod for the local MCP server). Resolve each via
+    //    createRequire so it's found wherever the package manager put it — CRITICAL
+    //    for `npx`, which HOISTS deps to its cache root (not PKG_ROOT/node_modules).
+    //    Walk transitive deps resolved FROM each package's own context (handles
+    //    nesting). @huggingface/transformers (optional, huge) is intentionally
+    //    skipped — semantic recall degrades to lexical until the host warms it.
+    // Resolve a package DIR by walking node_modules upward (Node-style): checks
+    // fromDir/node_modules/<name>, then each parent — so it finds hoisted deps under
+    // npx AND nested ones. fs-based on purpose: require.resolve('<name>/package.json')
+    // is blocked by restrictive "exports" (e.g. fractional-indexing v3) and would
+    // silently drop a dep the hook needs.
+    const destMods = path.join(BRAIN_DIR, 'node_modules');
+    const findPkgDir = (name, fromDir) => {
+        let dir = fromDir;
+        for (; ;) {
+            const cand = path.join(dir, 'node_modules', ...name.split('/'));
+            if (exists(path.join(cand, 'package.json'))) return cand;
+            const parent = path.dirname(dir);
+            if (parent === dir) return null;
+            dir = parent;
+        }
+    };
+    const seen = new Set();
+    const queue = ['jszip', 'fractional-indexing', '@modelcontextprotocol/sdk', 'zod'].map(name => ({ name, fromDir: PKG_ROOT }));
+    let deps = 0; const missing = [];
+    while (queue.length) {
+        const { name, fromDir } = queue.shift();
+        if (seen.has(name)) continue; seen.add(name);
+        const dir = findPkgDir(name, fromDir);
+        if (!dir) { missing.push(name); continue; }
+        if (!exists(path.join(destMods, name))) { copyDir(dir, path.join(destMods, name)); deps++; }
+        try { const pj = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); for (const d of Object.keys(pj?.dependencies || {})) queue.push({ name: d, fromDir: dir }); } catch { /* no readable package.json */ }
+    }
+    if (missing.length) { console.error(`✗ could not resolve required dep(s): ${missing.join(', ')} — aborting (the brain hook needs them).`); process.exit(1); }
+    // 4) mark the dir an ESM package
+    fs.writeFileSync(path.join(BRAIN_DIR, 'package.json'), JSON.stringify({ name: 'klypix-project-brain', private: true, type: 'module' }, null, 2));
+
+    // 5) wire the 4 hooks into settings.json (refuse on invalid JSON; back up; atomic)
+    const brainCmd = (arg) => `node "${fwd(path.join(BRAIN_DIR, 'global-brain-hook.mjs'))}"${arg ? ' ' + arg : ''}`;
+    const GROUPS = [
+        ['SessionStart', { matcher: 'startup|resume', hooks: [{ type: 'command', command: brainCmd('') }] }],
+        ['UserPromptSubmit', { hooks: [{ type: 'command', command: brainCmd('--prompt'), timeout: 10 }] }],
+        ['Stop', { hooks: [{ type: 'command', command: brainCmd('--capture') }] }],
+        ['PostToolUse', { matcher: 'Bash|PowerShell|Edit|Write', hooks: [{ type: 'command', command: brainCmd('--live'), timeout: 10 }] }],
+    ];
+    const stripOurs = (arr) => (Array.isArray(arr) ? arr : [])
+        .map(g => (g && Array.isArray(g.hooks)) ? { ...g, hooks: g.hooks.filter(h => !(typeof h?.command === 'string' && h.command.includes(HOOK_MARK))) } : g)
+        .filter(g => !g || !Array.isArray(g.hooks) || g.hooks.length > 0);
+    let settings = {};
+    let rawSettings = '';
+    if (exists(SETTINGS)) {
+        rawSettings = fs.readFileSync(SETTINGS, 'utf8');
+        if (rawSettings.trim()) {
+            try { settings = JSON.parse(rawSettings); }
+            catch (e) { console.error(`✗ ${SETTINGS} is invalid JSON (${e.message}). Fix it and re-run — refusing to overwrite a broken config.`); process.exit(1); }
+        }
+    }
+    if (!settings.hooks || typeof settings.hooks !== 'object' || Array.isArray(settings.hooks)) settings.hooks = {};
+    for (const [evt, entry] of GROUPS) { const cleaned = stripOurs(settings.hooks[evt]); cleaned.push(JSON.parse(JSON.stringify(entry))); settings.hooks[evt] = cleaned; }
+    fs.mkdirSync(CLAUDE_DIR, { recursive: true });
+    if (rawSettings) { try { fs.writeFileSync(SETTINGS + '.klypix-bak', rawSettings, 'utf8'); } catch { /* best-effort backup */ } }
+    const tmp = SETTINGS + '.klypix-tmp';
+    fs.writeFileSync(tmp, JSON.stringify(settings, null, 2), 'utf8');
+    JSON.parse(fs.readFileSync(tmp, 'utf8'));   // verify before swap
+    fs.renameSync(tmp, SETTINGS);
+
+    // 6) stamp the install (unified brain version → never-downgrade across channels)
+    fs.writeFileSync(path.join(BRAIN_DIR, '.brain-version.json'), JSON.stringify({ brainVersion: VERSION, via: 'npm', dirty: false, installedAt: new Date().toISOString() }, null, 2));
+
+    console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
+    console.log('✓ wired 4 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) → settings.json');
+    console.log('  Every project with a ./brain.klypix now auto-reads its brief + captures decisions. Restart open Claude Code sessions to load the hooks.');
+} catch (e) {
+    console.error(`✗ install failed: ${e?.message || e}`);
+    process.exit(1);
+}

package/bin/klypix-mcp.mjs

@@ -34,6 +34,13 @@ const PKG_VERSION = (() => { try { return createRequire(import.meta.url)('../pac
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
 const log = (...a) => console.error('[klypix-mcp]', ...a);
 
+// `npx klypix-mcp install` — lay the WHOLE brain (hook + engine + local servers)
+// into ~/.claude/project-brain and wire the Claude Code hooks. This is the single
+// agent-neutral installer, so a brain release reaches every machine via one npm
+// publish + this command (the global brain serves every project). Runs before any
+// server setup; delegates to the dedicated bin so `npx klypix-install` also works.
+if (process.argv[2] === 'install') { await import('./klypix-install.mjs'); process.exit(0); }
+
 // `npx klypix-mcp init` — 60-second onboarding: seed a starter project brain in
 // the current folder so a new user's FIRST contact isn't an empty vault, then
 // print a paste-ready MCP config. Runs before any server setup.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.9.0",
+  "version": "1.10.1",
   "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
   "type": "module",
   "license": "MIT",
@@ -29,7 +29,8 @@
     "klypix-a2a": "bin/klypix-a2a.mjs",
     "klypix-read": "bin/klypix-read.mjs",
     "klypix-write": "bin/klypix-write.mjs",
-    "klypix-append": "bin/klypix-append.mjs"
+    "klypix-append": "bin/klypix-append.mjs",
+    "klypix-install": "bin/klypix-install.mjs"
   },
   "main": "index.mjs",
   "exports": {

package/src/brain-git-hook.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// brain-git-hook — agent-NEUTRAL commit capture for ./brain.klypix.
+//
+// Installed by KLYPIX as a git post-commit / post-merge hook (Settings → connect
+// a project's brain). It captures rationale-bearing feat/fix/perf commit BODIES
+// into the project brain regardless of WHICH agent (Cursor, Cline, Codex, or a
+// human) made the commit — the universal half of the Claude-Code Stop hook,
+// which keys off the COMMIT rather than an agent-specific transcript.
+//
+// Bulletproof by contract (it runs on EVERY commit in a connected repo): instant
+// no-op when there's no ./brain.klypix, NEVER throws, ALWAYS exits 0. It is the
+// SAME capture rule the Claude-Code hook uses (CC_RE + body>=12 rationale gate).
+//
+// Two safety properties for the case where a repo ALSO runs the Claude-Code Stop
+// hook (the dogfood scenario — both would otherwise capture the same commit):
+//   • No double-record — captureIntoBrain does NOT dedup, so this hook reads the
+//     brain inside the lock and SKIPS any commit whose `#commit-<7>` tag is
+//     already present (catches both a re-run and the Claude-Code hook's copy).
+//   • No lost write — it takes the SAME advisory `.claude/brain-capture.lock` the
+//     Stop hook uses, so a concurrent post-commit + Stop serialize (atomicWrite
+//     stops corruption, the lock stops last-writer-wins update loss).
+//
+// Lives in the project-brain bundle beside klypix-format.mjs (which it imports
+// for parse/capture/tidy/atomic-write); a tiny per-repo last-commit file keeps it
+// incremental + flood-proof (baselines to HEAD on first run, re-baselines on a
+// rewritten history).
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+const CWD = process.argv[2] || process.cwd();
+const BRAIN = path.resolve(CWD, 'brain.klypix');
+const STATE = path.resolve(CWD, '.claude', 'brain-last-commit-git');
+const LOCK = path.resolve(CWD, '.claude', 'brain-capture.lock'); // SAME lock the Claude-Code Stop hook uses
+
+// Advisory lockfile (mirrors global-brain-hook.mjs): O_EXCL create wins; a held
+// lock is waited on (sync sleep, no busy-spin); a STALE lock is stolen so a
+// crashed writer can't wedge the brain. Best-effort — write anyway past budget.
+const LOCK_STALE_MS = 15000;
+const sleepSync = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* */ } };
+function acquireLock(lockPath, { tries = 60, waitMs = 60 } = {}) {
+    try { fs.mkdirSync(path.dirname(lockPath), { recursive: true }); } catch { /* */ }
+    for (let i = 0; i < tries; i++) {
+        try { const fd = fs.openSync(lockPath, 'wx'); fs.writeSync(fd, String(process.pid)); fs.closeSync(fd); return true; }
+        catch (e) {
+            if (e && e.code !== 'EEXIST') return false;
+            try { if (Date.now() - fs.statSync(lockPath).mtimeMs > LOCK_STALE_MS) { fs.unlinkSync(lockPath); continue; } } catch { /* lost a race on the stale file — retry */ }
+            sleepSync(waitMs);
+        }
+    }
+    return false;
+}
+function releaseLock(lockPath) { try { fs.unlinkSync(lockPath); } catch { /* */ } }
+
+const git = (a) => execSync(`git ${a}`, { cwd: CWD, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000 }).trim();
+const slug = (s) => String(s).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const CC_RE = /^(feat|fix|perf)(?:\(([^)]+)\))?!?:\s*(.+)$/i;
+
+function commitToCard(c) {
+    const m = CC_RE.exec(c.subject);
+    if (!m) return null;                                            // only feat / fix / perf
+    const body = c.body.replace(/\s+/g, ' ').trim();
+    if (body.length < 12) return null;                             // rationale-bearing only — not a log dump
+    const type = m[1].toLowerCase(), scope = (m[2] || '').trim(), desc = m[3].trim();
+    const area = scope || (type === 'feat' ? 'Milestones' : 'Fixes');
+    const prefix = type === 'feat' ? '🏁 ' : '';
+    return {
+        text: `${area}: ${prefix}${desc}\n\n${body.slice(0, 400)}\n#${slug(area)} #commit-${c.hash.slice(0, 7)}`,
+        area, borderColor: type === 'feat' ? 'rgba(59,130,246,0.8)' : 'rgba(16,185,129,0.6)', createdVia: 'git',
+    };
+}
+function parseLog(raw) {
+    return String(raw).split('\x1e').map(s => s.trim()).filter(Boolean).map(rec => {
+        const p = rec.split('\x1f');
+        return { hash: (p[0] || '').trim(), subject: (p[1] || '').trim(), body: (p[2] || '').trim() };
+    }).filter(c => c.hash && c.subject);
+}
+const readPrev = () => { try { return fs.readFileSync(STATE, 'utf8').trim() || null; } catch { return null; } };
+const writePrev = (s) => { try { fs.mkdirSync(path.dirname(STATE), { recursive: true }); fs.writeFileSync(STATE, String(s || '')); } catch { /* best-effort */ } };
+
+async function main() {
+    if (!fs.existsSync(BRAIN)) return;                              // not a brain project → instant no-op
+    let head = ''; try { head = git('rev-parse HEAD'); } catch { return; }
+    if (!head) return;
+    const prev = readPrev();
+    if (!prev) { writePrev(head); return; }                        // BASELINE: record HEAD, capture nothing
+    if (prev === head) return;                                     // nothing new
+    try { execSync(`git merge-base --is-ancestor ${prev} HEAD`, { cwd: CWD, stdio: 'ignore', timeout: 2000 }); }
+    catch { writePrev(head); return; }                             // history rewritten → re-baseline, don't dump
+    let raw = ''; try { raw = git(`log ${prev}..HEAD --no-merges --format=%x1e%H%x1f%s%x1f%b`); } catch { writePrev(head); return; }
+    const candidates = parseLog(raw).slice(0, 15)
+        .map(c => ({ card: commitToCard(c), hash7: c.hash.slice(0, 7).toLowerCase() }))
+        .filter(x => x.card);
+    if (!candidates.length) { writePrev(head); return; }
+
+    const lib = await import('./klypix-format.mjs');               // lazy: only when there's something to write
+    // Read-modify-write UNDER the shared lock so a concurrent Claude-Code Stop
+    // hook can't clobber this batch (or vice-versa). Inside the lock, dedup
+    // against commits ALREADY in the brain so neither a re-run nor the Stop hook
+    // double-records the same commit.
+    const gotLock = acquireLock(LOCK);
+    try {
+        const buf = fs.readFileSync(BRAIN);
+        const already = new Set();
+        try {
+            const { struct } = await lib.parseKlypix(buf);
+            for (const c of (struct.cards || []))
+                for (const m of String(c.text || '').matchAll(/#commit-([0-9a-f]{7})/gi)) already.add(m[1].toLowerCase());
+        } catch { /* parse failed → don't dedup; atomicWrite re-verifies the result anyway */ }
+        const cards = candidates.filter(x => !already.has(x.hash7)).map(x => x.card);
+        if (!cards.length) { writePrev(head); return; }            // every new commit already recorded (e.g. by the Stop hook)
+        const res = await lib.captureIntoBrain(buf, {
+            cards: cards.map(c => ({ text: c.text, color: '#e8e8ed', borderColor: c.borderColor, area: c.area, createdVia: c.createdVia })),
+        });
+        let out = res.buffer; try { out = (await lib.tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
+        await lib.atomicWrite(BRAIN, out);
+        writePrev(head);
+        try { process.stderr.write(`[klypix-brain] git capture: ${res.stats?.added ?? cards.length} commit card(s) → brain.klypix\n`); } catch { /* */ }
+    } finally {
+        if (gotLock) releaseLock(LOCK);
+    }
+}
+main().catch(() => { /* never break a commit */ }).finally(() => process.exit(0));

package/src/brain-note.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// brain-note — a DELIBERATE, marker-aware write to a .klypix brain (cwd-keyed).
+//
+// The Claude-Code / Codex-via-bash twin of the brain_note MCP tool: the SAME
+// capture engine (supersede / resolve / close-link / update / dedup) as the Stop-
+// hook harvest, but ON DEMAND — so a decision / lock-note / open question lands the
+// instant you run it (and a concurrent session's next prompt can see it) instead of
+// waiting for Stop. cwd-keyed: it writes ./brain.klypix in the current project, the
+// SAME brain the global hook reads — no MCP vault mismatch, no session-id needed.
+//
+// Usage:
+//   node brain-note.mjs "Auth: switch to refresh tokens — sessions don't scale"
+//   node brain-note.mjs "Lock: refactoring src/auth/** for ~1h, hands off" --marker !
+//   node brain-note.mjs "shipped v1.6.0" --marker resolve --closes "v1.6.0 release"
+//   echo '{"text":"...","area":"Auth","marker":"?"}' | node brain-note.mjs
+//
+// --marker:  (none)=decision · ?/question · !/milestone · ✓/resolve · ~/update
+// --area X   route into the [Area] container (also a #tag) · --closes "<title>"
+// Optional trailing path picks a different .klypix (default ./brain.klypix).
+import fs from 'fs';
+import path from 'path';
+import { captureIntoBrain, tidyBrain, atomicWrite, noteToCaptureInput } from './klypix-format.mjs';
+
+const MARKERS = { '': '', '?': '?', '!': '!', '✓': '✓', '~': '~', question: '?', milestone: '!', resolve: '✓', update: '~', decision: '', done: '✓' };
+const normMarker = (m) => MARKERS[String(m || '').toLowerCase()] ?? '';
+
+function parseArgs(argv) {
+    const out = { text: '', area: '', marker: '', closes: '', file: '' };
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--area') out.area = argv[++i] || '';
+        else if (a === '--marker' || a === '-m') out.marker = normMarker(argv[++i]);
+        else if (a === '--closes') out.closes = argv[++i] || '';
+        else rest.push(a);
+    }
+    // A trailing .klypix/.any token is the target file; the rest is the note text.
+    if (rest.length && /\.(klypix|any)$/i.test(rest[rest.length - 1])) out.file = rest.pop();
+    out.text = rest.join(' ').trim();
+    return out;
+}
+// Read JSON or raw text from a PIPED stdin only (a TTY would block).
+function readStdin() {
+    try { if (process.stdin.isTTY) return ''; return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+let opts = parseArgs(process.argv.slice(2));
+if (!opts.text) {
+    const raw = readStdin().trim();
+    if (raw) {
+        try { const j = JSON.parse(raw); opts = { ...opts, ...j, marker: normMarker(j.marker ?? opts.marker) }; }
+        catch { opts.text = raw; }
+    }
+}
+const file = path.resolve(opts.file || 'brain.klypix');
+if (!opts.text) { console.error('brain-note: nothing to write — pass a note as an arg, or JSON/text on stdin.'); process.exit(1); }
+if (!fs.existsSync(file)) { console.error(`brain-note: no brain at ${file} (run from a project with ./brain.klypix, or pass a path).`); process.exit(1); }
+
+const input = noteToCaptureInput({ text: opts.text, area: opts.area, marker: opts.marker, closes: opts.closes, createdVia: 'cli' });
+try {
+    const res = await captureIntoBrain(fs.readFileSync(file), input);
+    let out = res.buffer;
+    try { out = (await tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
+    await atomicWrite(file, out);
+    const s = res.stats || {};
+    const bits = [`${s.added || 0} added`];
+    for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
+    console.error(`✓ brain-note → ${path.basename(file)} (${bits.join(' · ')})`);
+} catch (e) {
+    console.error(`brain-note failed (brain unchanged): ${e?.message || e}`);
+    process.exit(1);
+}

package/src/brain-semantic.mjs

@@ -0,0 +1,94 @@
+// brain-semantic — OPTIONAL on-device semantic lane for the project-brain hook.
+//
+// WHY a separate module: the hook's per-prompt recall is LEXICAL (keyword) — fast
+// and bulletproof. Semantic (embedding) recall would understand paraphrase, but the
+// hook is a ONE-SHOT process (no daemon allowed), so loading the 23MB MiniLM model
+// costs ~550ms EVERY prompt — unacceptable on the common path. The measured-and-
+// verified design is therefore: run semantic ONLY when lexical found nothing (the
+// paraphrase / keyword-miss case, where you'd otherwise get zero recall), pay the
+// cost just there, timeout-bounded, and read-only.
+//
+// CONTRACT (mirrors the hook): never throw → returns null on ANY failure; never
+// blocks beyond `timeoutMs`; NEVER embeds cards in-process (embedding all cards is
+// a 10s–195s stall — we read whatever the MCP host already warmed and embed ONLY
+// the short query). Transformers is a DYNAMIC, OPTIONAL import — this module's only
+// static deps are node builtins, so the hook gains zero new static deps and stays a
+// no-op until the user runs the one-click semantic install.
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+
+const PB_DIR = path.join(os.homedir(), '.claude', 'project-brain');
+const EMB_DIR = path.join(PB_DIR, 'embeddings');
+const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
+
+// Memoized within THIS process only (a one-shot hook run) — across prompts it
+// reloads cold, which is exactly why we only pay it on a lexical miss.
+let _embedder;
+function getEmbedder() {
+    if (_embedder !== undefined) return _embedder;
+    _embedder = (async () => {
+        let t;
+        try { t = await import('@huggingface/transformers'); }
+        catch {
+            const base = path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers', 'dist');
+            let last;
+            for (const f of ['transformers.node.mjs', 'transformers.mjs']) {
+                try { t = await import(new URL('file:///' + path.join(base, f).replace(/\\/g, '/')).href); last = null; break; }
+                catch (e) { last = e; }
+            }
+            if (!t) throw last;
+        }
+        t.env.cacheDir = path.join(PB_DIR, 'hf-cache');
+        return await t.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' });
+    })().catch(() => null);   // not installed / load fail → null → lexical fallback
+    return _embedder;
+}
+
+async function embedTexts(pipe, texts) {
+    const out = await pipe(texts, { pooling: 'mean', normalize: true });
+    const [n, d] = out.dims;
+    const vecs = [];
+    for (let i = 0; i < n; i++) vecs.push(Array.from(out.data.slice(i * d, (i + 1) * d)));
+    return vecs;
+}
+// Vectors are unit-normalized, so dot == cosine.
+export const dot = (a, b) => { let s = 0; const n = Math.min(a.length, b.length); for (let i = 0; i < n; i++) s += a[i] * b[i]; return s; };
+
+// READ-ONLY card-vector cache — NEVER embeds or writes (embedding all cards in the
+// per-prompt process is the multi-second stall we forbid). Reuses the SAME warm
+// cache the MCP host fills, keyed sha1(path, slashes-only). The MCP keys WITHOUT
+// lowercasing the drive letter, so a brain can have an `e:`-keyed and an `E:`-keyed
+// cache file — try the drive-case variants so we hit whichever exists.
+function readCachedVecs(brainPath, cards) {
+    const slashed = String(brainPath).replace(/\\/g, '/');
+    const variants = [...new Set([
+        slashed,
+        slashed.replace(/^([a-zA-Z]):/, (_m, d) => d.toLowerCase() + ':'),
+        slashed.replace(/^([a-zA-Z]):/, (_m, d) => d.toUpperCase() + ':'),
+    ])];
+    let cache = null;
+    for (const v of variants) {
+        try { const c = JSON.parse(fs.readFileSync(path.join(EMB_DIR, sha1(v) + '.json'), 'utf8')); if (c && c.cards) { cache = c; break; } } catch { /* try next variant */ }
+    }
+    const map = new Map();
+    if (cache && cache.cards) for (const c of cards) { const e = cache.cards[c.id]; if (e && e.v) map.set(c.id, e.v); }
+    return map;
+}
+
+// Entry point: embed the QUERY (needs the model) + read cached card vectors.
+// Returns { qv, vecsMap, dot } or null (not installed / timeout / any failure →
+// the hook keeps its exact lexical behavior). NEVER throws, NEVER embeds cards.
+export async function semanticVecs(brainPath, struct, query, { timeoutMs = 1200 } = {}) {
+    try {
+        const pipe = await Promise.race([getEmbedder(), new Promise(r => setTimeout(() => r(null), timeoutMs))]);
+        if (!pipe) return null;
+        const q = String(query || '').toLowerCase().trim();
+        if (!q) return null;
+        const [qv] = await embedTexts(pipe, [q]);
+        if (!qv) return null;
+        const vecsMap = readCachedVecs(brainPath, (struct && struct.cards) || []);
+        return { qv, vecsMap, dot };
+    } catch { return null; }
+}