klypix-mcp 1.5.0 → 1.6.0

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,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
 
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
@@ -147,6 +147,21 @@ server.registerTool('add_to_canvas', {
   return toContent(await opAddToCanvas({ vault: VAULT, canvas, cards, connections, via }));
 });
 
+server.registerTool('brain_note', {
+  title: 'Write a deliberate note to the project brain (decision / question / milestone / resolve / update)',
+  description: 'Record something in the project brain ON DEMAND — the agent-neutral twin of the Claude-Code capture hook, so any client (Cursor / Cline / Desktop) can write the brain, not just read it. Unlike add_to_canvas (a flat append), this routes through the brain\'s capture engine, so a new decision SUPERSEDES a heavily-overlapping older one, ✓ RESOLVES/archives a matching card, closes: resolves the strategy/question a milestone fulfils, and ~ UPDATES a card in place — the full decision lifecycle, with dedup. Use it to remember a decision, ask an open question, mark a milestone, resolve a finished item, or correct a card. Defaults to the project brain ("brain").',
+  inputSchema: {
+    text: z.string().describe('The note — one concise idea; the first line becomes the card title.'),
+    marker: z.enum(['', '?', '!', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
+    area: z.string().optional().describe('Area/topic — routes the card into that titled container and becomes a #tag (e.g. "Auth", "Release").'),
+    closes: z.string().optional().describe('Title or [[wikilink]] of a strategy/question card this note fulfils — resolves+archives it and draws a "closed by" arrow.'),
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+  },
+}, async ({ text, marker, area, closes, canvas }) => {
+  let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
+  return toContent(await opBrainNote({ vault: VAULT, canvas, text, area, marker: marker || '', closes, via }));
+});
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 log(`ready · vault=${VAULT}`);

package/package.json

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

@@ -24,7 +24,7 @@ import { z } from 'zod';
 import {
   parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown,
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
-  findUnrecordedMigrations,
+  findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -110,8 +110,16 @@ export function getEmbedder(log = () => {}) {
       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);
+        // The optional dep ships dist/transformers.node.mjs on v4 (Node build) and
+        // dist/transformers.mjs on older lines — try both so a correct one-click
+        // install resolves regardless of version.
+        const base = path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers', 'dist');
+        let lastErr;
+        for (const f of ['transformers.node.mjs', 'transformers.mjs']) {
+          try { t = await import(new URL('file:///' + path.join(base, f).replace(/\\/g, '/')).href); lastErr = null; break; }
+          catch (e) { lastErr = e; }
+        }
+        if (!t) throw lastErr;
       }
       t.env.cacheDir = path.join(PB_DIR, 'hf-cache');
       return await t.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' });
@@ -465,5 +473,31 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
   }
 }
 
+// brain_note — the DELIBERATE, marker-aware write every agent (not just the
+// Claude-Code Stop hook) can make on demand. Routes through the SAME captureInto-
+// Brain engine the hook uses, so supersede / resolve / close-link / dedup behave
+// identically to a harvested 🧠 marker. The agent-neutral half of "the brain is an
+// open file any agent reads AND writes": a hookless client (Cursor/Cline/Desktop)
+// can now record a decision, ask an open question, mark a milestone, resolve a card,
+// or correct one — with the full lifecycle, not just a flat append.
+export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via }) {
+  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
+  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  if (!noteText || !String(noteText).trim()) return err('brain_note needs a non-empty text.');
+  if (!['', '?', '!', '✓', '~'].includes(marker)) return err(`Invalid marker "${marker}" — use: (none)=decision · ?=open question · !=milestone · ✓=resolve a matching card · ~=update a matching card.`);
+  const input = noteToCaptureInput({ text: noteText, area, marker, closes: closes || '', createdVia: via || 'mcp' });
+  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}`);
+    return { blocks: [text(`✓ brain_note → ${path.relative(vault, file)} (${bits.join(' · ')}). Reopen the brain in KLYPIX to see it.`)] };
+  } catch (e) {
+    return err(`brain_note failed (brain unchanged): ${e.message}`);
+  }
+}
+
 // Re-export the format helpers the bins need for non-op work (init onboarding).
 export { buildKlypixMap, parseKlypix };

package/src/klypix-format.mjs

@@ -573,8 +573,11 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const live = texts.filter(c => !isArchived(c));
     const focus = live.filter(isFocus);
     const rest = live.filter(c => !isFocus(c));
-    const open = rest.filter(c => /❓/.test(c.text));
-    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓/.test(c.text));
+    // 🎯 (goal/target) reads as an OPEN item alongside ❓ — a goal card is
+    // still-to-do until a ✓/closes: or a covering milestone closes it (so it
+    // must NOT masquerade as a plain decision that quietly ages out of view).
+    const open = rest.filter(c => /❓|🎯/.test(c.text));
+    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓|🎯/.test(c.text));
     const plain = rest.filter(c => !open.includes(c) && !miles.includes(c));
     const recent = plain.filter(c => c.createdAt >= cutoff).sort((a, b) => b.createdAt - a.createdAt).slice(0, maxRecent);
     const archivedCount = texts.length - live.length;
@@ -607,7 +610,7 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
         push('', '## 📌 Human focus (cards the human placed here — act on these first)');
         for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
     }
-    if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
+    if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${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');
@@ -837,7 +840,7 @@ export function brainInsights(struct, { staleDays = 21, topHubs = 6 } = {}) {
         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 isQuestion = (c) => /❓|🎯/.test(c.text); // ❓ open question + 🎯 goal both read as "open"
     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)
@@ -1042,7 +1045,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             let best = null, bestScore = 0;
             for (const c of liveTextCards()) {
                 if (r.area && (c.area || '').toLowerCase() !== r.area.toLowerCase()) continue;
-                const s = overlapScore(rTok, tokenSet(c.text)) + (/❓/.test(c.text) ? 0.15 : 0);
+                const s = overlapScore(rTok, tokenSet(c.text)) + (/❓|🎯/.test(c.text) ? 0.15 : 0);
                 if (s > bestScore) { bestScore = s; best = c; }
             }
             if (best && bestScore >= RESOLVE_AT) {
@@ -1092,7 +1095,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
         // to the new card is drawn in pass 2 (after the new ids exist), matched
         // back by remembering which old card each new card displaced.
         for (const card of cards) {
-            if (/❓|🏁/.test(card.text)) continue; // only plain decisions supersede
+            if (/❓|🎯|🏁/.test(card.text)) continue; // only plain decisions supersede (not questions/goals/milestones)
             const nTok = tokenSet(card.text);
             const area = (card.area || '').toLowerCase();
             let best = null, bestScore = 0;
@@ -1197,6 +1200,60 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
     return { buffer: work, 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
+// quietly SHIPPED keeps surfacing in recall as a "next move". This pure pass
+// finds open cards a LATER live 🏁 milestone appears to fulfil (its text COVERS
+// the open card's distinctive tokens) and returns them so the surface can PROMPT
+// the human to close them — never auto-archives (precision-first, suggestion-only,
+// like the migration tripwire). Requires the milestone to post-date the goal so a
+// pre-existing milestone can't "fulfil" a newer goal. No I/O, node-runnable.
+export function findStaleOpenCards(struct, { coverAt = 0.6, max = 5 } = {}) {
+    const empty = { gaps: [], total: 0 };
+    if (!struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const isOpen = (c) => /❓|🎯/.test(c.text);
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !isArchived(c) && !/↩|✅/.test(c.text));
+    const opens = live.filter(isOpen);
+    const miles = live.filter(c => /🏁/.test(c.text) && !isOpen(c));
+    if (!opens.length || !miles.length) return empty;
+    const out = [];
+    for (const o of opens) {
+        const oTok = tokenSet(o.text);
+        if (oTok.size < 3) continue;                       // too vague to match safely → leave it
+        let best = null, bestCov = 0;
+        for (const m of miles) {
+            if ((m.createdAt || 0) <= (o.createdAt || 0)) continue; // only a milestone shipped AFTER the goal
+            const cov = coverageOf(oTok, tokenSet(m.text));          // how much of the goal the milestone covers
+            if (cov > bestCov) { bestCov = cov; best = m; }
+        }
+        if (best && bestCov >= coverAt) out.push({ open: o, by: best, cov: Math.round(bestCov * 100) / 100 });
+    }
+    out.sort((a, b) => b.cov - a.cov);
+    return { gaps: out.slice(0, max), total: out.length };
+}
+
+// ── Deliberate note → capture input ──────────────────────────────────────────
+// Turn ONE structured note into captureIntoBrain's input shape — the deliberate
+// twin of the Stop hook's transcript marker parser. This is what lets an ON-DEMAND
+// write (the brain_note MCP tool, the brain-note CLI — any agent, not just the
+// Claude-Code hook) get IDENTICAL supersede / resolve / close / dedup semantics as
+// a harvested 🧠 marker. marker ∈ '' (decision) | '?' (open question) | '!'
+// (milestone) | '✓' (resolve+archive a match) | '~' (update a match in place).
+export function noteToCaptureInput({ text = '', area = '', marker = '', closes = '', evidence = null, createdVia = 'mcp' } = {}) {
+    const body = String(text).trim();
+    if (!body) return { cards: [], resolutions: [], updates: [] };
+    const a = String(area || '').trim();
+    if (marker === '✓') return { cards: [], resolutions: [{ area: a, text: body }], updates: [] };
+    if (marker === '~') return { cards: [], resolutions: [], updates: [{ area: a, text: body, createdVia, ...(evidence ? { evidence } : {}) }] };
+    const prefix = marker === '?' ? '❓ ' : marker === '!' ? '🏁 ' : '';
+    const borderColor = marker === '?' ? 'rgba(245,166,35,0.8)' : marker === '!' ? 'rgba(59,130,246,0.8)' : 'rgba(16,185,129,0.6)';
+    const tag = a ? `\n#${a.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : '';
+    const cardText = (a ? `${a}: ${prefix}${body}` : `${prefix}${body}`) + tag;
+    return { cards: [{ text: cardText, area: a, color: '#e8e8ed', borderColor, createdVia, ...(closes ? { closes } : {}), ...(evidence ? { evidence } : {}) }], resolutions: [], updates: [] };
+}
+
 /**
  * Build a RICH "map" .klypix: areas become titled containers, their cards
  * stack inside, connections draw across. Produces a real spatial board (used by