klypix-mcp 1.18.1 → 1.19.0

package/bin/klypix-mcp.mjs

@@ -24,7 +24,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk,
 } from '../src/klypix-core.mjs';
 
 // Real package version for the MCP handshake (was hardcoded '1.0.0', which
@@ -116,6 +116,17 @@ server.registerTool('search_all_brains', {
   },
 }, async ({ query, as_of }) => toContent(await opSearchAllBrains({ vault: VAULT, query, as_of, log })));
 
+server.registerTool('brain_ask', {
+  title: 'Ask the project brain a question (whole-brain, correction-aware answer)',
+  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card (semantic on-device + lexical hybrid), INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Defaults to the project brain ("brain").',
+  inputSchema: {
+    question: z.string().describe('The natural-language question to answer from the brain.'),
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+    as_of: z.string().optional().describe('Optional YYYY-MM-DD: answer as of that date (superseded cards count as live if they were current then).'),
+    k: z.number().optional().describe('Max cards to surface for synthesis (default 10, capped 20).'),
+  },
+}, async ({ question, canvas, as_of, k }) => toContent(await opBrainAsk({ vault: VAULT, canvas, question, as_of, k, log })));
+
 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.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.18.1",
+  "version": "1.19.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",
@@ -53,7 +53,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs"
+    "test": "node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",

package/src/agent-rules.mjs

@@ -55,7 +55,7 @@ survives across sessions, agents, and context resets.
 
 **At the start of a task — read it** so you know the project's state and past decisions:
 - if \`.claude/brain-brief.md\` exists, read it — it is the full session brief the brain hook regenerates at every session start (Focus, open questions, skills, recent decisions).
-- with the \`klypix-canvas\` MCP server: call \`search_canvases\` / \`read_canvas\` (canvas: \`"brain"\`), or \`brain_insights\` for the load-bearing cards.
+- with the \`klypix-canvas\` MCP server: to **answer a question** from the brain ("what did we decide about X?", "where did Y land?"), call \`brain_ask\` — it ranks the whole brain, includes superseded history, and surfaces the current truth for any corrected card. Use \`search_canvases\` for a raw keyword lookup, \`read_canvas\` (canvas: \`"brain"\`) for the whole thing, or \`brain_insights\` for the load-bearing cards.
 - or via CLI: \`npx klypix-read brain.klypix\`
 
 **When you make a real decision, finding, or milestone — capture it HERE** so it persists for the next session/agent:

package/src/klypix-core.mjs

@@ -26,6 +26,7 @@ import {
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
   findUnrecordedMigrations, captureIntoBrain, tidyBrain, noteToCaptureInput,
   selectGardenCandidates, applyGarden, detectContradictions,
+  rankForQuestion, questionContextToMarkdown,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -369,6 +370,40 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
   return { blocks: [text(`# Cross-project matches for "${query}" (${scored.length} hits in ${brains.length} brains, top ${top.length} · ${mode}${asOfNote})\n\n${lines.join('\n')}`)] };
 }
 
+// ── brain_ask — answer a natural-language question over the WHOLE brain ───────
+// "What did we decide about X?" / "Where did the auth work land?" The daily-use
+// surface: hybrid retrieval (semantic on-device + lexical) over every card
+// (including archived history, flagged), correction-aware (a stale hit carries its
+// live correction), assembled into a SYNTHESIS-READY context the calling agent
+// turns into a direct, cited answer. The engine never calls an LLM (pure retrieval
+// + assembly) — same "engine selects, model writes" contract as brain_connect.
+export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log = () => {} }) {
+  const q = String(question || '').trim();
+  if (!q) return err('brain_ask needs a question.');
+  const t = brainTarget(vault, canvas);
+  if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);
+  if (!t.file) return err(`No brain found — looked for ./brain.klypix in the project, then ${vault}. Pass canvas: "<name>".`);
+  const asOfTs = as_of ? Date.parse(as_of) : null;
+  if (as_of && Number.isNaN(asOfTs)) return err(`Bad as_of date: "${as_of}" — use YYYY-MM-DD.`);
+  let struct;
+  try { ({ struct } = await parseKlypix(fs.readFileSync(t.file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  const stamp = brainStamp(t.file, struct, t.how);
+  // Semantic blend (best-effort, time-bounded): embed the question + the brain's
+  // cards on-device, hand rankForQuestion a Map<cardId, cosine>. A missing/warming
+  // model degrades cleanly to pure lexical.
+  let semantic = null, mode = 'lexical';
+  try {
+    const pipe = await Promise.race([getEmbedder(log), new Promise(r => setTimeout(() => r(null), 20_000))]);
+    if (pipe) {
+      const [qv] = await embedTexts(pipe, [q]);
+      const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
+      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); mode = 'semantic+lexical (on-device)'; }
+    }
+  } catch { semantic = null; mode = 'lexical (semantic warming — retry for semantic ranking)'; }
+  const result = rankForQuestion(struct, q, { semantic, k: Math.max(1, Math.min(20, k || 10)), as_of: asOfTs != null ? as_of : null });
+  return { blocks: [text(stamp + questionContextToMarkdown(q, result, { mode, as_of: asOfTs != null ? as_of : null }))] };
+}
+
 export async function opBrainInsights({ vault, canvas, staleDays }) {
   const t = brainTarget(vault, canvas);
   if (t.ambiguous) return ambiguousBrainErr(t.ambiguous);

package/src/klypix-format.mjs

@@ -1006,6 +1006,118 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
     return scored.filter(s => s.score >= minScore).slice(0, topK);
 }
 
+// ── Ask-the-brain — whole-brain, correction-aware retrieval for a question ───
+// The surface a human actually uses ("what did we decide about X?", "where did
+// the auth work land?"). Distinct from the per-prompt recall hook (which injects
+// a few RELATED cards into every prompt) and search_canvases (raw substring): this
+// RANKS the whole brain against a natural-language question and assembles a
+// SYNTHESIS-READY context for the calling agent to answer from — the engine stays
+// model-free (mirrors brain_connect/garden: engine selects, model writes prose).
+// Three things make it an ANSWER path, not a card dump:
+//   1. Hybrid-ready — lexical always (the shared scorer's weights + length-norm),
+//      semantic blended when the caller (core, with the on-device embedder) passes
+//      a sim map; on a lexical miss the semantic floor still surfaces paraphrases.
+//   2. History-aware — INCLUDES archived/superseded cards (penalized + flagged), so
+//      "what did we decide" can show the arc (decided A → changed to B), and an
+//      optional as_of answers "what was true then".
+//   3. Truth-aware — every stale hit carries its live CORRECTION (the P1 machinery),
+//      so the agent answers from the correction, never the outdated card alone.
+// Pure + node-runnable. `semantic` is Map<cardId, 0..1> or null.
+const deathDateOfCard = (text) => { const m = /(?:↩︎ superseded|↩ superseded|✅) (\d{4}-\d{2}-\d{2})/.exec(String(text)); return m ? Date.parse(m[1]) : null; };
+export function rankForQuestion(struct, question, { semantic = null, k = 10, as_of = null, now = Date.now(), semFloor = 0.30, recentDays = 30 } = {}) {
+    const tokens = queryTokens(question);
+    if (!struct || !Array.isArray(struct.cards) || (!tokens.length && !semantic)) return { hits: [], total: 0, tokens };
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const asOfTs = as_of ? Date.parse(as_of) : null;
+    const timeTravel = asOfTs != null && Number.isFinite(asOfTs);
+    const cutoff = now - recentDays * 86_400_000;
+    const scored = [];
+    for (const c of struct.cards) {
+        if (c.type === 'container' || !(c.text || '').trim()) continue;
+        const arch = isArchived(c);
+        if (timeTravel) {
+            if ((c.createdAt || 0) > asOfTs) continue;                     // didn't exist yet
+            if (arch) {
+                // A card archived NOW: keep it ONLY if it demonstrably outlived
+                // as_of (its retirement is stamped LATER) — then it was the live
+                // truth then. If it died by as_of, or carries NO dated stamp (we
+                // can't prove it was still live), exclude it — precision-first, so
+                // a "what was true then" answer never asserts a since-dead fact.
+                const died = deathDateOfCard(c.text);
+                if (died == null || died <= asOfTs) continue;
+            }
+        }
+        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));
+        const lenNorm = Math.min(1, 6 / Math.max(6, Math.log2(bodyW.size || 1)));
+        let lex = 0;
+        for (const tok of tokens) {
+            if (titleW.has(tok)) lex += 3;
+            else if (tagStems.has(tok)) lex += 3;
+            else if (bodyW.has(tok)) lex += lenNorm;
+        }
+        const sem = semantic ? (semantic.get(c.id) ?? null) : null;
+        if (lex <= 0 && (sem == null || sem < semFloor)) continue;         // no lexical AND no strong semantic → skip
+        // In time-travel a surviving card WAS live at as_of, so it is NOT stale
+        // history — don't demote or flag it as archived (that status is a present
+        // fact). Outside time-travel, archived cards are demoted but never excluded
+        // (history matters for "what did we…").
+        const effArch = timeTravel ? false : arch;
+        let score = sem != null ? sem * 10 + Math.min(lex, 6) * 0.5 : lex;
+        if (!timeTravel && (c.createdAt || 0) >= cutoff) score += 0.5;
+        if (/🛠/.test(c.text)) score += 1;                                  // standing skills
+        if (effArch) score -= 1.5;
+        scored.push({ card: c, score, sem, archived: effArch });
+    }
+    scored.sort((a, b) => b.score - a.score || (b.card.createdAt || 0) - (a.card.createdAt || 0));
+    const top = scored.slice(0, k);
+    // Correction overlays on the surfaced hits — a stale card gets its live
+    // corrector so the agent answers from the truth (edge or cue; P1 machinery).
+    // NOT in time-travel: a correction is a PRESENT fact; importing a future
+    // corrector into a "what was true then" answer would contaminate it (a
+    // 2026-05 correction leaking into a 2026-02 query). Then-live cards stand
+    // as they were.
+    let overlays = new Map();
+    if (!timeTravel) { try { overlays = correctionOverlaysFor(struct, top.map(h => h.card)); } catch { /* best-effort */ } }
+    const hits = top.map(h => ({ ...h, correction: overlays.get(h.card.id) || null }));
+    return { hits, total: scored.length, tokens };
+}
+
+// Assemble the ranked hits into a SYNTHESIS-READY markdown context: a header that
+// instructs the agent to answer the question directly (cite cards, honor
+// corrections, admit gaps), then each hit full-text with provenance + lifecycle +
+// its correction. Char-budgeted so a huge brain can't blow the tool result.
+export function questionContextToMarkdown(question, result, { mode = 'lexical', as_of = null, budgetChars = 9000 } = {}) {
+    const { hits, total } = result;
+    const flat = (s) => String(s || '').replace(/\s+/g, ' ').trim();
+    const day = (ts) => ts ? new Date(ts).toISOString().slice(0, 10) : '';
+    if (!hits.length) {
+        return `# No brain cards answer: “${flat(question)}”\n`
+            + `Searched the whole brain (${mode}) and found nothing relevant. Tell the user the brain doesn't cover this yet — don't guess. If you learn the answer this session, capture it: \`🧠 BRAIN [Area]: <decision>\`.\n`;
+    }
+    const out = [];
+    out.push(`# Answer “${flat(question)}” from these ${hits.length} brain card(s)${as_of ? ` (as of ${as_of})` : ''} — ${total} matched, ${mode} ranking`);
+    out.push('_Synthesize a DIRECT answer from the cards below, then cite the ones you used by [Area]+date. Where a card is marked ⚠️ CORRECTED, answer from the correction, NOT the stale card. Include superseded/archived cards only to show how a decision CHANGED. If the cards don\'t actually answer the question, say so — don\'t pad._');
+    out.push('');
+    let used = out.join('\n').length;
+    let shown = 0;
+    for (const h of hits) {
+        const c = h.card;
+        const status = h.archived ? ' · ⛔ archived/superseded' : '';
+        const rel = h.sem != null ? ` · sim ${h.sem.toFixed(2)}` : '';
+        let block = `## [${flat(c.area) || 'Notes'}] ${day(c.createdAt)}${status}${rel}\n${flat(c.text)}`;
+        if (h.correction) {
+            block += `\n\n  ⚠️ CORRECTED — this card is STALE; the current truth is:\n  ${flat(h.correction.by.text).slice(0, 600)}`;
+        }
+        if (used + block.length + 2 > budgetChars && shown > 0) { out.push(`\n_…and ${hits.length - shown} more matched card(s) omitted for length — narrow the question or use search for the rest._`); break; }
+        out.push(block, '');
+        used += block.length + 2;
+        shown++;
+    }
+    return out.join('\n') + '\n';
+}
+
 // ── External-state reconcile — migration omission tripwire ───────────────────
 // The brain is a NARRATION-capture system: a fact exists only if someone wrote a
 // 🧠 marker or a rationale-bearing commit body. Applying a DB migration to prod