knit-mcp 0.11.4 → 0.12.0

package/README.md

@@ -452,6 +452,7 @@ LongMemEval-S R@5/R@10 + LOCOMO LLM-as-Judge runs are on the roadmap (v0.13+). U
 
 | Version | Headline |
 |---|---|
+| **v0.12.0** | **Picture Perfect: Structural Enforcement.** Diagnostic → enforcing. Budget verdict surfaces in the MCP `instructions` field at handshake (before any tool description is read). `knit_load_session` carries `budget_health` + `learnings_health` nudges. `engram doctor` exits non-zero on over-budget; `engram setup` runs doctor as final step. New PostToolUse hook warns immediately on over-budget CLAUDE.md edits (HOOKS_VERSION 11→12; auto-rolls to existing users). This repo dogfoods: hand-curated 16KB CLAUDE.md migrated to lean 3.8KB + `.claude/MARKETING.md` sidecar. New `npm run bench:tokens` measures real MCP-on vs MCP-off cost: 93% smaller per-recall call, 50% smaller per-classify, payback at 3 recall calls. 53 tools, 705 tests. |
 | **v0.11.4** | Dogfood audit · ran a full audit of Knit's own codebase using its own `knit_spawn_team_worktree` primitive (4 parallel teams: Core Logic, Infrastructure, UI, Quality Assurance). Fixes: HIGH `engram refresh` no longer clobbers user-curated CLAUDE.md (now uses `spliceKnitBlock` like `cache.ts`); `saveSource`/`loadSource` validate `sourceId`; `appendGlobalLearning` propagates write failures; `redactSecrets` applied to `label`/`tags`/`domains` across all persistence boundaries; 100KB response ceiling on `knit_generate_test_cases`; full v0.11 tool surface now documented in `workflow-protocol.ts` generator (was frozen at the v0.4 surface). Plus: 16 key tools reclassified with `[PROTOCOL]`/`[REVIEW]`/`[MEMORY]`/`[GRAPH]` prefixes so the LLM picks the right tool reliably. 53 tools, 687 tests. |
 | **v0.11.3** | Propagation patch · `update_available` flag now surfaces in `knit_load_session` response (≈100% session reach vs. brain_status' low reach) + startup stderr nag on stale versions. Helps FUTURE upgrades land faster; doesn't retroactively reach v0.10.x users. 53 tools, 665 tests. |
 | **v0.11.2** | Pre-publish polish · chunk cap (2000) + `errorResponse` envelope across handlers + CLAUDE.md generator surfaces v0.11 tools · new `engram doctor` install health-check CLI · upgrade-path smoke test caught + fixed a data-loss bug in cache.ts (Case B was wiping user permissions on upgrade) · 11 real exploit-payload integration tests prove C1/C2/H1 fixes hold · `npm run bench` ships a synthetic retrieval harness (50 Q&A) measuring 86% top-1 / 96% R@5. 53 tools, 664 tests. |

package/dist/{cache-7HSMIYDJ.js → cache-46OKHDRR.js}

@@ -2,9 +2,9 @@ import {
   detectProjectRoot,
   getBrain,
   refreshBrain
-} from "./chunk-I63UMEBF.js";
-import "./chunk-HROSQ5MS.js";
+} from "./chunk-KKLAJLPO.js";
 import "./chunk-GATMQQK5.js";
+import "./chunk-WADRF26Z.js";
 import "./chunk-WKQHCLLO.js";
 import "./chunk-MOOVNMIN.js";
 import "./chunk-ST4X7LZT.js";

package/dist/{chunk-I63UMEBF.js → chunk-KKLAJLPO.js}

@@ -1,11 +1,11 @@
-import {
-  HOOKS_VERSION,
-  generateSettings
-} from "./chunk-HROSQ5MS.js";
 import {
   installAgentsForProject,
   pruneSessionsByAge
 } from "./chunk-GATMQQK5.js";
+import {
+  HOOKS_VERSION,
+  generateSettings
+} from "./chunk-WADRF26Z.js";
 import {
   importFromMarkdown,
   loadKnowledgeBaseSafe,

package/dist/{chunk-LV73YTVN.js → chunk-QQNHF4XY.js}

@@ -1,4 +1,6 @@
 // src/mcp/instructions.ts
+import { statSync } from "fs";
+import { join } from "path";
 var KNIT_INSTRUCTIONS_BASE = `Knit is a memory + workflow layer for this project. It provides per-project memory across sessions, a knowledge graph (imports/exports/tests), and a tier-routed workflow protocol.
 
 ALWAYS at session start:
@@ -32,8 +34,28 @@ Knit provides inputs; you make the calls. When in doubt, under-classify \u2014 e
 
 Citation rule: when you state a fact about this codebase ("file X imports Y", "function Z is defined in W", "tests for A live in B"), cite the Knit tool result that verified it \u2014 e.g. "(per knit_query_imports)". If you can't cite a tool result, mark the claim as 'unverified' explicitly. This makes hallucinations visible at the claim level instead of letting them ship as confident-sounding prose. The verifier exists; use it.`;
 var KNIT_INSTRUCTIONS = KNIT_INSTRUCTIONS_BASE;
-function buildInstructions(scan) {
-  if (!scan) return KNIT_INSTRUCTIONS_BASE;
+var CLAUDE_MD_BUDGET_BYTES = 6500;
+function buildBudgetVerdict(rootPath) {
+  let bytes = 0;
+  try {
+    bytes = statSync(join(rootPath, "CLAUDE.md")).size;
+  } catch {
+    return "";
+  }
+  if (bytes <= CLAUDE_MD_BUDGET_BYTES) return "";
+  const verdict = bytes > CLAUDE_MD_BUDGET_BYTES * 1.25 ? "over-budget" : "warn";
+  const kb = Math.round(bytes / 1024 * 10) / 10;
+  const targetKb = Math.round(CLAUDE_MD_BUDGET_BYTES / 1024 * 10) / 10;
+  return `BUDGET ${verdict}: CLAUDE.md is ${kb}KB / ${targetKb}KB target. Run \`engram doctor\` to see the full per-surface report and \`engram refresh\` to regenerate the marker block.`;
+}
+function buildInstructions(scan, rootPath) {
+  const budgetLine = rootPath ? buildBudgetVerdict(rootPath) : "";
+  const budgetSuffix = budgetLine ? `
+
+\u2014 Budget check \u2014
+
+${budgetLine}` : "";
+  if (!scan) return KNIT_INSTRUCTIONS_BASE + budgetSuffix;
   const addenda = [];
   if (scan.detected.ruflo.present) {
     addenda.push(
@@ -60,12 +82,14 @@ function buildInstructions(scan) {
       `DETECTED: this project's CLAUDE.md has user-curated workflow sections (${scan.detected.custom_workflow_sections.join("; ")}). Treat that as the canonical workflow doc for project-specific phases; Knit's tier protocol applies underneath as the routing layer.`
     );
   }
-  if (addenda.length === 0) return KNIT_INSTRUCTIONS_BASE;
-  return KNIT_INSTRUCTIONS_BASE + "\n\n\u2014 Per-project integrations \u2014\n\n" + addenda.join("\n\n") + "\n\nGeneral rule: when an integration above provides a higher-level routing primitive (slash command, swarm orchestrator, methodology framework), use it. Knit handles the substrate it doesn't cover: memory, classification, and the workflow protocol for tasks the integration doesn't route.";
+  if (addenda.length === 0) return KNIT_INSTRUCTIONS_BASE + budgetSuffix;
+  return KNIT_INSTRUCTIONS_BASE + "\n\n\u2014 Per-project integrations \u2014\n\n" + addenda.join("\n\n") + "\n\nGeneral rule: when an integration above provides a higher-level routing primitive (slash command, swarm orchestrator, methodology framework), use it. Knit handles the substrate it doesn't cover: memory, classification, and the workflow protocol for tasks the integration doesn't route." + budgetSuffix;
 }
 
 export {
   KNIT_INSTRUCTIONS_BASE,
   KNIT_INSTRUCTIONS,
+  CLAUDE_MD_BUDGET_BYTES,
+  buildBudgetVerdict,
   buildInstructions
 };

package/dist/{doctor-4DN2P2JR.js → chunk-TE6NP6BZ.js}

@@ -1,9 +1,12 @@
+import {
+  HOOKS_VERSION
+} from "./chunk-WADRF26Z.js";
 import {
   VERSION
 } from "./chunk-UTVFELXS.js";
 import {
-  HOOKS_VERSION
-} from "./chunk-HROSQ5MS.js";
+  CLAUDE_MD_BUDGET_BYTES
+} from "./chunk-QQNHF4XY.js";
 import {
   knowledgebasePath,
   projectDataDir
@@ -125,6 +128,45 @@ function runDoctor(rootPath) {
     } catch {
     }
   }
+  const claudeMdPath = join(rootPath, "CLAUDE.md");
+  if (existsSync(claudeMdPath)) {
+    try {
+      const bytes = statSync(claudeMdPath).size;
+      const kb = Math.round(bytes / 1024 * 10) / 10;
+      const targetKb = Math.round(CLAUDE_MD_BUDGET_BYTES / 1024 * 10) / 10;
+      if (bytes <= CLAUDE_MD_BUDGET_BYTES) {
+        checks.push({
+          name: "Token budget",
+          status: "ok",
+          detail: `CLAUDE.md ${kb}KB / ${targetKb}KB target \u2014 healthy`
+        });
+      } else if (bytes <= CLAUDE_MD_BUDGET_BYTES * 1.25) {
+        checks.push({
+          name: "Token budget",
+          status: "warn",
+          detail: `CLAUDE.md ${kb}KB / ${targetKb}KB target \u2014 over budget, within 25% slack. Run \`engram refresh\` or trim the file.`
+        });
+      } else {
+        checks.push({
+          name: "Token budget",
+          status: "error",
+          detail: `CLAUDE.md ${kb}KB / ${targetKb}KB target \u2014 over budget by >25%. Move long-form content to .claude/MARKETING.md or run \`engram refresh\`.`
+        });
+      }
+    } catch (err) {
+      checks.push({
+        name: "Token budget",
+        status: "warn",
+        detail: `CLAUDE.md unreadable: ${err.message}`
+      });
+    }
+  } else {
+    checks.push({
+      name: "Token budget",
+      status: "info",
+      detail: "no CLAUDE.md yet \u2014 created on first MCP call"
+    });
+  }
   const nodeMajor = parseInt(process.versions.node.split(".")[0], 10);
   if (Number.isFinite(nodeMajor) && nodeMajor < 18) {
     checks.push({
@@ -173,7 +215,8 @@ async function doctorCommand(directory) {
     console.log(chalk.green("  All checks passed \u2014 install is healthy."));
   }
 }
+
 export {
-  doctorCommand,
-  runDoctor
+  runDoctor,
+  doctorCommand
 };

package/dist/{chunk-HROSQ5MS.js → chunk-WADRF26Z.js}

@@ -15,7 +15,7 @@ import {
 } from "./chunk-27TA2ZQZ.js";
 
 // src/generators/settings.ts
-var HOOKS_VERSION = 11;
+var HOOKS_VERSION = 12;
 function generateSettings(config, rootPath) {
   return {
     mcpServers: {
@@ -288,6 +288,39 @@ function generateHooks(config, rootPath) {
       }
     ]
   });
+  hooks.PostToolUse.push({
+    _knitOwned: true,
+    matcher: "Write|Edit|MultiEdit",
+    hooks: [
+      {
+        type: "command",
+        command: nodeHook(`
+          let d = "";
+          process.stdin.on("data", (c) => d += c);
+          process.stdin.on("end", () => {
+            try {
+              const fs = require("fs");
+              const path = require("path");
+              const i = JSON.parse(d);
+              const ti = i.tool_input || {};
+              const f = ti.file_path || (i.tool_response && i.tool_response.filePath) || "";
+              if (!f) return;
+              if (path.basename(f) !== "CLAUDE.md") return;
+              const TARGET = 6500;
+              const SLACK = 6500 * 1.25;
+              let size = 0;
+              try { size = fs.statSync(f).size; } catch { return; }
+              if (size <= TARGET) return;
+              const kb = Math.round(size/1024*10)/10;
+              const verdict = size > SLACK ? "over-budget" : "warn";
+              process.stderr.write("[knit] BUDGET " + verdict + ": " + f + " is now " + kb + "KB (target 6.5KB). Move long-form content to .claude/MARKETING.md or run \\\`engram refresh\\\`.\\n");
+            } catch (e) { try { process.stderr.write('[knit] claude-md size watch hook failed: ' + (e && e.message ? e.message : e) + '\\n'); } catch {} }
+          });
+        `),
+        timeout: 5
+      }
+    ]
+  });
   hooks.PostToolUse.push({
     _knitOwned: true,
     matcher: "Write|Edit|MultiEdit",

package/dist/cli.js

@@ -19,12 +19,12 @@ if (hasSubcommand) {
 async function runCLI() {
   const gradient = (await import("gradient-string")).default;
   const chalk = (await import("chalk")).default;
-  const { setupCommand } = await import("./setup-5TUUWLIJ.js");
+  const { setupCommand } = await import("./setup-62ZH7GEI.js");
   const { statusCommand } = await import("./status-2SEITNIE.js");
   const { refreshCommand } = await import("./refresh-S62AZ3QA.js");
-  const { installAgentsCommand } = await import("./install-agents-WDBQBWMN.js");
+  const { installAgentsCommand } = await import("./install-agents-AH7EBB4J.js");
   const { exportCommand } = await import("./export-4BO6HCXP.js");
-  const { doctorCommand } = await import("./doctor-4DN2P2JR.js");
+  const { doctorCommand } = await import("./doctor-NI22FPXV.js");
   const ENGRAM_GRADIENT = gradient(["#7c3aed", "#2563eb", "#06b6d4"]);
   const banner = `
   \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557
@@ -98,9 +98,9 @@ async function runMCP() {
   const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
   const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
   const { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
-  const { getBrain, detectProjectRoot, refreshBrain } = await import("./cache-7HSMIYDJ.js");
-  const { getActiveToolDefinitionsForBrain, handleToolCall } = await import("./tools-ECHCPLCB.js");
-  const { buildInstructions } = await import("./instructions-JARSXQPO.js");
+  const { getBrain, detectProjectRoot, refreshBrain } = await import("./cache-46OKHDRR.js");
+  const { getActiveToolDefinitionsForBrain, handleToolCall } = await import("./tools-ZQHRWMVK.js");
+  const { buildInstructions } = await import("./instructions-CF6K57Z2.js");
   const { registerToolsListChangedNotifier } = await import("./notifier-4L27HKHI.js");
   const { loadScanResult } = await import("./integration-scanner-LBD2PIZ3.js");
   const { prewarmLatestVersion, getCachedLatestVersion, isNewerVersion } = await import("./update-check-GQVDVT2N.js");

package/dist/doctor-NI22FPXV.js

@@ -0,0 +1,12 @@
+import {
+  doctorCommand,
+  runDoctor
+} from "./chunk-TE6NP6BZ.js";
+import "./chunk-WADRF26Z.js";
+import "./chunk-UTVFELXS.js";
+import "./chunk-QQNHF4XY.js";
+import "./chunk-27TA2ZQZ.js";
+export {
+  doctorCommand,
+  runDoctor
+};

package/dist/{install-agents-WDBQBWMN.js → install-agents-AH7EBB4J.js}

@@ -1,10 +1,10 @@
 import {
   getBrain
-} from "./chunk-I63UMEBF.js";
-import "./chunk-HROSQ5MS.js";
+} from "./chunk-KKLAJLPO.js";
 import {
   installAgentsForProject
 } from "./chunk-GATMQQK5.js";
+import "./chunk-WADRF26Z.js";
 import "./chunk-WKQHCLLO.js";
 import "./chunk-MOOVNMIN.js";
 import "./chunk-ST4X7LZT.js";

package/dist/{instructions-JARSXQPO.js → instructions-CF6K57Z2.js}

@@ -1,10 +1,14 @@
 import {
+  CLAUDE_MD_BUDGET_BYTES,
   KNIT_INSTRUCTIONS,
   KNIT_INSTRUCTIONS_BASE,
+  buildBudgetVerdict,
   buildInstructions
-} from "./chunk-LV73YTVN.js";
+} from "./chunk-QQNHF4XY.js";
 export {
+  CLAUDE_MD_BUDGET_BYTES,
   KNIT_INSTRUCTIONS,
   KNIT_INSTRUCTIONS_BASE,
+  buildBudgetVerdict,
   buildInstructions
 };

package/dist/{setup-5TUUWLIJ.js → setup-62ZH7GEI.js}

@@ -1,3 +1,11 @@
+import {
+  runDoctor
+} from "./chunk-TE6NP6BZ.js";
+import "./chunk-WADRF26Z.js";
+import "./chunk-UTVFELXS.js";
+import "./chunk-QQNHF4XY.js";
+import "./chunk-27TA2ZQZ.js";
+
 // src/commands/setup.ts
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
@@ -89,7 +97,7 @@ For new projects, call \`knit_brain_status\` first \u2014 triggers auto-initiali
   console.log(chalk.bold("  How it works"));
   console.log(`  ${chalk.cyan("1.")} Open ${chalk.bold("any project")} in Claude Code`);
   console.log(`  ${chalk.cyan("2.")} Agent calls \`knit_classify_task\` \u2192 brain auto-initializes`);
-  console.log(`  ${chalk.cyan("3.")} Agent gets 35 tools: imports, exports, tests, learnings, teams`);
+  console.log(`  ${chalk.cyan("3.")} Agent gets 53+ tools: imports, exports, tests, learnings, teams, requirements`);
   console.log(`  ${chalk.cyan("4.")} Brain compounds with every session \u2014 gets smarter over time`);
   console.log();
   console.log(chalk.dim("  No CLI needed after this. The MCP server handles everything."));
@@ -98,6 +106,28 @@ For new projects, call \`knit_brain_status\` first \u2014 triggers auto-initiali
     console.log(chalk.dim(`  Config written to: ${settingsPath}`));
   }
   console.log();
+  console.log(chalk.bold("  Install health check"));
+  console.log();
+  try {
+    const report = runDoctor(process.cwd());
+    for (const c of report.checks) {
+      const icon = c.status === "ok" ? chalk.green("\u2713") : c.status === "warn" ? chalk.yellow("\u26A0") : c.status === "error" ? chalk.red("\u2717") : chalk.gray("\xB7");
+      console.log(`  ${icon} ${c.name.padEnd(22)} ${chalk.dim(c.detail)}`);
+    }
+    const errors = report.checks.filter((c) => c.status === "error").length;
+    const warnings = report.checks.filter((c) => c.status === "warn").length;
+    console.log();
+    if (errors > 0) {
+      console.log(chalk.red(`  ${errors} error(s) \u2014 run \`engram doctor\` for full details + fix commands.`));
+    } else if (warnings > 0) {
+      console.log(chalk.yellow(`  ${warnings} warning(s) \u2014 setup complete, but check items above.`));
+    } else {
+      console.log(chalk.green("  All checks passed \u2014 install is healthy."));
+    }
+  } catch (err) {
+    console.log(chalk.dim(`  (doctor skipped: ${err.message})`));
+  }
+  console.log();
 }
 export {
   setupCommand

package/dist/{tools-ECHCPLCB.js → tools-ZQHRWMVK.js}

@@ -1,3 +1,12 @@
+import {
+  appendSession,
+  getRecentSessions,
+  installAgentsForProject,
+  loadAllSessions,
+  pruneSessionsByAge,
+  searchSessions,
+  sessionCount
+} from "./chunk-GATMQQK5.js";
 import {
   appendGlobalLearning,
   buildGlobalLearning,
@@ -8,21 +17,12 @@ import {
 import {
   notifyToolsListChanged
 } from "./chunk-WMESQUZU.js";
-import {
-  KNIT_INSTRUCTIONS
-} from "./chunk-LV73YTVN.js";
 import {
   VERSION
 } from "./chunk-UTVFELXS.js";
 import {
-  appendSession,
-  getRecentSessions,
-  installAgentsForProject,
-  loadAllSessions,
-  pruneSessionsByAge,
-  searchSessions,
-  sessionCount
-} from "./chunk-GATMQQK5.js";
+  KNIT_INSTRUCTIONS
+} from "./chunk-QQNHF4XY.js";
 import {
   addEntry,
   bumpClassificationTier,
@@ -2012,20 +2012,23 @@ var TOKEN_BUDGETS = {
   /** Generated CLAUDE.md block. v0.7 trim landed at ~2KB on typical projects;
    *  6.5KB target allows for projects with many domains / large project map. */
   claude_md_bytes: 6500,
-  /** Tier-gated tools/list response. v0.12 typical: 38 Tier-1 active × ~280
-   *  bytes ≈ 10.6KB. 11KB target allows headroom for the v0.12 + v0.13
-   *  growth without immediately warning; full 51-tool exposure
-   *  (everything enabled) sits in warn range, surfacing the bloat. */
-  tool_registry_bytes: 11e3,
+  /** Tier-gated tools/list response. v0.12 typical: 40 Tier-1 active × ~280
+   *  bytes ≈ 11.2KB. 12KB target gives Tier-1 healthy headroom; full
+   *  51-tool exposure (everything enabled) sits in warn range, surfacing
+   *  the bloat. Bumped from 11000 in v0.12 to reflect actual Tier-1 size. */
+  tool_registry_bytes: 12e3,
   /** MCP server `instructions` field — sent at handshake. v0.11.1 surfaces
    *  9 new tools (verify_claim, calibration, requirements ingestion,
-   *  fingerprint, infer_domains, compose_template) → ~3.5KB. The
-   *  discoverability-vs-budget trade-off favors surfacing real tools. */
+   *  fingerprint, infer_domains, compose_template) → ~3.5KB. v0.12 may
+   *  append a one-line budget verdict (~200B) when CLAUDE.md is over
+   *  budget. The discoverability-vs-budget trade-off favors surfacing
+   *  real tools. */
   instructions_bytes: 4e3,
   /** Sum of the three above — the per-session fixed cost Knit imposes.
-   *  v0.12 typical: ~14KB (CLAUDE.md ~2KB + tools ~10.6KB + instructions ~2KB);
-   *  20KB target covers the union with slack as more tools come online. */
-  per_session_overhead_bytes: 2e4
+   *  v0.12 typical: ~15KB (CLAUDE.md ~2KB + tools ~11.2KB + instructions
+   *  ~2.6KB); 22KB target covers the union with slack as more tools
+   *  come online. Bumped from 20000 alongside tool_registry. */
+  per_session_overhead_bytes: 22e3
 };
 function verdict(actual, target) {
   if (actual <= target) return "healthy";
@@ -3560,6 +3563,57 @@ function parseLoadSessionInclude(raw) {
     raw.split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)
   );
 }
+function computeBudgetHealth(brain) {
+  let claudeMdBytes = 0;
+  try {
+    claudeMdBytes = statSync3(join3(brain.rootPath, "CLAUDE.md")).size;
+  } catch {
+  }
+  const shape = detectProjectShape(brain);
+  const listing = computeFeatureListing(shape);
+  const toolRegistryBytes = listing.totals.active * 280;
+  const instructionsBytes = KNIT_INSTRUCTIONS.length;
+  const perSessionOverheadBytes = claudeMdBytes + toolRegistryBytes + instructionsBytes;
+  const cv = verdict(claudeMdBytes, TOKEN_BUDGETS.claude_md_bytes);
+  const tv = verdict(toolRegistryBytes, TOKEN_BUDGETS.tool_registry_bytes);
+  const iv = verdict(instructionsBytes, TOKEN_BUDGETS.instructions_bytes);
+  const ov = verdict(perSessionOverheadBytes, TOKEN_BUDGETS.per_session_overhead_bytes);
+  const verdicts = [cv, tv, iv, ov];
+  const overall = verdicts.includes("over-budget") ? "over-budget" : verdicts.includes("warn") ? "warn" : "healthy";
+  if (overall === "healthy") return void 0;
+  const rank = (v) => v === "over-budget" ? 2 : v === "warn" ? 1 : 0;
+  const surfaces = [
+    ["claude_md", cv],
+    ["tool_registry", tv],
+    ["instructions", iv]
+  ];
+  surfaces.sort((a, b) => rank(b[1]) - rank(a[1]));
+  const worst = surfaces[0][0];
+  const suggestions = {
+    claude_md: "CLAUDE.md is over the 6.5KB target \u2014 run `engram refresh` to splice the lean marker-block, or check that the file is using the generator (not hand-curated).",
+    tool_registry: "Tool registry over budget \u2014 call knit_list_features to see which Tier-2/3 tools are active and disable any you do not need.",
+    instructions: "Instructions block over budget \u2014 likely a v0.x \u2192 v0.y growth. Restart Claude Code to pick up the trimmed instructions."
+  };
+  return {
+    verdict: overall,
+    per_session_kb: Math.round(perSessionOverheadBytes / 1024 * 10) / 10,
+    worst_surface: worst,
+    suggestion: suggestions[worst]
+  };
+}
+function computeLearningsHealth(brain) {
+  const total = brain.knowledgeBase.entries.length;
+  if (total < 5) return void 0;
+  const accessed = brain.knowledgeBase.entries.filter((e) => e.accessCount > 0).length;
+  const pct = total > 0 ? Math.round(accessed / total * 100) : 0;
+  if (pct >= 30) return { total, accessed_pct: pct, verdict: "healthy" };
+  return {
+    total,
+    accessed_pct: pct,
+    verdict: "low-utilization",
+    suggestion: `${total} learnings recorded but only ${pct}% have been recalled. Either call knit_search_learnings before re-investigating, or prune stale entries with knit_consolidate_learnings.`
+  };
+}
 function handleLoadSession(params, brain) {
   const include = parseLoadSessionInclude(params.include);
   const wantAll = include.has("all");
@@ -3641,6 +3695,8 @@ function handleLoadSession(params, brain) {
       changelog: "https://github.com/PDgit12/knit/blob/main/CHANGELOG.md"
     };
   }
+  const budgetHealth = computeBudgetHealth(brain);
+  const learningsHealth = computeLearningsHealth(brain);
   const response = {
     session_context: {
       last_session: lastSession,
@@ -3659,6 +3715,8 @@ function handleLoadSession(params, brain) {
       ...recentSessions !== void 0 ? { recent_sessions: recentSessions } : {}
     },
     ...updateAvailable ? { update_available: updateAvailable } : {},
+    ...budgetHealth ? { budget_health: budgetHealth } : {},
+    ...learningsHealth && learningsHealth.verdict === "low-utilization" ? { learnings_health: learningsHealth } : {},
     instruction: handoff2 ? "UNFINISHED WORK DETECTED. Read the handoff above \u2014 pick up where the last session left off. Do NOT start fresh." : topLearnings.length > 0 ? `Session loaded. ${topLearnings.length} key learnings, ${fps.length} false positives. Call knit_classify_task to begin. Use include=patterns,teams,metrics,recent_sessions,full_learnings,full_knowledge for more.` : "Fresh brain \u2014 no past learnings yet. Call knit_classify_task to begin."
   };
   return JSON.stringify(response);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knit-mcp",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "description": "Knit — second brain for Claude Code. MCP server giving any AI agent project-scoped memory, tiered workflow protocol, and parallel team worktrees.",
   "type": "module",
   "bin": {
@@ -14,7 +14,10 @@
     "lint": "eslint src/ tests/ --ext .ts",
     "test": "vitest run",
     "test:watch": "vitest",
-    "bench": "tsx benchmarks/retrieval-synthetic.ts",
+    "bench": "npm run bench:retrieval",
+    "bench:retrieval": "tsx benchmarks/retrieval-synthetic.ts",
+    "bench:tokens": "tsx benchmarks/token-economy.ts",
+    "bench:all": "npm run bench:retrieval && npm run bench:tokens",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
   },
   "keywords": [