@nxuss/lemma 1.7.1 → 1.7.2

package/dist/cjs/proxy/ComplexityRouter.d.ts

@@ -1,11 +1,18 @@
 export interface ComplexityRouterConfig {
     cheapModel?: string;
+    /**
+     * Cheap model to fall back to per provider family, keyed by a substring of the
+     * requested model id ('claude', 'gemini', ...). Overridable from lemma.config.json
+     * so a retired model id can be corrected without shipping a new build.
+     */
+    cheapModelsByFamily?: Record<string, string>;
     complexKeywords?: string[];
     complexityThreshold?: number;
     disabled?: boolean;
 }
 export declare class ComplexityRouter {
     private cheapModel;
+    private cheapModelsByFamily;
     private complexKeywords;
     private syntaxDensityThreshold;
     constructor(config?: ComplexityRouterConfig);

package/dist/cjs/proxy/ComplexityRouter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ComplexityRouter.d.ts","sourceRoot":"","sources":["../../../src/proxy/ComplexityRouter.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,eAAe,CAAW;IAClC,OAAO,CAAC,sBAAsB,CAAS;gBAE3B,MAAM,GAAE,sBAA2B;IAWxC,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAMlD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE;CAqEvG;AAED,eAAe,gBAAgB,CAAC"}
+{"version":3,"file":"ComplexityRouter.d.ts","sourceRoot":"","sources":["../../../src/proxy/ComplexityRouter.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,sBAAsB;IACrC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAYD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,mBAAmB,CAAyB;IACpD,OAAO,CAAC,eAAe,CAAW;IAClC,OAAO,CAAC,sBAAsB,CAAS;gBAE3B,MAAM,GAAE,sBAA2B;IAYxC,YAAY,CAAC,MAAM,EAAE,sBAAsB,GAAG,IAAI;IASlD,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,CAAC,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE;CAsEvG;AAED,eAAe,gBAAgB,CAAC"}

package/dist/cjs/proxy/ComplexityRouter.js

@@ -1,9 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComplexityRouter = void 0;
+/**
+ * Model ids go stale as providers retire them; these are defaults, not truth. If the
+ * router starts recommending a model your provider rejects, override
+ * routing.complexity.cheapModelsByFamily in lemma.config.json.
+ */
+const DEFAULT_CHEAP_MODELS_BY_FAMILY = {
+    claude: 'claude-haiku-4-5-20251001',
+    gemini: 'gemini-2.0-flash',
+};
 class ComplexityRouter {
     constructor(config = {}) {
         this.cheapModel = config.cheapModel || 'gpt-4o-mini';
+        this.cheapModelsByFamily = { ...DEFAULT_CHEAP_MODELS_BY_FAMILY, ...(config.cheapModelsByFamily || {}) };
         this.complexKeywords = config.complexKeywords || [
             'architecture', 'design', 'debug', 'trace', 'system', 'microservices',
             'refactor', 'optimize', 'implement', 'algorithm', 'distributed',
@@ -15,6 +25,9 @@ class ComplexityRouter {
     updateConfig(config) {
         if (config.cheapModel)
             this.cheapModel = config.cheapModel;
+        if (config.cheapModelsByFamily) {
+            this.cheapModelsByFamily = { ...this.cheapModelsByFamily, ...config.cheapModelsByFamily };
+        }
         if (config.complexKeywords)
             this.complexKeywords = config.complexKeywords;
         if (config.complexityThreshold)
@@ -72,11 +85,11 @@ class ComplexityRouter {
             let cheapModel = this.cheapModel;
             if (originalModel) {
                 const lowerModel = originalModel.toLowerCase();
-                if (lowerModel.includes('claude')) {
-                    cheapModel = 'claude-3-5-haiku-20241022';
-                }
-                else if (lowerModel.includes('gemini')) {
-                    cheapModel = 'gemini-1.5-flash';
+                for (const [family, model] of Object.entries(this.cheapModelsByFamily)) {
+                    if (lowerModel.includes(family)) {
+                        cheapModel = model;
+                        break;
+                    }
                 }
             }
             console.log(`[ComplexityRouter] Low complexity detected. Routing to ${cheapModel}`);

package/dist/cjs/proxy/ComplexityRouter.js.map

@@ -1 +1 @@
-{"version":3,"file":"ComplexityRouter.js","sourceRoot":"","sources":["../../../src/proxy/ComplexityRouter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ComplexityRouter.js","sourceRoot":"","sources":["../../../src/proxy/ComplexityRouter.ts"],"names":[],"mappings":"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"}

package/dist/cjs/utils/TokenReceipt.d.ts

@@ -14,6 +14,12 @@ export interface ReceiptEvent {
     meta?: Record<string, unknown>;
 }
 export declare function recordReceiptEvent(type: ReceiptEventType, label: string, meta?: Record<string, unknown>): void;
+/**
+ * Number of events recorded so far. The dispatcher samples this around a handler to
+ * tell whether the handler already logged something specific (a cache hit, a miss)
+ * before falling back to a generic tool_call entry.
+ */
+export declare function getLedgerLength(): number;
 export interface ReceiptSummary {
     totalEvents: number;
     byType: Record<ReceiptEventType, number>;

package/dist/cjs/utils/TokenReceipt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TokenReceipt.d.ts","sourceRoot":"","sources":["../../../src/utils/TokenReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,oBAAoB,GACpB,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK9G;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,SAAK,GAAG,cAAc,CAc5D;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"TokenReceipt.d.ts","sourceRoot":"","sources":["../../../src/utils/TokenReceipt.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,oBAAoB,GACpB,WAAW,GACX,WAAW,GACX,WAAW,CAAC;AAEhB,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAID,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAK9G;AAED;;;;GAIG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAExC;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC;IACzC,MAAM,EAAE,YAAY,EAAE,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAAC,KAAK,SAAK,GAAG,cAAc,CAc5D;AAED,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/cjs/utils/TokenReceipt.js

@@ -9,6 +9,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.recordReceiptEvent = recordReceiptEvent;
+exports.getLedgerLength = getLedgerLength;
 exports.getReceiptSummary = getReceiptSummary;
 exports.clearReceiptLedger = clearReceiptLedger;
 const MAX_EVENTS = 2000;
@@ -19,6 +20,14 @@ function recordReceiptEvent(type, label, meta) {
         sessionLedger.splice(0, sessionLedger.length - MAX_EVENTS);
     }
 }
+/**
+ * Number of events recorded so far. The dispatcher samples this around a handler to
+ * tell whether the handler already logged something specific (a cache hit, a miss)
+ * before falling back to a generic tool_call entry.
+ */
+function getLedgerLength() {
+    return sessionLedger.length;
+}
 function getReceiptSummary(limit = 20) {
     const byType = {
         exact_cache_hit: 0,

package/dist/cjs/utils/TokenReceipt.js.map

@@ -1 +1 @@
-{"version":3,"file":"TokenReceipt.js","sourceRoot":"","sources":["../../../src/utils/TokenReceipt.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAoBH,gDAKC;AAQD,8CAcC;AAED,gDAEC;AAjDD,MAAM,UAAU,GAAG,IAAI,CAAC;AAgBxB,MAAM,aAAa,GAAmB,EAAE,CAAC;AAEzC,SAAgB,kBAAkB,CAAC,IAAsB,EAAE,KAAa,EAAE,IAA8B;IACtG,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,IAAI,aAAa,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACtC,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAQD,SAAgB,iBAAiB,CAAC,KAAK,GAAG,EAAE;IAC1C,MAAM,MAAM,GAAqC;QAC/C,eAAe,EAAE,CAAC;QAClB,kBAAkB,EAAE,CAAC;QACrB,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,CAAC;KACb,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,aAAa;QAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;IAChD,OAAO;QACL,WAAW,EAAE,aAAa,CAAC,MAAM;QACjC,MAAM;QACN,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,SAAgB,kBAAkB;IAChC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;AAC3B,CAAC"}
+{"version":3,"file":"TokenReceipt.js","sourceRoot":"","sources":["../../../src/utils/TokenReceipt.ts"],"names":[],"mappings":";AAAA;;;;;;;GAOG;;AAoBH,gDAKC;AAOD,0CAEC;AAQD,8CAcC;AAED,gDAEC;AA1DD,MAAM,UAAU,GAAG,IAAI,CAAC;AAgBxB,MAAM,aAAa,GAAmB,EAAE,CAAC;AAEzC,SAAgB,kBAAkB,CAAC,IAAsB,EAAE,KAAa,EAAE,IAA8B;IACtG,aAAa,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,IAAI,aAAa,CAAC,MAAM,GAAG,UAAU,EAAE,CAAC;QACtC,aAAa,CAAC,MAAM,CAAC,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,UAAU,CAAC,CAAC;IAC7D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe;IAC7B,OAAO,aAAa,CAAC,MAAM,CAAC;AAC9B,CAAC;AAQD,SAAgB,iBAAiB,CAAC,KAAK,GAAG,EAAE;IAC1C,MAAM,MAAM,GAAqC;QAC/C,eAAe,EAAE,CAAC;QAClB,kBAAkB,EAAE,CAAC;QACrB,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,CAAC;QACZ,SAAS,EAAE,CAAC;KACb,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,aAAa;QAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;IAChD,OAAO;QACL,WAAW,EAAE,aAAa,CAAC,MAAM;QACjC,MAAM;QACN,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC;KACpC,CAAC;AACJ,CAAC;AAED,SAAgB,kBAAkB;IAChC,aAAa,CAAC,MAAM,GAAG,CAAC,CAAC;AAC3B,CAAC"}

package/dist/esm/mcp/tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AA2hCnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAQA;AAoHD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CA+DN"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAiiCnE,oFAAoF;AACpF,wBAAgB,kBAAkB,IAAI,MAAM,CAM3C;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAEjD;AAED,iFAAiF;AACjF,wBAAgB,qBAAqB,IAAI;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAQA;AAoHD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAC1B,MAAM,EAAE,IAAI,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,CAAC;IACxC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAqCD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,GAC1C,IAAI,CAwEN"}

package/dist/esm/mcp/tools.js

@@ -33,7 +33,7 @@ import { surgicalASTInsert } from "../utils/SurgicalASTInsert.js";
 import { getInfraToolDefinitions, getInfraToolHandlers, INFRA_TOOL_NAMES } from "../infra/mcp-tools.js";
 import { resolveToolSurface, buildToolboxCatalog } from "./tool-profiles.js";
 import { lookupStateHash, storeStateHash } from "../utils/StateHashCache.js";
-import { recordReceiptEvent, getReceiptSummary } from "../utils/TokenReceipt.js";
+import { recordReceiptEvent, getReceiptSummary, getLedgerLength } from "../utils/TokenReceipt.js";
 import { distillCommandOutput, buildDistillFooter, readRegion } from "../utils/CommandOutputDistiller.js";
 import { findMatch, reindentReplacement } from "../utils/PatchMatcher.js";
 import { searchWorkspace, groupSearchResults, parseExtensionFilter } from "../utils/WorkspaceSearch.js";
@@ -103,6 +103,11 @@ const toolDefinitions = [
             properties: {
                 query: { type: "string", description: "The natural language query" },
                 limit: { type: "number", description: "Maximum results to return", default: 5 },
+                minSimilarity: {
+                    type: "number",
+                    description: "Similarity floor (0.0-1.0) a memory must clear to be returned. Lowering this surfaces loosely related memories that are usually noise — leave it alone unless a known-relevant memory is being filtered out.",
+                    default: 0.75,
+                },
             },
             required: ["query"],
         },
@@ -1156,6 +1161,41 @@ async function handleToolbox(args) {
     }
     throw new Error(`Unknown action: ${action}. Use 'list', 'schema', or 'call'.`);
 }
+/** Tools whose whole job is to put file contents into the model's context. */
+const FILE_READ_TOOLS = new Set([
+    "read_workspace_file",
+    "smart_file_slice",
+    "get_symbol_surgical_context",
+    "get_ast_hologram",
+    "list_workspace_dir",
+    "search_workspace",
+    "read_token_budgeted",
+    "bulk_file_digest",
+    "import_tree_context",
+]);
+function receiptTypeForTool(name) {
+    return FILE_READ_TOOLS.has(name) ? "file_read" : "tool_call";
+}
+/**
+ * A receipt entry is only useful if it says what the call was about. Pull the most
+ * identifying argument without dragging whole file contents into the ledger.
+ */
+function receiptLabelMeta(name, args) {
+    if (!args)
+        return {};
+    const meta = {};
+    if (typeof args.filePath === "string")
+        meta.filePath = args.filePath;
+    if (typeof args.dirPath === "string")
+        meta.dirPath = args.dirPath;
+    if (typeof args.query === "string")
+        meta.query = args.query.substring(0, 100);
+    if (typeof args.command === "string")
+        meta.command = args.command.substring(0, 100);
+    if (typeof args.symbolName === "string")
+        meta.symbolName = args.symbolName;
+    return meta;
+}
 export function setupToolsHandlers(server, onToolCall) {
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: toolDefinitionsArray,
@@ -1190,7 +1230,16 @@ export function setupToolsHandlers(server, onToolCall) {
             throw new Error(`Unknown tool: ${name}`);
         }
         try {
+            // Sampled around the handler so a tool that logs its own, more specific event
+            // (a cache hit, a miss) isn't double-counted by the generic entry below.
+            const ledgerBefore = getLedgerLength();
             const result = await handler((args || {}));
+            if (getLedgerLength() === ledgerBefore) {
+                recordReceiptEvent(receiptTypeForTool(name), name, {
+                    tool: name,
+                    ...receiptLabelMeta(name, args),
+                });
+            }
             const tokensImpact = estimateTokensFromResult(result);
             onToolCall?.({
                 tool: name,
@@ -1225,16 +1274,35 @@ async function handleScrubPrivacy(args) {
     const { maskedPrompt } = scrubber.mask(text);
     return { content: [{ type: "text", text: maskedPrompt }] };
 }
+/**
+ * Minimum similarity for a stored memory to be offered for reuse. Shared by
+ * search_memory and smarter_cache so the two never disagree about whether the same
+ * query is a hit.
+ */
+const DEFAULT_MEMORY_SIMILARITY_FLOOR = 0.75;
 async function handleSearchMemory(args) {
     const query = args?.query;
     const limit = args?.limit || 5;
+    // A floor of 0 returns the nearest neighbour no matter how unrelated it is, and the
+    // formatting below then presents it as a reusable memory. Match smarter_cache's
+    // threshold so both paths agree on what counts as a hit.
+    const minSimilarity = typeof args?.minSimilarity === "number" ? args.minSimilarity : DEFAULT_MEMORY_SIMILARITY_FLOOR;
     if (!query)
         throw new Error("Query is required");
     try {
         const brain = getBrain();
-        const results = brain.search(query, limit, 0, { projectId: deriveProjectId() });
+        const results = brain.search(query, limit, minSimilarity, { projectId: deriveProjectId() });
         if (results.length === 0) {
-            return { content: [{ type: "text", text: "No relevant memories found in Lemma's Brain." }] };
+            recordReceiptEvent("reasoning", query.substring(0, 100), {
+                tool: "search_memory",
+                reason: `no memory above the ${minSimilarity} similarity floor`,
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: `No memory in Lemma's Brain scored at or above the ${(minSimilarity * 100).toFixed(0)}% similarity floor for this query. Investigate from scratch — there is nothing safe to reuse.`,
+                    }],
+            };
         }
         const fresh = results.filter((r) => r.fresh);
         const stale = results.filter((r) => !r.fresh);
@@ -1245,6 +1313,17 @@ async function handleSearchMemory(args) {
             const bestFresh = fresh[0];
             const tokensSaved = Math.max(100, Math.floor(String(bestFresh.response).length / 4));
             reportSavings({ source: "cache", tokens: tokensSaved, toolName: "search_memory", query: query.substring(0, 100) });
+            recordReceiptEvent("semantic_cache_hit", query.substring(0, 100), {
+                tool: "search_memory",
+                similarity: bestFresh.similarity,
+                tokensSaved,
+            });
+        }
+        else {
+            recordReceiptEvent("reasoning", query.substring(0, 100), {
+                tool: "search_memory",
+                reason: `${stale.length} similar memory/memories found but all stale — must re-verify`,
+            });
         }
         const parts = [];
         if (fresh.length > 0) {
@@ -1273,12 +1352,13 @@ async function handleStoreMemory(args) {
     try {
         const brain = getBrain();
         const storeRes = brain.store(query, responseText, provider, 0.92, filePaths);
-        const tokensSaved = Math.max(100, Math.floor(responseText.length / 4));
-        reportSavings({
-            source: "cache",
-            tokens: tokensSaved,
-            toolName: "store_memory",
-            query: query.substring(0, 100),
+        // Storing a memory saves nothing — it only creates the chance of a saving later.
+        // Crediting tokens here inflated the ledger on write and then credited the same
+        // answer again on every read. The saving is booked by search_memory on a fresh hit.
+        recordReceiptEvent("tool_call", `store_memory: ${query.substring(0, 100)}`, {
+            tool: "store_memory",
+            filePaths,
+            note: "memory written — no tokens saved yet",
         });
         const trackingNote = filePaths && filePaths.length > 0 ? ` Tracking freshness against ${filePaths.length} file(s) — this memory auto-invalidates if they change.` : "";
         return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}` }] };
@@ -1800,7 +1880,7 @@ async function handleGetProjectOnboarding(_args) {
         ],
     };
 }
-function extractSymbolsWithTsCompiler(filePath, relPath) {
+function extractSymbolsWithTsCompiler(filePath, relPath, parseErrors) {
     try {
         const src = fs.readFileSync(filePath, "utf8");
         const sourceFile = ts.createSourceFile(filePath, src, ts.ScriptTarget.Latest, true);
@@ -1808,7 +1888,10 @@ function extractSymbolsWithTsCompiler(filePath, relPath) {
         function visit(node) {
             const mods = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
             const isExport = mods?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
-            if (isExport || ts.isSourceFile(node.parent)) {
+            // node.parent is undefined on the SourceFile root itself, and ts.isSourceFile()
+            // dereferences .kind without a guard — calling it unguarded threw on the very
+            // first visit(), so the catch below swallowed it and every file returned [].
+            if (isExport || (node.parent && ts.isSourceFile(node.parent))) {
                 if (ts.isFunctionDeclaration(node) && node.name) {
                     symbols.push({
                         kind: "function",
@@ -1877,10 +1960,11 @@ function extractSymbolsWithTsCompiler(filePath, relPath) {
     }
     catch (err) {
         logWarn("get_ast_hologram", `Could not parse ${relPath}: ${err}`);
+        parseErrors?.push(`${relPath}: ${err}`);
         return [];
     }
 }
-function walkDirForHologram(dir, rel, extensions) {
+function walkDirForHologram(dir, rel, extensions, stats) {
     let allSymbols = [];
     try {
         const entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -1890,18 +1974,20 @@ function walkDirForHologram(dir, rel, extensions) {
             const fullPath = path.join(dir, entry.name);
             const relPath = rel ? path.join(rel, entry.name) : entry.name;
             if (entry.isDirectory()) {
-                allSymbols = allSymbols.concat(walkDirForHologram(fullPath, relPath, extensions));
+                allSymbols = allSymbols.concat(walkDirForHologram(fullPath, relPath, extensions, stats));
             }
             else {
                 const ext = entry.name.split(".").pop() || "";
                 if (extensions.includes(ext)) {
-                    allSymbols = allSymbols.concat(extractSymbolsWithTsCompiler(fullPath, relPath));
+                    stats.filesScanned++;
+                    allSymbols = allSymbols.concat(extractSymbolsWithTsCompiler(fullPath, relPath, stats.parseErrors));
                 }
             }
         }
     }
     catch (err) {
         logWarn("get_ast_hologram", `Error walking dir ${dir}: ${err}`);
+        stats.parseErrors.push(`walk ${rel || "."}: ${err}`);
     }
     return allSymbols;
 }
@@ -1910,18 +1996,32 @@ async function handleGetAstHologram(args) {
     const extensions = args?.extensions || ["ts", "tsx", "js", "jsx"];
     const workspaceRoot = process.cwd();
     const { resolved } = safeResolvePath(workspaceRoot, dirPath);
-    const symbols = walkDirForHologram(resolved, dirPath, extensions);
+    const stats = { filesScanned: 0, parseErrors: [] };
+    const symbols = walkDirForHologram(resolved, dirPath, extensions, stats);
     const byFile = {};
     symbols.forEach((s) => {
         if (!byFile[s.file])
             byFile[s.file] = [];
         byFile[s.file].push({ kind: s.kind, name: s.name, line: s.line });
     });
+    // An empty map is reported as a failure, not as an answer: a silent "0 symbols" is
+    // indistinguishable from a working scan of an empty dir, which is how a parse bug
+    // stayed invisible here before. Say when nothing could be read.
+    const warning = stats.filesScanned === 0
+        ? `No files matching [${extensions.join(", ")}] were found under "${dirPath || "."}" — check the path and extensions.`
+        : symbols.length === 0
+            ? `Scanned ${stats.filesScanned} file(s) but extracted 0 symbols — this is very likely an extraction failure, not an empty codebase. Do not treat this as "the directory has no exports".`
+            : undefined;
     const hologram = {
         workspace: path.basename(workspaceRoot),
         scannedDir: dirPath || ".",
         totalSymbols: symbols.length,
+        filesScanned: stats.filesScanned,
         totalFiles: Object.keys(byFile).length,
+        ...(warning ? { warning } : {}),
+        ...(stats.parseErrors.length > 0
+            ? { parseErrors: stats.parseErrors.slice(0, 10), parseErrorCount: stats.parseErrors.length }
+            : {}),
         map: byFile,
     };
     return { content: [{ type: "text", text: JSON.stringify(hologram, null, 2) }] };
@@ -2324,7 +2424,7 @@ async function handleCompressContext(args) {
 async function handleSmarterCache(args) {
     const query = args?.query;
     const context = args?.context || "";
-    const threshold = typeof args?.threshold === "number" ? args.threshold : 0.75;
+    const threshold = typeof args?.threshold === "number" ? args.threshold : DEFAULT_MEMORY_SIMILARITY_FLOOR;
     if (!query)
         throw new Error("query is required");
     const fullQuery = context ? `${query}\n\nContext: ${context}` : query;