brainllm 12.6.4 → 12.7.0

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.6.4-f59e0b?style=flat-square)](https://github.com/miisodev/BrainLLM/releases)
+[![Version](https://img.shields.io/badge/version-12.7.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)
@@ -54,7 +54,7 @@ Placement, naming, labels, deduplication, relation bookkeeping, lifecycle aging,
 - **Timeless notes, dated records** — knowledge, information and thread books hold no state or history (only a domain's *Current State* does); `maintain(deep=true)` flags dated prose that creeps in. Every note except a log carries an icon, set by kind and backfilled by the sweep.
 - **Resilient plumbing** — every backend call is timeout-bounded with retry on idempotent reads; routine core writes are idempotent or duplicate-guarded, while full-mode raw overwrites remain explicit; content surgery survives the editor's own HTML rewriting; renaming a domain cascades to everything inside it; the maintenance sweep heals drift it finds.
 - **Multi-agent by default** — all write-classified tools serialize behind a process-wide FIFO lock, so two agents (an interactive session and an automated run, say) writing through one hosted instance queue in arrival order instead of racing; reads stay fully parallel. Deletion catch-up in the daily log keeps a note deleted after its day's close from vanishing without a trace — and its window is configurable (`deletionCatchupDays` in the lifecycle policy), defaulting to Trilium's 7-day retention.
-- **Ask in prose, split on a seam** — `consistency(subject="…")` finds every note asserting about a fact however it is phrased, no regex guessing; `consistency(pattern, staleAfterDays=N)` surfaces figures held in exactly one untouched note, the ones that rot silently because nothing disagrees with them; `read(ids=[…])` batches a multi-note orientation into one round trip; and `split(noteId, sections=[…], into="…")` is the write half of the oversized-note problem — it lifts whole sections into a new note and leaves a pointer back. Information notes can carry a `#mandate` marker so a scoped session finds the one note it must obey without reading every note's prose.
+- **Ask in prose, split on a seam** — `consistency(subject="…")` finds every note asserting about a fact however it is phrased, no regex guessing; `consistency(pattern, staleAfterDays=N)` surfaces figures held in exactly one untouched note, the ones that rot silently because nothing disagrees with them, and skips sessions and diaries, which are history rather than claims; `diff(since="today")` reviews every note a session changed in one call; `revise(find="Phase 2", within="tr")` edits, inserts or removes a table row named by a few words inside it; `read(ids=[…])` batches a multi-note orientation into one round trip; and `split(noteId, sections=[…], into="…")` is the write half of the oversized-note problem — it lifts whole sections into a new note and leaves a pointer back. Information notes can carry a `#mandate` marker so a scoped session finds the one note it must obey without reading every note's prose.
 
 ---
 

package/SECURITY.md

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

package/dist/index.js

@@ -20488,6 +20488,27 @@ function checkedDate(value) {
 function localNowTime() {
   return localNowDateTime().slice(11, 16);
 }
+function sinceCutoff(value) {
+  const v = value.trim().toLowerCase();
+  if (v === "today" || v === "session")
+    return `${localToday()} 00:00`;
+  const m = /^(\d{4}-\d{2}-\d{2})(?:[ t](\d{2}):(\d{2}))?$/.exec(v);
+  if (!m)
+    return null;
+  try {
+    checkedDate(m[1]);
+  } catch {
+    return null;
+  }
+  if (m[2] !== undefined && (Number(m[2]) > 23 || Number(m[3]) > 59))
+    return null;
+  return `${m[1]} ${m[2] ?? "00"}:${m[3] ?? "00"}`;
+}
+function rollingBackupName(date) {
+  const [y, m, d] = checkedDate(date).split("-").map(Number);
+  const day = new Date(Date.UTC(y, m - 1, d)).getUTCDay();
+  return `brainllm-${["sun", "mon", "tue", "wed", "thu", "fri", "sat"][day]}`;
+}
 
 // src/trilium.ts
 var MAX_ETAPI_CONTENT_BYTES = 50 * 1024 * 1024;
@@ -23894,6 +23915,134 @@ async function catchUpDeletions(trilium, cfg, today) {
   return { windowDays, coverage: "full", deletionsFound: total, regenerated };
 }
 
+// src/diffing.ts
+function revisionsSince(revisions, cutoff) {
+  return revisions.filter((r) => (r.dateCreated ?? "").slice(0, 16) >= cutoff);
+}
+function firstRevisionSince(revisions, cutoff) {
+  const since = revisionsSince(revisions, cutoff);
+  if (!since.length)
+    return null;
+  return since.reduce((a, b) => (a.dateCreated ?? "") <= (b.dateCreated ?? "") ? a : b);
+}
+function blockDiff(before, after, pad = 1, cap = 40) {
+  if (before === after)
+    return { identical: true, sizeBefore: before.length, sizeAfter: after.length, summary: "Identical: the writes left the body byte-for-byte as it was." };
+  const lines = (s) => s.replace(/></g, `>
+<`).split(`
+`);
+  const a = lines(before);
+  const b = lines(after);
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head])
+    head++;
+  let tail = 0;
+  while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail])
+    tail++;
+  const midA = a.slice(head, a.length - tail);
+  const midB = b.slice(head, b.length - tail);
+  const lcs = changedLines(midA, midB);
+  const removed = lcs ? lcs.removed : midA;
+  const added = lcs ? lcs.added : midB;
+  const bound = (arr) => arr.length > cap ? [...arr.slice(0, cap), `\u2026 ${arr.length - cap} more line(s)`] : arr;
+  const delta = after.length - before.length;
+  return {
+    identical: false,
+    sizeBefore: before.length,
+    sizeAfter: after.length,
+    contextBefore: bound(a.slice(Math.max(0, head - pad), head)),
+    removed: bound(removed),
+    added: bound(added),
+    contextAfter: bound(a.slice(a.length - tail, a.length - tail + pad)),
+    summary: `${lcs ? `${lcs.hunks} change(s): ` : ""}${removed.length} block(s) removed, ${added.length} added, ${delta >= 0 ? "+" : ""}${delta} characters.`
+  };
+}
+function changedLines(a, b, budget = 4000000) {
+  const n = a.length;
+  const m = b.length;
+  if ((n + 1) * (m + 1) > budget)
+    return null;
+  const w = m + 1;
+  const t = new Uint32Array((n + 1) * w);
+  for (let i = n - 1;i >= 0; i--)
+    for (let j = m - 1;j >= 0; j--)
+      t[i * w + j] = a[i] === b[j] ? t[(i + 1) * w + j + 1] + 1 : Math.max(t[(i + 1) * w + j], t[i * w + j + 1]);
+  const removed = [];
+  const added = [];
+  let hunks = 0;
+  let inHunk = false;
+  let i = 0;
+  let j = 0;
+  while (i < n || j < m) {
+    if (i < n && j < m && a[i] === b[j]) {
+      inHunk = false;
+      i++;
+      j++;
+      continue;
+    }
+    if (!inHunk) {
+      hunks++;
+      inHunk = true;
+    }
+    if (j >= m || i < n && t[(i + 1) * w + j] >= t[i * w + j + 1])
+      removed.push(a[i++]);
+    else
+      added.push(b[j++]);
+  }
+  return { removed, added, hunks };
+}
+
+// src/elements.ts
+var WITHIN_TAGS = ["tr", "td", "th", "li", "p", "blockquote", "figure", "table", "ul", "ol"];
+function elementSpans(html, tag) {
+  const rx = new RegExp(`<(/?)${tag}(?=[\\s>/])[^>]*>`, "gi");
+  const spans = [];
+  const open = [];
+  let m;
+  while ((m = rx.exec(html)) !== null) {
+    if (m[1] === "/") {
+      const start = open.pop();
+      if (start !== undefined)
+        spans.push({ start, end: m.index + m[0].length });
+    } else if (!m[0].endsWith("/>")) {
+      open.push(m.index);
+    }
+  }
+  return spans.sort((a, b) => a.start - b.start);
+}
+function containingElement(html, tag, from, to) {
+  let best = null;
+  for (const s of elementSpans(html, tag)) {
+    if (s.start <= from && s.end >= to && (!best || s.end - s.start < best.end - best.start))
+      best = s;
+  }
+  return best;
+}
+function editWithin(html, hits, tag, action, body, nth) {
+  if (!hits.length)
+    return { ok: false, reason: "no_match", matches: 0 };
+  const seen = new Map;
+  for (const h of hits) {
+    const el = containingElement(html, tag, h.start, h.start + h.length);
+    if (el)
+      seen.set(el.start, el);
+  }
+  const elements = [...seen.values()].sort((a, b) => a.start - b.start);
+  if (!elements.length)
+    return { ok: false, reason: "no_element", matches: hits.length };
+  const preview = (s) => html.slice(s.start, Math.min(s.end, s.start + 160));
+  let target;
+  if (nth !== undefined)
+    target = elements[nth - 1];
+  else if (elements.length === 1)
+    target = elements[0];
+  if (!target)
+    return { ok: false, reason: "ambiguous", matches: elements.length, elements: elements.slice(0, 10).map(preview) };
+  const el = html.slice(target.start, target.end);
+  const out = action === "replace" ? html.slice(0, target.start) + body + html.slice(target.end) : action === "remove" ? html.slice(0, target.start) + html.slice(target.end) : action === "before" ? html.slice(0, target.start) + body + html.slice(target.start) : html.slice(0, target.end) + body + html.slice(target.end);
+  return { ok: true, html: out, element: el, matches: elements.length };
+}
+
 // src/tools-surface.ts
 var txt = (obj) => ({
   content: [{ type: "text", text: typeof obj === "string" ? obj : JSON.stringify(obj, null, 2) }]
@@ -24062,13 +24211,15 @@ Resolution plus an index of its [yyyy-mm-dd] children (newest first: the latest
 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.`, {
+section="<heading>" reads one section. index=true on a dated thread returns only child ids,
+dates and block markers (no book body, no leads): the cheap answer to "what is the newest entry".`, {
     ...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)"),
+    index: booleanType().optional().describe("Dated threads: ids, dates and block markers only \u2014 no book body, no block leads"),
     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: idArg, noteId, date, limit, section, occurrence }) => {
+  }, async ({ id: idArg, noteId, date, limit, index, section, occurrence }) => {
     const id = idArg ?? noteId;
     if (!id)
       return missingId("memory");
@@ -24101,6 +24252,21 @@ section="<heading>" reads one section.`, {
       orderBy: "dateCreated",
       orderDirection: "desc"
     }).catch(() => ({ results: [] }));
+    if (index) {
+      const compact = await Promise.all(children.results.map(async (c) => ({
+        id: c.noteId,
+        date: labelOf(c, "created") ?? c.dateCreated.slice(0, 10),
+        blocks: addendumIndex(await trilium.getNoteContent(c.noteId).catch(() => "")).map(({ marker, identity }) => ({ marker, identity }))
+      })));
+      return txt({
+        id,
+        title: note.title,
+        kind: "thread",
+        totalChildren,
+        children: compact,
+        ...totalChildren > compact.length ? { more: `Showing the newest ${compact.length} of ${totalChildren}. Pass limit= for more.` } : {}
+      });
+    }
     const indexed = await Promise.all(children.results.map(async (c) => {
       const content = await trilium.getNoteContent(c.noteId).catch(() => "");
       const blocks = addendumIndex(content);
@@ -24300,6 +24466,12 @@ function registerTools(server, trilium, brainRef) {
     preCloseSeq = 0;
   };
   const RECORD_KINDS = new Set(["session", "diary", "log", "threadEntry"]);
+  const isRecordNote = (n) => {
+    const kind = ownedLabel(n, "noteType");
+    if (kind === "session" || kind === "diary" || kind === "log")
+      return true;
+    return kind === "threadEntry" && /^\[\d{4}-\d{2}-\d{2}\]$/.test(n.title.trim());
+  };
   const structuralFindings = (kind, html) => {
     if (!html || kind && RECORD_KINDS.has(kind))
       return {};
@@ -24678,7 +24850,7 @@ ${contentBlock}` }));
         await trilium.addRelation(logReport.noteId, "references", noteId).catch(() => null);
     }
     let backupStatus = "disabled";
-    let backupName = `brainllm-${d}`;
+    let backupName = rollingBackupName(d);
     if (backup !== false) {
       try {
         await trilium.createBackup(backupName);
@@ -24702,11 +24874,11 @@ ${contentBlock}` }));
       ...warnings.length ? { sanitized: warnings } : {}
     });
   });
-  server.tool("backup", `Named database snapshot. close() already backs up; use this before a large restructure.`, {
-    name: stringType().optional().describe("Backup name without extension (default: brainllm-{today}). Use a descriptive name for milestones.")
+  server.tool("backup", `Named database snapshot. close() already backs up into a rolling weekday slot (brainllm-mon \u2026 brainllm-sun, overwritten weekly); use this before a large restructure. A named backup is kept until someone deletes it on the server, so name milestones sparingly: every one is a full copy of the database on Trilium's volume.`, {
+    name: stringType().optional().describe("Backup name without extension (default: today's rolling slot, e.g. brainllm-thu). A descriptive name keeps a milestone.")
   }, async ({ name }) => {
     const d = today();
-    const backupName = name ?? `brainllm-${d}`;
+    const backupName = name ?? rollingBackupName(d);
     try {
       await trilium.createBackup(backupName);
       return txt3({ ok: true, backup: backupName, backupStatus: "completed", date: d });
@@ -24768,7 +24940,7 @@ Kinds: biography | goals | preferences | responsibilities | protocols (singleton
 Collection kinds dedup by title \u2014 mustCreate=true refuses instead of adopting an existing note, and check action= on the receipt. connect=[{relation, toNoteId}] wires relations in the same call. diary/session/log/claim/domain have dedicated paths.`, {
     kind: enumType(Kinds).describe("What kind of memory this is"),
     title: stringType().optional().describe("Title \u2014 collection kinds (thread/knowledge/information sub-category); ignored for singletons & sources"),
-    body: stringType().optional().describe("Content: plain text, markdown, or HTML"),
+    body: stringType().optional().describe("Content: plain text, markdown, or HTML. Send real tags: entity-escaped markup (&lt;p&gt;) is decoded and reported in sanitized[]"),
     goal: stringType().optional().describe("thread creation: the goal statement \u2014 REQUIRED for a new thread (query the user for it); becomes the Context \u2192 Goal section"),
     shape: enumType(["dated", "collection"]).optional().describe('thread creation: "dated" (default \u2014 one [yyyy-mm-dd] child per active day) or "collection" (one titled child per item, e.g. an ideas list)'),
     thread: stringType().optional().describe(`kind="threadEntry" only: the collection thread's id \u2014 adds a titled child to it`),
@@ -25181,7 +25353,8 @@ ${block}`), d);
       const notes = [
         rejected ? `${rejected} backend candidate(s) did not actually match the pattern and were dropped \u2014 results are verified against the real regex, not just the search index.` : null,
         tagSpanning ? `${tagSpanning} match(es) were found only after stripping markup \u2014 the phrase is split by an inline tag there.` : null,
-        results.length === 0 ? "No bodies matched that pattern, searched both as stored HTML and tag-stripped. Note that Trilium's %= pre-filter reads a striptags'd copy, so a pattern anchored ON tags may never reach verification \u2014 consistency() scans exhaustively if you need certainty." : null
+        results.length === 0 ? "No bodies matched that pattern, searched both as stored HTML and tag-stripped. Note that Trilium's %= pre-filter reads a striptags'd copy, so a pattern anchored ON tags may never reach verification \u2014 consistency() scans exhaustively if you need certainty." : null,
+        results.length === 0 && regex.includes("\\") ? `The pattern reached the server as /${regex}/i. In it, \\d is a digit and \\\\ is one literal backslash (a Windows path separator); a backslash doubled once too often matches a literal backslash instead of escaping. If that is not the pattern you meant, adjust the escaping and retry.` : null
       ].filter(Boolean);
       return txt3({
         mode: "regex",
@@ -25258,7 +25431,13 @@ ${block}`), d);
   }, async ({ name, includeArchived }) => {
     const cfg = b();
     const slug = slugify(name);
-    const runIn = (ancestor, q) => ancestor ? trilium.searchNotes(q, { ancestorNoteId: ancestor, limit: 100, fastSearch: true, includeArchivedNotes: includeArchived ?? false }).then((r) => r.results).catch(() => []) : Promise.resolve([]);
+    const CAP = 500;
+    let capped = false;
+    const runIn = (ancestor, q, archived = includeArchived ?? false) => ancestor ? trilium.searchNotes(q, { ancestorNoteId: ancestor, limit: CAP, fastSearch: true, includeArchivedNotes: archived }).then((r) => {
+      if (r.results.length >= CAP)
+        capped = true;
+      return r.results;
+    }).catch(() => []) : Promise.resolve([]);
     const [domainContainers, byTopic, byDomain] = await Promise.all([
       runIn(cfg.knowledge.domains, `#noteType=domain #domain='${slug}'`),
       runIn(cfg.root, `#topic='${slug}'`),
@@ -25306,11 +25485,24 @@ ${block}`), d);
       const k = ownedLabel(n, "noteType");
       return k && k !== "domain";
     }).length;
+    let archivedOmitted = 0;
+    if (!includeArchived) {
+      const [archTopic, archDomain] = await Promise.all([runIn(cfg.root, `#topic='${slug}'`, true), runIn(cfg.root, `#domain='${slug}'`, true)]);
+      const extra = new Set;
+      for (const n of [...archTopic, ...archDomain]) {
+        const k = ownedLabel(n, "noteType");
+        if (k && k !== "domain" && !seen.has(n.noteId))
+          extra.add(n.noteId);
+      }
+      archivedOmitted = extra.size;
+    }
     return txt3({
       domain: name,
       slug,
       knowledgeDomain,
       total,
+      ...archivedOmitted ? { archivedOmitted, archivedNote: `${archivedOmitted} archived note(s) carry this slug and are not listed; includeArchived=true shows them.` } : {},
+      ...capped ? { truncated: `A query hit its ${CAP}-note cap, so some notes may be missing; narrow with recall(domain=) or maintain(domain=).` } : {},
       ...staleCount ? { stale: `${staleCount} note(s) untouched ${staleAfter}d+ \u2014 marked stale:true below; re-verify against live sources before treating them as current` } : {},
       groups,
       ...total === 0 && !knowledgeDomain ? { note: `No content found for "${slug}". Create a Knowledge domain with remember(kind="information", domain="${name}") or tag notes with topics=["${slug}"].` } : {}
@@ -25340,18 +25532,19 @@ ${block}`), d);
   });
   server.tool("revise", `Edit a note by id. A revision is taken first; "Last updated" lines are bumped on content writes.
 
-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.
+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. find= + within="tr" (or li, p, td, \u2026) acts on the element containing a short anchor: replace it, insert a row before/after it, or remove it, so a table row never needs its full stored markup. A replacement equal to its match writes nothing and reports unchanged. 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, 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)."),
+    body: stringType().optional().describe("Content to add/replace: plain text, markdown, or HTML. Send real tags: entity-escaped markup (&lt;p&gt;) is decoded and reported in sanitized[]. With find=, the raw replacement string (no conversion)."),
     title: stringType().optional().describe("New title (normalized server-side)"),
     section: stringType().optional().describe("Target a section by heading text (h2/h3/h4, in that order); omit for whole-note append/replace"),
     occurrence: numberType().int().positive().optional().describe("section=: which same-text heading to target, 1-based (default: the first). Read them with outline(noteId)."),
     strict: booleanType().optional().describe("Refuse (note untouched) on a section= miss or a body needing structural repair, instead of writing a new section"),
     mode: enumType(["append", "replace", "before", "after", "prepend", "remove"]).optional().describe("append (default) | replace | before | after (around the whole section=) | prepend (top of its body) | remove (delete section=, no body needed)"),
     find: stringType().optional().describe("Exact raw string to replace throughout the body with body= \u2014 targeted surgery without a read+full-replace. Takes precedence over section/mode."),
-    nth: numberType().int().positive().optional().describe("find=: replace only the Nth occurrence, 1-based (default: all of them)"),
+    nth: numberType().int().positive().optional().describe("find=: replace only the Nth occurrence, 1-based (default: all of them). With within=: the Nth containing element"),
+    within: enumType(WITHIN_TAGS).optional().describe('With find=: act on the <tag> element that contains the find text (a short unique anchor) \u2014 mode="replace" (default) swaps it for body=, "before"/"after" insert body= as a sibling (add a table row), "remove" deletes it'),
     edits: arrayType(objectType({
       find: stringType().describe("Exact raw string to replace"),
       body: stringType().describe("Raw replacement string"),
@@ -25360,9 +25553,11 @@ Check the receipt: matched=false means a NEW section was written (available= lis
     identity: stringType().optional().describe('Appending to a dated thread: the identification line "LLM \xB7 environment \xB7 agent/mode [\xB7 Run N]" (required)'),
     icon: stringType().optional().describe('Display icon \u2014 a boxicons class ("bx bx-brain") or a bare name; normalized server-side'),
     date: stringType().optional().describe("ISO date (default: today)")
-  }, async ({ noteId, body, title, section, occurrence, mode, find, nth, edits, identity, icon, date, strict }) => {
+  }, async ({ noteId, body, title, section, occurrence, mode, find, nth, within, edits, identity, icon, date, strict }) => {
     if (isContainer(b(), noteId))
       return err("protected_note", `Note ${noteId} is a container \u2014 its content cannot be edited directly.`, "Use remember() to write to singletons, or specify a content note id.");
+    if (within && find === undefined)
+      return err("missing_param", "within= needs find= as its anchor.", 'Pass a short text unique to the element, e.g. revise(noteId, find="Phase 2", within="tr", body="<tr>\u2026</tr>").');
     const d = checkedDate(date);
     const note = await trilium.getNote(noteId);
     const noteKind = labelOf2(note, "noteType");
@@ -25402,7 +25597,7 @@ Check the receipt: matched=false means a NEW section was written (available= lis
       for (const [i, e] of plan.entries()) {
         if (!e.find)
           return err("missing_param", `edits[${i}].find cannot be empty.`, 'Pass the exact text to replace, e.g. revise(noteId, find="Brainllm", body="BrainLLM").');
-        if (e.body === undefined)
+        if (e.body === undefined && !within)
           return err("missing_param", `edits[${i}] requires body as the replacement string.`, 'Call revise(noteId, find="<exact text>", body="<replacement>").');
       }
       const applyEdit = (source, needle, replacement, index) => {
@@ -25451,6 +25646,59 @@ Check the receipt: matched=false means a NEW section was written (available= lis
         return near ? { matchedUpTo: near.fragment, storedNearby: near.context } : {};
       };
       const current = await trilium.getNoteContent(noteId);
+      if (within) {
+        if (edits !== undefined)
+          return err("conflicting_params", "within= works with a single find=, not edits=.", "Make one revise() call per element.");
+        const action = mode === "before" || mode === "after" || mode === "remove" ? mode : mode === undefined || mode === "replace" ? "replace" : null;
+        if (!action)
+          return err("invalid_mode", `mode="${mode}" does not apply to within=.`, 'Use mode="replace" (default), "before", "after" or "remove".');
+        if (action !== "remove" && body === undefined)
+          return err("missing_param", `within= with mode="${action}" needs body= (the raw element HTML).`, `e.g. revise(noteId, find="Phase 2", within="tr", mode="after", body="<tr><td>\u2026</td></tr>")`);
+        const exact = [];
+        for (let at = current.indexOf(find);at !== -1; at = current.indexOf(find, at + find.length))
+          exact.push({ start: at, length: find.length });
+        const rx = exact.length ? null : tolerantFindRegex(find);
+        const hits = exact.length ? exact : rx ? [...current.matchAll(rx)].map((m) => ({ start: m.index, length: m[0].length })) : [];
+        const res = editWithin(current, hits, within, action, body ?? "", nth);
+        if (!res.ok) {
+          const hint = res.reason === "no_match" ? missHint(find, current, false) : res.reason === "no_element" ? `The anchor matched ${res.matches} time(s), but never inside a <${within}>. Check the tag, or drop within= to edit the text itself.` : `The anchor sits in ${res.matches} different <${within}> elements. Lengthen it until it is unique, or pass nth= (1-based, in document order) \u2014 elements[] previews them.`;
+          return txt3({
+            ok: false,
+            noteId,
+            mode: `within:${within}:${action}`,
+            replaced: 0,
+            date: d,
+            reason: res.reason,
+            hint,
+            ...res.elements ? { elements: res.elements } : {},
+            ...res.reason === "no_match" ? missContext(find, current) : {}
+          });
+        }
+        if (res.html === current)
+          return txt3({ ok: true, noteId, mode: `within:${within}:${action}`, unchanged: true, date: d, note: "The body equals the element it would replace, so nothing was written and no revision was taken." });
+        await trilium.createRevision(noteId).catch(() => null);
+        const withinResult = sanitizeHtml(res.html);
+        const stampedWithin = bumpLastUpdated(withinResult.html, d);
+        await trilium.updateNoteContent(noteId, stampedWithin.html);
+        const titledWithin = await applyTitle();
+        const iconWithin = await applyIcon(noteId, icon);
+        await trilium.updateLabelValue(noteId, "updated", d);
+        if (labelOf2(note, "status") === "dormant")
+          await trilium.updateLabelValue(noteId, "status", "active");
+        const relsWithin = relationSnippet(note);
+        return txt3({
+          ok: true,
+          noteId,
+          mode: `within:${within}:${action}`,
+          date: d,
+          element: toText(res.element, 200),
+          ...titledWithin.retitled ? { retitled: titledWithin.retitled } : {},
+          ...iconWithin ? { icon: iconWithin } : {},
+          ...relsWithin ? { relations: relsWithin } : {},
+          ...structuralFindings(noteKind, stampedWithin.html),
+          ...withinResult.warnings.length ? { sanitized: withinResult.warnings } : {}
+        });
+      }
       let working = current;
       const results = [];
       let total = 0;
@@ -25486,6 +25734,22 @@ Check the receipt: matched=false means a NEW section was written (available= lis
           }
         });
       }
+      if (working === current) {
+        const titledNoop = await applyTitle();
+        const iconNoop = await applyIcon(noteId, icon);
+        return txt3({
+          ok: true,
+          noteId,
+          mode: edits ? "edits" : "find-replace",
+          replaced: 0,
+          unchanged: true,
+          date: d,
+          ...edits ? { results } : { matchMode: results[0].matchMode },
+          ...titledNoop.retitled ? { retitled: titledNoop.retitled } : {},
+          ...iconNoop ? { icon: iconNoop } : {},
+          note: "Every match already equals its replacement, so the body was not written and no revision was taken."
+        });
+      }
       await trilium.createRevision(noteId).catch(() => null);
       const replacedResult = sanitizeHtml(working);
       const stamped = bumpLastUpdated(replacedResult.html, d);
@@ -25913,16 +26177,32 @@ calling twice is safe. Use remove=true to delete an edge.`, {
       }
     }
   });
-  server.tool("consistency", `Does the brain agree with itself? pattern= is a regex with ONE capture group naming the value that should match across notes, e.g. "(\\\\d+) mailboxes"; the result groups every asserting note by value with agreement unanimous or DISAGREEMENT. subject="<fact in prose>" finds notes asserting about a subject however phrased. staleAfterDays=N also reports values held in exactly one note untouched N+ days. Matches stored HTML and tag-stripped text; escape backslashes; scope with domain=/kinds=. Scans every in-scope note (fast=true uses Trilium's lossy pre-filter). Run it after correcting any fact recorded in more than one place.`, {
+  server.tool("consistency", `Does the brain agree with itself? pattern= is a regex with ONE capture group naming the value that should match across notes, e.g. "(\\\\d+) mailboxes"; the result groups every asserting note by value with agreement unanimous or DISAGREEMENT. subject="<fact in prose>" finds notes asserting about a subject however phrased. staleAfterDays=N also reports values held in exactly one note untouched N+ days. Matches stored HTML and tag-stripped text; escape backslashes; scope with domain=/kinds=. Records (sessions, diary, logs, dated thread entries) are skipped by default because they are never rewritten; includeRecords=true or a kinds= naming them brings them back. Scans every in-scope note (fast=true uses Trilium's lossy pre-filter). Run it after correcting any fact recorded in more than one place.`, {
     pattern: stringType().optional().describe("Regex over note bodies. One capture group = the value that should agree across notes. Omit when using subject= (prose mode)."),
     subject: stringType().optional().describe("A fact in prose \u2014 returns notes asserting about it however phrased (instead of pattern=)"),
     staleAfterDays: numberType().optional().describe("With pattern: also report values held in exactly one note untouched N+ days (staleSingles)"),
     domain: stringType().optional().describe("Restrict to one knowledge domain"),
-    kinds: arrayType(enumType(Kinds)).optional().describe("Restrict to these kinds"),
+    kinds: arrayType(enumType(Kinds)).optional().describe("Restrict to these kinds. Naming a record kind (session, diary, log, threadEntry) includes those records"),
+    includeRecords: booleanType().optional().describe("Also match records: sessions, diary, logs and dated thread entries (default false: they are history, never rewritten)"),
     includeArchived: booleanType().optional().describe("Include archived notes (default false)"),
     limit: numberType().optional().describe("Max notes to examine (default 60)"),
     fast: booleanType().optional().describe("Use Trilium's faster but lossy %= pre-filter (default: scan every in-scope note)")
-  }, async ({ pattern, subject, staleAfterDays, domain, kinds, includeArchived, limit, fast }) => {
+  }, async ({ pattern, subject, staleAfterDays, domain, kinds, includeRecords, includeArchived, limit, fast }) => {
+    const wantsRecords = includeRecords === true || (kinds ?? []).some((k) => RECORD_KINDS.has(k));
+    let recordsSkipped = 0;
+    const inScope = (n) => {
+      const kind = ownedLabel(n, "noteType");
+      if (!kind)
+        return false;
+      if (kinds?.length && !kinds.includes(kind))
+        return false;
+      if (!wantsRecords && isRecordNote(n)) {
+        recordsSkipped++;
+        return false;
+      }
+      return true;
+    };
+    const recordsNote = () => recordsSkipped ? { recordsSkipped, recordsNote: `${recordsSkipped} record(s) (sessions, diary, logs, dated thread entries) were skipped: they are never rewritten. includeRecords=true matches them too.` } : {};
     if (!pattern && !subject)
       return err("missing_param", "consistency() needs either a regex pattern or a prose subject.", 'Pass pattern="(\\\\d+) users" to compare a captured value, or subject="<a fact in prose>" to find every note asserting about that subject however phrased.');
     if (subject && !pattern) {
@@ -25933,13 +26213,8 @@ calling twice is safe. Use remove=true to delete an edge.`, {
       const clauses = ["#noteType"];
       if (domain)
         clauses.push(`#domain='${slugify(domain)}'`);
-      const notes = await trilium.searchNotes(clauses.join(" AND "), { ancestorNoteId: b().root, limit: max, includeArchivedNotes: includeArchived ?? false }).then((r) => r.results).catch(() => []);
-      const scoped = notes.filter((n) => {
-        const kind = ownedLabel(n, "noteType");
-        if (!kind)
-          return false;
-        return !kinds?.length || kinds.includes(kind);
-      });
+      const notes = await trilium.searchNotes(clauses.join(" AND "), { ancestorNoteId: b().root, limit: wantsRecords ? max : max * 4, includeArchivedNotes: includeArchived ?? false }).then((r) => r.results).catch(() => []);
+      const scoped = notes.filter(inScope).slice(0, max);
       const threshold = Math.max(1, Math.ceil(tokens.length / 2));
       const hits = [];
       for (const n of scoped) {
@@ -25961,6 +26236,7 @@ calling twice is safe. Use remove=true to delete an edge.`, {
         notes: hits,
         total: hits.length,
         ...domain ? { domain: slugify(domain) } : {},
+        ...recordsNote(),
         note: hits.length ? `${hits.length} note(s) assert something about "${subject}". Open each to read the claim \u2014 or narrow with domain= / kinds=.` : `No note in scope matched ${threshold}+ of the subject's tokens. That is evidence about the phrasing, not the brain \u2014 this mode is deliberately phrase-agnostic, so if you expected a hit, the fact may not be recorded here at all.`
       });
     }
@@ -25976,13 +26252,8 @@ calling twice is safe. Use remove=true to delete an edge.`, {
     const clauses = fast ? [`note.content %= '${escapeQueryRegex(pattern)}'`] : ["#noteType"];
     if (domain)
       clauses.push(`#domain='${slugify(domain)}'`);
-    const notes = await trilium.searchNotes(clauses.join(" AND "), { ancestorNoteId: b().root, limit: max, includeArchivedNotes: includeArchived ?? false }).then((r) => r.results).catch(() => []);
-    const scoped = notes.filter((n) => {
-      const kind = ownedLabel(n, "noteType");
-      if (!kind)
-        return false;
-      return !kinds?.length || kinds.includes(kind);
-    });
+    const notes = await trilium.searchNotes(clauses.join(" AND "), { ancestorNoteId: b().root, limit: wantsRecords ? max : max * 4, includeArchivedNotes: includeArchived ?? false }).then((r) => r.results).catch(() => []);
+    const scoped = notes.filter(inScope).slice(0, max);
     const byValue = new Map;
     const noCapture = [];
     let hasCaptureGroup = false;
@@ -26031,6 +26302,7 @@ calling twice is safe. Use remove=true to delete an edge.`, {
         pattern,
         scan: fast ? "fast (%= pre-filter)" : "exhaustive",
         notesExamined: scoped.length,
+        ...recordsNote(),
         notes: noCapture,
         total: noCapture.length,
         note: noCapture.length === 0 ? `No note body matched that pattern across ${scoped.length} note(s), searched both as stored HTML and tag-stripped.${fast ? " fast=true used Trilium's %= pre-filter, which reads a striptags'd copy and can drop notes \u2014 re-run without it before concluding anything." : " That is evidence about the pattern, not the brain."}` : 'The pattern has no capture group, so this is a presence check only. Add one \u2014 consistency("(\\\\d+) users") \u2014 to compare the values these notes actually assert.'
@@ -26045,6 +26317,7 @@ calling twice is safe. Use remove=true to delete an edge.`, {
       scan: fast ? "fast (%= pre-filter)" : "exhaustive",
       ...domain ? { domain: slugify(domain) } : {},
       notesExamined: scoped.length,
+      ...recordsNote(),
       ...tagSpanning ? { tagSpanning, tagSpanningNote: `${tagSpanning} note(s) matched only once markup was stripped \u2014 the phrase is split by an inline tag there. Before v10.3 those were invisible.` } : {},
       distinctValues: groups.length,
       agreement: groups.length === 0 ? "no-data" : agrees ? "unanimous" : "DISAGREEMENT",
@@ -26329,11 +26602,58 @@ assertion + check \u2192 register (deduped by assertion); claimId + holds + evid
       ...all.length === 0 ? { note: 'No claims registered. Register one with claim(assertion="\u2026", check="\u2026") \u2014 the assertions worth registering are the ones that would be expensive to discover had gone stale.' } : {}
     });
   });
-  server.tool("diff", `What a write actually changed: a revision snapshot (default the latest) against the note as it stands, as changed lines with context and added/removed counts. The revision list comes back on every call; pass revisionId to compare against an earlier one.`, {
-    noteId: stringType().describe("Note to diff"),
+  server.tool("diff", `What a write actually changed: a revision snapshot (default the latest) against the note as it stands, as changed lines with context and added/removed counts. The revision list comes back on every call; pass revisionId to compare against an earlier one. since="today" (or a date, or "YYYY-MM-DD HH:mm") reviews everything changed since then in one call: with noteId, that note's net change across all its writes since; without, every maintained note changed since, each diffed against its state before the first of those writes. Run it before close to check today's corrections agree with each other.`, {
+    noteId: stringType().optional().describe("Note to diff (omit with since= to review every note changed since then)"),
     revisionId: stringType().optional().describe("Compare against this revision (default: the most recent one)"),
+    since: stringType().optional().describe('"today", a date (YYYY-MM-DD) or a local datetime (YYYY-MM-DD HH:mm): the net change since then, across all writes'),
+    includeRecords: booleanType().optional().describe("since= without noteId: also list records (sessions, diary, logs, dated thread entries), which only ever gain addenda (default false)"),
+    limit: numberType().int().min(1).max(50).optional().describe("since= without noteId: max notes to diff (default 25)"),
     context: numberType().int().min(0).max(10).optional().describe("Unchanged lines to show around each change (default: 1)")
-  }, async ({ noteId, revisionId, context }) => {
+  }, async ({ noteId, revisionId, since, includeRecords, limit, context }) => {
+    const pad = context ?? 1;
+    if (since !== undefined) {
+      const cutoff = sinceCutoff(since);
+      if (!cutoff)
+        return err("invalid_since", `since="${since}" is not "today", a date or a local datetime.`, 'Pass since="today", since="2026-10-01" or since="2026-10-01 14:30".');
+      if (noteId) {
+        const revisions = await trilium.getNoteRevisions(noteId).catch(() => []);
+        const after = await trilium.getNoteContent(noteId).catch(() => null);
+        if (after === null)
+          return err("not_found", `Note ${noteId} not found.`, "Check the id with brain() or recall().");
+        const first = firstRevisionSince(revisions, cutoff);
+        if (!first)
+          return txt3({ noteId, since: cutoff, changed: false, note: `No content write to this note since ${cutoff} (no revision was taken after it).` });
+        const before = await trilium.getRevisionContent(first.revisionId);
+        return txt3({ noteId, since: cutoff, writes: revisionsSince(revisions, cutoff).length, comparedTo: first.revisionId, ...blockDiff(before, after, pad) });
+      }
+      const changed = await trilium.searchNotes(`#noteType note.dateModified >= '${cutoff}'`, { ancestorNoteId: b().root, limit: 200, orderBy: "dateModified", orderDirection: "desc" }).then((r) => r.results).catch(() => []);
+      const maintained = includeRecords ? changed : changed.filter((n) => !isRecordNote(n));
+      const max = limit ?? 25;
+      const notes = [];
+      for (const n of maintained.slice(0, max)) {
+        const stub = { id: n.noteId, title: n.title, kind: ownedLabel(n, "noteType") ?? "" };
+        const revisions = await trilium.getNoteRevisions(n.noteId).catch(() => []);
+        const first = firstRevisionSince(revisions, cutoff);
+        if (!first) {
+          notes.push({ ...stub, ...n.dateCreated >= cutoff ? { created: true } : { note: "Changed without a content revision (attributes or title only)." } });
+          continue;
+        }
+        const [before, after] = await Promise.all([trilium.getRevisionContent(first.revisionId), trilium.getNoteContent(n.noteId)]);
+        const d = blockDiff(before, after, pad, 12);
+        notes.push({ ...stub, writes: revisionsSince(revisions, cutoff).length, ...d.identical ? { identical: true } : { summary: d.summary, removed: d.removed, added: d.added } });
+      }
+      const recordsSkipped = changed.length - maintained.length;
+      return txt3({
+        since: cutoff,
+        notesChanged: maintained.length,
+        ...maintained.length > max ? { shown: max, more: `${maintained.length - max} more; raise limit= or diff one note with noteId=.` } : {},
+        ...recordsSkipped ? { recordsSkipped, recordsNote: "Records only gain dated addenda; includeRecords=true lists them too." } : {},
+        notes,
+        note: maintained.length ? "Each note is diffed from its state before its first write since the cutoff. Check the changes agree with each other, and run consistency() on any fact you changed in more than one note." : `No maintained note changed since ${cutoff}.`
+      });
+    }
+    if (!noteId)
+      return err("missing_param", "diff() needs noteId=, since=, or both.", `Pass noteId= for one note's last write, or since="today" to review everything changed today.`);
     const revisions = await trilium.getNoteRevisions(noteId).catch(() => []);
     if (!revisions.length)
       return txt3({ noteId, note: "No revisions \u2014 this note has not been written through a content-mutating tool yet, or its revisions have been pruned.", revisions: [] });
@@ -26359,33 +26679,11 @@ assertion + check \u2192 register (deduped by assertion); claimId + holds + evid
         note: "The snapshot and the current body are byte-identical \u2014 the write after this revision changed nothing, or the revision was taken after it."
       });
     }
-    const lines = (s) => s.replace(/></g, `>
-<`).split(`
-`);
-    const a = lines(before);
-    const bLines = lines(after);
-    let head = 0;
-    while (head < a.length && head < bLines.length && a[head] === bLines[head])
-      head++;
-    let tail = 0;
-    while (tail < a.length - head && tail < bLines.length - head && a[a.length - 1 - tail] === bLines[bLines.length - 1 - tail])
-      tail++;
-    const pad = context ?? 1;
-    const removed = a.slice(head, a.length - tail);
-    const added = bLines.slice(head, bLines.length - tail);
-    const cap = (arr) => arr.length > 40 ? [...arr.slice(0, 40), `\u2026 ${arr.length - 40} more line(s)`] : arr;
     return txt3({
       noteId,
       comparedTo: target.revisionId,
       revisionDate: target.dateCreated?.slice(0, 16),
-      identical: false,
-      sizeBefore: before.length,
-      sizeAfter: after.length,
-      contextBefore: cap(a.slice(Math.max(0, head - pad), head)),
-      removed: cap(removed),
-      added: cap(added),
-      contextAfter: cap(a.slice(a.length - tail, a.length - tail + pad)),
-      summary: `${removed.length} block(s) removed, ${added.length} added, ${after.length - before.length >= 0 ? "+" : ""}${after.length - before.length} characters.`,
+      ...blockDiff(before, after, pad),
       revisions: index
     });
   });
@@ -27660,10 +27958,10 @@ note.dateModified >= 'YYYY-MM-DD', AND/OR. Unscoped unless ancestorNoteId is giv
   server.tool("get_inbox_note", "Get the Trilium inbox note for a date (fixed #inbox note, or the day note). Format: YYYY-MM-DD.", { date: stringType().optional() }, async ({ date }) => txt4(await trilium.getInboxNote(date ?? localToday())));
   server.tool("get_app_info", "Trilium server version, DB version, runtime metadata.", {}, async () => txt4(await trilium.getAppInfo()));
   server.tool("create_backup", `Named Trilium database backup (raw). The resulting file path is not exposed.`, {
-    name: stringType().optional().describe("Backup file name without .db extension (default: brainllm-{today})"),
-    date: stringType().optional().describe("ISO date used in the default name when name is omitted (default: today)")
+    name: stringType().optional().describe("Backup file name without .db extension (default: the date's rolling weekday slot, e.g. brainllm-thu)"),
+    date: stringType().optional().describe("ISO date whose weekday slot is used when name is omitted (default: today)")
   }, async ({ name, date }) => {
-    const backupName = name ?? `brainllm-${date ?? localToday()}`;
+    const backupName = name ?? rollingBackupName(date ?? localToday());
     try {
       await trilium.createBackup(backupName);
       return txt4({ ok: true, backup: backupName, backupStatus: "completed" });
@@ -28843,7 +29141,7 @@ function createServer(origin = null) {
   const s = new McpServer({
     name: "BrainLLM",
     title: "BrainLLM",
-    version: "12.6.4",
+    version: "12.7.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.6.4",
+  "version": "12.7.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.6.4",
+  "version": "12.7.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.6.4",
+  "version": "12.7.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.6.4",
+"version": "12.7.0",
       "transport": {
         "type": "stdio"
       },

package/skills/brainllm/SKILL.md

@@ -30,7 +30,7 @@ DURING   remember(...)                   the moment something is worth keeping
          resolve / withdraw / recover    thread and note lifecycle
          connect(...)                    wire a real relation when you see one
          read: <surface>, domain, recall, read(ids), outline, inspect, assembly, brain
-         verify: consistency(...), claim(...)
+         verify: consistency(...), claim(...), diff(since="today")
 END      session() → [update singletons] → addendum() → maintain() → remarks() → diary() → close()
 ```
 
@@ -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 (newest days, up to 30 and ~24k characters; `limit=` for more) 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; `index=true` for ids, dates and block markers only |
 | a knowledge note | `knowledge(id)` — `section=` for one section |
 | a day's change log | `insights(date?)` |
 | skim a surface | `<surface>_recall` |
@@ -148,8 +148,11 @@ Read `template(kind)` before your first write of a kind, then read a sibling.
 | `section=` + `mode="remove"` | delete the section |
 | `find="<exact stored text>"` | replace every occurrence (`nth=` for one) |
 | `edits=[{find, body}]` | several surgeries in one read and one write |
+| `find="<short anchor>"` + `within="tr"` | act on the element containing the anchor: replace it (default), `mode="before"/"after"` to insert a row beside it, `mode="remove"` to delete it (`li`, `p`, `td` … too) |
 
-- A revision is taken before every content write; `diff(noteId)` shows what the last write changed.
+- **Tables are edited by row.** Anchor on a few words unique to the row and pass `within="tr"`; never copy a whole stored row into `find=`. An anchor in several rows is refused with previews; `nth=` picks one.
+- A replacement equal to its match writes nothing and reports `unchanged`.
+- A revision is taken before every content write; `diff(noteId)` shows what the last write changed, and `diff(since="today")` reviews every note you changed today in one call — run it before closing.
 - **Check the receipt.** `matched: false` means a new section was written — `available[]` lists real headings and `didYouMean` catches typos; `strict=true` refuses instead. `headingCount > 1` means only the first match was touched. `replacedSubsections[]` names nested headings a section replace took with it.
 - **`find=` matches stored HTML, not rendered text.** Pass tags literally; `outline()` gives the `raw` form of headings with inline markup. On a miss the hint names the cause and shows the stored text nearby.
 - A section replace swaps everything under the heading — use `find=` for anything smaller.
@@ -175,7 +178,7 @@ Read `template(kind)` before your first write of a kind, then read a sibling.
 
 ## Verification — `consistency` and `claim`
 
-- **`consistency(pattern | subject)`** — does the brain agree with itself? A regex with one capture group (or a fact in prose) returns every asserting note grouped by value. **Run it after correcting any fact that could be recorded in more than one place.** `staleAfterDays=N` reports values held in only one note untouched N+ days.
+- **`consistency(pattern | subject)`** — does the brain agree with itself? A regex with one capture group (or a fact in prose) returns every asserting note grouped by value. **Run it after correcting any fact that could be recorded in more than one place.** `staleAfterDays=N` reports values held in only one note untouched N+ days. Records (sessions, diary, logs, dated thread entries) are skipped because they are never rewritten; `includeRecords=true` brings them back.
 - **`claim(...)`** — does the brain still agree with the world? Register `assertion` + `check`; verify with `claimId` + `holds` + `evidence` (evidence required); read with `claimId`; list with no arguments. BrainLLM never runs the check — you do. Register claims that would be expensive to discover had gone stale.
 
 ---
@@ -205,7 +208,7 @@ Lite runs inside `start`/`close` (thread aging, label checks). `maintain(deep=tr
 
 ## Other tools
 
-`attach`/`detach` — raw artifacts on a note. `backup(name)` — milestone snapshot (close already backs up). `bootstrap()` — create or refresh the structure. `template(kind)` — the canonical skeleton. **Full mode** (`BRAINLLM_MODE=full`) adds raw ETAPI tools with none of the server's guarantees. Read `references/fullmode.md` before any raw work.
+`attach`/`detach` — raw artifacts on a note. `backup(name)` — milestone snapshot (close already backs up into a rolling weekday slot; every named backup is a full database copy kept on Trilium's volume, so name them sparingly). `bootstrap()` — create or refresh the structure. `template(kind)` — the canonical skeleton. **Full mode** (`BRAINLLM_MODE=full`) adds raw ETAPI tools with none of the server's guarantees. Read `references/fullmode.md` before any raw work.
 
 ## Quick-fix