@nxuss/lemma 1.37.0 → 1.39.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![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](https://img.shields.io/badge/MCP-111%20tools-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
+[![MCP](https://img.shields.io/badge/MCP-91%20tools-ff69b4?style=flat-square)](https://github.com/Nxusbets/lemma)
 [![Local-first](https://img.shields.io/badge/local--first-no%20cloud%20required-success?style=flat-square)](https://github.com/Nxusbets/lemma)
 
 **A memory your AI agent can verify, and a context window that only holds what matters.**
@@ -60,8 +60,7 @@ pretending (`capability_matrix`).
 
 ## Free vs Pro
 
-61 of the 111 tools are free, including all memory, upkeep and export tools and the 22
-infrastructure tools (Jenkins, OKD/OpenShift, Terraform). Pro adds writing and patching,
+41 of the 91 tools are free, including all memory, upkeep and export tools. Pro adds writing and patching,
 `search_workspace`, `run_workspace_command`, static analysis, PR review and auto-heal.
 
 | | Free | Pro |
@@ -70,7 +69,7 @@ infrastructure tools (Jenkins, OKD/OpenShift, Terraform). Pro adds writing and p
 | Context | `read_workspace_file`, `scrub_privacy`, `token_budget`, `token_receipt`, `auto_context_bundle` | `get_ast_hologram`, `smart_file_slice`, `get_symbol_surgical_context` |
 | Workspace | — | `apply_workspace_patch`, `write_workspace_file`, `run_workspace_command`, `validate_patch_sandbox`, `surgical_ast_insert` |
 | Analysis & review | `type_coverage_report`, `git_blame_heat` | `depgraph`, `entropy_score`, `refactor`, `review_diff`, `review_pr`, `test_oracle` |
-| Infrastructure | all 22 `infra_*`, `jenkins_*`, `okd_*`, `terraform_*` | — |
+| Monolith analysis | `infra_analyze_monolith`, `infra_suggest_split` (not advertised; via `lemma_toolbox`) | — |
 
 Without a license, Pro tools aren't advertised to the model at all. Full list:
 `lemma_toolbox { "action": "list" }`. Get Pro: `lemma activate <key>` →
@@ -87,8 +86,12 @@ Without a license, Pro tools aren't advertised to the model at all. Full list:
 | Claude Desktop / any MCP client | `{ "command": "npx", "args": ["-y", "@nxuss/lemma", "mcp"] }` |
 
 `lemma init` also installs the hooks that feed the Brain (git `post-commit` / `post-merge` /
-`post-checkout`, and post-tool hooks for Claude Code, Codex, Cursor and OpenCode). Existing hooks
-are kept; `--no-hooks` skips them. Health check: `lemma doctor`.
+`post-checkout`, and post-tool hooks for Claude Code, Codex, Cursor and OpenCode). In Claude Code
+it adds a `SessionStart` briefing and a prompt-time recall too, and pre-approves the read and
+memory tools so using them never costs a permission prompt. Existing hooks are kept; `--no-hooks`
+skips them. An install from an older version gets the missing Claude Code hooks the next time the
+MCP server starts; re-run `lemma init` after upgrading to refresh the agent rules. Health check:
+`lemma doctor`.
 
 ### CLI
 

package/bin/brain-ingest.js

@@ -4,16 +4,16 @@
 /**
  * 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`:
+ * Commit ingestion is opt-in (`--commits`). It used to run on every commit from a post-commit
+ * hook, and on Lemma's own repo it made 295 of 339 memories — a copy of `git log`, recalled
+ * twice in total, that crowded out the memories written on purpose. Hooks an older `lemma init`
+ * installed still call this with no flags; that is now a no-op for commits.
  *
- *   echo 'lemma-brain-ingest "$(git rev-parse --show-toplevel)" &' >> .git/hooks/post-commit
+ * With `--commits` it's an incremental catch-up: a marker file under .lemma/session/ tracks the
+ * last commit ingested, so repeated runs never double-store. `--max N` only matters the first
+ * time there is no marker yet. `--no-commits` is accepted and ignored (older hooks pass it).
  *
- * 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] [--team-pull]
+ * Usage: lemma-brain-ingest [projectRoot] [--commits [--max N]] [--changelog] [--team-pull]
  *        lemma-brain-ingest --hook-result [--host=claude|codex|cursor|opencode] < payload.json
  *        lemma-brain-ingest --prompt-submit < payload.json
  *
@@ -49,12 +49,27 @@ function readStdin() {
   }
 }
 
-function hookResult(args) {
+// Tell the dashboard which memories a note offered (see reportRecall). Awaited: this process
+// exits as soon as it has answered the host, and an unfinished request would die with it.
+async function reportOffered(dist, root, notes) {
+  try {
+    const { reportRecall } = require(path.join(dist, 'utils', 'reportSavings.js'));
+    const { repoRoot } = require(path.join(dist, 'subconscious', 'TeamBrain.js'));
+    const projectPath = repoRoot(root || process.cwd());
+    await Promise.all(
+      notes.filter((n) => n && n.offered.length > 0).map((n) => reportRecall({ projectPath, trigger: n.trigger, memoryIds: n.offered }))
+    );
+  } catch {
+    // Reporting is bookkeeping; the note itself already went to the host.
+  }
+}
+
+async function hookResult(args) {
   const dist = path.join(__dirname, '..', 'dist', 'cjs');
-  let recordHookPayload, recallForHookPayload, normalizeHostPayload, formatHostOutput, parseHost;
+  let recordHookPayload, hookRecall, normalizeHostPayload, formatHostOutput, parseHost;
   try {
     ({ recordHookPayload } = require(path.join(dist, 'utils', 'FixCapture.js')));
-    ({ recallForHookPayload } = require(path.join(dist, 'subconscious', 'HostRecall.js')));
+    ({ hookRecall } = require(path.join(dist, 'subconscious', 'HostRecall.js')));
     ({ normalizeHostPayload, formatHostOutput, parseHost } = require(path.join(dist, 'subconscious', 'HostAdapters.js')));
   } catch {
     return; // no build — a hook must stay silent and harmless
@@ -68,23 +83,30 @@ function hookResult(args) {
     return;
   }
   const notes = [];
+  const recalled = [];
+  let root;
   for (const payload of normalizeHostPayload(host, raw)) {
     try {
       const res = recordHookPayload(payload, payload.cwd);
       if (res && res.captured) console.error(res.note.trim());
     } catch { /* capture failing must not cost the recall below */ }
-    const note = recallForHookPayload(payload, payload.cwd);
-    if (note && !notes.includes(note)) notes.push(note);
+    const recall = hookRecall(payload, payload.cwd);
+    if (recall && !notes.includes(recall.text)) {
+      notes.push(recall.text);
+      recalled.push(recall);
+      root = root || payload.cwd;
+    }
   }
   const out = formatHostOutput(host, notes.join('\n'));
   if (out) process.stdout.write(out);
+  await reportOffered(dist, root, recalled);
 }
 
-function promptSubmit() {
+async function promptSubmit() {
   const dist = path.join(__dirname, '..', 'dist', 'cjs');
-  let recallForPrompt, formatHostOutput;
+  let promptRecall, formatHostOutput;
   try {
-    ({ recallForPrompt } = require(path.join(dist, 'subconscious', 'HostRecall.js')));
+    ({ promptRecall } = require(path.join(dist, 'subconscious', 'HostRecall.js')));
     ({ formatHostOutput } = require(path.join(dist, 'subconscious', 'HostAdapters.js')));
   } catch {
     return; // no build — a hook must stay silent and harmless
@@ -95,18 +117,53 @@ function promptSubmit() {
   } catch {
     return;
   }
-  const out = formatHostOutput('claude', recallForPrompt(payload, payload && payload.cwd, undefined, { mcpEntry: path.join(dist, 'mcp', 'index.js') }), 'UserPromptSubmit');
+  const recall = promptRecall(payload, payload && payload.cwd, undefined, { mcpEntry: path.join(dist, 'mcp', 'index.js') });
+  const out = formatHostOutput('claude', recall ? recall.text : '', 'UserPromptSubmit');
+  if (out) process.stdout.write(out);
+  await reportOffered(dist, payload && payload.cwd, [recall]);
+}
+
+// SessionStart hook (Claude Code): the Brain's briefing and the Lemma playbook, in context
+// before the first prompt — no tool call for the agent to remember or skip.
+async function sessionStart() {
+  const dist = path.join(__dirname, '..', 'dist', 'cjs');
+  let sessionRecall, formatHostOutput;
+  try {
+    ({ sessionRecall } = require(path.join(dist, 'subconscious', 'HostRecall.js')));
+    ({ formatHostOutput } = require(path.join(dist, 'subconscious', 'HostAdapters.js')));
+  } catch {
+    return;
+  }
+  let payload = {};
+  try {
+    payload = JSON.parse(readStdin()) || {};
+  } catch {
+    // No payload is fine: the briefing only needs a directory.
+  }
+  // Work that landed since the last session began becomes a "store what you learned" reminder
+  // for the first prompt — no SessionEnd hook needed, which no installer wires up.
+  try {
+    const { draftSinceLastSession } = require(path.join(dist, 'utils', 'StoreDraft.js'));
+    const { repoRoot } = require(path.join(dist, 'subconscious', 'TeamBrain.js'));
+    draftSinceLastSession(repoRoot(payload.cwd || process.cwd()));
+  } catch {
+    // the reminder is a courtesy; the briefing must still go out
+  }
+  const recall = sessionRecall(payload, payload.cwd);
+  const out = formatHostOutput('claude', recall ? recall.text : '', 'SessionStart');
   if (out) process.stdout.write(out);
+  await reportOffered(dist, payload.cwd, [recall]);
 }
 
-function main() {
+async function main() {
   const args = process.argv.slice(2);
+  if (args.includes('--session-start')) return sessionStart();
   if (args.includes('--prompt-submit')) return promptSubmit();
   if (args.includes('--hook-result')) return hookResult(args);
   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 includeCommits = args.includes('--commits');
   const teamPull = args.includes('--team-pull');
   const positional = args.filter((a, i) => !a.startsWith("--") && (maxIndex < 0 || i !== maxIndex + 1));
   const projectRoot = path.resolve(positional[0] || process.cwd());
@@ -156,11 +213,13 @@ function flushBrain() {
   }
 }
 
-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);
-}
-flushBrain();
-process.exit(0);
+(async () => {
+  try {
+    await 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);
+  }
+  flushBrain();
+  process.exit(0);
+})();

package/bin/doctor.js

@@ -3,7 +3,7 @@
 
 /**
  * Lemma doctor — verifies the Lemma wiring on this machine / project:
- * wrapper, project skill, user skill (muse), and AGENTS.md block.
+ * wrapper, project skill, user skill (muse), AGENTS.md block, and Claude Code hooks/permissions.
  *
  * Usage: `lemma doctor` (exit 0 = usable, exit 1 = wrapper broken).
  */
@@ -111,10 +111,37 @@ async function main() {
   const agentsPath = path.join(cwd, 'AGENTS.md');
   if (!fs.existsSync(agentsPath) || !fs.readFileSync(agentsPath, 'utf8').includes('@nxuss/lemma')) {
     warn('no Lemma block in ./AGENTS.md — run `lemma init`');
-  } else if (fs.readFileSync(agentsPath, 'utf8').includes('At session')) {
-    ok('AGENTS.md block current (session-start guard)');
+  } else if (fs.readFileSync(agentsPath, 'utf8').includes('## Triggers')) {
+    ok('AGENTS.md block current (trigger-based rules)');
   } else {
-    warn('AGENTS.md block is stale (pre Muse guard) — re-run `lemma init`');
+    warn('AGENTS.md block is stale (pre trigger rules) — re-run `lemma init`');
+  }
+
+  // 5. Claude Code hooks + permissions — what makes the Brain speak without being asked.
+  const claudeLocal = path.join(cwd, '.claude', 'settings.local.json');
+  let claudeSettings = null;
+  try {
+    claudeSettings = JSON.parse(fs.readFileSync(claudeLocal, 'utf8'));
+  } catch {
+    // missing or unreadable — reported below
+  }
+  if (!claudeSettings) {
+    warn('no .claude/settings.local.json — run `lemma init` for Claude Code hooks');
+  } else {
+    const hooksText = JSON.stringify(claudeSettings.hooks || {});
+    const missing = [
+      ['PostToolUse', 'lemma-brain-ingest --hook-result'],
+      ['UserPromptSubmit', 'lemma-brain-ingest --prompt-submit'],
+      ['SessionStart', 'lemma-brain-ingest --session-start'],
+    ].filter(([, mark]) => !hooksText.includes(mark)).map(([event]) => event);
+    if (missing.length === 0) ok('Claude Code hooks current (PostToolUse, UserPromptSubmit, SessionStart)');
+    else warn(`Claude Code hooks missing: ${missing.join(', ')} — re-run \`lemma init\` (or restart the MCP server: it repairs an existing install)`);
+
+    const allow = (claudeSettings.permissions && claudeSettings.permissions.allow) || [];
+    const core = ['search_memory', 'get_memory', 'verify_memory', 'store_memory', 'update_memory', 'read_workspace_file', 'search_workspace'];
+    const unallowed = core.filter((t) => !allow.includes(`mcp__lemma__${t}`) && !allow.includes('mcp__lemma'));
+    if (unallowed.length === 0) ok('core Lemma tools pre-approved (no permission prompt)');
+    else warn(`core Lemma tools still prompt for permission: ${unallowed.join(', ')} — re-run \`lemma init\``);
   }
 
   process.stdout.write(`\n  ${DIM}Brain: ~/.lemma-cache/lemma_brain.json · proxy: lemma-proxy.cjs status${RESET}\n\n`);

package/bin/init.js

@@ -260,17 +260,41 @@ function loadLemmaToolNames() {
 }
 
 const LEMMA_TOOL_NAMES = loadLemmaToolNames();
-const LEMMA_MCP_TOOLS = LEMMA_TOOL_NAMES.map((name) => `mcp__lemma__${name}`);
+// Pre-approved in Claude Code: reading, searching and the Brain's lifecycle — local, and nothing
+// a native Read/Grep couldn't already do. Tools that write code (apply_workspace_patch,
+// surgical_ast_insert), run commands (run_workspace_command), delete (forget_memory) or
+// dispatch arbitrary tools (lemma_toolbox) still ask.
+const LEMMA_PREAPPROVED_TOOLS = [
+  'search_memory', 'get_memory', 'verify_memory', 'store_memory', 'update_memory', 'refresh_memory',
+  'downvote_memory', 'read_workspace_file', 'list_workspace_dir', 'search_workspace', 'smart_file_slice',
+  'get_ast_hologram', 'get_symbol_surgical_context', 'output_region', 'get_project_onboarding',
+  'state_hash_cache', 'smarter_cache', 'token_receipt', 'get_routing_advice',
+].map((name) => `mcp__lemma__${name}`);
 
 const CLAUDE_MD_CONTENT = `# Lemma MCP — Cómo usar las herramientas de este proyecto
 
-Tienes conectado el servidor MCP \`lemma\`. Úsalo cuando aporte algo real — caché verificable,
-scrubbing de secretos, contexto de proyecto ya indexado — no como sustituto automático de tus
-herramientas nativas en cada caso. Si una tool de Lemma no encaja con lo que necesitas hacer,
-usa la herramienta nativa; una regla que te obliga a usar la tool equivocada para ahorrar
-tokens sale más cara que los tokens que ahorra.
+Tienes conectado el servidor MCP \`lemma\`. Lo que hace que las herramientas nativas no pueden
+es **recordar entre sesiones**: el Brain guarda fixes y decisiones verificadas, y avisa cuando el
+código del que dependen cambió. Ese valor solo existe si se consulta y se alimenta, así que estos
+momentos no son opcionales:
 
-## Por defecto, para esto sí conviene usar Lemma
+## Disparadores — haz esto siempre
+
+| Cuando… | Llama | Por qué no basta lo nativo |
+|---|---|---|
+| Vas a investigar un bug, un error o un "¿por qué X?" | \`mcp__lemma__search_memory\` con el texto del error o la pregunta | Puede que ya esté resuelto; \`grep\` no encuentra lo que se aprendió en otra sesión |
+| Un aviso 🧠 de Lemma nombra memorias | \`mcp__lemma__get_memory\` de la primera | El aviso trae solo el titular; el cuerpo tiene los archivos y el porqué |
+| Un fix quedó verificado (tests pasan, build ok, el usuario confirmó) | \`mcp__lemma__store_memory\` con \`filePaths\`: la causa raíz, la trampa o lo que no funcionó — no un resumen de qué cambió | Si no se guarda, la próxima sesión lo vuelve a investigar desde cero; un resumen de cambios ya está en git log y nadie lo vuelve a buscar |
+| Una memoria resultó desactualizada o incorrecta | \`mcp__lemma__update_memory\` / \`forget_memory\` | Guardar otra al lado deja dos versiones y la búsqueda mezcla ambas |
+| Vas a leer código que aún no ubicaste, o que puede tener secretos | \`mcp__lemma__search_workspace\` / \`read_workspace_file\` | Enmascaran API keys antes de que entren a tu contexto |
+
+Si las tools de Lemma te llegan diferidas (solo el nombre), cárgalas en **una sola** llamada a
+ToolSearch: \`select:mcp__lemma__search_memory,mcp__lemma__get_memory,mcp__lemma__verify_memory,mcp__lemma__store_memory,mcp__lemma__update_memory,mcp__lemma__read_workspace_file,mcp__lemma__search_workspace\`.
+
+Fuera de esos momentos usa tu criterio: para un archivo chico que ya ubicaste, \`Read\` nativo
+cuesta menos que el ida y vuelta, y para procesos, puertos o git Lemma no tiene nada que aportar.
+
+## Referencia: qué tool para qué
 
 | Tarea | Tool de Lemma | Por qué |
 |---|---|---|
@@ -312,14 +336,13 @@ No le pidas que pegue archivos, logs o documentación que puedes obtener tú: ag
 
 ## Al iniciar en este proyecto
 
-1. Llama \`mcp__lemma__get_project_onboarding\` para orientarte con el contexto ya indexado.
-2. Si el problema se parece a algo ya resuelto, llama \`mcp__lemma__search_memory\`.
-3. No lo trates como un hecho hasta verificarlo contra el estado actual del código.
+El hook \`SessionStart\` de Lemma ya te dio un resumen del Brain al arrancar (si no lo ves,
+\`lemma doctor\` dice qué falta). Para más contexto: \`mcp__lemma__get_project_onboarding\`.
+Lo que venga del Brain no es un hecho hasta verificarlo contra el estado actual del código.
 
-## Al reportar o investigar un bug
+## Al investigar un bug, además
 
-1. \`mcp__lemma__search_memory\` con el mensaje de error, por si ya se resolvió algo parecido.
-2. \`lemma_toolbox\` → \`get_telepathic_hints\` con el archivo relevante para contexto de runtime.
+\`lemma_toolbox\` → \`get_telepathic_hints\` con el archivo relevante para contexto de runtime.
 
 ## Una sola regla dura
 
@@ -342,6 +365,13 @@ function configureClaudeCode() {
     const existingMd = fs.readFileSync(claudeMdPath, 'utf8');
     if (!existingMd.includes('@nxuss/lemma')) {
       fs.appendFileSync(claudeMdPath, '\n---\n\n' + CLAUDE_MD_CONTENT, 'utf8');
+    } else {
+      // Lemma's block — an older one ("úsalo cuando aporte algo real") or this one from an earlier
+      // release — is replaced in place with the current rules, keeping whatever the user wrote
+      // around it. Gating this on "already trigger-based" left every upgrade on stale rules.
+      const lemmaBlockRegex = /# Lemma MCP — Cómo usar[\s\S]*?\*Auto-generado por `lemma init` — @nxuss\/lemma\*/;
+      const updated = existingMd.replace(lemmaBlockRegex, CLAUDE_MD_CONTENT.trim());
+      if (updated !== existingMd) fs.writeFileSync(claudeMdPath, updated, 'utf8');
     }
   } else {
     fs.writeFileSync(claudeMdPath, CLAUDE_MD_CONTENT, 'utf8');
@@ -363,11 +393,17 @@ function configureClaudeCode() {
   );
   settings.enableAllProjectMcpServers = true;
 
-  // Rebuild Lemma tool permissions from the current catalog while preserving non-Lemma tools.
-  const preservedTools = (settings.allowedTools || []).filter(
-    (tool) => !tool.startsWith('mcp__lemma__')
-  );
-  settings.allowedTools = [...preservedTools, ...LEMMA_MCP_TOOLS];
+  // Pre-approve the core tools in permissions.allow — the key Claude Code reads from settings
+  // files. Earlier versions wrote the whole catalog to a top-level `allowedTools`, which left the
+  // tools the playbook asks for (get_memory, update_memory, ...) prompting on every call: a
+  // prompt per call is reason enough for an agent to fall back to its native tools. Lemma's
+  // entries are dropped from the legacy key; anything else in it is the user's and stays.
+  const legacy = (settings.allowedTools || []).filter((tool) => !tool.startsWith('mcp__lemma__'));
+  if (legacy.length > 0) settings.allowedTools = legacy;
+  else delete settings.allowedTools;
+  settings.permissions = settings.permissions && typeof settings.permissions === 'object' ? settings.permissions : {};
+  const allow = Array.isArray(settings.permissions.allow) ? settings.permissions.allow : [];
+  settings.permissions.allow = Array.from(new Set([...allow, ...LEMMA_PREAPPROVED_TOOLS]));
 
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2), 'utf8');
 
@@ -428,13 +464,13 @@ function configureClaudeCodeGateway(anthropicApiKey) {
   return { activated: true, settingsPath: claudeSettingsPath };
 }
 
-const LEMMA_RULES_CONTENT = `# Lemma MCP — Autonomous Behaviors
-
-> ⚠️ MANDATORY RULES — Follow without exception **for MCP-native clients**.
+const LEMMA_RULES_CONTENT = `# Lemma MCP — When to use it
 
-The MCP server \`lemma\` is connected. For clients with native MCP support
-(Claude Code, Cursor, Codex, Windsurf, Kiro, OpenCode), NEVER use native tools
-when a Lemma equivalent exists.
+The MCP server \`lemma\` is connected. What it does that your native tools can't is
+**remember across sessions**: the Brain keeps verified fixes and decisions and flags them when
+the code they depend on changes. That only pays off if it is consulted and fed, so the moments
+below are not optional for MCP-native clients (Claude Code, Cursor, Codex, Windsurf, Kiro,
+OpenCode).
 
 > **Muse Code:** you DO NOT have native \`mcp__lemma__*\` tools. At session
 > start, load the \`lemma\` skill (user scope if present, else
@@ -444,36 +480,34 @@ when a Lemma equivalent exists.
 > hard block; use \`lemma call\` when it actually helps. If no \`lemma\` skill
 > is installed, tell the user to run \`npx @nxuss/lemma init\`.
 
-## Mandatory Substitutions (MCP-native clients only)
+## Triggers — always do these
 
-## Mandatory Substitutions
+| When… | Call | Why native isn't enough |
+|---|---|---|
+| Session start | \`get_project_onboarding\`, then \`search_memory\` with the task topic | The Brain may already hold the answer |
+| Investigating a bug, an error, or a "why does X" | \`search_memory\` with the error text or question | grep can't find what was learned in another session |
+| A 🧠 Lemma note names memories | \`get_memory\` on the top one | The note carries the headline; the body has the files and the reason |
+| A fix is verified (tests pass, build ok, user confirmed) | \`store_memory\` with \`filePaths\`: the root cause, the trap or what didn't work — not a summary of what changed | Unsaved, the next session investigates it from scratch; a change summary is already in git log and nobody searches for it |
+| A memory turned out outdated or wrong | \`update_memory\` / \`forget_memory\` | A near-duplicate leaves two versions and search mixes them |
+| Reading code you haven't located yet, or that may hold secrets | \`search_workspace\` / \`read_workspace_file\` | They mask API keys before they reach your context |
+| Applying a generated patch | \`validate_patch_sandbox\` first | Validate before writing, not after |
 
-| ❌ NEVER use | ✅ ALWAYS use instead |
-|---|---|
-| Read / cat / open file | \`read_workspace_file\` |
-| Write / save file | \`write_workspace_file\` |
-| Create new file | \`create_workspace_file\` |
-| List / ls directory | \`list_workspace_dir\` |
-| Search / grep in files | \`search_workspace\` |
-| Search your own memory | \`search_memory\` |
-| Persist solutions | \`store_memory\` |
-| Project context | \`get_project_onboarding\` |
-| Runtime/bug context | \`get_telepathic_hints\` |
-| Apply a patch | \`validate_patch_sandbox\` first |
-
-## Mandatory Flow — Session Start
-
-1. Call \`get_project_onboarding\` — understand the project
-2. Call \`search_memory\` with the task topic — recall past solutions
-3. When done: call \`store_memory\` with the solution
+Outside those moments, use judgment: for a small file you already located, a native read costs
+less than the round-trip, and for processes, ports or git Lemma has nothing to add.
+
+## Bug Reporting
+
+1. Call \`search_memory\` with the error message
+2. Call \`get_telepathic_hints\` (via \`lemma_toolbox\`) with the relevant file
 
 > Muse: use \`lemma call <tool>\` (or \`node ./lemma-proxy.cjs call <tool>\` in this repo — see \`.agents/skills/lemma/SKILL.md\`).
 
-## Bug Reporting
+## One hard rule
 
-1. Call \`get_telepathic_hints\` with the relevant file
-2. Call \`search_memory\` with the error message
+Any answer that depends on a cache hit, an auto-suggested fix, or a file compressed for your own
+context must be delivered with the real information and without hiding where it came from.
 
+---
 *Auto-generated by \`lemma init\` — @nxuss/lemma*
 `;
 
@@ -491,14 +525,14 @@ function updateAgentsMd() {
     const existing = fs.readFileSync(agentsMdPath, 'utf8');
     if (!existing.includes('@nxuss/lemma')) {
       fs.appendFileSync(agentsMdPath, '\n---\n\n' + LEMMA_RULES_CONTENT, 'utf8');
-    } else if (!existing.includes('Muse Code:') || !existing.includes('MCP-native clients')) {
-      // Migrate old Lemma AGENTS.md (pre-Muse guard) to new version with Muse compatibility
-      // Replace the old block in-place to preserve any user content above it
+    } else {
+      // Replace Lemma's block in place — an older one (pre-Muse guard, the "never use native
+      // tools" table) or this one from an earlier release — preserving the user's content.
       const lemmaBlockRegex = /# Lemma MCP[\s\S]*?\*Auto-generated by `lemma init` — @nxuss\/lemma\*/;
       if (lemmaBlockRegex.test(existing)) {
         const updated = existing.replace(lemmaBlockRegex, LEMMA_RULES_CONTENT.trim());
-        fs.writeFileSync(agentsMdPath, updated, 'utf8');
-      } else {
+        if (updated !== existing) fs.writeFileSync(agentsMdPath, updated, 'utf8');
+      } else if (!existing.includes('## Triggers')) {
         // Fallback: append new block
         fs.appendFileSync(agentsMdPath, '\n---\n\n' + LEMMA_RULES_CONTENT, 'utf8');
       }
@@ -527,6 +561,11 @@ function updateWindsurfRules() {
     const existing = fs.readFileSync(wsRulesPath, 'utf8');
     if (!existing.includes('@nxuss/lemma')) {
       fs.appendFileSync(wsRulesPath, '\n---\n\n' + LEMMA_RULES_CONTENT, 'utf8');
+    } else {
+      // Same in-place refresh as AGENTS.md.
+      const lemmaBlockRegex = /# Lemma MCP[\s\S]*?\*Auto-generated by `lemma init` — @nxuss\/lemma\*/;
+      const updated = existing.replace(lemmaBlockRegex, LEMMA_RULES_CONTENT.trim());
+      if (updated !== existing) fs.writeFileSync(wsRulesPath, updated, 'utf8');
     }
   } else {
     fs.writeFileSync(wsRulesPath, LEMMA_RULES_CONTENT, 'utf8');
@@ -754,12 +793,10 @@ function ensureKiroMigratesAgentsMd() {
   try {
     if (fs.existsSync(agentsMdPath)) {
       const existing = fs.readFileSync(agentsMdPath, 'utf8');
-      if (existing.includes('@nxuss/lemma') && (!existing.includes('Muse Code:') || !existing.includes('MCP-native clients'))) {
+      if (existing.includes('@nxuss/lemma')) {
         const lemmaBlockRegex = /# Lemma MCP[\s\S]*?\*Auto-generated by `lemma init` — @nxuss\/lemma\*/;
-        if (lemmaBlockRegex.test(existing)) {
-          const updated = existing.replace(lemmaBlockRegex, LEMMA_RULES_CONTENT.trim());
-          fs.writeFileSync(agentsMdPath, updated, 'utf8');
-        }
+        const updated = existing.replace(lemmaBlockRegex, LEMMA_RULES_CONTENT.trim());
+        if (updated !== existing) fs.writeFileSync(agentsMdPath, updated, 'utf8');
       }
     }
   } catch {}
@@ -909,7 +946,7 @@ function parseInitArgs(argv = process.argv) {
   };
 }
 
-// The hooks that feed the Brain (git post-commit/post-merge/post-checkout, and the PostToolUse
+// The hooks that feed the Brain (git post-merge/post-checkout, and the PostToolUse
 // hook of each agent host) live in src/cli/{gitHooks,hostHooks}.ts. They were only wired into the
 // commander `init` in src/cli/lemma-proxy.ts, which the `lemma` binary (lemma-proxy.cjs → this
 // file) never reaches — so `lemma init` reported success and installed none of them.
@@ -929,6 +966,7 @@ function installBrainFeeds(cwd = process.cwd(), home = os.homedir(), mods = null
     if (hooks.manual) lines.push(`Git hooks live in versioned ${hooks.manual.hooksDir}/ — not touching them. To feed the Brain, add:\n${hooks.manual.snippet}`);
     else if (changed.length > 0) lines.push(`Git hooks feed the Brain (${changed.join(', ')})`);
     else if (hooks.skippedReason) lines.push(`Git hooks skipped: ${hooks.skippedReason}`);
+    if (hooks.removed && hooks.removed.length > 0) lines.push(`Git hooks no longer store every commit in the Brain (removed from ${hooks.removed.join(', ')})`);
     for (const { host: name, outcome } of host.installHostHooks(cwd, home)) {
       if (outcome.status === 'manual') lines.push(`${outcome.file} couldn't be merged safely — not touching it. For ${name}, add:\n${outcome.snippet}`);
       else if (outcome.status !== 'unchanged') lines.push(`${name} hook ${outcome.status} (${outcome.file})`);
@@ -1025,7 +1063,7 @@ async function main(argv = process.argv) {
     --gateway   Reroute this user's Claude Code model traffic through the proxy
                 (~/.claude/settings.json). Requires ANTHROPIC_API_KEY in env.
                 Without it, Claude Code keeps its own auth untouched.
-    --no-hooks  Skip the hooks that feed the Brain (git post-commit/post-merge/
+    --no-hooks  Skip the hooks that feed the Brain (git post-merge/
                 post-checkout; Claude Code, Codex, Cursor and OpenCode tool hooks).
 
 `);
@@ -1171,4 +1209,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { main, configureMuse, configureMuseUserSkill, updateAgentsMd, MUSE_SKILL_CONTENT, LEMMA_RULES_CONTENT, installProxyDaemon, removeProxyDaemon, parseInitArgs, createEnvFile, installBrainFeeds };
+module.exports = { main, configureMuse, configureMuseUserSkill, updateAgentsMd, configureClaudeCode, MUSE_SKILL_CONTENT, LEMMA_RULES_CONTENT, CLAUDE_MD_CONTENT, installProxyDaemon, removeProxyDaemon, parseInitArgs, createEnvFile, installBrainFeeds };