@nxuss/lemma 1.38.0 → 1.39.0

package/dist/esm/mcp/tools/memory.js

@@ -6,14 +6,14 @@
  */
 import fs from "fs";
 import path from "path";
-import { getBrain, deriveProjectId, currentGitContext } from "../../subconscious/TheBrainV2.js";
-import { reportSavings } from "../../utils/reportSavings.js";
+import { getBrain, deriveProjectId, currentGitContext, tokenize } from "../../subconscious/TheBrainV2.js";
+import { reportSavings, reportRecall } from "../../utils/reportSavings.js";
 import { netTokensSaved } from "./squeeze-cache.js";
 import { recordReceiptEvent } from "../../utils/TokenReceipt.js";
-import { logError, safeResolvePath, DEFAULT_MEMORY_SIMILARITY_FLOOR, tryElicitConfirmation } from "../utils.js";
+import { logError, safeResolvePath, tryElicitConfirmation } from "../utils.js";
 import { deriveDomainForFile } from "../cognitiveMap.js";
 import { getRecentEvidence } from "../../utils/SessionEvidence.js";
-import { bucketNearMiss } from "../../subconscious/NearMiss.js";
+import { narrowEvidence } from "../../subconscious/NarrowEvidence.js";
 import { ageLabel } from "../../utils/ageLabel.js";
 import { sanitizeRefs, describeRef, checkExternalRefs } from "../../subconscious/ExternalRefs.js";
 import { pushTeamBrain, pullTeamBrain, teamBrainStatus } from "../../subconscious/TeamBrain.js";
@@ -41,7 +41,7 @@ export const MEMORY_TOOL_DEFINITIONS = [
     {
         name: "search_memory",
         annotations: { readOnlyHint: true, openWorldHint: false },
-        description: "Search Lemma's semantic memory (The Brain) before investigating something from scratch — retrieves past solutions, fixes, and context from ALL your projects globally. Results split into 'fresh' (safe to reuse) and 'stale' (a tracked file changed since — re-verify before reusing). Never treat a stale result as current. If a returned memory turns out wrong once acted on, call downvote_memory with its id.",
+        description: "Search the Brain before investigating something from scratch: past fixes, traps, failed approaches and decisions from earlier sessions. Returns a ranked shortlist (headline, excerpt, fresh/STALE) — pick the one that answers your question and get_memory it for the body. Never treat a STALE result as current.",
         inputSchema: {
             type: "object",
             properties: {
@@ -49,8 +49,8 @@ export const MEMORY_TOOL_DEFINITIONS = [
                 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,
+                    description: "Optional floor (0-1) on the ranking score. Off by default: the score ranks well but does not separate relevant from unrelated.",
+                    default: 0,
                 },
                 domain: {
                     type: "string",
@@ -58,7 +58,12 @@ export const MEMORY_TOOL_DEFINITIONS = [
                 },
                 semanticDiff: {
                     type: "boolean",
-                    description: "Don't count a comment/whitespace-only change as stale.",
+                    description: "Don't count a comment/whitespace-only change as stale (default). Pass false to treat any edit to the tracked code as a change.",
+                    default: true,
+                },
+                allProjects: {
+                    type: "boolean",
+                    description: "Also search memories from your other projects (labelled as such). Off by default: they may be confidential and rarely apply here.",
                     default: false,
                 },
             },
@@ -85,7 +90,7 @@ export const MEMORY_TOOL_DEFINITIONS = [
     {
         name: "store_memory",
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-        description: "Save a verified solution, fix, decision or fact to the Brain so it needn't be re-investigated. Pass filePaths (or `symbols` for one function/class) so it goes stale when that code changes; if both are omitted, Lemma guesses from the files this session touched and flags it as a guess. outcome='failed' records a dead end. To correct or extend an existing memory use update_memory — storing a revision here creates a second entry and searches return a mix of both.",
+        description: "Save a verified fix, decision or fact so it needn't be re-investigated: what code and git can't tell the next session (root cause, trap, failed approach, how-to), not a log of what shipped. Pass filePaths (or `symbols`) so it goes stale when that code changes; omitted, Lemma guesses from files this session touched. outcome='failed' records a dead end. To correct a memory use update_memory — a re-store here leaves both versions.",
         inputSchema: {
             type: "object",
             properties: {
@@ -206,8 +211,8 @@ export const MEMORY_TOOL_DEFINITIONS = [
                 ids: { type: "array", items: { type: "string" }, description: "Entry and/or claim ids to revalidate, from a prior search_memory/store_memory result." },
                 semanticDiff: {
                     type: "boolean",
-                    description: "Don't count a comment/whitespace-only change as stale.",
-                    default: false,
+                    description: "Don't count a comment/whitespace-only change as stale (default). Pass false to treat any edit to the tracked code as a change.",
+                    default: true,
                 },
             },
             required: ["ids"],
@@ -363,142 +368,113 @@ export const MEMORY_TOOL_DEFINITIONS = [
         },
     },
 ];
+/**
+ * Ids the last search_memory calls put on a shortlist. A get_memory of one of them is the
+ * moment a memory was actually reused, so that is where its hit and its saving are booked —
+ * listing a headline saves nothing by itself.
+ */
+const _shortlisted = new Set();
+const SHORTLIST_MEMORY = 200;
+const EXCERPT_CHARS = 180;
+function excerpt(text) {
+    const flat = String(typeof text === "string" ? text : JSON.stringify(text)).replace(/\s+/g, " ").trim();
+    return flat.length > EXCERPT_CHARS ? `${flat.slice(0, EXCERPT_CHARS - 1)}…` : flat;
+}
+/**
+ * search_memory answers with a ranked shortlist, not a verdict.
+ *
+ * It used to return a memory only above a 0.75 similarity floor and otherwise said
+ * "Investigate from scratch — there is nothing safe to reuse". Measured on Lemma's own Brain
+ * (18 questions a later session would really ask), the right memory ranked first 15 times and
+ * in the top three every time — and cleared the floor zero times. The score can't carry a
+ * floor: BM25 is normalized against the best candidate *of the same search*, so the top result
+ * of an unrelated question scores 0.54–0.66, the same band as a correct one (0.56–0.73). The
+ * ranking is good; deciding relevance from headlines is something the agent does well. So the
+ * Brain shortlists and the agent picks, then reads the one that answers with get_memory.
+ */
 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;
+    const query = typeof args?.query === "string" ? args.query : "";
+    const limit = Math.min(Math.max(Math.floor(args?.limit || 5), 1), 10);
+    // Explicit floors are still honoured; by default nothing is cut, for the reason above.
+    const minSimilarity = typeof args?.minSimilarity === "number" ? args.minSimilarity : 0;
     const domain = typeof args?.domain === "string" && args.domain.trim() ? args.domain.trim() : undefined;
-    const semanticDiff = args?.semanticDiff === true;
+    const semanticDiff = args?.semanticDiff !== false;
     if (!query)
         throw new Error("Query is required");
     try {
         const brain = getBrain();
-        // searchHybrid is search() plus one boolean check unless LEMMA_BRAIN_EMBEDDINGS is set,
-        // so this costs nothing by default and picks up the semantic re-rank when it is enabled.
-        const results = await brain.searchHybrid(query, limit, minSimilarity, { projectId: deriveProjectId(), domain, semanticDiff });
-        if (results.length === 0) {
-            recordReceiptEvent("reasoning", query.substring(0, 100), {
-                tool: "search_memory",
-                reason: `no memory above the ${minSimilarity} similarity floor`,
-            });
-            // searchHybrid already filtered anything below minSimilarity out of `results`, so the
-            // near-miss check needs its own uncapped lookup — countStats:false, this must not
-            // register as a second miss on top of the one searchHybrid just counted.
-            const uncapped = brain.search(query, ORIENTATION_LIMIT, 0, { projectId: deriveProjectId(), domain, countStats: false });
-            const nearMiss = bucketNearMiss(uncapped[0] ? { id: uncapped[0].id, query: uncapped[0].query, similarity: uncapped[0].similarity } : undefined, minSimilarity);
-            // A miss that says nothing cannot tell "nothing related" from "something related at 60%".
-            // These are for orientation only: below the floor, never reusable, never credited.
-            const related = uncapped
-                .filter((r) => r.similarity >= ORIENTATION_MIN)
-                .map((r) => `  - ${r.id} (${(r.similarity * 100).toFixed(0)}%, stored ${ageLabel(r.timestamp)}): ${r.query.substring(0, 100)}`);
-            const orientation = related.length > 0
-                ? `\n\nBelow the reuse floor, for orientation only (not cache hits — get_memory to read, then verify against current state before relying on any):\n${related.join("\n")}`
-                : "";
+        // countStats:false — appearing on a shortlist is not a reuse; get_memory books that.
+        const projectId = deriveProjectId();
+        adoptOnce(brain, projectId);
+        const results = await brain.searchHybrid(query, limit, minSimilarity, {
+            projectId,
+            allProjects: args?.allProjects === true,
+            domain,
+            semanticDiff,
+            countStats: false,
+        });
+        if (results.length === 0 && tokenize(query).length === 0) {
             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.${nearMiss.hint ? ` ${nearMiss.hint}` : ""}${orientation}`,
-                    }],
+                content: [{ type: "text", text: "This query has no searchable words (only stop words or symbols). Search with the error text, a symbol or file name, or the words of the question." }],
             };
         }
-        // An entry that tracks nothing reports `fresh: true` vacuously (checkEntryFreshness has
-        // nothing to compare) — it must NOT land in the verified-fresh bucket, be credited as a
-        // cache hit, or be told "from cache". It gets its own UNTRACKED bucket instead.
-        const fresh = results.filter((r) => r.fresh && !r.untracked);
-        const stale = results.filter((r) => !r.fresh);
-        const untracked = results.filter((r) => r.fresh && r.untracked);
-        const formatClaims = (r) => {
-            if (!Array.isArray(r.claims) || r.claims.length === 0)
-                return "";
-            const lines = r.claims.map((c) => c.fresh
-                ? `  ✓ fresh: ${c.text}`
-                : `  ✗ STALE (${(c.staleFiles || []).join(", ")}): ${c.text}`);
-            const staleCount = r.claims.filter((c) => !c.fresh).length;
-            return `\nClaims (${r.claims.length - staleCount}/${r.claims.length} still fresh — trust only the ✓ ones):\n${lines.join("\n")}`;
-        };
-        const formatResult = (r, i) => `Result ${i + 1} (id: ${r.id}, Similarity: ${(r.similarity * 100).toFixed(1)}%, stored ${ageLabel(r.timestamp)})${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." : ""}${typeof r.tokensSaved === "number" && r.tokensSaved > 0
-            ? `\n💰 This memory has saved ${r.tokensSaved} tokens across ${r.hits || "?"} reuse(s) — prefer it over re-deriving.`
-            : ""}\nPrompt: ${r.query.substring(0, 300)}...\nResponse: ${typeof r.response === "string" ? r.response : JSON.stringify(r.response, null, 2)}${formatClaims(r)}${Array.isArray(r.evidence) && r.evidence.length > 0
-            ? `\nEvidence: ${r.evidence.map((e) => {
-                const sep = e.lastIndexOf("::");
-                return sep > 0 ? `${relLabel(e.substring(0, sep))}::${e.substring(sep + 2)}` : relLabel(e);
-            }).join(", ")}`
-            : ""}${Array.isArray(r.whyShown) && r.whyShown.length > 0
-            ? `\nWhy shown: ${r.whyShown.join(" · ")}`
-            : ""}${Array.isArray(r.cosmeticChanges) && r.cosmeticChanges.length > 0
-            ? `\n(comment/whitespace-only change, ignored under semanticDiff: ${r.cosmeticChanges.join(", ")})`
-            : ""}`;
-        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.
-            const bestFresh = fresh[0];
-            const { net: tokensSaved } = netTokensSaved(Math.max(400, String(bestFresh.response).length), query);
-            reportSavings({ source: "cache", tokens: tokensSaved, toolName: "search_memory", query: query.substring(0, 100) });
-            // Attribute the saving to the memory itself: the per-entry ROI ledger lives on the
-            // entry (persisted, merged, imported), booked on the same event as the ledger above
-            // so the two can never disagree about whether a reuse happened.
-            brain.creditSavings(bestFresh.id, tokensSaved);
-            recordReceiptEvent("semantic_cache_hit", query.substring(0, 100), {
-                tool: "search_memory",
-                similarity: bestFresh.similarity,
-                tokensSaved,
-                memoryId: bestFresh.id,
-            });
-        }
-        else if (untracked.length > 0) {
-            recordReceiptEvent("reasoning", query.substring(0, 100), {
-                tool: "search_memory",
-                reason: `${untracked.length} similar but UNTRACKED — no evidence to verify, not credited as a cache hit`,
-            });
-        }
-        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) {
-            parts.push(`Lemma found ${fresh.length} fresh ${fresh.length === 1 ? "memory" : "memories"} (from cache — say so if you use this):\n\n${fresh.map(formatResult).join("\n\n---\n\n")}`);
-        }
-        if (untracked.length > 0) {
-            const untrackedText = untracked
-                .map((r, i) => formatResult(r, i))
-                .join("\n\n---\n\n");
-            parts.push(`⚠️ ${untracked.length} ${untracked.length === 1 ? "memory is" : "memories are"} similar but UNTRACKED — ${untracked.length === 1 ? "it tracks" : "they track"} no files or symbols, so nothing was verified against current code (${untracked.length === 1 ? "it is" : "they are"} vacuously "fresh": there was nothing to check). ${untracked.length === 1 ? "It may" : "They may"} describe state that no longer exists — treat as a hint, re-verify against the repo before acting on it, and use update_memory/refresh_memory with filePaths/symbols so it becomes verifiable next time:\n\n${untrackedText}`);
+        if (results.length === 0) {
+            const why = minSimilarity > 0
+                ? `scored at or above the ${minSimilarity} floor you set`
+                : "shares a term with this query — nothing was learned about it in an earlier session";
+            recordReceiptEvent("reasoning", query.substring(0, 100), { tool: "search_memory", reason: `no memory ${why}` });
+            return { content: [{ type: "text", text: `No memory in Lemma's Brain ${why}. Investigate from scratch.` }] };
         }
-        if (stale.length > 0) {
-            const staleText = stale
-                .map((r, i) => {
-                // "You are on a different branch" and "someone rewrote this function" are the same
-                // hash mismatch and completely different situations for the reader: the first is
-                // usually not a reason to distrust the memory at all.
-                const cause = r.staleCause === "branch-changed"
-                    ? `\nNOTE: stored on branch \`${r.storedOnBranch}\`, you are on \`${currentGitContext().branch || "an unknown branch"}\`. The difference may be the branch switch rather than an edit — check before discarding this.`
+        for (const r of results)
+            _shortlisted.add(r.id);
+        while (_shortlisted.size > SHORTLIST_MEMORY)
+            _shortlisted.delete(_shortlisted.values().next().value);
+        void reportRecall({ projectPath: process.cwd(), trigger: "search", memoryIds: results.map((r) => r.id) });
+        recordReceiptEvent("reasoning", query.substring(0, 100), { tool: "search_memory", reason: `shortlisted ${results.length} memories` });
+        const line = (r, i) => {
+            const verdict = !r.fresh
+                ? r.staleCause === "branch-changed"
+                    ? `STALE — stored on branch ${r.storedOnBranch}, you are on ${currentGitContext().branch || "another branch"}`
+                    : `STALE — changed since: ${(r.staleFiles || []).map(relLabel).join(", ")}`
+                : r.untracked
+                    ? "untracked — tracks no files, nothing to check it against"
+                    : "fresh";
+            const failed = r.outcome === "failed" ? " ⚠️ FAILED APPROACH — tried before and did not work" : "";
+            const origin = r.scope === "other-project"
+                ? ` ⚠️ FROM ANOTHER PROJECT (${r.ownerProject}) — do not assume it applies here`
+                : r.scope === "unscoped"
+                    ? " [stored before memories were scoped to a project — may not be from this one]"
                     : "";
-                return `${formatResult(r, i)}\nSTALE — changed since stored: ${r.staleFiles.join(", ")}${cause}`;
-            })
-                .join("\n\n---\n\n");
-            parts.push(`${stale.length} more ${stale.length === 1 ? "memory is" : "memories are"} similar but STALE (underlying file(s) changed) — do not reuse verbatim, re-verify against current file state:\n\n${staleText}`);
-        }
-        return { content: [{ type: "text", text: parts.join("\n\n===\n\n") }] };
+            return `${i + 1}. ${r.id} (${ageLabel(r.timestamp)}, ${verdict})${failed}${origin}\n   ${r.query.replace(/\s+/g, " ").slice(0, 160)}\n   ${excerpt(r.response)}`;
+        };
+        const text = `Closest memories in Lemma's Brain, best match first. Ranking is lexical: the right memory is usually here, but so are unrelated ones that share words — judge each by its headline.\n\n` +
+            `${results.map(line).join("\n\n")}\n\n` +
+            `If one answers your question, get_memory <id> for the full body before relying on it (a STALE one must be re-checked against the current code; a FAILED one is a warning, not a suggestion). If none does, investigate from scratch. A memory that turns out wrong: downvote_memory or forget_memory it.`;
+        return { content: [{ type: "text", text }] };
     }
     catch (e) {
         logError("search_memory", e);
         return { content: [{ type: "text", text: `Local Search failed: ${e.message}` }] };
     }
 }
+/** Memories from before projects existed are adopted once per process, from the repo root. */
+let _adopted = false;
+function adoptOnce(brain, projectId) {
+    if (_adopted)
+        return;
+    _adopted = true;
+    try {
+        brain.adoptUnscopedByEvidence(projectId, process.cwd());
+    }
+    catch (e) {
+        logError("adoptUnscopedByEvidence", e);
+    }
+}
 /** Relative-to-cwd label for a tracked absolute path, matching how the Brain reports them. */
 function relLabel(abs) {
     const rel = path.relative(process.cwd(), abs);
     return rel.startsWith("..") ? abs : rel;
 }
-/** How many below-floor candidates a miss lists, and the weakest one still worth naming. */
-const ORIENTATION_LIMIT = 3;
-const ORIENTATION_MIN = 0.3;
 /** External refs (commit / MR / issue) an entry carries, as one readable line; "" if none. */
 function refsLine(entry) {
     const refs = Array.isArray(entry.refs) ? entry.refs : [];
@@ -548,6 +524,18 @@ async function handleGetMemory(args) {
             return { content: [{ type: "text", text: `No memory with id "${id}" in the Brain. It may have been deleted with forget_memory, or evicted at capacity — search_memory can find it by content if it is still there under another id.` }] };
         }
         const [status] = brain.verifyByIds([id]);
+        // Opened from a search_memory shortlist: this is the reuse. Booked once per shortlisting,
+        // and only for a memory that was checked against code and still holds — the same rule the
+        // old above-the-floor hit followed.
+        if (_shortlisted.delete(id) && includeResponse) {
+            brain.recordReuse(id);
+            if (status?.status === "fresh") {
+                const { net: tokensSaved } = netTokensSaved(Math.max(400, entry.response.length), entry.query);
+                reportSavings({ source: "cache", tokens: tokensSaved, toolName: "search_memory", query: entry.query.substring(0, 100) });
+                brain.creditSavings(id, tokensSaved);
+                recordReceiptEvent("semantic_cache_hit", entry.query.substring(0, 100), { tool: "get_memory", tokensSaved, memoryId: id });
+            }
+        }
         const facts = [
             `stored ${entry.timestamp}`,
             ...(entry.refreshedAt ? [`re-anchored ${entry.refreshedAt}`] : []),
@@ -620,7 +608,19 @@ async function handleUpdateMemory(args) {
             const ok = getBrain().setRefs(id, refs);
             return { content: [{ type: "text", text: ok ? `External refs on "${id}" ${refs.length > 0 ? `set to: ${refs.map(describeRef).join(", ")}` : "cleared"}. Nothing else was changed.` : `No entry with id "${id}" in the Brain.` }] };
         }
-        const result = getBrain().update(id, { query, response, filePaths, symbols, claims, outcome, domain, derivedFrom, supersededBy, refs });
+        // New files without symbols: track the symbols the memory names in them instead (see
+        // NarrowEvidence) — the text it is judged by is the new one when given, else the stored one.
+        let trackFiles = filePaths;
+        let trackSymbols = symbols;
+        if (filePaths && filePaths.length > 0 && !symbols) {
+            const current = getBrain().getEntry(id);
+            const narrowed = narrowEvidence(filePaths, `${query ?? current?.query ?? ""}\n${response ?? current?.response ?? ""}`);
+            if (narrowed.symbols.length > 0) {
+                trackFiles = narrowed.filePaths;
+                trackSymbols = narrowed.symbols;
+            }
+        }
+        const result = getBrain().update(id, { query, response, filePaths: trackFiles, symbols: trackSymbols, claims, outcome, domain, derivedFrom, supersededBy, refs });
         if (!result.ok)
             return { content: [{ type: "text", text: result.message }] };
         recordReceiptEvent("tool_call", `update_memory: ${id}`, {
@@ -646,6 +646,20 @@ async function handleUpdateMemory(args) {
         return { content: [{ type: "text", text: `Failed to update memory: ${e.message}` }], isError: true };
     }
 }
+/**
+ * A memory that reads as a log of what was done — "release v1.31.0: what shipped", "commit abc123:
+ * …", "hito v1.26.0". On Lemma's own repo these were most of the memories written on purpose and
+ * none was ever recalled: the next session asks why something breaks or how to do it, never what
+ * shipped on a date, and git log / the CHANGELOG answer that anyway. A how/why question is
+ * knowledge even when it mentions a release ("how to publish a release"), so it is let through.
+ */
+export function looksLikeLogbook(query) {
+    const q = query.toLowerCase();
+    if (/^(how|why|cómo|como|por qué|porque)\s/.test(q))
+        return false;
+    return (/^commit [0-9a-f]{7,}/.test(q) ||
+        /(?<![a-z])(what shipped|shipped|released?|milestone|hito|changelog|qué trae|qué se publicó|publicad[oa])(?![a-z])/.test(q));
+}
 async function handleStoreMemory(args) {
     const query = args?.query;
     const responseText = args?.response;
@@ -668,6 +682,17 @@ async function handleStoreMemory(args) {
             autoEvidence = true;
         }
     }
+    // A whole file goes stale on any edit anywhere in it; the symbols the memory names in it go
+    // stale only when what it talks about changes (see NarrowEvidence).
+    let narrowedNote = "";
+    if (filePaths && filePaths.length > 0 && (!symbols || symbols.length === 0) && query && responseText) {
+        const narrowed = narrowEvidence(filePaths, `${query}\n${responseText}`);
+        if (narrowed.symbols.length > 0) {
+            filePaths = narrowed.filePaths.length > 0 ? narrowed.filePaths : undefined;
+            symbols = narrowed.symbols;
+            narrowedNote = ` Tracking the symbols it names instead of their whole file (${narrowed.narrowed.join("; ")}) — an edit elsewhere in those files won't stale it; pass symbols explicitly to choose others.`;
+        }
+    }
     const claims = Array.isArray(args?.claims)
         ? args.claims.filter((c) => c?.text)
         : undefined;
@@ -720,10 +745,13 @@ async function handleStoreMemory(args) {
         // later store, verify_memory, refresh_memory, forget_memory. Without it the caller had
         // to search for the memory it had just written to do anything with it.
         const idNote = storeRes.id ? ` (id: ${storeRes.id})` : "";
+        const logbookNote = looksLikeLogbook(query)
+            ? "\n\n📓 This reads like a log of what was done or shipped. git log and the CHANGELOG already hold that, and log-style memories are the ones that never get recalled. If it contains what they don't — the root cause, the trap, the approach that failed, the non-obvious step — update_memory it so the key and body lead with that; otherwise forget_memory it."
+            : "";
         const scrubNote = storeRes.redactions > 0
             ? ` 🛡 ${storeRes.redactions} secret(s) redacted before storage — credentials are never persisted, only their placeholders.`
             : "";
-        return { content: [{ type: "text", text: `Success: Memory stored${idNote}. ${storeRes.reason}${trackingNote}${symbolNote}${autoEvidenceNote}${outcomeNote}${claimsNote}${domainNote}${refsNote}${derivedFromNote}${conflictsNote}${textConflictsNote}${scrubNote}` }] };
+        return { content: [{ type: "text", text: `Success: Memory stored${idNote}. ${storeRes.reason}${trackingNote}${symbolNote}${autoEvidenceNote}${outcomeNote}${claimsNote}${domainNote}${refsNote}${derivedFromNote}${conflictsNote}${narrowedNote}${textConflictsNote}${scrubNote}${logbookNote}` }] };
     }
     catch (e) {
         logError("store_memory", e);
@@ -1143,7 +1171,7 @@ async function handleBrainTeam(args) {
 }
 async function handleVerifyMemory(args) {
     const ids = Array.isArray(args?.ids) ? args.ids.filter((id) => typeof id === "string" && id) : [];
-    const semanticDiff = args?.semanticDiff === true;
+    const semanticDiff = args?.semanticDiff !== false;
     if (ids.length === 0)
         throw new Error("ids is required and must be a non-empty array");
     try {