klypix-mcp 1.8.0 → 1.9.0

package/bin/klypix-a2a.mjs

@@ -32,8 +32,9 @@ import { z } from 'zod';
 import {
   resolveVault, getEmbedder, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opCreateCanvas, opAddToCanvas,
+  opBrainInsights, opBrainConnect, opCreateCanvas, opAddToCanvas, opBrainNote,
 } from '../src/klypix-core.mjs';
+import { looksLikeSkill } from '../src/klypix-format.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Resolve the package version across layouts: the published package (bin/ →
@@ -87,12 +88,21 @@ function agentCard(publicUrl) {
       {
         id: 'remember',
         name: 'Remember into the canvas / brain',
-        description: 'Append a decision or cards (with optional connections) to an existing .klypix, preserving every existing item and position. The durable, cross-session memory a multi-agent run keeps writing to.',
-        tags: ['memory', 'append', 'write', 'brain'],
+        description: 'Append a decision or cards (with optional connections) to an existing .klypix, preserving every existing item and position. The durable, cross-session memory a multi-agent run keeps writing to. Pass a "marker" in args for the full lifecycle: ""=decision · "?"=open question · "!"=milestone · "+"=🛠️ skill · "✓"=resolve a match · "~"=update a match.',
+        tags: ['memory', 'append', 'write', 'brain', 'lifecycle'],
         examples: ['Remember that we chose Postgres over Mongo', 'Add a card with this finding to the roadmap canvas'],
         inputModes: ['text/plain', 'application/json'],
         outputModes: [KLYPIX_MIME, 'text/plain'],
       },
+      {
+        id: 'learn_skill',
+        name: 'Learn a reusable skill (how-to / gotcha)',
+        description: 'Record a 🛠️ SKILL — a reusable how-to, gotcha, or convention ("always dedup zKeys before REORDER") that should resurface every session and never age out, distinct from a one-time decision. Routes through the capture engine with the "+" marker. A delegating agent uses this to teach the shared brain how work is done here, so every future agent inherits it. Plain "remember" auto-promotes to a skill when the text reads as a general rule.',
+        tags: ['memory', 'skill', 'how-to', 'procedure', 'brain', 'learn'],
+        examples: ['Learn this gotcha: never set backgroundThrottling false — it breaks visibility detection', 'Remember the convention: Electron main imports must stay at top'],
+        inputModes: ['text/plain', 'application/json'],
+        outputModes: [KLYPIX_MIME, 'text/plain'],
+      },
       {
         id: 'recall',
         name: 'Recall context from the canvases',
@@ -195,7 +205,21 @@ async function runSkill(skill, args, text, via) {
       return await opCreateCanvas({ vault: VAULT, title: args.title ?? 'Untitled board', cards: parsed.data, connections: conns.data, filename: args.filename });
     }
     case 'remember':
-    case 'add_to_canvas': {
+    case 'add_to_canvas':
+    case 'learn_skill': {
+      // Route through the brain's CAPTURE ENGINE (full lifecycle + markers, incl.
+      // 🛠️ skills) when: the caller passed a marker, asked for learn_skill, or the
+      // text reads as a reusable rule (auto-skill from the flow — the same
+      // classifier the Claude-Code hook uses). Otherwise: flat multi-card append.
+      let marker = String(args.marker || '').trim();
+      if (skill === 'learn_skill') marker = '+';
+      const single = (!args.cards && text.trim()) ? stripVerb(text) : null;
+      if (!marker && single && looksLikeSkill(single)) marker = '+';   // NL "remember this gotcha: always…" → skill
+      if (marker) {
+        const noteText = single ?? (Array.isArray(args.cards) && args.cards[0]?.text) ?? '';
+        if (!String(noteText).trim()) return needInput('Nothing to capture — send text or a card to remember.');
+        return await opBrainNote({ vault: VAULT, canvas: args.canvas ?? 'brain', text: noteText, area: args.area, marker, closes: args.closes, via });
+      }
       // NL convenience: a bare "remember: X" becomes a single card on the brain.
       const cards = args.cards ?? (text.trim() ? [{ text: stripVerb(text) }] : null);
       const parsed = cardsArg.safeParse(cards);
@@ -250,6 +274,7 @@ function routeIntent(text, dataArgs) {
   const t = String(text || '').toLowerCase();
   const named = extractCanvas(text);
   if (/\b(make|build|create|draw|turn .* into).{0,30}(board|canvas|mind ?map|map|diagram)\b/.test(t)) return { skill: 'make_board', args: {} };
+  if (/\b(learn (this|a) skill|teach the brain|remember the (convention|rule|gotcha)|this is a (gotcha|pitfall|footgun))\b/.test(t) || /\bskill:/i.test(text)) return { skill: 'learn_skill', args: {} };
   if (/\b(remember|note this|capture this|log that|record that|add a card)\b/.test(t)) return { skill: 'remember', args: {} };
   // An explicit read verb OR a specific named canvas → read it. Checked BEFORE
   // list so "what's on the roadmap canvas" reads that canvas, not the vault index.

package/bin/klypix-mcp.mjs

@@ -46,6 +46,7 @@ if (process.argv[2] === 'init') {
       { 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: '🛠️ Skills', cards: [{ text: '🛠️ Reusable how-tos, gotchas & conventions land here — emit `🧠 BRAIN [Area] +: <skill>` (or just state a rule like "always X / never Y" and it auto-promotes). Skills resurface every session and never age out, unlike one-time decisions. This is "how we work here", inherited by every future agent.' }] },
       { 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.' }] },
@@ -166,11 +167,11 @@ server.registerTool('add_to_canvas', {
 });
 
 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").',
+  title: 'Write a deliberate note to the project brain (decision / question / milestone / skill / 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 marker "+" to record a 🛠️ SKILL — a reusable how-to/gotcha/convention ("always dedup zKeys before REORDER") that should resurface every session and never age out, distinct from a one-time decision. Use it to remember a decision, ask an open question, mark a milestone, log a skill, 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.'),
+    marker: z.enum(['', '?', '!', '+', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · +=🛠️ skill (reusable how-to/gotcha; always resurfaces, never ages out) · ✓=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").'),

package/package.json

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

@@ -576,7 +576,7 @@ export async function opBrainNote({ vault, canvas, text: noteText, area, marker
   if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
   const file = t.file;
   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.`);
+  if (!['', '?', '!', '✓', '~', '+'].includes(marker)) return err(`Invalid marker "${marker}" — use: (none)=decision · ?=open question · !=milestone · +=skill (reusable how-to) · ✓=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);

package/src/klypix-format.mjs

@@ -561,7 +561,7 @@ export async function tidyBrain(buffer) {
 // decisions + milestones. Everything older stays in the file, reachable via the
 // klypix-canvas MCP search or `--full`. Keeps the session-start cost flat as
 // the brain grows (the full markdown scales with history; this doesn't).
-export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, freshness = null } = {}) {
+export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, maxSkills = 24, freshness = null } = {}) {
     const cutoff = Date.now() - recentDays * 86_400_000;
     const texts = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim());
     const containers = struct.cards.filter(c => c.type === 'container');
@@ -576,9 +576,14 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     // 🎯 (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));
+    // 🛠️ Skills — reusable how-tos / gotchas / procedures (the '+' marker).
+    // Standing reference, NOT a point-in-time event: always shown, never
+    // recency-decayed, and excluded from open/milestones/recent so a skill never
+    // masquerades as (or ages out like) a decision.
+    const skills = rest.filter(c => /🛠/.test(c.text));
+    const open = rest.filter(c => /❓|🎯/.test(c.text) && !/🛠/.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) && !skills.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;
 
@@ -611,6 +616,11 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
         for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
     }
     if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
+    if (skills.length) {
+        push('', '## 🛠️ Skills — how we do things here (reusable; applies every session)');
+        for (const c of skills.slice(0, maxSkills)) push(`- ${fr(c)}${flat(c.text)}`);
+        if (skills.length > maxSkills) push(`- …and ${skills.length - maxSkills} more skill(s) — search the brain.`);
+    }
     // ⚠️ 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');
@@ -685,6 +695,7 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
         }
         if (score <= 0) continue;
         if ((c.createdAt || 0) >= cutoff) score += 0.5; // gentle recency tiebreak, never dominant
+        if (/🛠/.test(c.text)) score += 1; // 🛠️ skills are standing how-tos — surface them when relevant, regardless of age
         scored.push({ card: c, score });
     }
     scored.sort((a, b) => b.score - a.score || (b.card.createdAt || 0) - (a.card.createdAt || 0));
@@ -968,6 +979,25 @@ const overlapScore = (a, b) => {
 // a real `closes: v1.2.0 staged as a github draft` — only 3 long tokens — silently
 // failed to fire.)
 const coverageOf = (target, hay) => { if (!target.size) return 0; let h = 0; for (const w of target) if (hay.has(w)) h++; return h / target.size; };
+
+// ── Auto-skill classifier (skills emerge from the flow, not just the '+' marker) ─
+// A REUSABLE skill (how-to / gotcha / convention) reads as a GENERAL RULE that
+// applies next time — distinct from a one-time decision ("we shipped X"). This is
+// the high-precision signal the capture path uses to AUTO-promote a plain decision
+// or a rationale-bearing commit into a 🛠️ skill, so the brain learns "how we work
+// here" without anyone remembering to type '+'. Deliberately conservative: STRONG
+// rule cues only, and NOT pinned to a one-time event (a version/PR#/date/ship verb
+// makes it "what happened", not "how to do it"). The explicit '+' marker always
+// wins and covers everything this misses; a false miss is cheap, a false skill is
+// noisy — so this errs toward silence.
+const STRONG_SKILL_CUES = /(\balways\b|\bnever\b|\bmust\s+(?:not|always)\b|\bdon'?t\s+(?:ever|forget)\b|\bgotcha\b|\bwatch\s+out\b|\bthe\s+trick\s+is\b|\brule\s+of\s+thumb\b|\bby\s+convention\b|\bpitfall\b|\bfootgun\b|\bremember\s+to\b|\bbe\s+sure\s+to\b)/i;
+const SKILL_EVENT_PINS = /(\bv?\d+\.\d+\.\d+\b|\bPR\s*#?\d+\b|#\d{2,}\b|\b20\d{2}-\d{2}-\d{2}\b|\bshipped\b|\breleased\b|\bpublished\b|\bmerged\b|\bdeployed\b)/i;
+export function looksLikeSkill(text) {
+    const t = String(text || '');
+    if (/🛠|❓|🎯|🏁/.test(t)) return false;      // already glyphed (skill/question/goal/milestone) — don't reclassify
+    return STRONG_SKILL_CUES.test(t) && !SKILL_EVENT_PINS.test(t);
+}
+
 export async function captureIntoBrain(buffer, { cards = [], resolutions = [], updates = [] } = {}) {
     const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45, CLOSE_COVER_AT = 0.6;
     let work = buffer;
@@ -1095,12 +1125,13 @@ 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 (not questions/goals/milestones)
+            if (/❓|🎯|🏁|🛠/.test(card.text)) continue; // only plain decisions supersede (not questions/goals/milestones/skills)
             const nTok = tokenSet(card.text);
             const area = (card.area || '').toLowerCase();
             let best = null, bestScore = 0;
             for (const c of liveTextCards()) {
                 if (area && (c.area || '').toLowerCase() !== area) continue;
+                if (/🛠/.test(c.text)) continue; // never auto-archive a 🛠️ skill via a decision's supersede — skills are standing reference (correct with ~)
                 const s = overlapScore(nTok, tokenSet(c.text));
                 if (s > bestScore) { bestScore = s; best = c; }
             }
@@ -1253,7 +1284,7 @@ export function selectGardenCandidates(struct, { keepNewest = GARDEN_KEEP_NEWEST
         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))
+            .filter(c => c.type === 'text' && c.parentId === ctn.id && (c.text || '').trim() && !/⤵|↩|✅|🛠/.test(c.text))  // 🛠️ skills are standing reference — never consolidate them away
             .sort((a, b) => (a.createdAt || 0) - (b.createdAt || 0));
         const old = children
             .slice(0, Math.max(0, children.length - keepNewest))
@@ -1409,15 +1440,17 @@ export function findStaleOpenCards(struct, { coverAt = 0.6, max = 5 } = {}) {
 // 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).
+// (milestone) | '✓' (resolve+archive a match) | '~' (update a match in place) |
+// '+' (skill — a REUSABLE how-to/gotcha/procedure, standing reference that always
+// surfaces and never ages out, distinct from a point-in-time decision).
 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 prefix = marker === '?' ? '❓ ' : marker === '!' ? '🏁 ' : marker === '+' ? '🛠️ ' : '';
+    const borderColor = marker === '?' ? 'rgba(245,166,35,0.8)' : marker === '!' ? 'rgba(59,130,246,0.8)' : marker === '+' ? 'rgba(139,92,246,0.85)' : '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: [] };