klypix-mcp 1.6.0 → 1.7.0

package/README.md

@@ -52,9 +52,29 @@ notes into a board,"* or *"add a card with the decision we just made."*
 | `list_canvases` | List every `.klypix` in the vault |
 | `read_canvas` | Read a canvas as markdown (cards, the connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name + content |
+| `search_all_brains` | Cross-project memory search across every registered brain |
+| `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
+| `brain_connect` | Find + draw related-but-unlinked cards (densify the graph) |
+| `brain_reconcile` | Flag committed-but-unrecorded DB migrations (the brain can't see prod) |
 | `create_canvas` | Create a new `.klypix` from cards + connections |
 | `add_to_canvas` | Append cards/connections to an existing canvas (positions preserved) |
 
+### Tools vs. the *automatic* brain
+
+This package is the **agent-neutral read/write surface** — any MCP client (Claude
+Code, Claude Desktop, Cursor, Cline, Windsurf…) gets the **tools** above and can
+read, search, and write canvases on demand (*pull*). That works in any agent, in
+any project.
+
+The **automatic** brain — auto-capturing decisions from your work, injecting the
+relevant cards into each prompt, and coordinating across concurrent sessions
+(*push*) — runs in a host **hook**, which is a Claude Code / KLYPIX-desktop
+feature, not part of this npm package. So `npx klypix-mcp` gives you the tools
+everywhere; the hands-free brain comes with the [KLYPIX desktop app](https://klypix.com)
+or the Claude Code project-brain hook. (`search_all_brains` is also hook-fed — it
+reads the cross-project registry the hook writes, so it stays empty until a hook
+has registered at least one brain.)
+
 ## Also speaks A2A (Agent-to-Agent)
 
 The same engine is exposed as an **A2A agent** so other agents and orchestrators

package/bin/klypix-mcp.mjs

@@ -23,7 +23,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opBrainReconcile, opCreateCanvas, opAddToCanvas, opBrainNote,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
 
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
@@ -121,6 +121,19 @@ server.registerTool('brain_reconcile', {
   },
 }, async ({ canvas, root }) => toContent(await opBrainReconcile({ vault: VAULT, canvas, root })));
 
+server.registerTool('brain_garden', {
+  title: 'Garden the brain — consolidate over-grown areas (sleep-time compute)',
+  description: 'Tidy an over-grown brain WITHOUT losing anything — SMART and non-invasive: it only consolidates DORMANT cards (old + peripheral), never load-bearing ones. Two phases: call it with no apply to get the areas that have accumulated forgotten cards (deterministic: >3 cards that are older than 14 days, beyond the area\'s newest 8, AND have ≤1 connection — so hubs and still-referenced decisions are left untouched; Focus/Instructions/Archive/Open-questions areas protected) plus their card text; YOU write one tight synthesis per area; then call again with apply:true and syntheses:[{title, synthesis}]. Each area gets a 🌿 synthesis card, the originals are stamped "⤵ consolidated", moved to Archive, and arrowed to the synthesis — nothing is deleted, and one undo un-gardens. Run it when brain_insights or the brief shows an area has grown noisy.',
+  inputSchema: {
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+    apply: z.boolean().optional().describe('false (default) = list over-grown areas + cards to synthesize; true = consolidate using the supplied syntheses.'),
+    syntheses: z.array(z.object({
+      title: z.string().describe('Area title EXACTLY as returned by the dry run.'),
+      synthesis: z.string().describe('3-6 sentence prose synthesis preserving every still-relevant fact/decision/number.'),
+    })).optional().describe('Required when apply:true — one entry per area you want consolidated.'),
+  },
+}, async ({ canvas, apply, syntheses }) => toContent(await opBrainGarden({ vault: VAULT, canvas, apply, syntheses })));
+
 server.registerTool('create_canvas', {
   title: 'Create a KLYPIX canvas',
   description: 'Create a new .klypix canvas from cards + connections and save it to the vault. The user opens it in KLYPIX (Canvas → Open). Prefer short, titled cards (one idea each) connected by meaningful arrows.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.6.0",
+  "version": "1.7.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",

package/src/klypix-core.mjs

@@ -25,6 +25,7 @@ import {
   parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown,
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
+  selectGardenCandidates, applyGarden,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -374,6 +375,40 @@ export async function opBrainReconcile({ vault, canvas, root }) {
   return { blocks: [text(`# ⚠️ ${total} migration(s) committed but unrecorded in the brain\n_The brain can't see prod — it flags migrations that are in git but unmentioned, so you can confirm the rollout. It never asserts a migration was applied. To dismiss one without applying, record any card that names it (e.g. "committed, not applied")._\n\n${lines.join('\n')}${more}`)] };
 }
 
+// ── Brain gardener (two-phase: select → agent synthesizes → apply) ───────────
+// The portable /garden. Dry-run returns the over-grown areas + their old cards
+// for the CALLING agent to synthesize (the engine is pure — the model writes the
+// prose); apply consolidates each area into a 🌿 card and archives the originals
+// with audit arrows. Mirrors brain_connect's dry-run/apply discipline.
+export async function opBrainGarden({ vault, canvas, apply = false, syntheses }) {
+  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
+  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  let struct;
+  try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const areas = selectGardenCandidates(struct);
+  if (!areas.length) return { blocks: [text('Nothing to garden — no area has 3+ DORMANT cards (old, beyond its newest 8, AND peripheral/≤1 link). Anything still woven into the graph is protected. The brain is tidy.')] };
+
+  if (!apply) {
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    const body = areas.map(a => `## ${a.title}  (${a.candidates.length} dormant cards)\n` + a.candidates.map(c => `- ${flat(c.text).slice(0, 240)}`).join('\n')).join('\n\n');
+    return { blocks: [text(`# 🌿 Gardener — ${areas.length} area(s) with DORMANT cards to consolidate\nThese are old, peripheral (≤1 link) cards only — hubs and still-referenced decisions were left untouched. For EACH area below, write ONE tight synthesis (3-6 sentences, plain prose, no headers) that preserves every still-relevant fact / decision / number and drops only repetition + play-by-play. Then call \`brain_garden\` again with \`apply:true\` and \`syntheses: [{ "title": "<area title EXACTLY as shown>", "synthesis": "<text>" }, …]\`. Originals are archived with audit arrows — nothing is deleted; one undo un-gardens.\n\n${body}`)] };
+  }
+
+  if (!Array.isArray(syntheses) || !syntheses.length) return err('apply:true needs syntheses:[{title, synthesis}, …] — run the dry run first (apply omitted) to get the areas + their cards.');
+  try {
+    const { buffer, stats } = await applyGarden(fs.readFileSync(file), { syntheses });
+    const skippedNote = (stats.skipped && stats.skipped.length)
+      ? `\n\n⚠️ Left untouched (faithfulness guard): ${stats.skipped.map(s => `"${s.title}" — ${s.reason}`).join('; ')}.`
+      : '';
+    if (!stats.synthCards) return { blocks: [text(`No areas consolidated — each synthesis \`title\` must match a dry-run area title exactly.${skippedNote}`)] };
+    let out = buffer; try { out = (await tidyBrain(buffer)).buffer; } catch { /* keep apply result if tidy fails */ }
+    await atomicWrite(file, out);
+    return { blocks: [text(`🌿 Gardened ${stats.areas} area(s): ${stats.archived} old card(s) → ${stats.synthCards} synthesis card(s); originals archived with "consolidated into" arrows (any prose-dropped figures appended verbatim). Reopen the brain in KLYPIX to see it.${skippedNote}`)] };
+  } catch (e) {
+    return err(`Garden apply failed (brain unchanged): ${e.message}`);
+  }
+}
+
 export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, log = () => {} }) {
   const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
   if (!file) return err(`No brain canvas found in ${vault}.`);

package/src/klypix-format.mjs

@@ -1200,6 +1200,175 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
     return { buffer: work, stats };
 }
 
+// ── Brain gardener — sleep-time consolidation with a visible audit trail ─────
+// The portable engine twin of the in-app /garden (so ANY agent can run it over
+// MCP, not just the KLYPIX canvas). Two phases, like brain_connect: the engine
+// SELECTS deterministically (the model never decides WHAT merges, only writes the
+// prose), the agent writes one synthesis per area, then the engine APPLIES — each
+// area gets a 🌿 synthesis card; the originals are stamped "⤵ consolidated", moved
+// to Archive, and arrowed → the synthesis. Nothing is deleted (archived verbatim).
+const GARDEN_KEEP_NEWEST = 8;       // per area, never consolidate the newest N
+const GARDEN_MIN_AGE_DAYS = 14;     // only cards older than this are candidates
+const GARDEN_MIN_CANDIDATES = 3;    // don't bother merging fewer than this
+const GARDEN_MAX_DEGREE = 1;        // SMART guard: protect load-bearing cards —
+//   only consolidate cards with ≤ this many connections (orphans + leaves). A
+//   card the graph leans on (degree ≥ 2) is signal, not noise, and is left alone.
+// Areas the gardener must never touch: human steering + config + its own output.
+const GARDEN_PROTECTED = /^(archive|📌?\s*focus|(🤖\s*)?(agent\s+)?instructions|open questions|pending)/i;
+// Faithfulness guard: a synthesis shorter than this (after whitespace-collapse)
+// is treated as degenerate (model returned a stub) and its area is skipped.
+const MIN_SYNTHESIS_CHARS = 60;
+// Distinct "figures" worth never losing — tokens carrying ≥2 digits (versions
+// 1.3.7, dates 2026-06-24, sizes 50mb, counts 326, migration ids). Trivial single
+// digits (1, 3) are ignored. Used to append any prose-dropped figure verbatim.
+const figuresIn = (text) => {
+    const out = new Set();
+    for (const m of String(text || '').matchAll(/[0-9][0-9a-zA-Z._:-]*/g)) {
+        const tok = m[0].replace(/[._:-]+$/, '').toLowerCase();
+        if ((tok.match(/\d/g) || []).length >= 2) out.add(tok);
+    }
+    return out;
+};
+
+// Deterministic candidate selection — PURE, so the model never chooses WHAT to
+// merge. SMART + non-invasive: a card is a candidate only if it's DORMANT —
+// old (> minAgeDays), beyond the area's newest N, AND peripheral (connection
+// degree ≤ maxDegree). That protects hubs and still-referenced cards (the spine
+// of the brain), so consolidation hits forgotten noise — the same cards
+// brain_insights flags as orphaned — never load-bearing decisions. Returns each
+// over-grown area with its dormant cards (oldest first), each tagged with degree.
+export function selectGardenCandidates(struct, { keepNewest = GARDEN_KEEP_NEWEST, minAgeDays = GARDEN_MIN_AGE_DAYS, minCandidates = GARDEN_MIN_CANDIDATES, maxDegree = GARDEN_MAX_DEGREE, now = Date.now() } = {}) {
+    if (!struct || !Array.isArray(struct.cards)) return [];
+    const cutoff = now - minAgeDays * 86_400_000;
+    // Connection degree per card — both ends of every edge. A card that is linked
+    // to (or links out to) the rest of the graph is structurally load-bearing.
+    const degree = new Map();
+    for (const cn of (struct.connections || [])) {
+        if (cn.fromId) degree.set(cn.fromId, (degree.get(cn.fromId) || 0) + 1);
+        if (cn.toId) degree.set(cn.toId, (degree.get(cn.toId) || 0) + 1);
+    }
+    const out = [];
+    for (const ctn of struct.cards) {
+        if (ctn.type !== 'container') continue;
+        const title = (ctn.title || '').trim();
+        if (!title || GARDEN_PROTECTED.test(title)) continue;
+        const children = struct.cards
+            .filter(c => c.type === 'text' && c.parentId === ctn.id && (c.text || '').trim() && !/⤵|↩|✅/.test(c.text))
+            .sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
+        const old = children
+            .slice(0, Math.max(0, children.length - keepNewest))
+            .filter(c => (c.createdAt || 0) < cutoff && (degree.get(c.id) || 0) <= maxDegree);  // dormant: old AND peripheral
+        if (old.length >= minCandidates) out.push({ containerId: ctn.id, title, candidates: old.map(c => ({ id: c.id, text: c.text, createdAt: c.createdAt || 0, degree: degree.get(c.id) || 0 })) });
+    }
+    return out;
+}
+
+// Apply: re-selects deterministically (robust to drift since the dry-run) and,
+// for each area the agent supplied a synthesis for, adds the 🌿 card + archives
+// the originals with audit arrows. `syntheses`: [{ title, synthesis }].
+export async function applyGarden(buffer, { syntheses = [] } = {}) {
+    const stats = { areas: 0, archived: 0, synthCards: 0, skipped: [] };
+    const { zip, canvas, manifest, isV4, struct } = await parseKlypix(buffer);
+    if (!isV4 || !canvas.positions) throw new Error('garden needs a v4 .klypix');
+    const areas = selectGardenCandidates(struct);
+    const synthByTitle = new Map();
+    for (const s of syntheses || []) { const t = String(s?.title || '').trim().toLowerCase(); const txt = String(s?.synthesis || '').trim(); if (t && txt) synthByTitle.set(t, txt); }
+    if (!areas.length || !synthByTitle.size) return { buffer, stats };
+
+    const now = Date.now();
+    const today = new Date(now).toISOString().slice(0, 10);
+    const rand = () => Math.random().toString(36).slice(2, 10);
+    const top = Object.values(canvas.positions).map(p => p && p.zKey).filter(k => k && isValidZKey(k)).sort().pop() || null;
+    const nextZKey = makeZKeyGen(top);
+    canvas.connections = Array.isArray(canvas.connections) ? canvas.connections : [];
+    const byTitle = new Map();
+    for (const c of struct.cards) if (c.type === 'container') { const t = (c.title || '').trim().toLowerCase(); if (t && !byTitle.has(t)) byTitle.set(t, c.id); }
+    // Archive primitives (mirror captureIntoBrain): find-or-create Archive, move a
+    // card into it un-baking any group-shrink, and rewrite a card's text in place.
+    const ensureArchive = () => {
+        let id = byTitle.get('archive');
+        if (id) return id;
+        id = `ctn_${rand()}`;
+        const G = BRAIN_GEOM;
+        zip.file(`items/${shard(id)}/${id}.json`, JSON.stringify({ type: 'container', locked: false, createdAt: now, createdBy: 'agent', title: 'Archive', collapsed: false, scopeLocked: false, borderColor: 'rgba(120,120,135,0.6)' }));
+        canvas.positions[id] = { x: nextContainerX(canvas), y: G.START, w: G.AREA_W, h: G.TITLE_BAR + G.PAD * 2, zKey: nextZKey(), zIndex: canvas.order.length, parentId: null };
+        canvas.order.push(id);
+        byTitle.set('archive', id);
+        return id;
+    };
+    const rewriteCard = async (id, mutate) => {
+        const ip = `items/${shard(id)}/${id}.json`;
+        const f = zip.file(ip); if (!f) return false;
+        const j = JSON.parse(await f.async('string'));
+        mutate(j);
+        j.content = wrapText(String(j.content || ''));
+        zip.file(ip, JSON.stringify(j));
+        const pos = canvas.positions[id];
+        if (pos) canvas.positions[id] = { ...pos, h: measureCardH(j.content) };
+        return true;
+    };
+    const archiveCard = async (id) => {
+        const arc = ensureArchive();
+        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, ...(authoredW ? { w: authoredW } : {}) };
+    };
+
+    for (const area of areas) {
+        const synthesis = synthByTitle.get(area.title.trim().toLowerCase());
+        if (!synthesis) continue;                          // model skipped this area — leave it untouched
+        const ctnPos = canvas.positions[area.containerId];
+        if (!ctnPos) continue;
+        // FAITHFULNESS GUARD (1) — degeneracy: a synthesis far too thin for the
+        // cards it replaces is rejected; that area is left untouched + reported,
+        // so a one-word "done" can't bury real history. (Originals stay put.)
+        const collapsed = synthesis.replace(/\s+/g, ' ').trim();
+        if (collapsed.length < MIN_SYNTHESIS_CHARS) {
+            stats.skipped.push({ title: area.title, reason: `synthesis too thin (${collapsed.length} chars, need ${MIN_SYNTHESIS_CHARS}) — revise and re-apply` });
+            continue;
+        }
+        // FAITHFULNESS GUARD (2) — figures net: any distinct number (version /
+        // size / date / count) in the originals that the prose dropped is appended
+        // verbatim, so the crispest facts survive on the visible card even if the
+        // synthesis missed them. The originals are archived verbatim regardless.
+        const origFigs = new Set();
+        for (const c of area.candidates) for (const f of figuresIn(c.text)) origFigs.add(f);
+        const synLower = synthesis.toLowerCase();
+        const missing = [...origFigs].filter(f => !synLower.includes(f));
+        const finalSynth = missing.length ? `${synthesis}\n↳ figures: ${missing.slice(0, 10).join(', ')}${missing.length > 10 ? ' …' : ''}` : synthesis;
+        const span = `${new Date(area.candidates[0].createdAt || now).toISOString().slice(0, 10)} → ${new Date(area.candidates[area.candidates.length - 1].createdAt || now).toISOString().slice(0, 10)}`;
+        const content = wrapText(`${area.title}: 🌿 Consolidated history (${span}, ${area.candidates.length} cards)\n${finalSynth}`);
+        const sid = `txt_${rand()}`;
+        zip.file(`items/${shard(sid)}/${sid}.json`, JSON.stringify({ type: 'text', locked: false, createdAt: now, createdBy: 'agent', createdVia: 'gardener', content, fontSize: 12, color: '#e8e8ed', border: true, borderColor: 'rgba(59,130,246,0.6)', heading: false }));
+        canvas.positions[sid] = { x: ctnPos.x + 20, y: ctnPos.y + (ctnPos.h || 0) + 10, w: 300, h: measureCardH(content), zKey: nextZKey(), zIndex: canvas.order.length, parentId: area.containerId };
+        canvas.order.push(sid);
+        stats.synthCards++;
+        for (const cand of area.candidates) {
+            await rewriteCard(cand.id, j => { j.content = `⤵ consolidated ${today}\n${j.content}`; j.borderColor = 'rgba(120,120,135,0.5)'; });
+            await archiveCard(cand.id);
+            canvas.connections.push({ id: `con_${rand()}`, fromId: cand.id, toId: sid, relationship: 'relates_to', label: 'consolidated into', arrowHead: true, width: 1.5, color: 'rgba(120,120,135,0.7)', style: 'solid' });
+            stats.archived++;
+        }
+        stats.areas++;
+    }
+    if (!stats.synthCards) return { buffer, stats };
+    const out = await finalizeBrainZip(zip, canvas, manifest, now);
+    return { buffer: out, stats };
+}
+
 // ── Stale-open reconcile ("marked open, but a milestone says it's done") ─────
 // The READ-side twin of the closes: write path. An open ❓/🎯 card lingers as
 // "still to do" forever unless someone emits a ✓/closes: for it — so a goal that