klypix-mcp 1.0.4 → 1.2.0

package/README.md

@@ -47,7 +47,6 @@ notes into a board,"* or *"add a card with the decision we just made."*
 | `search_canvases` | Search across canvases by name + content |
 | `create_canvas` | Create a new `.klypix` from cards + connections |
 | `add_to_canvas` | Append cards/connections to an existing canvas (positions preserved) |
-| `search_all_brains` | Search every registered project brain (`~/.claude/project-brain/registry.json`) — cross-project recall |
 
 ## Use it as a library
 

package/bin/klypix-mcp.mjs

@@ -18,14 +18,39 @@
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
+import crypto from 'crypto';
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { parseKlypix, buildKlypix, appendToKlypix, structToMarkdown, atomicWrite } from '../src/klypix-format.mjs';
+import { parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown, brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite } from '../src/klypix-format.mjs';
 
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
 const log = (...a) => console.error('[klypix-mcp]', ...a);
 
+// `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. (Dormant for
+// the in-app bundled server, which always launches with --vault.)
+if (process.argv[2] === 'init') {
+    const target = path.resolve(process.cwd(), 'brain.klypix');
+    if (fs.existsSync(target)) { console.error(`brain.klypix already exists in ${process.cwd()} — not overwriting.`); process.exit(0); }
+    const buf = await buildKlypixMap({
+        title: 'project brain',
+        areas: [
+            { title: 'Goal', cards: [{ text: '❓ What is this project for, and for whom?\nAgent: survey the repo on your first session and replace this with the real goal.' }] },
+            { title: 'Architecture', cards: [{ text: '❓ Key components and how they fit.\nAgent: record the actual shape from the repo — only what a new session must know.' }] },
+            { title: 'Decisions', cards: [{ text: 'Decisions land here automatically: agents emit `🧠 BRAIN [Area]: …` markers; a new decision that replaces an old one archives it (superseded). Resolve finished items with `✓`, correct in place with `~`. Drag any card into 📌 Focus to make it lead every session brief.' }] },
+            { title: 'Pending / next', cards: [{ text: 'What is in flight and what comes next. Close finished items with the ✓ marker.' }] },
+            { title: 'Open questions', cards: [{ text: 'Unresolved questions (the ❓ marker) live here — the session brief surfaces them first.' }] },
+            { title: '📌 Focus', cards: [{ text: 'Drag any card into this area to make it lead every session brief — steer your agent by moving cards.' }] },
+        ],
+    });
+    fs.writeFileSync(target, buf);
+    const cfg = JSON.stringify({ mcpServers: { 'klypix-canvas': { command: 'npx', args: ['-y', 'klypix-mcp', '--vault', process.cwd().replace(/\\/g, '/')] } } }, null, 2);
+    console.error(`✓ Created ${target}\n\nAdd this to your MCP client config (.mcp.json / claude_desktop_config.json):\n\n${cfg}\n\nThen ask your agent to read the canvas "brain" — it now has a project memory.`);
+    process.exit(0);
+}
+
 const vaultArgIdx = process.argv.indexOf('--vault');
 const VAULT = path.resolve(
     vaultArgIdx >= 0 ? process.argv[vaultArgIdx + 1]
@@ -152,6 +177,15 @@ server.registerTool('search_canvases', {
 }, async ({ query }) => {
     const q = String(query || '').trim().toLowerCase();
     if (!q) return { content: [{ type: 'text', text: 'Provide a non-empty query.' }], isError: true };
+    // Tokenize so a multi-word query ("window snap") matches a card holding ANY
+    // term — the old verbatim `.includes(fullQuery)` only fired on an exact
+    // contiguous substring, so most multi-word searches silently found nothing.
+    // NOTE: deliberately NOT reusing the brief's scoreCardsAgainstQuery (its
+    // precision sibling, now shared in src/klypix-format.mjs) — that one skips
+    // containers + archived cards and applies a minScore floor, all of which
+    // would hide results a recall-first finder is expected to surface.
+    const terms = q.split(/\s+/).filter(Boolean);
+    const hit = (s) => { const v = String(s || '').toLowerCase(); return terms.some(t => v.includes(t)); };
     const hits = [];
     for (const f of walkVault()) {
         let struct;
@@ -159,11 +193,11 @@ server.registerTool('search_canvases', {
         const rel = path.relative(VAULT, f);
         // Match the canvas TITLE + FILENAME too — not just card text — so
         // searching a canvas by its name (e.g. "SS2") actually finds it.
-        const nameMatch = (struct.title || '').toLowerCase().includes(q) || rel.toLowerCase().includes(q);
+        const nameMatch = hit(struct.title) || hit(rel);
         const matched = struct.cards.filter(c =>
-            (c.title || '').toLowerCase().includes(q) ||
-            String(c.text || '').toLowerCase().includes(q) ||
-            (c.tags || []).some(t => ('#' + t).toLowerCase().includes(q)));
+            hit(c.title) ||
+            hit(c.text) ||
+            (c.tags || []).some(t => hit('#' + t)));
         if (nameMatch || matched.length) {
             // Rich hits: type + id + position + tags + a longer snippet, so the
             // agent can FIND a card (and tell duplicates apart) before it WRITES.
@@ -179,46 +213,135 @@ server.registerTool('search_canvases', {
     return { content: [{ type: 'text', text: hits.length ? `# Matches for "${query}"\n\n${hits.join('\n\n')}` : `No matches for "${query}" in ${VAULT}.` }] };
 });
 
+// ── On-device semantic memory ────────────────────────────────────────────────
+// Embeddings run INSIDE this long-lived server (the hook stays instant), 100%
+// local: transformers.js (WASM) + a 23MB MiniLM model cached under
+// ~/.claude/project-brain/hf-cache on first use. Per-brain vectors are cached
+// incrementally (content-hashed per card) in ~/.claude/project-brain/embeddings/
+// — brains themselves are never mutated by search. Everything degrades to
+// lexical scoring gracefully: no lib, no model, no network → search still works.
+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');
+let embedderPromise = null;
+function getEmbedder() {
+    if (!embedderPromise) {
+        embedderPromise = (async () => {
+            // Dual-path: (1) bare specifier — npx/npm installs ship the lib;
+            // (2) ~/.claude/project-brain/semantic — where KLYPIX's one-click
+            // "semantic memory" install places it for the bundled server
+            // (the ONNX runtimes are ~350MB unpacked, far too heavy to bundle
+            // in the installer payload).
+            let t;
+            try { t = await import('@huggingface/transformers'); }
+            catch {
+                const local = path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers', 'dist', 'transformers.mjs');
+                t = await import(new URL('file:///' + local.replace(/\\/g, '/')).href);
+            }
+            t.env.cacheDir = path.join(PB_DIR, 'hf-cache');
+            return await t.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' });
+        })().catch(e => { log('semantic unavailable (lexical fallback):', e?.message || e); return null; });
+    }
+    return embedderPromise;
+}
+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;
+}
+const dot = (a, b) => { let s = 0; for (let i = 0; i < a.length; i++) s += a[i] * b[i]; return s; };
+// Incremental per-brain vector cache: only new/changed cards get embedded.
+async function vectorsForBrain(pipe, brainPath, cards) {
+    const file = path.join(EMB_DIR, sha1(brainPath.replace(/\\/g, '/')) + '.json');
+    let cache = { v: 1, cards: {} };
+    try { cache = JSON.parse(fs.readFileSync(file, 'utf8')); } catch { /* fresh */ }
+    const want = cards.filter(c => c.type !== 'container' && (c.text || '').trim());
+    const missing = want.filter(c => cache.cards[c.id]?.h !== sha1(String(c.text)));
+    if (missing.length) {
+        const vecs = await embedTexts(pipe, missing.map(c => String(c.text).slice(0, 1500)));
+        missing.forEach((c, i) => { cache.cards[c.id] = { h: sha1(String(c.text)), v: vecs[i] }; });
+        const live = new Set(want.map(c => c.id));
+        for (const id of Object.keys(cache.cards)) if (!live.has(id)) delete cache.cards[id];
+        try { fs.mkdirSync(EMB_DIR, { recursive: true }); fs.writeFileSync(file, JSON.stringify(cache)); } catch { /* cache is best-effort */ }
+    }
+    const map = new Map();
+    for (const c of want) { const e = cache.cards[c.id]; if (e?.v) map.set(c.id, e.v); }
+    return map;
+}
+// Death date of an archived card (for as-of queries): the supersede/resolve stamp.
+const deathDateOf = (text) => { const m = /(?:↩︎ superseded|✅) (\d{4}-\d{2}-\d{2})/.exec(String(text)); return m ? Date.parse(m[1]) : null; };
+
 // Cross-project memory: search EVERY brain this machine has touched, not just
 // this vault. The SessionStart/Stop hook registers each ./brain.klypix it runs
 // against into ~/.claude/project-brain/registry.json — so simply having worked
 // in a project makes its decisions findable from any other project ("what did
-// I decide about auth — in ANY project?"). Lexical scoring v1: term hits
-// weighted title>tag>text, with a recency boost; the on-device embedding
-// upgrade ranks the same index later without changing this tool's shape.
+// I decide about auth — in ANY project?"). Hybrid ranking: on-device semantic
+// similarity (when the local model is ready) blended with lexical term hits;
+// as_of answers "what was true on <date>" via createdAt + supersession stamps.
 server.registerTool('search_all_brains', {
     title: 'Search every project brain on this machine',
-    description: 'Cross-project memory search: looks through every brain.klypix this machine has worked with (auto-registered by the brain hook), not just the current vault. Use when the answer may live in ANOTHER project\'s decisions.',
-    inputSchema: { query: z.string().describe('What to find across all project brains.') },
-}, async ({ query }) => {
+    description: 'Cross-project memory search: looks through every brain.klypix this machine has worked with (auto-registered by the brain hook), not just the current vault. Semantic (on-device) + lexical hybrid ranking. Use when the answer may live in ANOTHER project\'s decisions. Optional as_of (YYYY-MM-DD) answers "what was true then" — superseded cards count as live if they were current at that date.',
+    inputSchema: {
+        query: z.string().describe('What to find across all project brains.'),
+        as_of: z.string().optional().describe('Optional YYYY-MM-DD: rank what was TRUE at that date (time-travel query).'),
+    },
+}, async ({ query, as_of }) => {
     const q = String(query || '').trim().toLowerCase();
     if (!q) return { content: [{ type: 'text', text: 'Provide a non-empty query.' }], isError: true };
-    const reg = path.join(os.homedir(), '.claude', 'project-brain', 'registry.json');
+    const reg = path.join(PB_DIR, 'registry.json');
     let brains = [];
     try { brains = (JSON.parse(fs.readFileSync(reg, 'utf8')).brains || []).filter(b => b && b.path); } catch { /* no registry yet */ }
     if (!brains.length) return { content: [{ type: 'text', text: 'No brains registered yet — the brain hook registers each project as you work in it.' }] };
     const terms = q.split(/[^\p{L}\p{N}#]+/u).filter(t => t.length >= 3);
     if (!terms.length) return { content: [{ type: 'text', text: 'Query too short — use words of 3+ characters.' }], isError: true };
+    const asOfTs = as_of ? Date.parse(as_of) : null;
+    if (as_of && Number.isNaN(asOfTs)) return { content: [{ type: 'text', text: `Bad as_of date: "${as_of}" — use YYYY-MM-DD.` }], isError: true };
+
+    // Semantic lane: wait briefly for the embedder; first-ever use downloads
+    // the model in the background — searches stay lexical until it's warm.
+    const pipe = await Promise.race([getEmbedder(), new Promise(r => setTimeout(() => r(null), 20_000))]);
+    let qv = null;
+    if (pipe) { try { [qv] = await embedTexts(pipe, [q]); } catch { /* lexical only */ } }
+
     const fresh = Date.now() - 30 * 86_400_000;
     const scored = [];
     for (const b of brains) {
         let struct;
         try { ({ struct } = await parseKlypix(fs.readFileSync(b.path))); } catch { continue; }
+        let vecs = null;
+        if (qv) { try { vecs = await vectorsForBrain(pipe, b.path, struct.cards); } catch { /* lexical for this brain */ } }
         for (const c of struct.cards) {
             if (c.type === 'container') continue;
             const text = String(c.text || '').toLowerCase();
+            const isArchived = /^archive$/i.test(c.area || '');
+            if (asOfTs != null) {
+                if ((c.createdAt || 0) > asOfTs) continue;                  // didn't exist yet
+                const died = isArchived ? deathDateOf(c.text) : null;
+                if (died != null && died <= asOfTs) continue;               // already superseded then
+            }
+            let lex = 0;
             const title = String(c.title || '').toLowerCase();
             const tags = (c.tags || []).map(t => ('#' + t).toLowerCase());
-            let score = 0;
             for (const t of terms) {
-                if (title.includes(t)) score += 3;
-                if (tags.some(g => g.includes(t))) score += 2;
-                if (text.includes(t)) score += 1;
+                if (title.includes(t)) lex += 3;
+                if (tags.some(g => g.includes(t))) lex += 2;
+                if (text.includes(t)) lex += 1;
+            }
+            // Floor calibrated on real cards: related ≈ 0.25, unrelated ≈ 0.0
+            // (MiniLM, short decision texts) — 0.18 keeps recall with margin.
+            const sem = (qv && vecs?.get(c.id)) ? dot(qv, vecs.get(c.id)) : null;
+            if (!lex && (sem == null || sem < 0.18)) continue;
+            // Hybrid: semantic dominates when available; lexical is the tie-breaker
+            // and the only signal pre-warm-up. Recency/archive nudges skipped for
+            // time-travel queries (validity already handled above).
+            let score = sem != null ? sem * 10 + Math.min(lex, 6) * 0.5 : lex;
+            if (asOfTs == null) {
+                if ((c.createdAt || 0) >= fresh) score += 0.5;
+                if (isArchived) score -= 1;
             }
-            if (!score) continue;
-            if ((c.createdAt || 0) >= fresh) score += 1;            // recency boost
-            if (/^archive$/i.test(c.area || '')) score -= 0.5;      // superseded ranks lower
-            scored.push({ score, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c });
+            scored.push({ score, sem, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c });
         }
     }
     if (!scored.length) return { content: [{ type: 'text', text: `No matches for "${query}" across ${brains.length} registered brain(s).` }] };
@@ -228,7 +351,93 @@ server.registerTool('search_all_brains', {
         const when = h.c.createdAt ? new Date(h.c.createdAt).toISOString().slice(0, 10) : '';
         return `- [${h.project}${h.area ? ' › ' + h.area : ''}] ${when} ${String(h.c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
     });
-    return { content: [{ type: 'text', text: `# Cross-project matches for "${query}" (${scored.length} hits in ${brains.length} brains, top ${top.length})\n\n${lines.join('\n')}` }] };
+    const mode = qv ? 'semantic+lexical (on-device)' : 'lexical (semantic model warming — retry for semantic ranking)';
+    const asOfNote = asOfTs != null ? ` · as of ${as_of}` : '';
+    return { content: [{ type: 'text', text: `# Cross-project matches for "${query}" (${scored.length} hits in ${brains.length} brains, top ${top.length} · ${mode}${asOfNote})\n\n${lines.join('\n')}` }] };
+});
+
+server.registerTool('brain_insights', {
+    title: 'What matters in a brain — hubs, orphans, stale questions',
+    description: 'Structural read of a brain.klypix: the most-connected "hub" cards (load-bearing decisions), orphaned decisions (no connections — maybe forgotten), stale open questions (aging & unresolved), and area sizes. Use to answer "what matters here / what am I forgetting / what should I review?" — read it at the start of a planning session, or before tidying.',
+    inputSchema: {
+        canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
+        staleDays: z.number().optional().describe('Open questions older than this many days count as stale (default 21).'),
+    },
+}, async ({ canvas, staleDays }) => {
+    const file = resolveCanvas(canvas || 'brain') || resolveCanvas('brain.klypix');
+    if (!file) return { content: [{ type: 'text', text: `No brain canvas found in ${VAULT}. Pass canvas: "<name>", or run \`npx klypix-mcp init\` to create one.` }], isError: true };
+    try {
+        const { struct } = await parseKlypix(fs.readFileSync(file));
+        const ins = brainInsights(struct, staleDays ? { staleDays } : {});
+        return { content: [{ type: 'text', text: insightsToMarkdown(ins, struct.title) }] };
+    } catch (e) {
+        return { content: [{ type: 'text', text: `Insights failed: ${e.message}` }], isError: true };
+    }
+});
+
+server.registerTool('brain_connect', {
+    title: 'Connect related-but-unlinked brain cards (densify the graph)',
+    description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph.',
+    inputSchema: {
+        canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
+        apply: z.boolean().optional().describe('false (default) = suggest only; true = draw the connections.'),
+        max: z.number().optional().describe('Max connections to propose/draw (default 24).'),
+        threshold: z.number().optional().describe('Min semantic similarity 0–1 to link (default 0.45). Higher = fewer, tighter links.'),
+    },
+}, async ({ canvas, apply = false, max = 24, threshold = 0.45 }) => {
+    const file = resolveCanvas(canvas || 'brain') || resolveCanvas('brain.klypix');
+    if (!file) return { content: [{ type: 'text', text: `No brain canvas found in ${VAULT}.` }], isError: true };
+    let struct;
+    try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return { content: [{ type: 'text', text: `Read failed: ${e.message}` }], isError: true }; }
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, 70);
+    const byId = new Map(struct.cards.map(c => [c.id, c]));
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''));
+    const linked = new Set(struct.connections.map(c => [c.fromId, c.toId].sort().join('|')));
+
+    let edges = [];
+    let mode = 'structural (shared tags + [[mentions]])';
+    const pipe = await Promise.race([getEmbedder(), new Promise(r => setTimeout(() => r(null), 20_000))]);
+    if (pipe) {
+        try {
+            const vecs = await vectorsForBrain(pipe, file, struct.cards);
+            const items = live.filter(c => vecs.get(c.id));
+            for (const a of items) {
+                const av = vecs.get(a.id);
+                const sims = items
+                    .filter(b => b.id !== a.id)
+                    .map(b => ({ b, s: dot(av, vecs.get(b.id)), cross: (b.area || '') !== (a.area || '') }))
+                    .sort((x, y) => (y.s + (y.cross ? 0.03 : 0)) - (x.s + (x.cross ? 0.03 : 0))); // nudge toward cross-area links
+                let taken = 0;
+                for (const { b, s } of sims) {
+                    if (s < threshold || taken >= 2) break;       // each card keeps its ≤2 strongest fresh links
+                    const key = [a.id, b.id].sort().join('|');
+                    if (linked.has(key)) continue;
+                    linked.add(key);
+                    edges.push({ fromId: a.id, toId: b.id, sim: s });
+                    taken++;
+                }
+            }
+            edges.sort((x, y) => y.sim - x.sim);
+            mode = 'semantic (on-device)';
+        } catch (e) { mode = `structural (semantic failed: ${e.message})`; }
+    }
+    if (!edges.length && mode.startsWith('structural')) {
+        edges = proposeStructuralConnections(struct);
+    }
+    const chosen = edges.slice(0, max);
+    if (!chosen.length) return { content: [{ type: 'text', text: `Nothing to connect — no related-but-unlinked cards found (mode: ${mode}).` }] };
+
+    const render = (e) => `- ${flat(byId.get(e.fromId)?.text)} ↔ ${flat(byId.get(e.toId)?.text)}${e.sim != null ? `  (${e.sim.toFixed(2)})` : e.why ? `  (${e.why})` : ''}`;
+    if (!apply) {
+        return { content: [{ type: 'text', text: `# ${chosen.length} suggested connection(s) · ${mode}\n_Review, then re-run with apply:true to draw them._\n\n${chosen.map(render).join('\n')}` }] };
+    }
+    try {
+        const { buffer, added } = await addBrainConnections(fs.readFileSync(file), chosen);
+        await atomicWrite(file, buffer);
+        return { content: [{ type: 'text', text: `✓ Drew ${added} connection(s) into ${path.relative(VAULT, file)} (${mode}). Reopen the brain to see the new arrows.\n\n${chosen.slice(0, added).map(render).join('\n')}` }] };
+    } catch (e) {
+        return { content: [{ type: 'text', text: `Apply failed (brain unchanged): ${e.message}` }], isError: true };
+    }
 });
 
 // Format the cards (optionally only a set of new ids) + connection graph so an
@@ -291,7 +500,11 @@ server.registerTool('add_to_canvas', {
         // Snapshot existing ids so we can report ONLY the newly-added cards back.
         let beforeIds = new Set();
         try { const b = await parseKlypix(original); beforeIds = new Set(b.struct.cards.map(c => c.id)); } catch { /* new/legacy → treat all as new */ }
-        const buf = await appendToKlypix(original, { cards, connections });
+        // Provenance: stamp WHICH agent wrote these cards (cursor / claude /
+        // cline — from the MCP client's initialize handshake).
+        let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
+        const stamped = via ? cards.map(c => ({ ...c, createdVia: via })) : cards;
+        const buf = await appendToKlypix(original, { cards: stamped, connections });
         await atomicWrite(file, buf);
         let detail = '';
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.0.4",
+  "version": "1.2.0",
   "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",
@@ -19,7 +19,7 @@
   "homepage": "https://klypix.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/dahshanlabs/klypix-mcp.git"
+    "url": "https://github.com/dahshanlabs/klypix-mcp"
   },
   "bin": {
     "klypix-mcp": "bin/klypix-mcp.mjs",
@@ -48,5 +48,8 @@
     "jszip": "^3.10.1",
     "zod": "^4.3.6",
     "fractional-indexing": "^3.2.0"
+  },
+  "optionalDependencies": {
+    "@huggingface/transformers": "^4.2.0"
   }
 }

package/src/klypix-format.mjs

@@ -116,6 +116,7 @@ export async function parseKlypix(buffer) {
         })),
         connections: connections.map(c => ({
             from: titleOf(c.fromId), to: titleOf(c.toId),
+            fromId: c.fromId, toId: c.toId,        // raw ids — for graph analysis (brainInsights)
             relationship: c.relationship || null, label: c.label || null,
         })),
         assets: assetPaths.map(p => path.basename(p)),
@@ -302,6 +303,7 @@ export async function appendToKlypix(buffer, addition) {
     for (const a of added) {
         zip.file(`items/${shard(a.id)}/${a.id}.json`, JSON.stringify({
             type: 'text', locked: false, createdAt: now, createdBy: 'agent',
+            ...(a.card.createdVia ? { createdVia: String(a.card.createdVia) } : {}),
             content: String(a.card.text), fontSize: FONT,
             color: a.card.color || '#1a1a1f', border: !!a.card.border, borderColor: '#1e1e2e',
             heading: !!a.card.heading, fontFamily: 'Thmanyah Sans',
@@ -598,6 +600,10 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
         for (const c of focus) push(`- ${flat(c.text)}`);
     }
     if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${flat(c.text)}`); }
+    // ⚠️ Conflicts — pairs flagged conflicts_with (e.g. by parallel sessions);
+    // surfaced HIGH so the next session reconciles them, not buries them.
+    const conflicts = (struct.connections || []).filter(c => c.relationship === 'conflicts_with');
+    if (conflicts.length) { push('', '## ⚠️ Conflicts to reconcile (parallel decisions that may disagree)'); for (const c of conflicts.slice(0, 10)) push(`- ${flat(c.from)}  ⚔️  ${flat(c.to)}`); }
     const areaCounts = containers
         .filter(c => !/^archive$/i.test(c.title || ''))
         .map(c => `${flat(c.title)} (${texts.filter(t => t.parentId === c.id).length})`);
@@ -632,6 +638,214 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     return out.join('\n') + '\n';
 }
 
+// ── Relevance ranking ─────────────────────────────────────────────────────
+// ONE shared lexical ranker so the per-prompt retrieval hook (and, later, the
+// MCP search) rank cards the SAME way — no third divergent scorer. Weights
+// mirror the MCP convention: title 3, tag 2, body 1, plus a gentle recency
+// tiebreak. Pure + node-runnable (no embeddings / network) so the Stop/prompt
+// hooks can call it with zero extra deps. `#file-…`/`#dir-…` tags (added at
+// capture) are what make a git-diff token match a card precisely.
+const STOPWORDS = new Set(['the', 'and', 'for', 'that', 'this', 'with', 'from', 'have', 'has', 'was', 'were', 'are', 'you', 'your', 'not', 'but', 'its', 'into', 'out', 'can', 'will', 'use', 'using', 'about', 'what', 'when', 'why', 'how', 'add', 'fix', 'make', 'need', 'want', 'let', 'see', 'get', 'got', 'now', 'all', 'any', 'via', 'per', 'etc', 'should', 'could', 'would', 'does', 'did', 'still', 'just', 'like', 'also', 'then', 'than', 'them', 'they']);
+export function queryTokens(s) {
+    return [...new Set(String(s || '').toLowerCase().match(/[a-z0-9][a-z0-9_-]{2,}/g) || [])].filter(t => !STOPWORDS.has(t));
+}
+const wordsOf = (s) => new Set(String(s || '').toLowerCase().match(/[a-z0-9][a-z0-9_-]{1,}/g) || []);
+export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2, recentDays = 30 } = {}) {
+    const tokens = Array.isArray(query) ? query.filter(Boolean) : queryTokens(query);
+    if (!tokens.length || !struct || !Array.isArray(struct.cards)) return [];
+    const cutoff = Date.now() - recentDays * 86_400_000;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const scored = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || isArchived(c) || !(c.text || '').trim()) continue;
+        // WORD-level matching (not substring) so "app" can't hit "append-klypix"
+        // and "main" can't hit "domain". Tag match is on the tag's STEM (the
+        // slug after #file-/#dir-/#) so a git-diff token (slugify(basename))
+        // lands EXACTLY on its #file- anchor — the precise signal, weighted = a
+        // title hit so ONE anchored file match (3 + 0.5 recency) clears minScore.
+        const titleW = wordsOf(c.title);
+        const bodyW = wordsOf(c.text);
+        const tagStems = new Set((c.tags || []).map(t => String(t).toLowerCase().replace(/^#/, '').replace(/^(file|dir)-/, '')).filter(Boolean));
+        let score = 0;
+        for (const tok of tokens) {
+            if (titleW.has(tok)) score += 3;
+            else if (tagStems.has(tok)) score += 3;
+            else if (bodyW.has(tok)) score += 1;
+        }
+        if (score <= 0) continue;
+        if ((c.createdAt || 0) >= cutoff) score += 0.5; // gentle recency tiebreak, never dominant
+        scored.push({ card: c, score });
+    }
+    scored.sort((a, b) => b.score - a.score || (b.card.createdAt || 0) - (a.card.createdAt || 0));
+    return scored.filter(s => s.score >= minScore).slice(0, topK);
+}
+
+// ── Conflict candidate detection ───────────────────────────────────────────
+// REAL conflicts only — a conflict is two decisions that genuinely CONTRADICT
+// (you can't honor both about the same thing). Topical similarity, duplication,
+// and sequential supersession are explicitly NOT conflicts and must never be
+// flagged (no false-conflict dump). This is a cheap LEXICAL pre-filter that
+// returns CANDIDATES only — same-subject, not-already-connected pairs where at
+// least one card uses explicit REVERSAL language. Candidates mean nothing on
+// their own: the caller (brain-conflicts.mjs) confirms each with an LLM
+// contradiction-check before anything is ever drawn or surfaced. No verifier →
+// nothing surfaces. Pure + node-runnable.
+// Strong reversal/contradiction terms ONLY — deliberately NOT bare "not"/"don't"
+// (too common → false positives). A candidate still has to clear the LLM gate.
+const OPPOSITION_RE = /\b(instead of|reverted?|no longer|dropp(?:ed|ing)?|deprecat\w*|abandon\w*|replaced?\b|supersed\w*|changed from|switch(?:ed)? (?:from|to)|rolled? back|overrod|overrides?|contradic\w*|disagree\w*|conflicts? with|reversed?\b)/i;
+export function detectConflicts(struct, { minOverlap = 0.45, topK = 12 } = {}) {
+    if (!struct || !Array.isArray(struct.cards)) return [];
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !isArchived(c));
+    const wset = new Map(live.map(c => [c.id, new Set(queryTokens(c.text))]));
+    const connected = new Set();
+    for (const e of struct.connections || []) { connected.add(e.fromId + '|' + e.toId); connected.add(e.toId + '|' + e.fromId); }
+    const out = [];
+    for (let i = 0; i < live.length; i++) {
+        for (let j = i + 1; j < live.length; j++) {
+            const a = live[i], b = live[j];
+            if (connected.has(a.id + '|' + b.id)) continue;
+            const A = wset.get(a.id), B = wset.get(b.id);
+            if (A.size < 4 || B.size < 4) continue;
+            let inter = 0; for (const t of A) if (B.has(t)) inter++;
+            const overlap = inter / Math.min(A.size, B.size); // overlap coefficient — same subject?
+            // Must be same-subject AND carry an explicit reversal signal. Pure
+            // similarity / duplication is NOT a candidate (that was the dump).
+            if (overlap < minOverlap) continue;
+            if (!(OPPOSITION_RE.test(a.text) || OPPOSITION_RE.test(b.text))) continue;
+            out.push({ aId: a.id, bId: b.id, a: a.text, b: b.text, area: a.area, overlap: Math.round(overlap * 100) / 100 });
+        }
+    }
+    out.sort((x, y) => y.overlap - x.overlap);
+    return out.slice(0, topK);
+}
+
+// ── Brain insights ───────────────────────────────────────────────────────────
+// "What matters here, and what am I forgetting?" — a deterministic structural
+// read of the brain (borrowed from graphify's GRAPH_REPORT, applied to the
+// AUTHORED brain, not derived code). Surfaces:
+//   • hubs       — the most-connected cards (load-bearing decisions)
+//   • orphans    — decision/milestone cards with NO connections (isolated;
+//                  maybe forgotten — link them or archive them)
+//   • stale ❓   — open questions older than `staleDays` (aging unknowns)
+//   • areas      — live-card count per area (what's growing / dormant)
+// Pure + node-runnable: no LLM, no network. The agent renders/acts on it.
+export function brainInsights(struct, { staleDays = 21, topHubs = 6 } = {}) {
+    const cutoff = Date.now() - staleDays * 86_400_000;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const cards = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim());
+    const live = cards.filter(c => !isArchived(c));
+    const deg = new Map();
+    for (const cn of struct.connections) {
+        if (cn.fromId) deg.set(cn.fromId, (deg.get(cn.fromId) || 0) + 1);
+        if (cn.toId) deg.set(cn.toId, (deg.get(cn.toId) || 0) + 1);
+    }
+    const headline = (c) => String(c.text || '').replace(/\s+/g, ' ').trim().replace(/^(.*?)([.!?](\s|$)|$)/, '$1').slice(0, 120);
+    const isQuestion = (c) => /❓/.test(c.text);
+    const hubs = live
+        .map(c => ({ id: c.id, area: c.area, degree: deg.get(c.id) || 0, headline: headline(c) }))
+        .filter(x => x.degree > 0)
+        .sort((a, b) => b.degree - a.degree)
+        .slice(0, topHubs);
+    const orphans = live
+        .filter(c => !isQuestion(c) && !/🌿|⤵/.test(c.text) && !(deg.get(c.id) > 0))
+        .map(c => ({ id: c.id, area: c.area, headline: headline(c), age: c.createdAt }));
+    const staleQuestions = live
+        .filter(c => isQuestion(c) && (c.createdAt || 0) < cutoff)
+        .map(c => ({ id: c.id, area: c.area, headline: headline(c), age: c.createdAt }))
+        .sort((a, b) => (a.age || 0) - (b.age || 0));
+    const areas = struct.cards
+        .filter(c => c.type === 'container' && !/^archive$/i.test(c.title || ''))
+        .map(c => ({ title: c.title, count: cards.filter(t => t.parentId === c.id).length }))
+        .sort((a, b) => b.count - a.count);
+    return {
+        hubs, orphans, staleQuestions, areas,
+        totals: { live: live.length, archived: cards.length - live.length, connections: struct.connections.length },
+    };
+}
+
+// Render brainInsights as a compact markdown report (used by the MCP tool).
+export function insightsToMarkdown(ins, title = 'brain') {
+    const out = [`# ${title} — insights`, `*${ins.totals.live} live cards · ${ins.totals.archived} archived · ${ins.totals.connections} connections*`];
+    if (ins.hubs.length) { out.push('', '## 🪢 Hubs (most-connected — the load-bearing cards)'); for (const h of ins.hubs) out.push(`- (${h.degree}) [${h.area || '?'}] ${h.headline}`); }
+    if (ins.orphans.length) { out.push('', `## 🔌 Orphaned decisions (${ins.orphans.length} — no connections; link them or archive)`); for (const o of ins.orphans.slice(0, 12)) out.push(`- [${o.area || '?'}] ${o.headline}`); if (ins.orphans.length > 12) out.push(`- …and ${ins.orphans.length - 12} more`); }
+    if (ins.staleQuestions.length) { out.push('', `## ⏳ Stale open questions (${ins.staleQuestions.length} — unresolved & aging)`); for (const q of ins.staleQuestions.slice(0, 12)) out.push(`- [${q.area || '?'}] ${q.headline}`); }
+    out.push('', '## 📍 Areas (by live cards)', ins.areas.map(a => `${a.title} (${a.count})`).join(' · ') || '(none)');
+    if (!ins.hubs.length && !ins.orphans.length && !ins.staleQuestions.length) out.push('', '_Brain is small/tidy — no hubs, orphans, or stale questions to flag yet._');
+    return out.join('\n') + '\n';
+}
+
+// Append raw connections (by id) to a brain — additive, never deletes, skips
+// self-links / duplicates / dangling ids, verifies a round-trip parse. Used by
+// the brain_connect tool to densify a sparse brain into a real graph.
+export async function addBrainConnections(buffer, edges) {
+    const { zip, canvas, manifest, isV4 } = await parseKlypix(buffer);
+    if (!isV4 || !canvas.positions) throw new Error('connections need a v4 .klypix');
+    canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+    const linked = (a, b) => canvas.connections.some(c => (c.fromId === a && c.toId === b) || (c.fromId === b && c.toId === a));
+    const rand = () => Math.random().toString(36).slice(2, 10);
+    let added = 0;
+    for (const e of edges || []) {
+        if (!e.fromId || !e.toId || e.fromId === e.toId) continue;
+        if (!canvas.positions[e.fromId] || !canvas.positions[e.toId]) continue; // both must exist
+        if (linked(e.fromId, e.toId)) continue;
+        canvas.connections.push({
+            id: `con_${rand()}`, fromId: e.fromId, toId: e.toId,
+            relationship: REL.has(e.relationship) ? e.relationship : 'relates_to',
+            label: typeof e.label === 'string' ? e.label : undefined,
+            arrowHead: true, width: 2, color: typeof e.color === 'string' ? e.color : '#10b981', style: 'solid',
+        });
+        added++;
+    }
+    if (!added) return { buffer, added: 0 };
+    const out = await finalizeBrainZip(zip, canvas, manifest, Date.now());
+    return { buffer: out, added };
+}
+
+// Structural connection suggestions — pure, no embeddings (the fallback when
+// the on-device model isn't installed, and the twin of the in-app Connect
+// button). Signals, strongest first: an unlinked [[title]] mention (3), a
+// shared topical tag ACROSS areas (2), a shared tag within an area (1). The
+// area-name tag is dropped (redundant with containment), and — crucially —
+// each card keeps at most `maxPerCard` links, so a tag shared by ten cards
+// can't explode into a 45-edge clique. Mirrors the semantic pass's discipline.
+export function proposeStructuralConnections(struct, { maxPerCard = 2 } = {}) {
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !/^archive$/i.test(c.area || ''));
+    const linked = new Set(struct.connections.map(c => [c.fromId, c.toId].sort().join('|')));
+    const titleIx = live.filter(c => (c.title || '').trim()).map(c => ({ id: c.id, t: c.title.trim().toLowerCase() }));
+    const tagsOf = (c) => (c.tags || [])
+        .map(t => String(t).toLowerCase().replace(/^#/, ''))
+        .filter(t => t && t !== 'area' && t !== String(c.area || '').toLowerCase());
+    const cand = [];
+    for (const c of live) {
+        for (const link of (c.links || [])) {
+            const want = String(link).trim().toLowerCase();
+            const tgt = titleIx.find(e => e.id !== c.id && (e.t === want || e.t.startsWith(want)));
+            if (tgt) cand.push({ a: c.id, b: tgt.id, score: 3, why: 'mention' });
+        }
+        const ct = tagsOf(c);
+        if (!ct.length) continue;
+        for (const d of live) {
+            if (d.id <= c.id) continue;
+            if (tagsOf(d).some(t => ct.includes(t))) cand.push({ a: c.id, b: d.id, score: c.area !== d.area ? 2 : 1, why: 'shared tag' });
+        }
+    }
+    cand.sort((x, y) => y.score - x.score);
+    const per = new Map();
+    const edges = [];
+    for (const e of cand) {
+        if (e.a === e.b) continue;
+        const key = [e.a, e.b].sort().join('|');
+        if (linked.has(key)) continue;
+        if ((per.get(e.a) || 0) >= maxPerCard || (per.get(e.b) || 0) >= maxPerCard) continue;
+        linked.add(key);
+        per.set(e.a, (per.get(e.a) || 0) + 1);
+        per.set(e.b, (per.get(e.b) || 0) + 1);
+        edges.push({ fromId: e.a, toId: e.b, why: e.why });
+    }
+    return edges;
+}
+
 // ── Atomic brain capture: supersede + append + resolve + auto-link ──────────
 // One verified write per capture batch. Beyond appendIntoContainers it adds:
 //   • SUPERSEDE — a new decision that heavily overlaps an existing live card in
@@ -693,10 +907,28 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             if (pos) canvas.positions[id] = { ...pos, h: measureCardH(j.content) };
             return true;
         };
-        const archiveCard = (id) => {
+        const archiveCard = async (id) => {
             const arc = ensureArchive();
+            // The Archive is readable STORAGE, not a vector-scaled layout: un-bake
+            // any group-shrink (font/width baked tiny) by restoring the frozen
+            // authored baseline and dropping it, so the card sits in the Archive
+            // at full readable size and re-seeds cleanly if the Archive is resized.
+            let authoredW = null;
+            const ip = `items/${shard(id)}/${id}.json`;
+            const f = zip.file(ip);
+            if (f) {
+                const j = JSON.parse(await f.async('string'));
+                const a = j.authoredInParent;
+                if (a) {
+                    if (j.type === 'text' && a.fontSize) j.fontSize = a.fontSize;
+                    if (a.authoredWidth != null) j.authoredWidth = a.authoredWidth;
+                    authoredW = a.w || null;
+                    delete j.authoredInParent;
+                    zip.file(ip, JSON.stringify(j));
+                }
+            }
             const pos = canvas.positions[id];
-            if (pos) canvas.positions[id] = { ...pos, parentId: arc };
+            if (pos) canvas.positions[id] = { ...pos, parentId: arc, ...(authoredW ? { w: authoredW } : {}) };
         };
         canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
 
@@ -715,7 +947,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     j.content = `${j.content}\n✅ ${today}: ${r.text}`;
                     j.borderColor = 'rgba(16,185,129,0.35)';
                 });
-                archiveCard(best.id);
+                await archiveCard(best.id);
                 best.text += ` ✅ ${r.text}`; // keep in-memory struct honest for later matching
                 stats.resolved++;
             } else {
@@ -768,7 +1000,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     j.content = `↩︎ superseded ${today}\n${j.content}`;
                     j.borderColor = 'rgba(120,120,135,0.5)';
                 });
-                archiveCard(best.id);
+                await archiveCard(best.id);
                 best.text = `↩︎ ${best.text}`;
                 card.__supersedes = best.id;
                 stats.superseded++;