@nxuss/lemma 1.7.2 → 1.8.0

package/README.md

@@ -1,11 +1,11 @@
-# 🧠 Lemma v1.7.0
+# 🧠 Lemma v1.8.0
 
 [![npm version](https://img.shields.io/npm/v/@nxuss/lemma.svg?color=orange&style=flat-square)](https://www.npmjs.com/package/@nxuss/lemma)
 [![License](https://img.shields.io/npm/l/@nxuss/lemma.svg?color=blue&style=flat-square)](https://github.com/Nxusbets/lemma/blob/main/LICENSE)
-[![MCP Tools](https://img.shields.io/badge/MCP%20tools-94-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![MCP Tools](https://img.shields.io/badge/MCP%20tools-95-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
 [![Security](https://img.shields.io/badge/privacy-firewall%20active-blueviolet?style=flat-square)](https://github.com/Nxusbets/lemma)
 [![Caching](https://img.shields.io/badge/semantic%20memory-enabled-success?style=flat-square)](https://github.com/Nxusbets/lemma)
-[![Tests](https://img.shields.io/badge/tests-267%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![Tests](https://img.shields.io/badge/tests-293%20passing-00c853?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 ```text
     __                                
@@ -17,9 +17,9 @@
 
 > **The Intelligent local-first AI Gateway — Privacy, Performance, Static Code Intelligence, and Infrastructure Command Center for the Agentic Era.**
 
-Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, **Privacy Guardrails**, **22 Infrastructure Management Tools**, and a suite of **94 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
+Lemma is a high-performance orchestration layer that sits between your development environment and LLM providers. It transforms the way you build with AI by providing **Shared Semantic Memory**, **Autonomous Cost Optimization**, **Privacy Guardrails**, **22 Infrastructure Management Tools**, and a suite of **95 MCP tools** — including zero-token static code intelligence that runs entirely on your machine with no LLM calls required.
 
-Since v1.7.0 those 94 tools are all registered, but only the ones your project can actually use
+Since v1.7.0 those 95 tools are all registered, but only the ones your project can actually use
 are advertised to the model each turn. The rest stay one `lemma_toolbox` call away. See
 [Tool profiles](#-tool-profiles).
 
@@ -27,7 +27,41 @@ are advertised to the model each turn. The rest stay one `lemma_toolbox` call aw
 
 ## 📋 Changelog
 
-### v1.7.0 — The cost of being connected *(NEW)*
+### v1.8.0 — The Brain learns from project history, not just what it's told *(NEW)*
+
+Every memory in The Brain used to depend on the assistant remembering to call `store_memory`. If
+nobody called it, the Brain knew nothing about work that already happened.
+
+| Change | What it does | Why it matters |
+| :--- | :--- | :--- |
+| **`lemma-brain-ingest`** *(new CLI)* | Feeds The Brain from git commits and `CHANGELOG.md` — no assistant call needed. Incremental via a marker file, safe to wire to `post-commit`. | The Brain stops depending on the model remembering to save anything. |
+| **Checkpoints now feed The Brain** | `saveCheckpoint()` indexes any checkpoint with real content into the same Brain `search_memory` reads. | Decisions and bugs recorded in a checkpoint used to be invisible to search. |
+| **`get_project_history`** *(new tool)* | Merges recent commits, checkpoints, and Brain memories for the current project into one call. | Answers "what have we done here" without three separate lookups. |
+| **Outcome tagging** | `store_memory` accepts `outcome: 'failed'`; search surfaces it as a warning, not a suggestion. | A dead end is now as memorable as a fix. |
+| **Symbol-level freshness** | `store_memory` accepts `symbols: [{filePath, symbolName}]` — freshness is judged by that function's own source, not the whole file. | An unrelated edit elsewhere in the file no longer stales the memory out. |
+
+**PR review memory was silently going nowhere.** `BrainBridge` talked to the proxy's
+`/api/search`/`/api/memory/store`, both backed by ChromaDB + a local Ollama server on `:11434` —
+the exact stack TheBrainV2 replaced in 1.0.0. Whenever Ollama wasn't running (the common case
+now), every call failed inside a `try/catch` and returned empty. It now reads/writes `TheBrainV2`
+directly, so PR review and interactive coding share one memory instead of two disconnected ones.
+
+**Two projects could quietly share — or split — memories.** `deriveProjectId` hashed the
+project path without resolving symlinks; on macOS `process.cwd()` and an `os.tmpdir()`-built path
+can report different strings for the same directory, hashing to two different project scopes. It
+now resolves via `fs.realpathSync` first.
+
+**Spanish text was mangled before it reached the index.** `tokenize()` used `\w` to strip
+punctuation, which doesn't match accented letters — "Cómo" became "mo", "diseño" became "dise",
+and the same word typed without its accent tokenized completely differently. `tokenize()` now
+normalizes diacritics first, and gained an additive English/Spanish stemmer and Spanish stopwords.
+
+**`token_budget` reported a multiplier no ledger backed.** It fetched a proxy route that doesn't
+exist, silently fell back to an uncosted estimate, and reported a bigger number than the
+session's own auditable ledger would support. It now reads the real `SavingsLedger` net position
+(`/api/savings-breakdown`) or says plainly there's nothing to report if the proxy isn't running.
+
+### v1.7.0 — The cost of being connected
 
 Every tool schema Lemma advertises goes into the model's system prompt and is **re-sent on every
 request of the session** — including schemas for tools the project can never use. On this repo that
@@ -288,7 +322,7 @@ Or use environment variables: `JENKINS_URL`, `JENKINS_USERNAME`, `JENKINS_API_TO
 ## 🎚️ Tool profiles
 
 Every tool schema an MCP server advertises is injected into the model's system prompt and re-sent
-on **every request** of the session. Advertising all 94 tools costs ~11,600 tokens per turn — much
+on **every request** of the session. Advertising all 95 tools costs ~11,600 tokens per turn — much
 of it schemas for tools a given project can never use.
 
 Lemma advertises a scoped surface instead. Nothing is removed: every tool stays registered and
@@ -349,9 +383,35 @@ the richer record when one exists.
 
 ---
 
+## 🧠 Feeding The Brain from project history
+
+`store_memory` also depends on the assistant remembering to call it. `lemma-brain-ingest` pulls
+memories from sources that already exist and don't need an assistant in the loop:
+
+```bash
+lemma-brain-ingest [projectRoot] [--max N] [--changelog] [--no-commits]
+```
+
+- Every git commit (message + files touched) becomes one Brain entry, so `search_memory` and
+  `get_telepathic_hints` can recall *why* a change happened, not just what the code looks like now.
+- `--changelog` also ingests `CHANGELOG.md` (falls back to `docs/CHANGELOG.md`) — one entry per release, parsed
+  directly, no LLM involved.
+
+A marker file under `<project>/.lemma/session/` tracks the last commit and changelog version
+ingested, so this is safe to run after every commit and safe to run by hand for a one-time
+backfill of existing history — both take the same incremental path and never double-store.
+Wire it to a post-commit hook to keep it current automatically:
+
+```bash
+echo 'lemma-brain-ingest "$(git rev-parse --show-toplevel)" &' >> .git/hooks/post-commit
+chmod +x .git/hooks/post-commit
+```
+
+---
+
 ## 💎 Free vs Pro
 
-### 🆓 Free (33 Tools)
+### 🆓 Free (34 Tools)
 
 These tools work **without a Pro license**. Activate them with just `lemma init`:
 
@@ -366,6 +426,7 @@ These tools work **without a Pro license**. Activate them with just `lemma init`
 | `auto_context_bundle` | Full context bundle per file |
 | `repeat_guard` | Duplicate output detector |
 | `conversation_checkpoint` | Session state save/load |
+| `get_project_history` | Git log + checkpoints + Brain memories in one call |
 | `test_autofix_interceptor` | Test failure → Brain auto-fix |
 | `prompt_pattern_cache` | Reusable prompt templates |
 | `infra_discover` | Auto-detect Jenkins, OKD, Terraform |

package/bin/brain-ingest.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * Feeds The Brain from sources the model never has to remember to store manually.
+ *
+ * Meant to be wired to a git post-commit hook so every commit becomes a searchable memory
+ * without depending on the assistant calling `store_memory`:
+ *
+ *   echo 'lemma-brain-ingest "$(git rev-parse --show-toplevel)" &' >> .git/hooks/post-commit
+ *
+ * With no flags it's an incremental catch-up: a marker file under .lemma/session/ tracks the
+ * last commit ingested, so running this after every commit or by hand both take the same path
+ * and never double-store. `--max N` only matters the first time there is no marker yet.
+ *
+ * Usage: lemma-brain-ingest [projectRoot] [--max N] [--changelog] [--no-commits]
+ */
+
+const path = require('path');
+
+function main() {
+  const args = process.argv.slice(2);
+  const maxIndex = args.indexOf('--max');
+  const maxCommits = maxIndex >= 0 ? parseInt(args[maxIndex + 1], 10) : undefined;
+  const includeChangelog = args.includes('--changelog');
+  const includeCommits = !args.includes('--no-commits');
+  const positional = args.filter((a, i) => !a.startsWith('--') && i !== maxIndex + 1);
+  const projectRoot = path.resolve(positional[0] || process.cwd());
+
+  const distPath = path.join(__dirname, '..', 'dist', 'cjs', 'subconscious', 'GitIngest.js');
+  let ingestRecentCommits, ingestChangelog;
+  try {
+    ({ ingestRecentCommits, ingestChangelog } = require(distPath));
+  } catch {
+    console.error('[lemma-brain-ingest] Build not found. Run "npm run build" first.');
+    return;
+  }
+
+  if (includeCommits) {
+    const res = ingestRecentCommits(projectRoot, { maxCommits });
+    console.error(`[lemma-brain-ingest] commits: ${res.ingested} stored, ${res.skipped} skipped (up to ${res.lastSha ? res.lastSha.substring(0, 12) : 'none'})`);
+  }
+
+  if (includeChangelog) {
+    const res = ingestChangelog(projectRoot);
+    console.error(`[lemma-brain-ingest] changelog: ${res.ingested} stored, ${res.skipped} skipped (${res.versionsSeen} version(s) seen)`);
+  }
+}
+
+try {
+  main();
+} catch (err) {
+  // A hook that fails must never be the reason a commit or session goes bad.
+  console.error('[lemma-brain-ingest] Skipped:', err && err.message);
+}
+process.exit(0);

package/dist/cjs/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;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"}
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAwjCnE,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;AAqHD,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/cjs/mcp/tools.js

@@ -101,7 +101,7 @@ function isProUser() {
 }
 const FREE_TOOLS = new Set([
     // Cache & Memory — the hook that shows instant value
-    "smarter_cache", "state_hash_cache", "token_receipt", "search_memory", "store_memory",
+    "smarter_cache", "state_hash_cache", "token_receipt", "search_memory", "store_memory", "get_project_history",
     // Token optimization — shows what they're saving
     "token_budget", "squeeze_prompt", "turbosqueeze",
     // Utility — just enough to function
@@ -157,7 +157,7 @@ const toolDefinitions = [
     },
     {
         name: "store_memory",
-        description: "Persist a technical solution, bug fix, architecture decision, or key fact into Lemma's Brain — so future questions on the same topic (even phrased differently) don't require re-investigating the repo. Pass filePaths for anything derived from specific files (e.g. 'where is X implemented', 'how does Y work') so the memory auto-invalidates the moment those files change, instead of risking a stale answer being reused.",
+        description: "Persist a technical solution, bug fix, architecture decision, or key fact into Lemma's Brain — so future questions on the same topic (even phrased differently) don't require re-investigating the repo. Pass filePaths for anything derived from specific files (e.g. 'where is X implemented', 'how does Y work') so the memory auto-invalidates the moment those files change, instead of risking a stale answer being reused. If the answer is really about one function/class rather than the whole file, pass `symbols` instead (or in addition) so an unrelated edit elsewhere in that file doesn't stale it out. Pass outcome='failed' for an approach that was tried and did NOT work — that's just as worth remembering as a fix, so the Brain can warn 'already tried, didn't work' instead of only ever suggesting reuse.",
         inputSchema: {
             type: "object",
             properties: {
@@ -165,6 +165,19 @@ const toolDefinitions = [
                 response: { type: "string", description: "The complete technical content to memorize" },
                 provider: { type: "string", description: "Optional model provider name", default: "generic" },
                 filePaths: { type: "array", items: { type: "string" }, description: "Paths (relative to project root) this answer depends on. If any changes later, this memory is marked stale instead of being silently reused." },
+                symbols: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            filePath: { type: "string", description: "Path (relative to project root) containing the symbol" },
+                            symbolName: { type: "string", description: "Function/class/interface/type/enum/const name" },
+                        },
+                        required: ["filePath", "symbolName"],
+                    },
+                    description: "Symbols (not whole files) this answer depends on. Freshness is then judged by that symbol's own source, so edits elsewhere in the same file don't stale this memory out.",
+                },
+                outcome: { type: "string", enum: ["confirmed", "failed"], description: "Default 'confirmed' (a verified working solution). Set 'failed' to record a dead end — an approach ruled out, not one to recommend." },
             },
             required: ["query", "response"],
         },
@@ -316,6 +329,16 @@ const toolDefinitions = [
             properties: {},
         },
     },
+    {
+        name: "get_project_history",
+        description: "Answers 'what have we done in this project': merges recent git commits, session checkpoints, and The Brain's memories (decisions, fixes, prior PR reviews) for the current project into one narrative. Use this instead of piecing the same picture together from search_memory + git log + reading checkpoint files separately.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                limit: { type: "number", description: "Max items per section (commits, checkpoints, Brain memories)", default: 10 },
+            },
+        },
+    },
     {
         name: "get_ast_hologram",
         description: "Generate a dense, token-efficient Holographic AST Map of the workspace using the TypeScript compiler. Returns structured JSON of all exported symbols with file paths and line numbers.",
@@ -1164,6 +1187,7 @@ const toolHandlers = {
     auto_context_bundle: handleAutoContextBundle,
     repeat_guard: handleRepeatGuard,
     conversation_checkpoint: handleConversationCheckpoint,
+    get_project_history: handleGetProjectHistory,
     test_autofix_interceptor: handleTestAutofixInterceptor,
     prompt_pattern_cache: handlePromptPatternCache,
     lemma_toolbox: handleToolbox,
@@ -1349,7 +1373,7 @@ async function handleSearchMemory(args) {
         }
         const fresh = results.filter((r) => r.fresh);
         const stale = results.filter((r) => !r.fresh);
-        const formatResult = (r, i) => `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}`;
+        const formatResult = (r, i) => `Result ${i + 1} (Similarity: ${(r.similarity * 100).toFixed(1)}%)${r.outcome === "failed" ? "\n⚠️ TAGGED AS A FAILED ATTEMPT — this was tried before and did NOT work. Do not repeat it; treat this as a warning, not a suggestion." : ""}\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}`;
         if (fresh.length > 0) {
             // Only a fresh hit (or an untracked, purely conceptual entry) counts as a real
             // avoided re-investigation — this is the only case worth crediting as savings.
@@ -1390,11 +1414,15 @@ async function handleStoreMemory(args) {
     const responseText = args?.response;
     const provider = args?.provider || "generic";
     const filePaths = Array.isArray(args?.filePaths) ? args.filePaths : undefined;
+    const outcome = args?.outcome === "failed" ? "failed" : undefined;
+    const symbols = Array.isArray(args?.symbols)
+        ? args.symbols.filter((s) => s?.filePath && s?.symbolName)
+        : undefined;
     if (!query || !responseText)
         throw new Error("Query and response are required");
     try {
         const brain = (0, TheBrainV2_1.getBrain)();
-        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths);
+        const storeRes = brain.store(query, responseText, provider, 0.92, filePaths, undefined, outcome, symbols);
         // 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.
@@ -1404,7 +1432,9 @@ async function handleStoreMemory(args) {
             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}` }] };
+        const symbolNote = symbols && symbols.length > 0 ? ` Tracking freshness against ${symbols.length} symbol(s) specifically — unrelated edits elsewhere in those files won't stale this out.` : "";
+        const outcomeNote = outcome === "failed" ? " Tagged as a FAILED attempt — future searches will surface it as a warning, not a suggestion." : "";
+        return { content: [{ type: "text", text: `Success: Memory stored. ${storeRes.reason}${trackingNote}${symbolNote}${outcomeNote}` }] };
     }
     catch (e) {
         (0, utils_1.logError)("store_memory", e);
@@ -1923,6 +1953,59 @@ async function handleGetProjectOnboarding(_args) {
         ],
     };
 }
+// ── Project History (aggregate: git log + checkpoints + Brain) ─────
+/**
+ * "What have we done in this project" today means piecing together search_memory, git log,
+ * and manually reading .lemma/session/ checkpoint files by hand — three separate calls whose
+ * results the model has to merge itself. This does that merge in one call.
+ */
+async function handleGetProjectHistory(args) {
+    const cwd = process.cwd();
+    const limit = typeof args?.limit === "number" ? args.limit : 10;
+    try {
+        const projectId = (0, TheBrainV2_1.deriveProjectId)(cwd);
+        const brainEntries = (0, TheBrainV2_1.getBrain)()
+            .getEntriesForProject(projectId)
+            .sort((a, b) => (b.hits - a.hits) || (new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime()))
+            .slice(0, limit);
+        const checkpoints = (0, ConversationCheckpoint_1.loadRecentCheckpoints)(cwd, Math.min(limit, 5));
+        let recentCommits = [];
+        try {
+            const log = (0, child_process_1.execFileSync)("git", ["-C", cwd, "log", `-${limit}`, "--pretty=format:%h %s (%ar)"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+            recentCommits = log.split("\n").filter(Boolean);
+        }
+        catch {
+            // Not a git repo, or no commits yet — sections below just won't include this one.
+        }
+        const parts = [`# Project history — ${path_1.default.basename(cwd)}`];
+        if (recentCommits.length > 0) {
+            parts.push(`## Recent commits\n${recentCommits.map((c) => `- ${c}`).join("\n")}`);
+        }
+        if (checkpoints.length > 0) {
+            const checkpointLines = checkpoints.map((cp) => {
+                const date = new Date(cp.timestamp).toISOString().replace("T", " ").slice(0, 16);
+                return `- **${date}** — ${cp.summary.replace(/\n+/g, " ")}`;
+            });
+            parts.push(`## Session checkpoints\n${checkpointLines.join("\n")}`);
+        }
+        if (brainEntries.length > 0) {
+            const brainLines = brainEntries.map((e) => {
+                const tag = e.outcome === "failed" ? " ⚠️ FAILED ATTEMPT" : "";
+                const snippet = e.response.length > 300 ? `${e.response.substring(0, 300)}...` : e.response;
+                return `- **${e.query}**${tag} _(${e.provider}, ${e.hits} hit(s))_\n  ${snippet}`;
+            });
+            parts.push(`## Brain memories (decisions, fixes, prior reviews)\n${brainLines.join("\n")}`);
+        }
+        if (parts.length === 1) {
+            parts.push("Nothing recorded yet — no git history, checkpoints, or Brain memories found for this project.");
+        }
+        return { content: [{ type: "text", text: parts.join("\n\n") }] };
+    }
+    catch (e) {
+        (0, utils_1.logError)("get_project_history", e);
+        return { content: [{ type: "text", text: `get_project_history failed: ${e.message}` }] };
+    }
+}
 function extractSymbolsWithTsCompiler(filePath, relPath, parseErrors) {
     try {
         const src = fs_1.default.readFileSync(filePath, "utf8");
@@ -2243,7 +2326,7 @@ async function handleGetTelepathicHints(args) {
             const similarity = (r.similarity * 100).toFixed(1);
             const prompt = r.query || "Unknown";
             const responseContent = r.response || "";
-            hintsText += `### Hint ${i + 1} (${similarity}% match)\n`;
+            hintsText += `### Hint ${i + 1} (${similarity}% match)${r.outcome === "failed" ? " — ⚠️ FAILED ATTEMPT, do not repeat" : ""}\n`;
             hintsText += `**Memory:** ${prompt}\n\n`;
             hintsText += `${responseContent.substring(0, 400)}${responseContent.length > 400 ? "..." : ""}\n\n---\n\n`;
         });
@@ -2592,48 +2675,64 @@ async function handleTokenReceipt(args) {
 }
 // ── Token Budget ─────────────────────────────────────────────────
 async function handleTokenBudget(_args) {
-    const statsFile = path_1.default.join(os_1.default.homedir(), '.lemma-cache/stats.json');
     const port = (0, utils_1.getProxyPort)();
-    let stats = {};
+    const schemaTokens = Math.round(getToolSchemaChars() / 4);
+    // /api/savings-breakdown serves SavingsLedger.getSnapshot() — the same ledger that
+    // already nets tokensSaved against what Lemma itself spent (MCP schema injection,
+    // tool-result bytes, cache misses). There is no separate "membership multiplier" to
+    // compute: reusing that one number keeps this tool from reporting a bigger win than
+    // the ledger the user can audit via `token_receipt` actually shows.
+    let snapshot = null;
     try {
-        stats = JSON.parse(fs_1.default.readFileSync(statsFile, 'utf8'));
+        const resp = await axios_1.default.get(`http://localhost:${port}/api/savings-breakdown`);
+        snapshot = resp.data;
     }
     catch { }
-    let ledger = [];
-    try {
-        const resp = await axios_1.default.get(`http://localhost:${port}/api/ledger`);
-        ledger = resp.data.events || [];
+    if (!snapshot) {
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        note: "El proxy de Lemma no está corriendo, así que no hay bitácora de ahorro/costo que leer — no se inventa un número aquí. Arranca el proxy para que este reporte sea real.",
+                        perTurnOverhead: { ...getToolSurfaceSummary(), schemaTokens },
+                    }, null, 2),
+                }],
+        };
     }
-    catch { }
-    const totalTokensSaved = stats.totalTokens || ledger.reduce((sum, e) => sum + (e.tokensImpact || 0), 0);
-    const monthlyTokens = stats.monthlyTokens || stats.totalTokens || 100000;
-    const multiplier = monthlyTokens > 0 ? ((monthlyTokens + totalTokensSaved) / monthlyTokens).toFixed(1) : "N/A";
-    const toolCallCount = ledger.length || stats.toolCalls || 0;
+    const { total, totalCost, net } = snapshot;
+    const ratioStr = net.ratio === Infinity ? "n/a (sin costo registrado todavía)" : `${net.ratio.toFixed(2)}x`;
     return {
         content: [{
                 type: "text",
                 text: JSON.stringify({
-                    membershipMultiplier: `${multiplier}x`,
-                    totalTokensSaved: totalTokensSaved.toLocaleString(),
-                    estimatedTokensPerMonth: monthlyTokens.toLocaleString(),
-                    effectiveBudget: (monthlyTokens + totalTokensSaved).toLocaleString(),
-                    toolCallsOptimized: toolCallCount,
-                    activeStrategies: {
-                        turboSqueeze: true,
-                        contextCompression: true,
-                        semanticCaching: true,
-                        historyPruning: true,
-                        astNavigation: true,
-                        privacyScrubbing: true,
+                    netRatio: ratioStr,
+                    note: "netRatio = tokensSaved / tokensSpent, ambos de la misma bitácora auditable que expone token_receipt. Por debajo de 1.0x, Lemma está costando más de lo que ahorra en esta sesión.",
+                    tokensSaved: total.tokensSaved.toLocaleString(),
+                    tokensSpent: totalCost.tokensSpent.toLocaleString(),
+                    netTokens: net.netTokens.toLocaleString(),
+                    netCostUSD: net.netCost.toFixed(4),
+                    breakdown: {
+                        saved: {
+                            cache: snapshot.cache?.tokensSaved ?? 0,
+                            contextSqueeze: snapshot.contextSqueeze?.tokensSaved ?? 0,
+                            historyPrune: snapshot.historyPrune?.tokensSaved ?? 0,
+                            complexityRouting: snapshot.complexityRouting?.tokensSaved ?? 0,
+                            clipboard: snapshot.clipboard?.tokensSaved ?? 0,
+                        },
+                        spent: {
+                            mcpInstructions: snapshot.costs?.mcpInstructions?.tokensSpent ?? 0,
+                            toolResult: snapshot.costs?.toolResult?.tokensSpent ?? 0,
+                            cacheMiss: snapshot.costs?.cacheMiss?.tokensSpent ?? 0,
+                        },
                     },
                     // The fixed cost of being connected, re-sent on every request of the session.
                     perTurnOverhead: {
                         ...getToolSurfaceSummary(),
-                        schemaTokens: Math.round(getToolSchemaChars() / 4),
+                        schemaTokens,
                         note: "Hidden tools stay callable via lemma_toolbox. Set mcp.toolProfile='full' in lemma.config.json to advertise all of them.",
                     },
-                    recommendations: toolCallCount === 0
-                        ? ["No se han usado tools de Lemma todavía. Asegúrate de que el agente esté usando el prompt lemma-turbomode."]
+                    recommendations: net.ratio !== Infinity && net.ratio < 1
+                        ? ["netRatio < 1.0x: revisa si search_memory/smarter_cache se están llamando antes de razonar, o si el toolProfile anuncia más tools de las que este proyecto necesita — cada schema extra es costo fijo por turno."]
                         : ["Sigue usando turbosqueeze antes de cada code block grande.", "Usa smarter_cache antes de razonar."],
                 }, null, 2),
             }],