brainllm 12.5.0 → 12.6.0

package/.env.example

@@ -25,6 +25,13 @@ TRILIUM_PASSWORD=
 # Leave unset to use the host clock — correct when BrainLLM runs on your machine.
 # BRAINLLM_TZ=
 
+# ── Deleted-note retention ────────────────────────────────────────────────────
+# Days Trilium keeps a deleted note before erasing it (Options → Other → "Erase
+# notes after"). BrainLLM reports deletions only within this window, and ETAPI
+# cannot read the option, so set this when your instance differs from Trilium's
+# default of 7. A whole number from 1 to 3650; overrides brainllm.json's policy.
+# BRAINLLM_DELETION_CATCHUP_DAYS=7
+
 # ── HTTP connector mode (Railway / remote) ────────────────────────────────────
 # When PORT is set the server starts an HTTP/SSE connector instead of stdio.
 # Railway sets PORT automatically; do NOT set it for local Claude Code usage.

package/README.md

@@ -10,7 +10,7 @@ A persistent, graph-structured second brain for Claude and any MCP client — bu
 
 [**brainllm site**](https://miisodev.github.io/BrainLLM/) · [How it works](https://miisodev.github.io/BrainLLM/how-it-works.html) · [Use cases](https://miisodev.github.io/BrainLLM/use-cases.html) · [Docs](https://miisodev.github.io/BrainLLM/docs.html)
 
-[![Version](https://img.shields.io/badge/version-12.5.0-f59e0b?style=flat-square)](https://github.com/miisodev/BrainLLM/releases)
+[![Version](https://img.shields.io/badge/version-12.6.0-f59e0b?style=flat-square)](https://github.com/miisodev/BrainLLM/releases)
 [![CI](https://img.shields.io/github/actions/workflow/status/miisodev/BrainLLM/ci.yml?branch=main&style=flat-square&label=CI&color=f59e0b)](https://github.com/miisodev/BrainLLM/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-a1a1aa?style=flat-square)](./LICENSE)
 [![Runtime: Bun](https://img.shields.io/badge/runtime-Bun%20%E2%89%A5%201.0-a1a1aa?style=flat-square&logo=bun&logoColor=white)](https://bun.sh)
@@ -296,6 +296,7 @@ Without a volume, leave `BRAINLLM_CONFIG` unset — auto-discovery re-finds the
 | `TRILIUM_PASSWORD` | ◐ | Alternative to the token: BrainLLM mints one on first start and caches it beside `brainllm.json`, reusing it across restarts. Also used by `bun run init` |
 | `BRAINLLM_MODE` | — | `core` (default) or `full` (adds the raw ETAPI surface) |
 | `BRAINLLM_TZ` | — | IANA timezone (e.g. `Africa/Johannesburg`) so dates stamp in *your* day on hosted deploys; unset = host clock |
+| `BRAINLLM_DELETION_CATCHUP_DAYS` | — | How many days your Trilium keeps deleted notes (Options → Other → "Erase notes after"). Deletions are reported only within this window, and ETAPI cannot read the option. Default `7`, Trilium's own default; overrides `policy.deletionCatchupDays` |
 | `PORT` | — | Presence switches to HTTP-connector mode |
 | `MCP_AUTH_TOKEN` | — | Static bearer token accepted on `/mcp` — what Claude Code and `mcp-remote` send |
 | `BRAINLLM_OWNER_PASSWORD` | — | Enables the OAuth 2.1 / CIMD endpoints, required for claude.ai. The password you type on the consent screen |
@@ -322,6 +323,7 @@ A handful of values in this repo reflect the author's own machine. None are secr
 | What | Where | Make it yours |
 |---|---|---|
 | **Timezone** | `BRAINLLM_TZ` in `.env` | Your IANA zone — or unset for the host clock |
+| **Deleted-note retention** | `BRAINLLM_DELETION_CATCHUP_DAYS` in `.env` | Only if your Trilium erases deleted notes after something other than 7 days |
 | **Config path** | `BRAINLLM_CONFIG` env var | Only needed on persistent-volume deploys (see above) |
 | **Bundle path** | your MCP client config | The real absolute path to `dist/index.js` on your machine |
 | **Author · repo · funding** | `package.json`, `.github/FUNDING.yml`, the badges above | Your own details if you fork; the funding links support the original author |

package/SECURITY.md

@@ -6,8 +6,8 @@ Security fixes ship on the latest release line. Older versions may remain useful
 
 | Version | Supported |
 |---|---|
-| 12.4.x | ✅ |
-| 12.3.x and earlier | ❌ |
+| 12.6.x | ✅ |
+| 12.5.x and earlier | ❌ |
 
 ## Reporting a vulnerability
 

package/dist/index.js

@@ -21254,6 +21254,19 @@ function saveCachedToken(token) {
     return null;
   }
 }
+var MAX_CATCHUP_DAYS = 3650;
+function envDeletionCatchupDays(env = process.env) {
+  const raw = env.BRAINLLM_DELETION_CATCHUP_DAYS?.trim();
+  if (!raw)
+    return {};
+  const days = Number(raw);
+  if (!/^\d+$/.test(raw) || days < 1 || days > MAX_CATCHUP_DAYS)
+    return { invalid: raw };
+  return { days };
+}
+function deletionCatchupDays(cfg, env = process.env) {
+  return envDeletionCatchupDays(env).days ?? cfg.policy?.deletionCatchupDays ?? DEFAULT_POLICY.deletionCatchupDays;
+}
 function loadConfig() {
   const path = configFilePath();
   if (!existsSync(path))
@@ -21425,13 +21438,141 @@ function normalizeIcon(raw) {
   const name = s.replace(/^bx[sl]?-/, "").replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
   return name ? `bx bx-${name}` : "";
 }
-var HTML_TAG = /<\/?[a-z][a-z0-9-]*(\s[^<>]*)?>/i;
+var HTML_TAG = /<\/?([a-z][a-z0-9-]*)(\s[^<>]*)?>/gi;
+var HTML_ELEMENTS = new Set([
+  "a",
+  "abbr",
+  "address",
+  "area",
+  "article",
+  "aside",
+  "audio",
+  "b",
+  "base",
+  "bdi",
+  "bdo",
+  "blockquote",
+  "body",
+  "br",
+  "button",
+  "canvas",
+  "caption",
+  "center",
+  "cite",
+  "code",
+  "col",
+  "colgroup",
+  "data",
+  "datalist",
+  "dd",
+  "del",
+  "details",
+  "dfn",
+  "dialog",
+  "div",
+  "dl",
+  "dt",
+  "em",
+  "embed",
+  "fieldset",
+  "figcaption",
+  "figure",
+  "font",
+  "footer",
+  "form",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "head",
+  "header",
+  "hgroup",
+  "hr",
+  "html",
+  "i",
+  "iframe",
+  "img",
+  "input",
+  "ins",
+  "kbd",
+  "label",
+  "legend",
+  "li",
+  "link",
+  "main",
+  "map",
+  "mark",
+  "math",
+  "menu",
+  "meta",
+  "meter",
+  "nav",
+  "noscript",
+  "object",
+  "ol",
+  "optgroup",
+  "option",
+  "output",
+  "p",
+  "param",
+  "picture",
+  "pre",
+  "progress",
+  "q",
+  "rp",
+  "rt",
+  "ruby",
+  "s",
+  "samp",
+  "script",
+  "search",
+  "section",
+  "select",
+  "slot",
+  "small",
+  "source",
+  "span",
+  "strike",
+  "strong",
+  "style",
+  "sub",
+  "summary",
+  "sup",
+  "svg",
+  "table",
+  "tbody",
+  "td",
+  "template",
+  "textarea",
+  "tfoot",
+  "th",
+  "thead",
+  "time",
+  "title",
+  "tr",
+  "track",
+  "tt",
+  "u",
+  "ul",
+  "var",
+  "video",
+  "wbr",
+  "applet"
+]);
+function isHtmlElement(name) {
+  return HTML_ELEMENTS.has(name.toLowerCase());
+}
 function looksLikeHtml(body) {
-  return HTML_TAG.test(body);
+  for (const m of body.matchAll(HTML_TAG))
+    if (isHtmlElement(m[1]))
+      return true;
+  return false;
 }
 var ENCODED_TAG = /&lt;\/?[a-z][a-z0-9-]*(?:\s[^&<>]*?)?\s*\/?&gt;/i;
 function looksLikeEncodedHtml(body) {
-  return !HTML_TAG.test(body) && ENCODED_TAG.test(body);
+  return !looksLikeHtml(body) && ENCODED_TAG.test(body);
 }
 function decodeEncodedHtml(body) {
   let s = body;
@@ -21492,15 +21633,102 @@ function nearestHeading(requested, available) {
 function inlineMd(escaped) {
   return escaped.replace(/\*\*([^*]+)\*\*/g, "<strong>$1</strong>").replace(/(^|[\s(])\*([^*\s][^*]*)\*/g, "$1<em>$2</em>").replace(/`([^`]+)`/g, "<code>$1</code>").replace(/\[([^\]]+)\]\((https?:\/\/[^\s)]+)\)/g, '<a href="$2">$1</a>');
 }
-function toHtml(body) {
+function renderMarkup(raw) {
+  const body = raw.replace(/\u0000/g, "");
   if (!body.trim())
-    return "<p></p>";
+    return { html: "<p></p>", convertedRuns: 0 };
   if (looksLikeHtml(body))
-    return body;
+    return mixedToHtml(body);
   if (looksLikeEncodedHtml(body))
-    return decodeEncodedHtml(body);
+    return { html: decodeEncodedHtml(body), convertedRuns: 0 };
+  return { html: markdownToHtml(body), convertedRuns: 0 };
+}
+var BLOCK_ELEMENTS = new Set([
+  "address",
+  "article",
+  "aside",
+  "blockquote",
+  "dd",
+  "details",
+  "div",
+  "dl",
+  "dt",
+  "figcaption",
+  "figure",
+  "footer",
+  "h1",
+  "h2",
+  "h3",
+  "h4",
+  "h5",
+  "h6",
+  "header",
+  "hr",
+  "li",
+  "main",
+  "nav",
+  "ol",
+  "p",
+  "pre",
+  "section",
+  "summary",
+  "table",
+  "tbody",
+  "td",
+  "tfoot",
+  "th",
+  "thead",
+  "tr",
+  "ul"
+]);
+var VOID_BLOCKS = new Set(["hr"]);
+var LEADING_BLOCK_TAG = /^\s*<([a-z][a-z0-9]*)(?=[\s>/])/i;
+var BLOCK_TAG = /<(\/?)([a-z][a-z0-9]*)(?=[\s>/])[^>]*?(\/?)>/gi;
+function mixedToHtml(body) {
   const lines = body.replace(/\r\n/g, `
 `).split(`
+`);
+  const out = [];
+  let run = [];
+  let depth = 0;
+  let convertedRuns = 0;
+  const flushRun = () => {
+    if (!run.length)
+      return;
+    const text = run.join(`
+`);
+    if (text.trim()) {
+      out.push(markdownToHtml(text, true));
+      convertedRuns++;
+    } else {
+      out.push(text);
+    }
+    run = [];
+  };
+  for (const line of lines) {
+    const lead = LEADING_BLOCK_TAG.exec(line)?.[1]?.toLowerCase();
+    if (depth === 0 && !(lead && BLOCK_ELEMENTS.has(lead))) {
+      run.push(line);
+      continue;
+    }
+    flushRun();
+    out.push(line);
+    for (const [, close, name, selfClose] of line.matchAll(BLOCK_TAG)) {
+      const tag = name.toLowerCase();
+      if (!BLOCK_ELEMENTS.has(tag) || VOID_BLOCKS.has(tag) || selfClose)
+        continue;
+      depth = Math.max(0, depth + (close ? -1 : 1));
+    }
+  }
+  flushRun();
+  return { html: out.join(`
+`), convertedRuns };
+}
+function markdownToHtml(body, inlineHtml = false) {
+  const kept = [];
+  const source = inlineHtml ? body.replace(HTML_TAG, (tag, name) => isHtmlElement(name) ? `\x00${kept.push(tag) - 1}\x00` : tag) : body;
+  const lines = source.replace(/\r\n/g, `
+`).split(`
 `);
   const out = [];
   let para = [];
@@ -21598,8 +21826,12 @@ function toHtml(body) {
   flushTable();
   flushPara();
   flushList();
-  return out.join(`
+  const html = out.join(`
 `) || "<p></p>";
+  if (!kept.length)
+    return html;
+  const restore = (token) => kept[Number(token)] ?? "";
+  return html.replace(/(<pre><code>[\s\S]*?<\/code><\/pre>)|\u0000(\d+)\u0000/g, (_m, pre, i) => pre ? pre.replace(/\u0000(\d+)\u0000/g, (_x, j) => escapeHtml(restore(j), false)) : restore(i));
 }
 function toText(html, maxLength = 300) {
   const text = decodeEntities(html.replace(/<(style|script)[\s\S]*?<\/\1>/gi, " ").replace(/<(h[1-6]|p|li|div|tr|br)[^>]*>/gi, `
@@ -21800,17 +22032,27 @@ function safeHtmlUrl(value) {
     return null;
   return decoded;
 }
+function keptAsText(full, warnings) {
+  warnings.push(`Kept ${full} as text \u2014 not an HTML element`);
+  return escapeHtml(full, false);
+}
 function sanitizeTag(full, warnings) {
   if (full.startsWith("<!--"))
     return "";
   const close = /^<\s*\/\s*([a-z][a-z0-9-]*)\s*>$/i.exec(full);
-  if (close)
-    return SAFE_TAGS.has(close[1].toLowerCase()) ? `</${close[1].toLowerCase()}>` : "";
+  if (close) {
+    const name = close[1].toLowerCase();
+    if (SAFE_TAGS.has(name))
+      return `</${name}>`;
+    return isHtmlElement(name) ? "" : keptAsText(full, warnings);
+  }
   const open = /^<\s*([a-z][a-z0-9-]*)(\s[\s\S]*?)?\/?\s*>$/i.exec(full);
   if (!open)
     return "";
   const tag = open[1].toLowerCase();
   if (!SAFE_TAGS.has(tag)) {
+    if (!isHtmlElement(tag))
+      return keptAsText(full, warnings);
     warnings.push(`Stripped unsupported <${tag}> element`);
     return "";
   }
@@ -21927,16 +22169,16 @@ function sanitizeHtml(html) {
 }
 function renderBody(body) {
   const wasEncoded = looksLikeEncodedHtml(body);
-  const result = sanitizeHtml(toHtml(body));
-  if (!wasEncoded)
-    return result;
-  return {
-    html: result.html,
-    warnings: [
-      "Entity-encoded markup decoded to real HTML \u2014 pass tags as <p>\u2026</p>, not &lt;p&gt;\u2026&lt;/p&gt;; the escaped form would otherwise be stored as literal text",
-      ...result.warnings
-    ]
-  };
+  const { html, convertedRuns } = renderMarkup(body);
+  const result = sanitizeHtml(html);
+  const notes = [];
+  if (wasEncoded) {
+    notes.push("Entity-encoded markup decoded to real HTML \u2014 pass tags as <p>\u2026</p>, not &lt;p&gt;\u2026&lt;/p&gt;; the escaped form would otherwise be stored as literal text");
+  }
+  if (convertedRuns) {
+    notes.push(`Converted ${convertedRuns} text run(s) outside HTML blocks from markdown to HTML \u2014 send a body as all markdown or all HTML to control its shape exactly`);
+  }
+  return notes.length ? { html: result.html, warnings: [...notes, ...result.warnings] } : result;
 }
 function repairedStructure(warnings) {
   return warnings.filter((w) => w.startsWith("Closed unclosed block tag") || w.startsWith("<br> normalized to paragraph separators"));
@@ -22894,7 +23136,7 @@ async function sweep(trilium, cfg, opts = {}) {
       dormantAfterDays: policy.dormantAfterDays,
       archiveDormantAfterDays: policy.archiveDormantAfterDays,
       staleAfterDays: policy.staleAfterDays,
-      deletionCatchupDays: policy.deletionCatchupDays ?? 7
+      deletionCatchupDays: deletionCatchupDays(cfg)
     }
   };
   if (!cfg.root)
@@ -23043,7 +23285,7 @@ async function sweep(trilium, cfg, opts = {}) {
   }
   if (deep && !domainSlug) {
     const feed = await trilium.getNoteHistory(cfg.root).catch(() => []);
-    const deletionsWindow = isoDaysAgo(policy.deletionCatchupDays ?? 7);
+    const deletionsWindow = isoDaysAgo(deletionCatchupDays(cfg));
     const recent = feed.filter((h) => h.current_isDeleted && h.date.slice(0, 10) >= deletionsWindow);
     report.scanned += recent.length;
     for (const [i, h] of recent.entries()) {
@@ -23369,7 +23611,7 @@ async function hygienePasses(trilium, cfg, report, ctx) {
     for (const n of heavy) {
       if (!eligible(n) || ownedLabel(n, "threadShape") === "collection")
         continue;
-      report.flagged.push(`consolidate: ${n.title} [${n.noteId}] \u2014 ${n.childNoteIds.length} day-children. Fold what the thread has ESTABLISHED into its Context section with revise(section="Context"), so a successor reads the conclusion instead of walking the history.`);
+      report.flagged.push(`consolidate: ${n.title} [${n.noteId}] \u2014 ${n.childNoteIds.length} day-children. Move what the thread has established into its domain: timeless knowledge into the information notes, measured state into Current State. The book keeps only its goal and the entries stay as the record, so a successor reads the conclusion instead of walking the history.`);
     }
   }
   if (cfg.knowledge.domains) {
@@ -23613,9 +23855,8 @@ async function generateDailyLog(trilium, cfg, date) {
   await trilium.addLabel(logNoteId, "created", date);
   return { date, noteId: logNoteId, ...counts, action: "created" };
 }
-var DELETION_CATCHUP_DAYS = 7;
 async function catchUpDeletions(trilium, cfg, today) {
-  const windowDays = cfg.policy.deletionCatchupDays ?? DELETION_CATCHUP_DAYS;
+  const windowDays = deletionCatchupDays(cfg);
   const empty = { windowDays, coverage: "full", deletionsFound: 0, regenerated: [] };
   if (!cfg.root || !cfg.insights.logs)
     return empty;
@@ -23656,6 +23897,11 @@ async function catchUpDeletions(trilium, cfg, today) {
 var txt = (obj) => ({
   content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }]
 });
+var idParams = {
+  id: stringType().optional().describe("The note's id (noteId is accepted as an alias)"),
+  noteId: stringType().optional().describe("Alias of id")
+};
+var missingId = (tool) => txt({ error: "missing_id", detail: `${tool}() needs the note's id.`, hint: "Pass id=<noteId> (noteId= works too)." });
 var labelOf = (n, name) => n.attributes.find((a) => isOwnedAttribute(n, a) && a.type === "label" && a.name === name)?.value;
 async function skim(trilium, ancestorNoteId, opts = {}) {
   const { query, kind, limit = 20, includeArchived = false } = opts;
@@ -23771,14 +24017,16 @@ function registerLlmTools(server, trilium, brainRef) {
   const b = () => brainRef.config;
   server.tool("llm", `Read an LLM singleton \u2014 responsibilities, protocols or selfcorrection \u2014 or a diary entry by id. Self-correction holds general rules learned from mistakes; read it before work that has gone wrong before (audits, large edits, completeness claims). section="<heading>" reads one section.`, {
     which: enumType(["responsibilities", "protocols", "selfcorrection", "diary"]),
-    id: stringType().optional().describe("diary only: the entry id from llm_recall"),
+    id: stringType().optional().describe("diary only: the entry id from llm_recall (noteId is accepted as an alias)"),
+    noteId: stringType().optional().describe("Alias of id"),
     section: stringType().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole note"),
     occurrence: numberType().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
-  }, async ({ which, id, section, occurrence }) => {
+  }, async ({ which, id, noteId: idAlias, section, occurrence }) => {
     if (which === "diary") {
-      if (!id)
+      const entry = id ?? idAlias;
+      if (!entry)
         throw new Error("Reading a diary entry needs its id \u2014 use llm_recall to find one.");
-      return txt(await readFull(trilium, id, { section, occurrence }));
+      return txt(await readFull(trilium, entry, { section, occurrence }));
     }
     const noteId = b().llm[which];
     if (!noteId) {
@@ -23804,18 +24052,25 @@ function registerLlmTools(server, trilium, brainRef) {
 }
 
 // src/tools-memory.ts
+var MEMORY_INDEX_DEFAULT = 30;
+var MEMORY_INDEX_CHAR_BUDGET = 24000;
 function registerMemoryTools(server, trilium, brainRef) {
   const b = () => brainRef.config;
   server.tool("memory", `Read a Memory note by id \u2014 a thread or a session. A dated thread returns its Context and
-Resolution plus an index of its [yyyy-mm-dd] children (newest first), each listed by its
-addendum blocks; date="yyyy-mm-dd" resolves straight to one day. A collection thread returns its
+Resolution plus an index of its [yyyy-mm-dd] children (newest first: the latest 30, fewer if their
+index passes ~24k characters, unless limit= says otherwise; with the total count), each listed by its addendum blocks;
+date="yyyy-mm-dd" resolves straight to one day. A collection thread returns its
 Context plus its titled entries (alphabetical, with a lead). Read a child with memory(<child id>).
 section="<heading>" reads one section.`, {
-    id: stringType(),
+    ...idParams,
     date: stringType().optional().describe("Thread books only: resolve directly to this day's child note (yyyy-mm-dd)"),
+    limit: numberType().int().positive().optional().describe("Dated threads: how many of the newest day-children to index (default 30)"),
     section: stringType().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole note"),
     occurrence: numberType().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
-  }, async ({ id, date, section, occurrence }) => {
+  }, async ({ id: idArg, noteId, date, limit, section, occurrence }) => {
+    const id = idArg ?? noteId;
+    if (!id)
+      return missingId("memory");
     const note = await trilium.getNote(id).catch(() => null);
     if (!note || labelOf(note, "noteType") !== "thread")
       return txt(await readFull(trilium, id, { section, occurrence }));
@@ -23836,14 +24091,16 @@ section="<heading>" reads one section.`, {
         return txt(await readFull(trilium, child.results[0].noteId, { section, occurrence }));
       return txt({ id, title: note.title, kind: "thread", note: `No entry for ${date}.` });
     }
+    const shown = limit ?? MEMORY_INDEX_DEFAULT;
+    const totalChildren = note.childNoteIds.length;
     const children = await trilium.searchNotes("#noteType=threadEntry", {
       ancestorNoteId: id,
       fastSearch: true,
-      limit: 200,
+      limit: shown,
       orderBy: "dateCreated",
       orderDirection: "desc"
     }).catch(() => ({ results: [] }));
-    const entries = await Promise.all(children.results.map(async (c) => {
+    const indexed = await Promise.all(children.results.map(async (c) => {
       const content = await trilium.getNoteContent(c.noteId).catch(() => "");
       const blocks = addendumIndex(content);
       return {
@@ -23852,8 +24109,22 @@ section="<heading>" reads one section.`, {
         ...blocks.length ? { blocks } : { preview: toText(content, 160) }
       };
     }));
+    const entries = [];
+    let used = 0;
+    for (const e of indexed) {
+      const size = JSON.stringify(e).length;
+      if (limit === undefined && entries.length && used + size > MEMORY_INDEX_CHAR_BUDGET)
+        break;
+      entries.push(e);
+      used += size;
+    }
     const full = await readFull(trilium, id, { section, occurrence });
-    return txt({ ...full, children: entries });
+    return txt({
+      ...full,
+      totalChildren,
+      children: entries,
+      ...totalChildren > entries.length ? { more: `Showing the newest ${entries.length} of ${totalChildren} day-children. Pass limit= for more, or date= for one day.` } : {}
+    });
   });
   server.tool("memory_recall", "Skim Memory: active threads and recent sessions (ids + previews). An optional query filters threads by title.", { query: stringType().optional(), limit: numberType().optional() }, async ({ query, limit }) => {
     const cfg = b();
@@ -23884,10 +24155,15 @@ section="<heading>" reads one section.`, {
 function registerKnowledgeTools(server, trilium, brainRef) {
   const b = () => brainRef.config;
   server.tool("knowledge", `Read a knowledge note by id \u2014 user knowledge, a domain information note or a Sources note. section="<heading>" reads one section (outline() lists them); use it on anything large.`, {
-    id: stringType(),
+    ...idParams,
     section: stringType().optional().describe("Read only this heading's section (h2/h3/h4), instead of the whole note"),
     occurrence: numberType().int().positive().optional().describe("section=: which same-text heading, 1-based (default: the first)")
-  }, async ({ id, section, occurrence }) => txt(await readFull(trilium, id, { section, occurrence })));
+  }, async ({ id, noteId, section, occurrence }) => {
+    const target = id ?? noteId;
+    if (!target)
+      return missingId("knowledge");
+    return txt(await readFull(trilium, target, { section, occurrence }));
+  });
   server.tool("knowledge_recall", "Skim Knowledge. With a domain: that domain's Sources + information notes. Without: user-knowledge notes plus the list of domains.", { query: stringType().optional(), domain: stringType().optional() }, async ({ query, domain }) => {
     const cfg = b();
     if (domain) {
@@ -23921,7 +24197,7 @@ section="<heading>" reads one section instead of the whole log.`, {
       return txt({ date: d, note: "No log for this day." });
     return txt(await readFull(trilium, found.results[0].noteId, { section, occurrence }));
   });
-  server.tool("insights_recall", "Skim recent change logs (days + previews).", { limit: numberType().optional() }, async ({ limit }) => txt(await skim(trilium, b().insights.logs, { kind: "log", limit: limit ?? 14 })));
+  server.tool("insights_recall", "Skim the most recent daily change logs (dates + previews), newest first. limit sets how many days (default 14). For one day's full log use insights(date).", { limit: numberType().optional() }, async ({ limit }) => txt(await skim(trilium, b().insights.logs, { kind: "log", limit: limit ?? 14 })));
 }
 
 // src/tools.ts
@@ -23970,6 +24246,20 @@ function registerTools(server, trilium, brainRef) {
     const found = await trilium.searchNotes(`#noteType=session #created='${date}'`, { ancestorNoteId: cfg.memory.sessions, fastSearch: true, limit: 1 });
     return found.results[0]?.noteId ?? null;
   };
+  const ensureGateNote = async (date) => {
+    const existing = await gateNote(date);
+    if (existing)
+      return existing;
+    const cfg = b();
+    if (!cfg.memory.sessions)
+      return null;
+    const created = await trilium.createNote(cfg.memory.sessions, `[${date}]`, contentFor("session", { date, body: "" }));
+    const noteId = created.note.noteId;
+    await trilium.addLabel(noteId, "noteType", "session");
+    await trilium.addLabel(noteId, "created", date);
+    await ensureIcon(trilium, noteId);
+    return noteId;
+  };
   const parseGate = (raw) => {
     const out = new Map;
     for (const pair of (raw ?? "").split(",")) {
@@ -23982,9 +24272,9 @@ function registerTools(server, trilium, brainRef) {
   const serializeGate = (m) => [...m.entries()].map(([step, seq]) => `${step}:${seq}`).join(",");
   const markStep = async (step, date) => {
     const d = checkedDate(date);
-    const noteId = await gateNote(d);
+    const noteId = await ensureGateNote(d);
     if (!noteId)
-      throw new Error(`Cannot record pre-close step "${step}": today's session note was not found`);
+      throw new Error(`Cannot record pre-close step "${step}": the brain has no Sessions container \u2014 run bootstrap()`);
     const note = await trilium.getNote(noteId);
     const stored = parseGate(labelOf2(note, "gate"));
     const next = Math.max(preCloseSeq, ...[...stored.values()], 0) + 1;
@@ -24092,7 +24382,7 @@ ${block}` }));
         deleted: [],
         flagged: [`sweep failed: ${e}`],
         dryRun: false,
-        policy: { dormantAfterDays: cfg.policy.dormantAfterDays, archiveDormantAfterDays: cfg.policy.archiveDormantAfterDays, staleAfterDays: cfg.policy.staleAfterDays, deletionCatchupDays: cfg.policy.deletionCatchupDays ?? 7 }
+        policy: { dormantAfterDays: cfg.policy.dormantAfterDays, archiveDormantAfterDays: cfg.policy.archiveDormantAfterDays, staleAfterDays: cfg.policy.staleAfterDays, deletionCatchupDays: deletionCatchupDays(cfg) }
       })),
       buildDigest(trilium, cfg, { depth: depth ?? "digest" })
     ]);
@@ -24129,11 +24419,7 @@ ${block}` }));
           sessionPreview = toText(content, 200);
           newDay = !/<h2(?:\s[^>]*)?>\s*Addendum/i.test(content);
         } else {
-          const created = await trilium.createNote(cfg.memory.sessions, `[${todayStr}]`, contentFor("session", { date: todayStr, body: "" }));
-          sessionNoteId = created.note.noteId;
-          await trilium.addLabel(sessionNoteId, "noteType", "session");
-          await trilium.addLabel(sessionNoteId, "created", todayStr);
-          await ensureIcon(trilium, sessionNoteId);
+          sessionNoteId = await ensureGateNote(todayStr);
           newDay = true;
         }
       } catch {}
@@ -25055,7 +25341,7 @@ ${block}`), d);
 
 Modes: default append (a dated addendum \u2014 right only for records; a dated thread's append lands in today's child), mode=replace (whole body), section="<heading>" (replace that section's whole body, h2\u2192h3\u2192h4, occurrence= for repeats), section= + mode=before|after (insert a sibling block around the whole section), mode=prepend (top of the section body), mode=remove (delete the section). find="<exact stored text>" replaces every occurrence (nth= for one); edits=[{find, body}] applies several in one write. title= composes with every mode; retitling a domain book cascades its #domain slug.
 
-Check the receipt: matched=false means a NEW section was written (available= lists real headings; strict=true refuses instead). A section replace swaps everything under the heading \u2014 use find= for anything smaller. find= matches stored HTML (tags literal), not rendered text.`, {
+Check the receipt: matched=false means a NEW section was written (available= lists real headings; strict=true refuses instead). A section replace swaps everything under the heading \u2014 use find= for anything smaller. find= matches stored HTML (tags literal), not rendered text, and is taken literally: a Windows path's backslash is one backslash, never doubled.`, {
     noteId: stringType().describe("Note to update"),
     body: stringType().optional().describe("Content to add/replace: plain text, markdown, or HTML. With find=, the raw replacement string (no conversion)."),
     title: stringType().optional().describe("New title (normalized server-side)"),
@@ -26218,7 +26504,7 @@ assertion + check \u2192 register (deduped by assertion); claimId + holds + evid
       ...found.length === 0 ? { note: "No notes with pending addendums." } : { hint: "Fold each addendum into its note: read the block, then revise(noteId, section='<heading>', body='<merged content>', mode='replace') to absorb it into the right section. These notes must be left clean \u2014 no addendum markers. Addendum-style history belongs only in sessions, diary, and logs. Scoped/autonomous agents: fold only what's in your lane \u2014 leaving personal or out-of-scope addendums for the next interactive session is correct, and calling this tool is what satisfies the pre-close gate." }
     });
   });
-  server.tool("maintain", `Brain hygiene. Lite (automatic in start/close): ages threads active \u2192 dormant \u2192 archived and checks labels. deep=true adds stale notes, orphans and sinks, structural lint (duplicate headings, unbalanced tags, missing required sections, dated prose in timeless notes, oversized notes), duplicate titles, lapsed or broken claims and hygiene passes. dryRun previews. ack=[ids] silences a note you reviewed until its content changes. domain= narrows deep passes to one lane. repair=[ids] unwinds entity double-escaping in place. coverage names any capped pass.`, {
+  server.tool("maintain", `Brain hygiene. Lite (automatic in start/close): ages threads active \u2192 dormant \u2192 archived and checks labels. deep=true adds stale notes, orphans and sinks, structural lint (duplicate headings, unbalanced tags, missing required sections, dated prose in timeless notes, oversized notes), duplicate titles, lapsed or broken claims and hygiene passes. dryRun previews. ack=[ids] silences a note you reviewed until its content changes. domain= narrows deep passes to one lane. repair=[ids] unwinds entity double-escaping in place. coverage names any capped pass: structural lint reads at most 40 notes per run and rotates through the rest day by day, so a whole-brain lint spans several runs.`, {
     deep: booleanType().optional().describe("Deep pass: stale-review + orphan/sink + structural lint + duplicate titles across Memory/Threads and Knowledge (default: false)"),
     dryRun: booleanType().optional().describe("Report what would change without changing it"),
     domain: stringType().optional().describe("Narrow the deep passes to one domain's notes (slugged server-side) \u2014 for scoped agents working a single lane"),
@@ -27142,7 +27428,7 @@ note.dateModified >= 'YYYY-MM-DD', AND/OR. Unscoped unless ancestorNoteId is giv
     const note = await trilium.getNote(noteId);
     return txt4(await trilium.getNoteContentResult(noteId, note.type));
   });
-  server.tool("create_note", "Create a note at an explicit parent. Types: text/code/book/canvas/mermaid/relationMap/render/search/file/image.", {
+  server.tool("create_note", 'Create a note at an explicit parent. Types: text/code/book/canvas/mermaid/relationMap/render/search/file/image. The note gets no #noteType, icon or placement, so core tools cannot see it until it is typed with label(id, "noteType", <kind>); use remember() for a memory.', {
     parentNoteId: stringType(),
     title: stringType(),
     content: stringType(),
@@ -27159,7 +27445,7 @@ note.dateModified >= 'YYYY-MM-DD', AND/OR. Unscoped unless ancestorNoteId is giv
       throw error;
     }
   });
-  server.tool("update_note_content", "Replace a note's full content. Binary input must use encoding=base64; text remains UTF-8.", { noteId: stringType(), content: stringType(), mime: stringType().optional(), encoding: enumType(["auto", "text", "base64"]).optional() }, async ({ noteId, content, mime, encoding }) => {
+  server.tool("update_note_content", "Replace a note's full content. Binary input must use encoding=base64; text remains UTF-8. No revision is taken and nothing is sanitised: call create_revision first to keep the prior content recoverable, and prefer revise() for any BrainLLM note.", { noteId: stringType(), content: stringType(), mime: stringType().optional(), encoding: enumType(["auto", "text", "base64"]).optional() }, async ({ noteId, content, mime, encoding }) => {
     const note = await trilium.getNote(noteId);
     const targetMime = mime ?? note.mime;
     try {
@@ -27183,7 +27469,7 @@ note.dateModified >= 'YYYY-MM-DD', AND/OR. Unscoped unless ancestorNoteId is giv
     const note = await trilium.patchNote(noteId, fields);
     return txt4({ noteId: note.noteId, title: note.title, type: note.type });
   });
-  server.tool("delete_note", "Hard-delete a note (and its subtree if this is its last branch). Irreversible.", { noteId: stringType() }, async ({ noteId }) => {
+  server.tool("delete_note", "Hard-delete a single note. Irreversible. Refused (blocked: true) while any relation points at it (backlinks_exist), while it has children or more than one parent (blast_radius), or if the backlink check itself fails. Remove or retarget those first; for a recoverable removal use forget().", { noteId: stringType() }, async ({ noteId }) => {
     const note = await trilium.getNote(noteId);
     let backlinks;
     try {
@@ -28514,6 +28800,12 @@ if (!brain) {
     console.error("[brainllm] BrainLLM not found in Trilium. Run the bootstrap tool to initialize.");
   }
 }
+{
+  const { invalid } = envDeletionCatchupDays();
+  if (invalid !== undefined) {
+    console.error(`[brainllm] BRAINLLM_DELETION_CATCHUP_DAYS="${invalid}" ignored \u2014 expected a whole number of days from 1 to 3650. Using ${deletionCatchupDays(brain ?? EMPTY_BRAINLLM)}.`);
+  }
+}
 var brainRef = { config: brain ?? EMPTY_BRAINLLM };
 var port = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
 var authToken = process.env.MCP_AUTH_TOKEN;
@@ -28536,7 +28828,7 @@ function createServer(origin = null) {
   const s = new McpServer({
     name: "BrainLLM",
     title: "BrainLLM",
-    version: "12.5.0",
+    version: "12.6.0",
     icons: brandingIcons(origin)
   });
   registerTools(s, trilium, brainRef);

package/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "brainllm",
   "display_name": "BrainLLM",
-  "version": "12.5.0",
+  "version": "12.6.0",
   "description": "Turns TriliumNext Notes into a persistent, graph-structured second brain for Claude and other LLM clients.",
   "long_description": "BrainLLM is an MCP server that organises memory into five purpose-built areas (Master, LLM, Memory, Knowledge, Insights). The model supplies content while the server owns placement, format, lifecycle, dates and backups. Includes a full raw ETAPI surface for advanced use. Requires a running TriliumNext instance and the Bun runtime.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainllm",
-  "version": "12.5.0",
+  "version": "12.6.0",
   "mcpName": "io.github.miisodev/brainllm",
   "description": "MCP server that turns TriliumNext Notes into a persistent, graph-structured second brain for Claude and other LLM clients.",
   "author": "Kevin Miiso Novo <miisodev@gmail.com>",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.miisodev/brainllm",
   "description": "Persistent graph-structured memory for LLMs in TriliumNext Notes — readable and editable by humans.",
-  "version": "12.5.0",
+  "version": "12.6.0",
   "websiteUrl": "https://github.com/miisodev/BrainLLM#readme",
   "repository": {
     "url": "https://github.com/miisodev/BrainLLM",
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "brainllm",
-"version": "12.5.0",
+"version": "12.6.0",
       "transport": {
         "type": "stdio"
       },

package/skills/brainllm/SKILL.md

@@ -89,7 +89,7 @@ worth keeping?
 | Need | Tool |
 |---|---|
 | a singleton | `master(which)` / `llm(which)` — `section=` for one section |
-| a thread or session | `memory(id)` — dated index or collection entries; `date=` for one day |
+| a thread or session | `memory(id)` — dated index (newest days, up to 30 and ~24k characters; `limit=` for more) or collection entries; `date=` for one day |
 | a knowledge note | `knowledge(id)` — `section=` for one section |
 | a day's change log | `insights(date?)` |
 | skim a surface | `<surface>_recall` |
@@ -122,7 +122,7 @@ Every read that can be large takes `section=`; a note past the read ceiling cann
 - **Wire at creation:** `connect=[{relation, toNoteId}]` on the same call. An unconnected note is an orphan until wired.
 - **Identity line** (`"LLM · environment · agent/mode [· Run N]"`) is required on diary, close and dated thread appends.
 - **Every note carries an icon except logs.** The server sets the kind default at creation (a thread entry takes its thread's icon) and the sweep backfills any missing; `icon=` picks a better one (boxicons class or bare name). Removing an icon is refused.
-- Bodies may be text, markdown or HTML; the server normalises them and reports `sanitized[]`.
+- Bodies may be text, markdown or HTML; the server normalises them to editor-native HTML and reports `sanitized[]` (markdown mixed into an HTML body is converted; a placeholder like `<name>` stays as text).
 - `diary`, `session`, `log`, `claim` and `domain` have dedicated paths; `remember` refuses them.
 
 **Four writing rules** (each applies to every note you touch):
@@ -214,6 +214,7 @@ Lite runs inside `start`/`close` (thread aging, label checks). `maintain(deep=tr
 | timeouts or connection errors | the Trilium instance at `TRILIUM_BASE_URL` is unreachable; tools don't need restarting |
 | `start()` → `uninitialized` | `bootstrap()` |
 | dates look off on a hosted deploy | set `BRAINLLM_TZ` (IANA) |
+| deletions older than a week go unreported | Trilium keeps deleted notes longer than its 7-day default: set `BRAINLLM_DELETION_CATCHUP_DAYS` to match |
 | an informational `{error, detail, hint}` | read `hint` and retry with corrected arguments |
 
 ## References

package/skills/brainllm/references/fullmode.md

@@ -20,7 +20,7 @@ BrainLLM memories are typed text notes; `code` / `file` / `image` notes aren't a
 - **Code / structured text** → embed it as a fenced block in an `information` note via core `remember` (fully conformant and full-text searchable), or
 - **Binary (image, PDF, file)** → core `attach()` it onto the relevant typed note (`role=image` / `file`) — pass standard base64 with `encoding="base64"`; read back with `attach(noteId, title)`, which returns the base64 envelope and MIME.
 
-Create a standalone `type=code` / `file` note only when you specifically need Trilium's native handling of that type. If you do: label it (`add_label noteType <closest kind>`) so `recall` can see it, give it the same `domain` / `topic` labels as its anchor, and `connect` it to a typed note — otherwise it's an orphan with a blueprint-less type, exactly what `maintain(deep=true)` flags.
+Create a standalone `type=code` / `file` note only when you specifically need Trilium's native handling of that type. If you do: label it (`add_label noteType <closest kind>`) so `recall` can see it, give it the same `domain` / `topic` labels as its anchor, and `connect` it to a typed note — otherwise it's an untyped orphan, exactly what `maintain(deep=true)` flags.
 
 ### Use-case → tool
 

package/skills/brainllm/references/troubleshooting.md

@@ -47,4 +47,3 @@
 | `bootstrap` created a duplicate brain tree | Caused by a transient network/auth error during the existence check — the old catch-all fell through to fresh create. Fixed: only a confirmed 404 (root deleted) now triggers a new tree. To recover: identify the newer duplicate by `dateCreated`, then `forget(rootId, hard=true)` its entire subtree or delete it directly in Trilium. |
 | Hosted deploy: `ENOENT` on startup / auto-discovery fails with a file-path error | `BRAINLLM_CONFIG` is set to a directory path instead of a file path (e.g. `/home/node/trilium-data` instead of `/vol/brainllm.json`). Mount a persistent volume on the BrainLLM MCP service (not the Trilium service) and set `BRAINLLM_CONFIG` to a file path inside it, or remove `BRAINLLM_CONFIG` entirely to rely on auto-discovery each startup. |
 | `revise`/`remember` on a thread returns `collection_thread` | It is a collection thread: add entries with `remember(kind="threadEntry", thread=, title=)`, edit them with `revise(<entry id>)` |
-| `content is not standard RFC 4648 base64` on a text note | Fixed in V12.5: a blank MIME type is now text. On an older server, rewrite the note with `update_note_content(mime="text/html", encoding="text")` |