brainllm 12.7.1 → 12.8.0

package/manifest.json

@@ -2,22 +2,22 @@
   "manifest_version": "0.3",
   "name": "brainllm",
   "display_name": "BrainLLM",
-  "version": "12.7.1",
-  "description": "Turns TriliumNext Notes into a persistent, graph-structured second brain for Claude and other LLM clients.",
+  "version": "12.8.0",
+  "description": "Self-hosted memory for LLMs in TriliumNext, structured by the server and editable by you.",
   "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": {
     "name": "Kevin Miiso",
     "email": "miisodev@gmail.com",
     "url": "https://github.com/miisodev"
   },
-  "homepage": "https://github.com/miisodev/BrainLLM#readme",
+  "homepage": "https://miisodev.github.io/BrainLLM/",
   "repository": {
     "type": "git",
     "url": "https://github.com/miisodev/BrainLLM.git"
   },
   "support": "https://github.com/miisodev/BrainLLM/issues",
   "license": "MIT",
-  "keywords": ["mcp", "trilium", "trilium-next", "second-brain", "knowledge-graph", "memory", "claude"],
+  "keywords": ["mcp", "trilium", "trilium-next", "knowledge-graph", "memory", "claude"],
   "icon": "public/BrainLLM.png",
   "server": {
     "type": "binary",

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "brainllm",
-  "version": "12.7.1",
+  "version": "12.8.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.",
+  "description": "Self-hosted memory for LLMs in TriliumNext, structured by the server and editable by you.",
   "author": "Kevin Miiso Novo <miisodev@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/miisodev/BrainLLM.git"
   },
-  "homepage": "https://github.com/miisodev/BrainLLM#readme",
+  "homepage": "https://miisodev.github.io/BrainLLM/",
   "bugs": {
     "url": "https://github.com/miisodev/BrainLLM/issues"
   },
@@ -22,7 +22,7 @@
     "model-context-protocol",
     "trilium",
     "trilium-next",
-    "second-brain",
+    "memory",
     "knowledge-graph",
     "llm",
     "claude",
@@ -54,6 +54,7 @@
     "test": "bun run src/test.ts",
     "test:unit": "bun test",
     "test:http": "bun run scripts/http-smoke.ts",
+    "test:live": "bun run scripts/live-smoke.ts",
     "init": "bun run src/init.ts",
     "icons": "bun run scripts/icons.ts",
     "validate:release": "bun run scripts/validate-release.ts",

package/server.json

@@ -1,9 +1,9 @@
 {
   "$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.7.1",
-  "websiteUrl": "https://github.com/miisodev/BrainLLM#readme",
+  "description": "Self-hosted memory for LLMs in TriliumNext, structured by the server and editable by you.",
+  "version": "12.8.0",
+  "websiteUrl": "https://miisodev.github.io/BrainLLM/",
   "repository": {
     "url": "https://github.com/miisodev/BrainLLM",
     "source": "github"
@@ -12,7 +12,7 @@
     {
       "registryType": "npm",
       "identifier": "brainllm",
-"version": "12.7.1",
+"version": "12.8.0",
       "transport": {
         "type": "stdio"
       },
@@ -39,7 +39,7 @@
         },
         {
           "name": "BRAINLLM_MODE",
-          "description": "core (default) exposes the 44 brain-aware tools; full additionally exposes the 33 raw ETAPI tools.",
+          "description": "core (default) exposes the 45 brain-aware tools; full additionally exposes the 33 raw ETAPI tools.",
           "isRequired": false,
           "format": "string",
           "default": "core"

package/skills/brainllm/SKILL.md

@@ -30,13 +30,13 @@ 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(...), diff(since="today")
+         verify: consistency(...), claim(...), diff(since="today"), health()
 END      session() → [update singletons] → addendum() → maintain() → remarks() → diary() → close()
 ```
 
 `start()` returns the date, **preferences and protocols in full**, the other singletons as section headings (pull one with `master(which)`/`llm(which)`, `section=` for one section; `depth="full"` inlines all), today's diary and session ids, active and dormant threads, the previous session and notes changed since. `newDay: true` on the first session of a day → call `day()` (previous session, its log, notes touched since). `day(recap=true)` returns everything written today, in order, across sessions, diary and thread entries.
 
-**Close protocol.** `session()` returns singleton stubs, `pending=` (what each remaining step has to do), `audit=` (do the singletons agree, and do the LLM ones still serve the master ones) and `next[]`. Update master singletons with what you learned about the user and LLM singletons with what you learned about yourself, fold any addenda (`addendum()`), `maintain()`, `remarks()` for diary cues, `diary()` your closing record, then `close(summary, identity)`. `close()` refuses until those steps ran and `session → remarks → diary` held; the gate is durable across restarts. `force=true` bypasses a step with nothing to do (reported). `continuing=true` is a second close on the same day. Scoped or autonomous runs pass `session(scope="agent")`.
+**Close protocol.** `session()` returns singleton stubs, `changedToday` (the maintained notes this day's writes touched: check every figure you changed agrees everywhere it is recorded, with `diff(since="today")` and `consistency()`), `pending=` (what each remaining step has to do), `audit=` (do the singletons agree, and do the LLM ones still serve the master ones) and `next[]`. Update master singletons with what you learned about the user and LLM singletons with what you learned about yourself, fold any addenda (`addendum()`), `maintain()`, `remarks()` for diary cues, `diary()` your closing record, then `close(summary, identity)`. `close()` refuses until those steps ran and `session → remarks → diary` held; the gate is durable across restarts. `force=true` bypasses a step with nothing to do (reported). `continuing=true` is a second close on the same day. Scoped or autonomous runs pass `session(scope="agent")`.
 
 **Write during the session, not at the end** — a fact written mid-conversation survives a crash.
 
@@ -89,13 +89,14 @@ 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; `index=true` for ids, dates and block markers only |
+| 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; `block="14:05"` (or `"-1"`, the newest) for one addendum of a session or day entry — `llm("diary", id, block=)` likewise |
 | a knowledge note | `knowledge(id)` — `section=` for one section |
 | a day's change log | `insights(date?)` |
 | skim a surface | `<surface>_recall` |
 | everything about an area | `domain(name)` — the reliable path; reach here first |
 | search | `recall(query, domain=…)` — scope it; `regex=` for structure; fuzzy hits are leads |
-| several bodies at once | `read(ids=[…])` (≤ 10) |
+| several bodies at once | `read(ids=[…])` (≤ 10). Bodies stop at ~80k characters; the rest come back in `deferred[]` for a second call. `text=true` returns readable plain text for orienting (not for building a `find=` anchor) |
+| storage and growth | `health()` — Trilium version, estimated database size, heaviest notes and their revisions, named backups |
 | what the brain holds | `assembly(area?)` — titles by surface with purposes |
 | inventory / locate by id | `brain()` — read `parent`, not position |
 | a note's heading tree | `outline(id)` — before any `section=` edit you're unsure of |
@@ -146,15 +147,16 @@ Read `template(kind)` before your first write of a kind, then read a sibling.
 | `section=` + `mode="before"/"after"` | insert a sibling block around the whole section |
 | `section=` + `mode="prepend"` | insert at the top of the section's body |
 | `section=` + `mode="remove"` | delete the section |
-| `find="<exact stored text>"` | replace every occurrence (`nth=` for one) |
+| `find="<text>"` | replace every occurrence (`nth=` for one) — exact first, then through re-serialized tags, then ignoring inline formatting (`matchMode` says which) |
 | `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) |
+| `domain="<name>"` + `find=`/`edits=` (no noteId) | the same find/replace across every maintained note in a domain; a dry run listing each match unless `dryRun=false`. Records are never touched. `dryRun` anywhere else is refused |
 
 - **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.
+- **`find=` prefers stored HTML.** Plain text also matches through inline formatting (`<strong>`, `<code>`, `<em>`, entities), so a short anchor rarely needs its markup; a span that opens or closes formatting is widened to keep it balanced. Block tags still match literally; `outline()` gives the `raw` form of headings. 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.
 - **Oversized note (past the read ceiling)?** It usually holds two subjects: `split(noteId, sections=[…], into="<title>")` moves whole sections to a new sibling and leaves a pointer.
 - Concurrent writers are serialised server-side; reads stay parallel.
@@ -191,7 +193,7 @@ Lite runs inside `start`/`close` (thread aging, label checks). `maintain(deep=tr
 |---|---|
 | stale | revise, resolve, or `ack=[id]` if correct as it stands |
 | orphan / sink | `connect()` |
-| dated prose | a timeless note carrying dates — move state to Current State, history to a thread entry |
+| dated prose | a timeless note carrying dates — move state to Current State, history to a thread entry. A register (a backlog, a defects list) whose rows carry evidence dates takes `label(id, "register", value="")`, which exempts its tables but not its prose |
 | duplicate heading / unbalanced tags / incomplete | fix with `revise` |
 | oversized / section-edit-risk / size trajectory | `section=` reads, `split()` |
 | dated / long title | retitle, fold into the note it should have updated, or split |
@@ -208,7 +210,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 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.
+`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; `health()` lists the named ones). `health()` — storage health: estimated database size, revision-heavy notes, named backups, with flags on growth. `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
 

package/skills/brainllm/references/troubleshooting.md

@@ -28,6 +28,10 @@
 |---|---|
 | BrainLLM tools time out or return connection errors | The backend is unreachable, not the tool — every ETAPI call is bounded at 30 s with one retry on idempotent reads, so a hang surfaces as a failed tool call rather than a stuck session. Check the instance `TRILIUM_BASE_URL` names: a hosted deploy should answer at its own URL, a local desktop install needs the Trilium app running. Then retry. |
 | `start` → `uninitialized` | `bootstrap` |
+| A result ends with `[BrainLLM: … cut at 140,000 to fit the client's limit]` | The result passed the server's size cap. Narrow it: `section=`, `block=`, `limit=`, or fewer `ids=` |
+| `revise` refuses `dryRun=` | `dryRun` exists only for `revise(domain=)`. To preview one note's edit, read the note (or `outline()`) first; `diff(noteId)` shows what a write changed |
+| `read(ids=[…])` returns `deferred[]` | The bodies passed ~80k characters together; read the deferred ids in a second call, or pass `text=true` |
+| `health()` flags a note's revisions | Revision history is most of the database's weight. Splitting the note, or tightening Trilium's revision-snapshot interval, bounds it |
 | Deep maintenance flags the same items every session | Act on them, or `maintain(ack=[…])` the ones you reviewed and found correct |
 | `revise(find=)` returns `replaced: 0` | Read the hint — it names the cause. Escaped search string (`&lt;h3&gt;` against stored real tags): pass the tag literally. Spans a block boundary (`</h3>` then `<ol>`): anchor inside one element, or use `section=` with `mode="before"/"after"`. Otherwise it was already replaced, or the text genuinely differs — check with `inspect(noteId, find="<shorter substring>")` |
 | `revise(section=)` returns `matched: false` | No heading matched, so a NEW section was written — at the note's own level, with the note's real headings in `available[]`. Re-target from that list; `outline(noteId)` gives the same tree plus levels and occurrence indices before you write |