shard-wiki/research/260614-trilium-deep-dive/findings.md

# Findings — Trilium (TriliumNext): note cloning, attribute inheritance, HTML-native

Date: 2026-06-14
Source kind: **modern shipped product** — an open-source hierarchical PKB; a *candidate
shard* whose distinctive traits are **note cloning (a DAG hierarchy)**, an
**attribute/relation system with inheritance + templates**, and **HTML-native** content
Lens: shard-wiki — the namespace model (identity vs placement), inherited/computed
metadata, HTML translation, per-note encryption, and the scripting/ETAPI surfaces

> Why Trilium earns a dive. It is another SQLite-local note app, but it brings a
> structural feature **none of the prior twelve systems had: note cloning** — a single
> note can sit in **multiple places in the tree at once**, so the hierarchy is a **DAG,
> not a tree**, and **note identity is cleanly separated from placement** (a note has
> many "branches"). That directly challenges shard-wiki's namespace model (UC-22 assumes
> a path) and is the clone/reference primitive made concrete at the *namespace* level.
> Trilium also has an **attribute system with inheritance and templates** (effective
> metadata is computed, not just stored), and it is one of the few **HTML-native** (not
> Markdown) tools — a useful stress on "Markdown-first must degrade."

Lineage note (like TWiki→Foswiki): **TriliumNext** is the community fork of the original
**Trilium** (zadam) after it went maintenance-only; the active project is TriliumNext.

Contrast set: Joplin (SQLite-local, files-on-sync, page-level), Logseq (block-graph on
files), Notion (hosted DB, schema+relations). Trilium = **SQLite-local, DAG hierarchy,
inherited attributes, HTML content, self-host sync + ETAPI**.

---

## 1. Core architecture — one SQLite file, server-syncable

- **Storage:** a single **SQLite** file (`document.db`, via better-sqlite3) holding
  notes, attachments, history, and settings. Local DB store (like Joplin; not files).
- **Clients/sync:** desktop (Electron) or a self-hosted **server**; multi-instance
  **sync protocol** with **conflict resolution + entity change tracking**, plus
  **WebSocket** realtime updates. Attach via the server, the ETAPI (§5), or the DB.
- **IDs:** 12-char IDs — **`noteId`, `branchId`, `attributeId`, `attachmentId`**. The
  **note vs branch** split is the key idea (§2).
- **Export:** to Markdown/HTML (lossy — content is HTML, §4).

---

## 2. Note cloning — a DAG hierarchy, identity separated from placement

Notes form an arbitrarily deep tree, **but a single note can be placed in multiple
locations** — "cloning," implemented via the **branches** model:

- A **note** (`noteId`) is the content + identity. A **branch** (`branchId`) is *one
  placement* of that note under a parent (with an optional **branch prefix** giving
  per-location context). A note with several branches is **cloned** — it appears in
  several places at once; editing it anywhere edits the one note.
- So the hierarchy is a **DAG**, not a tree, and **identity (note) is separated from
  location (branch)**. There is no single canonical path for a cloned note.

This is the most shard-wiki-relevant feature in the dive:

- It breaks the assumption behind **UC-22** (resolve a page by *a* path). shard-wiki's
  namespace model must allow **a page in multiple namespace locations** with no single
  canonical path (UC-66).
- The **note/branch split** is a clean model shard-wiki should borrow: **page identity ≠
  page placement**. A page is one entity; its locations are separate placement records —
  exactly how shard-wiki should treat a page that appears under multiple paths/shards.
- It is the **clone/reference-not-copy primitive** (Xanadu clone, ZigZag clone, UC-44/45,
  T16) realized at the *namespace* level: same note, many positions, one source of truth.

---

## 3. Attributes — labels + relations, with inheritance and templates

Trilium's metadata system is **attributes**:

- **Labels** (`#tag`, optionally `#key=value`) — typed metadata on a note.
- **Relations** (`~relation`) — **typed links to other notes** (a knowledge graph).
- **Inheritance** — attributes can be **inherited down the subtree** (inheritable
  attributes), and **templates** (a note whose attributes/structure are applied to
  instances via a `~template` relation) inject attribute sets. So a note's **effective
  metadata = its own attributes + inherited + templated** — computed, not just stored.
- Promoted attributes give a form-like UI; attributes drive **search/queries** and
  **scripting**.

shard-wiki read: this is structured data (UC-34) and typed relations (UC-58), but with a
**new wrinkle — inheritance/templates make metadata *computed***. Projecting such a shard
must distinguish **effective vs own** attributes (and record their provenance: own /
inherited-from / template), not flatten them (UC-67). Templates also reinforce blueprint
pages (UC-15).

---

## 4. Content model — HTML-native, many note types

- **Text notes are HTML** (WYSIWYG via **CKEditor5**), **not Markdown**. Trilium is one
  of the few HTML-first tools studied. Markdown participation therefore needs **HTML↔
  Markdown translation** — more tractable than Notion's block model but still **lossy**
  for some constructs (CKEditor features, includes) → a fidelity-aware case bridging
  UC-42 (lossless ideal) and UC-59 (lossy-with-report).
- **Note types:** text (HTML), code (CodeMirror), **canvas (Excalidraw)**, relation
  maps, mind maps (Mind Elixir), spreadsheets (Univer), geo maps (Leaflet), **render
  notes**, file/image, book — i.e. lots of **non-Markdown content** (UC-55) and
  **script/render-generated dynamic notes** (UC-54).

---

## 5. Extension surfaces — scripting (in-app) + ETAPI (external)

Two surfaces, like Joplin:

- **Scripting (in-engine host).** **Code notes** in JS run as **frontend** (UI widgets,
  buttons) or **backend** (server-side automation) scripts against a **Script API**
  (create/query notes, attributes, etc.). Executable, in-app — the adapter-host path
  (UC-38). "Render notes" + scripts produce **dynamic, generated content** (UC-54).
- **ETAPI (external REST API).** Trilium's public REST API (since v0.50), **token auth**
  (`Bearer ETAPITOKEN`), with client libs (`trilium-py`): CRUD over notes/branches/
  attributes/attachments, search, import/export — an external attach surface (UC-57)
  that, unlike Joplin's localhost-only Data API, is the **designed external integration
  API** for a (often self-hosted) server.

---

## 6. Security — per-note (partial) encryption

Trilium offers **strong per-note encryption** ("protected notes") unlocked in a
**protected session** (password; TOTP/OpenID for login). Crucially this is **per-note**:
a shard can hold **some encrypted and some plaintext notes at once**. This refines the
**content-opacity** dimension (UC-61, proposed twelfth spectrum from Joplin/Anytype):
opacity is **per-item, not only whole-shard** — the adapter must handle a shard where
*part* of the content is opaque without a key (protected notes projectable only as
structure-shell; unprotected notes fully).

---

## 7. Trilium as a shard — capability profile

| Capability | Trilium | Notes for the adapter contract |
|------------|---------|--------------------------------|
| Read | yes (ETAPI / sync / DB) | ETAPI REST (server) is the clean surface |
| Write | yes (ETAPI / script) | per-note; via ETAPI or backend code notes |
| Write granularity | per-note (page) | — |
| Identity / addressing | **`noteId` + `branchId`** (12-char) | **identity ≠ placement**; cloned notes have many branches (UC-51, UC-66) |
| Hierarchy | **DAG (cloning)** | a note in multiple locations; no single canonical path (UC-66) |
| Structure | **labels + relations, inherited + templated** | effective vs own metadata (UC-34, UC-58, UC-67) |
| Content | **HTML (CKEditor)** + many types | HTML↔MD lossy translation (UC-42/59); non-MD types (UC-55) |
| History | internal revisions in the DB | not portable git → supplement (UC-36) |
| Native query | attribute search / script queries | delegate or build index (UC-52/63) |
| Subscribe | WebSocket + sync protocol | push; conflict resolution built in (UC-31) |
| Content opacity | **per-note encryption (partial)** | per-item opacity (UC-61 refined) |
| Extension | **scripting (in-app) + ETAPI (external)** | dual surface (UC-38, UC-57) |
| Templates | yes (`~template`) | blueprint pages (UC-15) |

Verdict: a capable **SQLite-local, server-syncable** shard best attached via **ETAPI**.
Standout demands: the **DAG hierarchy / note-branch identity model** (UC-66) and
**inherited/templated attributes** (UC-67); plus HTML-native translation, per-note
opacity, and the scripting host.

---

## 8. Mapping to shard-wiki INTENT (compare, do not equate)

### 8.1 Reinforcements

- **Identity ≠ placement** (note/branch) is a model shard-wiki should adopt for pages
  that appear under multiple paths or in multiple shards — provenance and union without
  erasure depend on separating "what a page is" from "where it sits."
- **Typed relations + templates** validate the structured/relation demand (UC-58) and
  blueprints (UC-15) on a local-first, self-hostable backend.
- **ETAPI** is a clean example of a **designed external REST surface** for a self-hosted
  server (cf. Notion external API, but self-hosted/trust-boundary friendly).

### 8.2 Deliberate divergences (design bugs if conflated)

1. **Don't force a single canonical path.** A cloned note has many placements; modeling
   it with one path loses information (UC-66). Use the note/branch separation.
2. **Don't flatten computed metadata.** Effective attributes include inherited/templated
   values; record provenance (own vs inherited vs template), don't collapse (UC-67).
3. **HTML-native, not Markdown.** Translate HTML↔Markdown with a fidelity report; degrade
   to read-only where lossy (UC-42/59/03). Markdown-first must degrade gracefully.
4. **Per-note opacity.** Some notes are encrypted; never surface protected-note
   ciphertext; project them as structure-shell (UC-61).
5. **One Trilium instance = one shard**, not the federation layer; its sync protocol is
   its own — attach via ETAPI/replica, don't re-drive it (not-a-sync-daemon).

### 8.3 What Trilium teaches that shard-wiki should keep

- **Separate page identity from placement** (note vs branch) — the cleanest model for
  multi-location / multi-shard pages and for the clone/reference primitive (T16).
- **Model metadata as computed** (own + inherited + templated) with per-attribute
  provenance (UC-67) — not a flat key/value bag.
- **Content opacity is per-item**, not only whole-shard (UC-61 refinement).

---

## 9. Use-case seeds → catalog (promoted 2026-06-14)

Last existing UC is **UC-65**. New UCs **UC-66, UC-67** added; existing UCs enriched.

| Seed | Catalog action |
|------|----------------|
| **Attach a shard with a DAG hierarchy / note cloning** — a page may occupy multiple namespace locations at once (note identity separated from placement via branches); no single canonical path | **UC-66 (new)** |
| **Preserve inherited / templated attributes** — project a structured shard whose metadata is computed (own + inherited + template), distinguishing effective vs own with per-attribute provenance | **UC-67 (new)** |
| DAG/multi-parent vs tree; note/branch (identity vs placement) | **enriches UC-22** |
| Labels (`#tag`) + typed relations (`~relation`); HTML-native | **enriches UC-34** |
| Templates (`~template`) inject attribute sets | **enriches UC-15** |
| HTML (CKEditor) content → HTML↔Markdown lossy translation | **enriches UC-42** (links UC-59) |
| Per-note encryption (protected notes) = **partial** content opacity | **enriches UC-61** |
| Scripting (frontend/backend code notes, Script API) = in-app host | **enriches UC-38** |
| ETAPI (token REST) = designed external surface for a self-host server | links UC-57 |
| Render/script notes + attribute queries = dynamic content | links UC-54; typed relations link UC-58 |
| `noteId`/`branchId` 12-char IDs | links UC-51 |

---

## 10. Architecture notes for SHARD-WP-0002 (no UC)

- **Namespace model must support a DAG** and **separate page identity from placement**
  (note/branch). A page is one entity with N placements (paths/shards). Feeds the page/
  namespace model and the clone/reference primitive. (T12, T16.)
- **Computed/inherited metadata** (UC-67): the page model's structured-data
  representation must carry **effective vs own** with per-attribute provenance
  (own/inherited/template), not a flat bag. (T12.)
- **Content opacity is per-item** (UC-61 refinement): the content-opacity capability
  (proposed twelfth spectrum) should be **granular** (per-note), not only whole-shard.
  (T11.)
- **HTML as a source content model** joins TML/Notion-blocks in the translation
  capability (HTML↔Markdown, lossy-aware). (T15.)
- **Scripting as an in-engine host** + **ETAPI external REST** are two more adapter-host
  exemplars (with Roam/Obsidian/Joplin). (T14.)

---

## 11. Open questions (for spec / workplans)

1. How does shard-wiki represent a **cloned note** in the union — one page with multiple
   path placements, or a page transcluded into multiple locations? (UC-66 vs UC-44/45.)
2. When projecting **inherited attributes** (UC-67), does shard-wiki materialize
   effective values (snapshot) or compute them live from the shard's tree/templates?
3. Is **HTML↔Markdown** round-trip lossless enough for write-back overlays, or are
   Trilium overlays read-only/native-HTML (cf. UC-42 Q2)?
4. For **per-note encryption** (UC-61), is a partially-opaque shard projected with
   protected notes as visible-but-opaque placeholders, or hidden entirely?

---

## 12. Sources

| Source | Used for |
|--------|----------|
| TriliumNext/Trilium — DeepWiki (https://deepwiki.com/TriliumNext/Trilium) | SQLite `document.db`/better-sqlite3; tree + cloning via branches; note types; sync |
| Cloning notes — TriliumNext wiki (https://github.com/TriliumNext/Trilium/wiki/Cloning-notes) | Note in multiple locations; branches; branch prefixes |
| TriliumNext — DeepWiki API & Synchronization (https://deepwiki.com/TriliumNext/Trilium/4.3-api-and-synchronization) | WebSocket + sync protocol w/ conflict resolution; 12-char IDs (note/branch/attribute/attachment) |
| ETAPI (REST API) — Trilium docs (https://docs.triliumnotes.org/User%20Guide/User%20Guide/Advanced%20Usage/ETAPI%20(REST%20API)/) | Public REST API since v0.50; token/Bearer auth; trilium-py |
| Script API — TriliumNext wiki (https://github.com/TriliumNext/Trilium/wiki/Script-API) | Frontend/backend code notes; Script API |
| BrightCoding — TriliumNext overview (https://www.blog.brightcoding.dev/2025/09/20/triliumnext-notes...) | Attributes (labels/relations), inheritance, templates, per-note encryption, note types |

Cross-references: `research/260614-joplin-deep-dive/findings.md` (SQLite-local, dual
surface, content opacity), `research/260614-notion-deep-dive/findings.md` (typed
relations, external API), `research/260614-zigzag-deep-dive/findings.md` (clone /
dimensions), `research/260614-shard-spectrum-synthesis/findings.md` (spectra this
refines), `spec/UseCaseCatalog.md` (UC-15, UC-22, UC-34, UC-38, UC-42, UC-51, UC-54,
UC-57, UC-58, UC-61), `workplans/SHARD-WP-0002-federation-architecture.md` (T11, T12,
T14, T15, T16).

---

## 13. Traceability

- New UCs: **UC-66, UC-67** → `spec/UseCaseCatalog.md`.
- Enriched UCs: **UC-15, UC-22, UC-34, UC-38, UC-42, UC-61** (links UC-51, UC-54, UC-57,
  UC-58, UC-59).
- Architecture (no UC): DAG namespace + identity/placement (note/branch) split;
  computed/inherited metadata; per-item content opacity; HTML source model; scripting +
  ETAPI host surfaces → `SHARD-WP-0002` (T11, T12, T14, T15, T16).
- Boundary recorded: Trilium (TriliumNext) is **one SQLite-local candidate shard** with a
  DAG hierarchy and computed metadata, best attached via **ETAPI**; HTML-native (lossy to
  Markdown), per-note opacity; not a substrate, not the federation layer (INTENT
  graceful-degradation, no-silent-mutation, not-a-sync-daemon).
</content>