klypix-mcp 1.86.1 → 1.86.3

package/README.md

@@ -290,7 +290,7 @@ For a reproducible map artifact on every pull request and main-branch push, inst
 read-only workflow into a Git checkout:
 
 ```bash
-npx klypix-project-map setup-github /path/to/project
+npx -y -p klypix-mcp klypix-project-map setup-github /path/to/project
 ```
 
 The command refuses to overwrite an existing workflow unless `--force` is explicit. The installed
@@ -314,7 +314,7 @@ behaviour is unverified.
 | **VS Code (Copilot / Continue)** | MCP config + instructions file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
 | **Gemini CLI / Antigravity** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
 | **Windsurf** | Rules file only | `link` | Reaches the tools through Windsurf's own global MCP config | Model must call `brain_note` | Via its own MCP config |
-| **Aider** | Rules file only (no MCP) | `link` | CLI path: `npx klypix-read` | CLI path: `npx klypix-append` | — |
+| **Aider** | Rules file only (no MCP) | `link` | CLI path: `npx -y -p klypix-mcp klypix-read` | CLI path: `npx -y -p klypix-mcp klypix-append` | — |
 | **Claude Desktop** | One-time manual config edit | you | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
 
 `install` and `link` are different things and are not interchangeable: `install` sets up the

package/bin/klypix-install.mjs

@@ -436,7 +436,9 @@ try {
     // deliberately preserving every host/project config byte.
     const brainCmd = (arg) => `node "${fwd(path.join(BRAIN_DIR, 'global-brain-hook.mjs'))}"${arg ? ' ' + arg : ''}`;
     const GROUPS = [
-        ['SessionStart', { matcher: 'startup|resume', hooks: [{ type: 'command', command: brainCmd('') }] }],
+        // "clear" (1.86.2): a /clear starts a new conversation that needs the
+        // brief as much as a fresh one does.
+        ['SessionStart', { matcher: 'startup|resume|clear', hooks: [{ type: 'command', command: brainCmd('') }] }],
         ['UserPromptSubmit', { hooks: [{ type: 'command', command: brainCmd('--prompt'), timeout: 10 }] }],
         ['Stop', { hooks: [{ type: 'command', command: brainCmd('--capture') }] }],
         ['PostToolUse', { matcher: 'Bash|PowerShell|Edit|Write', hooks: [{ type: 'command', command: brainCmd('--live'), timeout: 10 }] }],

package/bin/klypix-worker.mjs

@@ -94,7 +94,9 @@ const runVerb = async (verb, moduleId) => {
 // into ~/.claude/project-brain and wire the Claude Code hooks. This is the single
 // agent-neutral installer, so a brain release reaches every machine via one npm
 // publish + this command (the global brain serves every project). Runs before any
-// server setup; delegates to the dedicated bin so `npx klypix-install` also works.
+// server setup; delegates to the dedicated bin so `npx -p klypix-mcp klypix-install`
+// also works (the bin name on its own is not an npm package we own — see
+// test/npx-owned-names.mjs).
 await runVerb('install', './klypix-install.mjs');
 
 // `npx klypix-mcp link` — make THIS project's brain automatic for EVERY agent tool,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.86.1",
+  "version": "1.86.3",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -84,7 +84,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/enrichment.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs &&node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",

package/src/agent-rules.mjs

@@ -444,12 +444,12 @@ survives across sessions, agents, and context resets.
 - do NOT automatically read the full \`.claude/brain-brief.md\`; open it only when \`brain_sync\`
   says its compact context is insufficient or the task asks for broad project history/status.
 - 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\`
+- or via CLI: \`npx -y -p klypix-mcp klypix-read brain.klypix\`
 
 **When you make a real decision, finding, or milestone — capture it HERE** so it persists for the next session/agent:
 - with MCP: call \`brain_note\` with a one-line decision, or
 - emit a marker line in your output: \`🧠 BRAIN [Area]: <one-line decision>\`, or
-- via CLI: \`echo "🧠 BRAIN [Area]: <decision>" | npx klypix-append brain.klypix\`
+- via CLI: \`echo "🧠 BRAIN [Area]: <decision>" | npx -y -p klypix-mcp klypix-append brain.klypix\`
 
 Capture **sparingly** — real decisions / milestones / open questions / reusable gotchas, not routine
 steps — and capture it **at the moment you decide** (a one-line marker inline), not batched or left in

package/src/brain-doctor.mjs

@@ -111,7 +111,15 @@ function inspectHooks(home) {
   const present = !!settings;
   const wired = present ? HOOK_EVENTS.filter(wiredFor) : [];
   const missing = present ? HOOK_EVENTS.filter(e => !wired.includes(e)) : HOOK_EVENTS.slice();
-  return { settingsPresent: present, wired, missing };
+  // Informational (never a verdict): installs before 1.86.2 wired SessionStart
+  // for "startup|resume" only, so /clear starts a conversation with no brain
+  // brief. A runtime-only update never rewrites settings.json; a full
+  // `npx klypix-mcp install` does. An empty/absent matcher means every source.
+  const ours = (Array.isArray(settings?.hooks?.SessionStart) ? settings.hooks.SessionStart : [])
+    .filter(g => Array.isArray(g?.hooks) && g.hooks.some(h => typeof h?.command === 'string' && h.command.includes(HOOK_MARK)));
+  const coversClear = (g) => !g.matcher || String(g.matcher).split('|').map(x => x.trim()).some(x => x === 'clear' || x === '*');
+  const sessionStartMissesClear = ours.length > 0 && !ours.some(coversClear);
+  return { settingsPresent: present, wired, missing, sessionStartMissesClear };
 }
 
 // ── TOOLS (discoverable manifest) layer ──────────────────────────────────────
@@ -788,6 +796,7 @@ export function render(r, opts = {}) {
   else if (r.hooks.missing.length === 1 && r.hooks.missing[0] === 'PreToolUse') L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   capture path intact; ${c.yel}guard lane not wired yet${c.rst} — \`npx klypix-mcp install\` adds the PreToolUse hook (guard cards)`);
   else if (r.hooks.missing.length) L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   half-wired — missing: ${c.yel}${r.hooks.missing.join(', ')}${c.rst}  ${c.dim}(liveness up, readiness no)${c.rst}`);
   else L.push(`${hmark} ${c.bold}CLAUDE${c.rst}   existing 5-hook capture path intact: ${r.hooks.wired.join(', ')}`);
+  if (r.hooks.sessionStartMissesClear) L.push(`   ${c.dim}note: SessionStart is not wired for /clear — a cleared conversation starts without the brain brief; "npx klypix-mcp install" adds "clear" to its matcher${c.rst}`);
   const chmark = r.layers.codexHooks === 'warning' ? warn : ok;
   const smart = r.codexSmart?.globalInstructions
     ? 'approval-free Context Gateway active (task memory + clean peers + proactive/guaranteed alerts)'

package/src/brain-semantic.mjs

@@ -118,6 +118,21 @@ async function embedQueries(pipe, texts) {
 // Vectors are unit-normalized, so dot == cosine.
 export const dot = (a, b) => { let s = 0; const n = Math.min(a.length, b.length); for (let i = 0; i < n; i++) s += a[i] * b[i]; return s; };
 
+// Copy of vectorEntryMatchesText in semantic-memory.mjs, where the rule is
+// explained (this one-shot module cannot import the long-lived runtime). It
+// takes precomputed hashes and references nothing outside itself. Keep the two
+// identical: test/semantic-hash-parity.mjs compares them.
+export function vectorEntryMatchesText(entry, fullHash, truncatedHash) {
+    try {
+        if (!entry || !entry.v || typeof fullHash !== 'string' || !fullHash) return false;
+        if (typeof entry.t === 'string' && entry.t === fullHash) return true;
+        if (typeof entry.h !== 'string' || !entry.h) return false;
+        if (entry.h === fullHash) return true;
+        const truncated = typeof truncatedHash === 'function' ? truncatedHash() : null;
+        return typeof truncated === 'string' && truncated !== '' && entry.h === truncated;
+    } catch { return false; }
+}
+
 // READ-ONLY card-vector cache — NEVER embeds or writes (embedding all cards in the
 // per-prompt process is the multi-second stall we forbid). Reuses the SAME warm
 // cache the MCP host fills. Current workers canonicalize absolute Windows paths
@@ -141,10 +156,23 @@ function readCachedVecs(brainPath, cards) {
         } catch { /* try next variant */ }
     }
     const map = new Map();
-    // A vector is accepted only for the text it was embedded from (the cache
-    // stores sha1(text) as `h`) — an edited card must fall back to lexical, never
-    // pair on a stale embedding (parity with semantic-memory.cachedVectorsForBrain).
-    if (cache && cache.cards) for (const c of cards) { const e = cache.cards[c.id]; if (e && e.v && (!e.h || e.h === sha1(String(c.text)))) map.set(c.id, e.v); }
+    // A vector is accepted only when its entry proves it was embedded from the
+    // card's current text: the full-text fingerprint `t`, or for an entry written
+    // before `t` existed its `h` against the full or the truncated text (`h` is
+    // the hash of the EMBED INPUT: the first 1,500 characters plus enrichment).
+    // An edited card must fall back to lexical, never pair on a stale embedding.
+    // Same card filter and same acceptance rule as
+    // semantic-memory.cachedVectorsForBrain, on ONE cache file: this reader
+    // stops at the first variant carrying the current modelKey, the server
+    // reader merges every alias file, so the two can differ until a writer run
+    // folds the aliases into the canonical file. The entry lookup comes first
+    // so a card with no cached vector costs no hash.
+    if (cache && cache.cards) for (const c of cards) {
+        if (!c || c.type === 'container' || typeof c.text !== 'string' || !c.text.trim()) continue;
+        const e = cache.cards[c.id];
+        if (!e || !e.v) continue;
+        if (vectorEntryMatchesText(e, sha1(c.text), () => (c.text.length > 1500 ? sha1(c.text.slice(0, 1500)) : null))) map.set(c.id, e.v);
+    }
     return map;
 }