klypix-mcp 1.2.0 → 1.3.0

package/bin/klypix-mcp.mjs

@@ -305,9 +305,17 @@ server.registerTool('search_all_brains', {
     let qv = null;
     if (pipe) { try { [qv] = await embedTexts(pipe, [q]); } catch { /* lexical only */ } }
 
+    // Current-project locality prior: a card from the project you're working in
+    // should outrank an equally-relevant card from an unrelated project (the
+    // "cross-project search drowned my own project's cards" complaint). The boost
+    // below is modest + mode-aware — never enough to bury a much stronger foreign hit.
+    let curKey = null;
+    try { const cb = resolveCanvas('brain') || resolveCanvas('brain.klypix'); if (cb) curKey = path.resolve(cb).replace(/\\/g, '/').toLowerCase(); } catch { /* no current brain */ }
     const fresh = Date.now() - 30 * 86_400_000;
     const scored = [];
     for (const b of brains) {
+        let isCur = false;
+        try { isCur = !!curKey && path.resolve(b.path).replace(/\\/g, '/').toLowerCase() === curKey; } catch { /* */ }
         let struct;
         try { ({ struct } = await parseKlypix(fs.readFileSync(b.path))); } catch { continue; }
         let vecs = null;
@@ -340,8 +348,9 @@ server.registerTool('search_all_brains', {
             if (asOfTs == null) {
                 if ((c.createdAt || 0) >= fresh) score += 0.5;
                 if (isArchived) score -= 1;
+                if (isCur) score += sem != null ? 1.5 : 1; // current-project locality prior
             }
-            scored.push({ score, sem, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c });
+            scored.push({ score, sem, cur: isCur, 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).` }] };
@@ -349,7 +358,7 @@ server.registerTool('search_all_brains', {
     const top = scored.slice(0, 20);
     const lines = top.map(h => {
         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 `- ${h.cur ? '★ ' : ''}[${h.project}${h.area ? ' › ' + h.area : ''}] ${when} ${String(h.c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
     });
     const mode = qv ? 'semantic+lexical (on-device)' : 'lexical (semantic model warming — retry for semantic ranking)';
     const asOfNote = asOfTs != null ? ` · as of ${as_of}` : '';
@@ -520,3 +529,8 @@ server.registerTool('add_to_canvas', {
 const transport = new StdioServerTransport();
 await server.connect(transport);
 log(`ready · vault=${VAULT}`);
+// Pre-warm the on-device embedder in the BACKGROUND so the first cross-project
+// search of a session is already semantic, not a lexical fallback while the
+// MiniLM model loads. getEmbedder() memoizes + swallows its own errors, so this
+// is a safe fire-and-forget (no await → zero added startup latency).
+getEmbedder().then(p => log(p ? 'semantic ready (pre-warmed)' : 'semantic unavailable — lexical only')).catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.2.0",
+  "version": "1.3.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-format.mjs

@@ -113,6 +113,9 @@ export async function parseKlypix(buffer) {
             parentId: it.parentId ?? null,
             // Parent container's title — the card's "area" in brain terms.
             area: it.parentId ? (cardTitle(items[it.parentId]) || null) : null,
+            // Evidence anchors (file:line / PR#) with the git blob OID stamped at
+            // capture-time — lets the hook flag a card whose cited code drifted.
+            evidence: Array.isArray(it.evidence) && it.evidence.length ? it.evidence : null,
         })),
         connections: connections.map(c => ({
             from: titleOf(c.fromId), to: titleOf(c.toId),
@@ -464,6 +467,8 @@ export async function appendIntoContainers(buffer, addition) {
             // Provenance: WHICH agent remembered this (claude-code / cursor /
             // cline / …) — additive field, ignored by older readers.
             ...(card.createdVia ? { createdVia: String(card.createdVia) } : {}),
+            // Evidence anchors (file:line / PR#) — additive, ignored by older readers.
+            ...(Array.isArray(card.evidence) && card.evidence.length ? { evidence: card.evidence } : {}),
             content: wrapped, fontSize: G.FONT,
             color: card.color || '#e8e8ed', border: true, borderColor: card.borderColor || card.color || 'rgba(16,185,129,0.45)',
             fillColor: 'rgba(18,18,26,0.85)', heading: !!card.heading, fontFamily: 'Thmanyah Sans',
@@ -556,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 } = {}) {
+export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMilestones = 8, maxConnections = 30, 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');
@@ -575,6 +580,9 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const archivedCount = texts.length - live.length;
 
     const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    // Freshness badge (✅ verified / ⚠️ drifted / 🌱 unverified) for code-anchored
+    // cards — supplied by the git-aware hook; absent → no badge. Trust at a glance.
+    const fr = (c) => (freshness && freshness[c.id]) ? freshness[c.id] + ' ' : '';
     // HEADLINE = first sentence-ish, hard-capped — the brief is a scannable
     // changelog; the agent pulls any card's full text via the MCP when needed.
     const headline = (c, max = 160) => {
@@ -597,9 +605,9 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     push(`*${struct.format} · ${struct.counts.cards} cards · ${struct.counts.connections} connections · tiered brief (focus + open + last ${recentDays}d headlines); full cards via klypix-canvas MCP search*`);
     if (focus.length) {
         push('', '## 📌 Human focus (cards the human placed here — act on these first)');
-        for (const c of focus) push(`- ${flat(c.text)}`);
+        for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
     }
-    if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${flat(c.text)}`); }
+    if (open.length) { push('', '## Open questions'); 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');
@@ -610,7 +618,7 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     if (areaCounts.length) { push('', '## Areas', areaCounts.join(' · ')); }
     if (miles.length) {
         push('', '## Milestones');
-        for (const c of miles.sort((a, b) => b.createdAt - a.createdAt).slice(0, maxMilestones)) push(`- ${headline(c)}`);
+        for (const c of miles.sort((a, b) => b.createdAt - a.createdAt).slice(0, maxMilestones)) push(`- ${fr(c)}${headline(c)}`);
     }
     let shownRecent = 0;
     if (recent.length) {
@@ -621,7 +629,7 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
             push(`### ${a}`);
             for (const c of cs) {
                 if (used > BUDGET_CHARS) break outer;
-                push(`- ${day(c.createdAt)} ${headline(c)}`);
+                push(`- ${fr(c)}${day(c.createdAt)} ${headline(c)}`);
                 shownRecent++;
             }
         }
@@ -680,6 +688,47 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
     return scored.filter(s => s.score >= minScore).slice(0, topK);
 }
 
+// ── Repeat / redundancy detection ("you already did this in another session") ─
+// The PRECISION-first sibling of scoreCardsAgainstQuery. Instead of "related
+// context" it answers a sharper question: is the user about to REDO work that's
+// already DONE? It scans COMPLETED-work cards ONLY — 🏁 shipped, ✅ resolved,
+// ↩︎ superseded — and INCLUDES the Archive (resolved/superseded cards live there,
+// which the relevance ranker deliberately skips). Deliberately strict: a high
+// score floor + ≥2 distinct query-token hits, because for a NUDGE a false "you
+// already did this" is costly (erodes trust) while a miss is cheap (the loose
+// recall list still shows below). Returns each card's `kind` so the caller can
+// say "reuse it" (shipped/resolved) vs "see what replaced it" (superseded).
+// Pure + node-runnable; reuses the one shared tokenizer — no divergent scorer.
+export function detectRepeatWork(struct, query, { topK = 2, minScore = 5, minTokens = 2 } = {}) {
+    const tokens = Array.isArray(query) ? query.filter(Boolean) : queryTokens(query);
+    if (tokens.length < minTokens || !struct || !Array.isArray(struct.cards)) return [];
+    const kindOf = (t) => /🏁/.test(t) ? 'shipped' : /✅/.test(t) ? 'resolved' : /↩/.test(t) ? 'superseded' : null;
+    const rank = { shipped: 2, resolved: 2, superseded: 1 };
+    const out = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !(c.text || '').trim()) continue;
+        const kind = kindOf(c.text);
+        if (!kind) continue;                          // only COMPLETED-work cards qualify
+        // Score the first MEANINGFUL line, not a marker stamp: supersede/resolve
+        // prepend "↩︎ superseded <date>" / lead with "✅ …", which would otherwise
+        // become the title and hide the real content from title-weighted matching.
+        const firstMeaningful = String(c.text).split('\n').map(s => s.trim()).filter(Boolean).find(l => !/^[↩✅🏁]/u.test(l));
+        const titleW = wordsOf(firstMeaningful || 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, matched = 0;
+        for (const tok of tokens) {
+            if (titleW.has(tok)) { score += 3; matched++; }
+            else if (tagStems.has(tok)) { score += 3; matched++; }
+            else if (bodyW.has(tok)) { score += 1; matched++; }
+        }
+        if (matched < minTokens || score < minScore) continue;   // precision-first floor
+        out.push({ card: c, score, kind });
+    }
+    out.sort((a, b) => b.score - a.score || (rank[b.kind] - rank[a.kind]) || (b.card.createdAt || 0) - (a.card.createdAt || 0));
+    return out.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,
@@ -863,9 +912,9 @@ const overlapScore = (a, b) => {
     return hit / Math.min(a.size, b.size);
 };
 export async function captureIntoBrain(buffer, { cards = [], resolutions = [], updates = [] } = {}) {
-    const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45;
+    const SUPERSEDE_AT = 0.6, RESOLVE_AT = 0.3, UPDATE_AT = 0.45, CLOSE_AT = 0.25;
     let work = buffer;
-    const stats = { added: 0, superseded: 0, resolved: 0, linked: 0, updated: 0 };
+    const stats = { added: 0, superseded: 0, resolved: 0, linked: 0, updated: 0, closed: 0 };
 
     // Pass 1 — resolutions + supersede marking operate on EXISTING cards.
     if (resolutions.length || cards.length || updates.length) {
@@ -974,11 +1023,14 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
                     j.createdAt = now;
                     j.borderColor = 'rgba(16,185,129,0.6)';
                     if (u.createdVia) j.createdVia = String(u.createdVia);
+                    // Self-heal: a ~ update re-stamps the evidence (fresh OID +
+                    // verifiedAt), so confirming/correcting a drifted fact marks it ✅.
+                    if (Array.isArray(u.evidence) && u.evidence.length) j.evidence = u.evidence;
                 });
                 best.text = u.text;
                 stats.updated++;
             } else {
-                cards.push({ text: (u.area ? `${u.area}: ` : '') + u.text + (u.area ? `\n#${u.area.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : ''), area: u.area, createdVia: u.createdVia });
+                cards.push({ text: (u.area ? `${u.area}: ` : '') + u.text + (u.area ? `\n#${u.area.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : ''), area: u.area, createdVia: u.createdVia, ...(Array.isArray(u.evidence) && u.evidence.length ? { evidence: u.evidence } : {}) });
             }
         }
 
@@ -1007,6 +1059,38 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             }
         }
 
+        // CLOSE-LINK — a card carrying `closes` resolves the (often cross-area)
+        // strategy/question card that SPAWNED it: stamp ✅, archive it, and draw a
+        // "closed by" arrow in pass 2. Unlike supersede (same-area, high lexical
+        // overlap), a shipped milestone rarely echoes the strategy's prose — so
+        // this matches across ALL areas, prefers an explicit [[wikilink]]/title
+        // hit, and otherwise fires on only a low overlap. This is the fix for
+        // "strategy cards never get closed out when their feature actually ships".
+        for (const card of cards) {
+            const target = (card.closes || '').toString().trim();
+            if (!target) continue;
+            const wantTitle = target.replace(/^\[\[/, '').replace(/\]\]$/, '').trim().toLowerCase();
+            const tTok = tokenSet(target);
+            let best = null, bestScore = 0;
+            for (const c of liveTextCards()) {
+                const ct = (c.title || '').trim().toLowerCase();
+                if (ct && wantTitle && (ct === wantTitle || ct.startsWith(wantTitle) || wantTitle.startsWith(ct))) { best = c; bestScore = 1; break; }
+                const s = overlapScore(tTok, tokenSet(c.text));
+                if (s > bestScore) { bestScore = s; best = c; }
+            }
+            if (best && bestScore >= CLOSE_AT) {
+                const ship = String(card.text).replace(/\s+/g, ' ').replace(/^[^:\n]{1,40}:\s*/, '').replace(/^🏁\s*/, '').trim().slice(0, 80);
+                await rewriteCard(best.id, j => {
+                    j.content = `${j.content}\n✅ ${today}: closed by → ${ship}`;
+                    j.borderColor = 'rgba(16,185,129,0.35)';
+                });
+                await archiveCard(best.id);
+                best.text = `✅ ${best.text}`;
+                card.__closes = best.id;
+                stats.closed++;
+            }
+        }
+
         cards.push(...milestonesFallback);
         work = await finalizeBrainZip(zip, canvas, manifest, now);
     }
@@ -1042,6 +1126,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             const created = findNew(card.text);
             if (!created) continue;
             if (card.__supersedes) addConn(card.__supersedes, created.id, 'superseded by', undefined);
+            if (card.__closes) addConn(card.__closes, created.id, 'closed by', undefined);
             for (const link of (created.links || [])) {
                 const want = String(link).trim().toLowerCase();
                 if (!want) continue;